Nimble Advertizer technology details

Server-side advertisement insertion technology is based on Nimble Streamer media server. Here you can find technical details of its setup and usage.

Also, take a look at Nimble Advertizer live demo to see it in action.

1. Basic workflow

Ads insertion technology workflow works as follows:

Nimble Streamer media server processes incoming streams to get content. See section 2 for prerequisites.
Nimble Advertizer calls your handler web application (see section 4), handler URL is defined in Nimble Streamer config file (see section 3).
Nimble Advertizer gets response from handler with ads scenarios (see section 5).
Advertizer gets files with advertisements to process them via Nimble Streamer according to ads scenarios logic defined by handler response.
Nimble inserts the ads into original media and packages it into outgoing stream.
End user connects to Nimble and gets media stream containing original content mixed with advertisements.
Currently HLS, RTMP, SLDP, and Icecast are supported as output protocols while all protocols supported by Nimble Streamer can be used as input.

2. Prerequisites

Before following the description below please make sure you comply with the following prerequisites:

You have WMSPanel account which has active subscription. Trial accounts have no access to this feature.
Your WMSPanel login has admin privileges.
You have Nimble Streamer installed and running.
You subscribed for Nimble Advertizer, got active license and registered it (see instruction below in this section).
Advertising files are packaged into MP4 container. You may use ffmpeg to re-package files into MP4.
Advertising video is encoded to H.264.
Advertising audio has the same codec and sample rate as your input stream. E.g. if your stream is AAC 44.1KHz, your ads will be packaged into MP4 file with AAC audio with 44.1KHz sample rate.
Advertizing files must be accessible for download from Nimble instance via HTTP/HTTPS URL.
Input streams are set up and their content is available.
For SLDP output: the output stream is set up and is publicly available. Use proper instruction from SLDP page to perform the setup.
For RTMP output: the output stream is set up and is publicly available. Use proper instruction from RTMP page to perform the setup.
For HLS output: the output stream is set up and is publicly available. Use proper instruction for your input protocols to set up HLS output.
Notice that Nimble Streamer application setting must have "HLS" output enabled; "HLS MPEGTS" or "HLS fMP4" are not yet supported.
For Icecast ads: input stream has either AAC or MP3 encoded audio. The output will have the same codec.
The Icecast output stream is set up and is publicly available. Use proper instruction from audio streaming page to perform the setup.

To obtain and register the Advertizer license follow these steps:

Go to Settings menu and open Advertizer licenses tab
Click on New SSAI subscription and select number of licenses, then click Next and once you see final cost, click on Pay now button.
Follow the payment procedure and once you complete it, you’ll see your active licenses.
Click on the license to see the registration procedure.
Log into the server which has Nimble Streamer installed and which you will use as your Nimble Advertizer host. Then use the registration procedure to make it work.

That’s it, you may now proceed with your Advertizer setup.

3. Config file setup

Nimble Advertizer behavior on server side is defined via Nimble Streamer configuration file. Its general parameters and usage are described in this article. The following settings must be used for serve setup.

advertising_url=http://server_addr/handler_app | https://server_addr/handler_app
Defines the URL of handler app.
Example: advertising_url=http://testradiowebsite.com/ads_handler.php

advertising_sync_interval=seconds
Defines how frequent Nimble Advertizer will request the handler for updates of ads scenarios. It’s 10 seconds by default.
Example: advertising_sync_interval=3

max_advertising_download_sessions=number
Defines how many concurrent sessions Nimble Advertizer will use for downloading the files which contain ads. It’s 10 sessions by default. If handler specifies more files that defined in this parameter, the extra files will be queued and downloaded in their turn.
Example: max_advertising_download_sessions=20

Once you define settings in config file, please restart Nimble Streamer. For Linux it’s done by "sudo service nimble restart" command.

Read this article to find more details regarding Nimble config.

4. Handler application

Nimble Advertizer business logic for ads insertion is defined by your handler.
Handler is a REST controller which is called by Nimble Advertizer and responds with ads scenarios. It’s called periodically as defined in Nimble config file, see section 3 for details. Handler app must be available via HTTP/HTTPS protocol and accessible from Nimble instance.
You may use any language and framework to create a handler application. Handler response must be a valid JSON text, its grammar is described below.

5. Handler response grammar

Handler application returns a JSON text as a response to server sync-up call. This response describes advertising scenarios for Nimble Advertizer to follow.
Here is a formatted example of response which shows its structure and elements.

{
  "contents":
  [
    {"id":"11","uri":"http:\/\/192.168.232.129\/SampleAudio_0.4mb_5s.aac.mp4"},
    {"id":"22","uri":"https:\/\/192.168.232.129\/testt.mp4"},
    {"id":"33","uri":"http:\/\/8.8.8.8\/SampleAudio_0.4mb_5s.mp3.mp4"}
  ],
  "rules":
  [
    {
    "id":"1",
    "protocols":["icecast", "sldp", "rtmp", "hls"], 
    "users":[],
    "type":"global",
    "time_sync":"stream",
    "time_offset":0,
    "time_interval":600,
    "contents":[{"id":"11","onerror":"stop","wait":"10"}, {"id":"22","onerror":"skip","wait":"2"}]
    }
  ]
}

Response has 2 general elements - contents and rules.

The contents element describes the ads files to be used in advertising rules. It’s an array of ads, each having id for ad’s ID and uri for ad location URI.

The ID is a unique identifier of an ad. Once new ID appears in handler response, it’s downloaded and put into Nimble cache for further insertion into streams. If you’d like to update the ad over time, you need to update your ad file and add it to your response with new ID. In this case the old file will be removed from cache and the new one will be uploaded. Removing ID from response means this ad will be played for all clients where it started to play already and then it will be removed from cache.

The URI is any valid web location available via HTTP or HTTPS.

The rules element describes the ads insertion logic. Each rule describes applicability of certain ads for certain set of streams or users. If several rules can be applied to the same stream, then all those rules will be applied one by one. The application order is defined by the time of ad appearance defined in each rule. If several ads apply for the same time, then they will be queued and played one after another.

Each rule has its id element to define its ID. If new ID appears in rules, this rules starts working. If it’s removed then the rule is removed too and it stops working. If you change the rule without changing the ID, this rule’s change will not be applied. So if you’d like to modify the rule - just assign new ID to it.

The protocols element describes which protocols this rule will apply to. Currently icecast, sldp, rtmp and hls values are supported.

The users element is populated in case you want to insert personalized ads. It’s a list of IDs of users to apply this rule for. It’s defined by pay-per-view framework available with Nimble. If you don’t want to personalize ads, just keep this list empty in all rules.

The type element defines what type of entity this rule is applied. Possible values are global, app and stream.

global type means this rule is applied to all streams on current server.
app type means this rule will be applied to a certain streaming application. In this case you also need to add app element with application name. E.g. if you have streams like live/stream1, live/stream2 etc. then you can add these elements: "type":"app","app":"live"
stream type means the rule will be applied to exact stream. It needs app and stream elements added to describe the stream. E.g. if you want to apply a rule to live/radio1 stream, then you’ll need to use these elements: "type":"stream","app":"live","stream":"radio1".
It may also be applied to a number of streams using array: "type":"stream","app":"live","stream": ["stream1", "stream2", "etc"]

The time_sync element defines the reference point for this rule to define time for ads insertion. It defines time_offset element usage.
If you use "time_sync":"gmt" value then your ad insertion will be defined by exact time point. "time_offset" will define time of insertion in "%Y-%m-%d %T" format, e.g. 2018-01-01 10:00:00
If you use "time_sync":"stream" value then you will define start time for your ads relatively to the time when a user is connected to the stream. In case of stream value, start time is defined in seconds. In this case "time_offset" will set when to start the ad after a user is connected. If it’s "time_offset":"0" then it’s inserted right after the user has connected.

The time_interval element defined the time period for next ads insertions. It’s defined in seconds. E.g. if it’s "3600" this means it will be played every hour. If it’s "0" then it will not be repeated.

The combination of these 3 elements allows defining different timing scenarios.
If you need to define the pre-roll ad, you will use "time_sync":"stream","time_offfset":"0","time_interval":"0"
If you need to start ads 5 minutes before the end of each hour, you will use "time_sync":"gmt","time_offfset":"2018-01-01 00:55:00","time_interval":"3600"

The contents element defines a list of elements, each describing one ad to insert at the time point defined by previous elements.
Each element has id which is the ID of an ad described in starting contents element of handler response.
The onerror element defined what to do if the ad is not yet in Nimble Streamer cache. Possible values are stop or skip. stop means Advertizer will stop the original stream for this user and skip means Advertizer will continue playing original stream without an ad. The wait element defines time in seconds which Nimble Advertizer will wait until the ad in downloaded.
So "id":"11","onerror":"stop","wait":"10" means Nimble will wait for 10 seconds trying to download the "11" ad and will stop the streaming if it fails to download during that time.
And "id":"22","onerror":"skip","wait":"2" means Nimble will wait for 2 seconds while it downloads "22" ad and if it doesn’t get the ad, then the playback will resume.

This is basic grammar covering major use cases. Let’s see some examples of responses for typical situations.

6. Some examples

You can find handler and responses examples in respective Advertizer repository on github.

7. Ads logging

You can track your ads performance using ads logging in Nimble Streamer.

To enable ads logs, go to nimble.conf and add log_advertisements = true line. Once you restart Nimble Streamer, you will get ads logs saved to advertisements.log file. Each line in the log represents a single ad insertion.

All lines in the log file will have the following format.
[date_time] "result_stream" "ad_id" "ad_rule_id" "ad_url" client_ip "ppv_user_id" "user-agent"

result_stream is the output stream which has the ad, it’s formatted as “/application_name/stream_name/”
ad_id is the ID of the ad from “content” element of JSON which is being inserted
ad_rule_id is the ID of the rule which was applied to make insertion
ad_url is full URL of the ad being inserted
client_ip is the IP address of the viewer
ppv_user_id is the user ID being used for per-user ads insertion
user-agent is the User-Agent of a viewer

Watch live demo

Demo page shows live streams with ads insertion, with full details on Advertizer setup.

If you have any questions on Nimble Advertizer usage, please contact us via company helpdesk.