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.
Ads insertion technology workflow works as follows:
Before following the description below please make sure you comply with the following prerequisites:
To obtain and register the Advertizer license follow these steps:
That’s it, you may now proceed with your Advertizer 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.
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.
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.
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.
You can find handler and responses examples in respective Advertizer repository on github.
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"
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.
This website or its third-party tools use cookies, which are necessary to its functioning
and required to achieve the purposes illustrated in the
Privacy Policy.
If you want to know more or withdraw your consent to all or some of the cookies, please
refer to the
Privacy Policy.
By closing this banner, scrolling this page, clicking a link or continuing to browse otherwise,
you agree to the use of cookies.