Advertizer per-session ads insertion and stats

Nimble Advertizer is a wide feature set for server-side ads insertion for Nimble Streamer software media server. It allows adding pre-roll and mid-roll ads into live and VOD streams according to customer business logic.

Dynamic ads can be inserted into HLS, RTMP, SLDP and Icecast outgoing live streams, along with HLS VOD output.

Previously the Advertizer allowed setting rules for ads insertion per application, per stream, as well as define per-user rules based on pay-per-view framework of Nimble Streamer.

With recent update it's now possible to apply Advertizer to more use cases:

1. Make per-session ads insertion for each individual user by using customer-side session handler.
2. Get per-session statistics to accumulate ads insertion metrics for advertisers' confidence.

In current article we'll focus on per-session mechanics without going into common details of Advertizer functionality like pre-requisites or general config grammar. You can find full set of details about Advertizer set setup and usage in Advertizer tech spec. You can also take a look Advertizer demo page showing the playback of all supported protocols with inserted ads.

Notice that per-session ads insertion is available for HLS, SLDP and Icecast outgoing live streams and for HLS VOD output. RTMP output is not supported for per-session scenarios.

1. Workflow

Let's see how Advertizer works with regular workflow and how it can be adjusted with per-session approach.

In a regular workflow the steps are straight-forward:

1. Nimble Advertizer calls ads handler web application to get a business logic description.
2. Advertising handler returns ads content description and applicability rules of what ads need to be inserted in which streams.
3. Nimble Streamer gets the ads files and inserts their content them into output streams according to.

In per-session workflow, the second and third steps will have additional layer or activities.

1. Your advertising handler (main handler) will now need to return the URL of per-session handler in addition to ads content description and applicability rules.
2. Nimble Advertizer will call the per-session handler to send rules request and session info.
3. Per-session handler gets the request and session info, and then makes the decision about who needs to watch which ads. It may also save the stats for further analysis.
4. Per-session handler returns a set of rules specific to individual users.
5. Nimble Advertizer serves ads according to new rules received by per-session handler, with session rules having priority over rules provided by the main handler.

Let's see how you can follow the described steps.

2. Enabling per-session handler

Per-session handler, just like main Advertizer handler, is a REST controller application which is called by Nimble Advertizer. You may use any language and framework to create it. Handler response must be a valid JSON text. Handler app must be available via HTTP/HTTPS protocol and accessible from Nimble instance.

Per-session handler URL needs to be returned in main handler's response in a new section called "session_handler" like shown below.

{

  "session_handler": {

    "apps": ["local", "remote", "live"],

    "url":"http://127.0.0.1:8085/session-handler"

  },

  "contents": [

    {"id":"1","uri":"http:\/\/127.0.0.1:8085\/ads\/1_180.mp4", "height":"180"},

    {"id":"2","uri":"http:\/\/127.0.0.1:8085\/ads\/1_240.mp4", "height":"240"},

    {"id":"3","uri":"http:\/\/127.0.0.1:8085\/ads\/1_360.mp4", "height":"360"},

    {"id":"4","uri":"http:\/\/127.0.0.1:8085\/ads\/1_360.mp4", "height":"480"},

    {"id":"5","uri":"http:\/\/127.0.0.1:8085\/ads\/pre-roll.aac.mp4"}

  ],

  "rules": [

  ]

}

This and other examples are available in Advertizer github repo, like this one.

Please note that Nimble streamer supports rendition-specific ads insertion taking the "height" parameter provided in the “contents” section which allows inserting ads with the stream’s appropriate resolution (see section 4 below).

The session_handler section may contain optional elements, here's full example:

"session_handler": {

  "url": "https://server/handler",

  "apps": ["app1", "app2"],

  "timeout": "1000",

  "onerror": "skip"

}

The elements mean the following:

• url is the URL of per-session handler.
• apps is a list of applications which are defined in Nimble Streamer, and which ads insertion will be applied to.
• timeout is a period of time which Nimble can wait for per-session handler response. It's measured in milliseconds and it's 1000 by default.
• onerror defines what action needs to be made is response is not received on time. It's "skip" by default which means that the playback will continue. The "stop" value means that the playback must be stopped and not processed since session handler has failed.

Let's see what happens when Nimble Streamer calls per-session handler.

3. Sending request to handler

First, open per-session-handler-request.json example from our github to illustrate the description below.

The request has two sections: session_info and rules_request. The handler is called in any of these events:

• Each 30 seconds to send session_info part, you can use advertising_session_rules_request_interval to set it.
• On each new connection, to send rules_request part. Also session_info can be sent with collected session information if available.
• Each request_interval time slot, as defined in section 4.

Let's see what each section provides.

session_info is included in the request to show the statistics of ads viewership.

It has subsections for all sessions served by Advertizer since the last handler call, each session has its subsection. Here are the elements of each session:

• session is a session ID.
• app and stream show the stream which was served.
• client_ip is the IP of a viewer.
• user_agent is a data from viewer's User Agent header.
• state is either active or inactive.
• views contain data about ad viewership. It has 3 subelements: rule has ID of an ads rule applied, content has ID of ads content shown and uri is a URL of content applied.
• user: if you use pay-per-view framework, you will get user element which indicates viewer's user ID.

rules_request is included in requests to get response about what Nimble must do for sessions. Each session has individual section. It has the following elements.

• session is s session ID.
• protocol is a protocol type of a stream. This can be "hls", "sldp" or "icecast".
• app and stream show the stream which is being served.
• client_ip is the IP of a viewer.
• user_agent is a data from viewer's User Agent header.
• stream_time is a duration of a session prior to the moment when the request was sent

With these two sections, your per-session handler can make decisions about the ads content to be shown to your viewers.

Here's what per-session handler is expected to return to Nimble Advertizer.

4. Getting response from session handler

Take a look at response example below.

{
  "rules":
  [
    {
      "time_offset": 0,

      "time_sync": "stream",

      "type": "session",

      "id": 101,
      "contents": [{"id": ["1", "2", "3", "4"]}]

    }
  ],
  "rules_response":
  [
    {
      "rules": [101],

      "session": 5,

      "request_interval": 10

    }
  ]
}

You may also find it in Advertizer github.

Per-session handler response has two sections.

rules section defines rules for ads insertion which will be applied to sessions from rules_response section. The grammar for this section is the same as for main handler response describe in Advertizer spec. The only difference is that "type" element must always be "session".

These rules are also appended to the rules from the main handler response, so you may combine both per-session and default approaches to ads insertion. If there are per-session and main handler rules with the same rule ID, then session rule will be applied as it has priority.

Note that content IDs for resolution-specific ads insertion are provided in the rule as an array of ids, like "contents": [{"id": ["1", "2", "3", "4"]}] while these content ids and the respective content URLs are defined in the in main handler's response previously (see section 2 above).

rules_response section describes which ads insertion rules need to be applied to a particular session.

• rules is the list of ads rules to be applied.
• session is the ID of the session where rules are applied
• request_interval defines how often after that Nimble Advertizer needs to request rules for this session.

The rules from response will be applied to current session once it's received by Advertizer. Some delay is possible in case of HLS just because of chunks download time and player reaction.

If you have any questions about Advertizer or per-session ads insertion, let us know.

Related documentation

Nimble Advertizer, Nimble Advertizer spec, github repo for Advertizer,