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:

2. Prerequisites

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

To obtain and register the Advertizer licensefollow these steps:

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 on this page. 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 page 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 havingid for ad’s ID anduri 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. Currentlyicecast, sldp, rtmp andhls 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 bypay-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.
If you use "time_sync":"scte35" value then start and end time for your ads will be completely defined by SCTE-35 markers that are delivered within incoming stream. "time_offset" and "time_interval" parameters are not used in this case. Read section "7. Working with SCTE-35" below to see how you can enable this capability.

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_offset":"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_offset":"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.
If several ads IDs are listed in the "contents" element, then those ads will be played one by one once the ad insertion is triggered.

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. Working with SCTE-35

To enable the processing of SCTE-35 markers on Nimble Streamer instance, you need to add the following parameter into Nimble Streamer config file:
scte35_processing_enabled = true
You'll need to re-start Nimble Streamer instance and input stream to make the changes work. Read this page to learn more about making changes to Nimble Streamer config.

The following articles will give all information about SCTE-35 markers usage in Nimble Streamer:

8. Ads logging

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

To enable ads logs, go to nimble.conf and add 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.
Visit config description page to learn more about making changes to Nimble Streamer config.

All lines in the log file will have the following format.

"result_stream" "ad_id" "ad_rule_id" "ad_url" client_ip "ppv_user_id" "user-agent"

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.