How to set up SSAI tracking

When using SSAI (Server-Side Ad Insertion) ads in your streams, Bitmovin Analytics can track SSAI playback events and measure the quality experienced by the viewer during SSAI ads. Tracking SSAI events and playback quality is important to ensure you can monetize your content while maintaining a good viewer experience.

To track and monitor the playback of SSAI streams we provide collector APIs allowing you to inform Analytics about your SSAI ads, along with a dashboard and query APIs where you can see your SSAI ad data & metrics.

Playback session including SSAI ads

What do we track?


SSAI tracking uses the same structure as regular playback tracking. We apply ad indicators and additional metadata provided via the API. This allows us to determine how long, at what time, and in what quality your SSAI ads are played.

This allows you to see several things:

  • Session Details: You can see where an SSAI ad occurred in your session, which events were happening at the time (playing, buffering, error, etc.), along with the given ad metadata and custom data fields.
  • SSAI-Filtered Metrics: View metrics that consider only SSAI ads using a filter (total watched hours, rebuffer percentage, etc.).
  • Comparison Metrics: Compare regular playback with SSAI playback (average video bitrate, etc.).
  • Dedicated SSAI Ads Metrics: Access metrics specific to SSAI ads.

Some of the options mentioned are only possible via the Query API.

We provide the necessary methods to call at the points where the ad transitions. These methods has to be called before the transition from regular playback to ad playback. Later in chapter Timing

Collector API

adBreakStart([adBreakMetadata])

This method collects information about the ad break and sets up the collector for SSAI tracking. It does not change the data collected on its own and needs to be called when the ad break starts, before adStart.

AdBreakMetadata

class AdBreakMetadata {
  adPosition: string
}
  • adPosition: Describes the ad break position. Values can be preroll, midroll or postroll

The adBreakMetadata parameter is optional.

adStart(adMetadata)

This method flags new samples with the ad flag and the provided adMetadata and customData. It is called for every ad that starts within the ad break. There is no dedicated adStop method; calling adStart for a second ad implicitly stops the first ad without passing metadata to the second ad.

AdMetadata

class AdMetadata {
  adId: string
  adSystem: string
  customData: CustomDataValues
}
  • adId: Unique identifier to track the ad in your ad decision server.
  • adSystem: System that delivered the ad.
  • customData: Object containing all custom data fields.

The adMetadata parameter and its properties are optional.

adBreakEnd()

This method stops the current ad by sending out a sample with the previous metadata and then resets all internal states regarding SSAI ads. After this call, the ad and ad break are considered finished, and it also removes the customData provided for an ad.

Note: This will only work if an ad break is running.

What do i need to do?

To track SSAI with Bitmovin Analytics collectors, you need to know the following:

  • Ad start position: The position in the stream where the ad starts.
  • Ad duration/ad end position: A way to determine when the ad stops.
  • Player position: A way to know the current playback position or a callback once a certain position has been reached.

Let’s discover how this works with an example:

Our ad will play at the 10-second mark, and its duration is 10 seconds.

  1. Wait for the player to reach 10 seconds in the playback.
    Aim for 9 seconds and 800 milliseconds. The collector methods need to be called right before the transition. There are different ways to accomplish this, such as using player event listeners that report on changing positions like the Bitmovin Player event TIMECHANGEEVENT.
  2. Right before the ad transition occurs, call adBreakStart() with or without ad break metadata, followed by adStart() with or without ad metadata.
    Now, you are tracking SSAI!
  3. Once the ad is over, follow the same approach as in step 1 to get to the position where the ad ends. Then, call adBreakEnd() to stop SSAI tracking.

Timing of Method Calls

The timing of method calls is crucial for correct tracking. The position in the video where the regular playback transitions to the ad playback is important because it marks a change in content and is also a potential point of failure. To correctly track errors that happen during this transition, we need to start SSAI tracking before the transition begins.

Start of Ad Break

We accomplish this by calling the SSAI start API approximately 200-400 milliseconds before the player reaches the position where the ad starts.

End of Ad Break

Similarly, at the end of the ad break, we want to stop SSAI tracking 200-400 milliseconds after the transition back to regular content.

With correct timing, you ensure that errors during the transition are flagged as SSAI playback. This can help debug errors produced during the insertion process by your SSAI provider.

How can I see the data?

SSAI in Session Details.

Within a session, we track the position and duration of each ad played. We provide an overview of all the ads played during a session along with all your provided metadata.

To view this information:

  1. Navigate to Audience > Latest Sessions in our Dashboard.
  2. Select a session that includes ads.
  3. In the SSAI tab, you will see a list of played ads:

SSAI via Queries

You can build your own queries that show the SSAI data you’ve collected by using the Analytics Query API.

Within the API, SSAI ads are denoted by an ad type of '2'.
For example, the query below will return the total time that SSAI ads were played each day:

queryBuilder
  .sum('PLAYED')
  .licenseKey('<YOUR LICENSE KEY>')
  .between(fromDate, toDate)
  .filter('AD', 'EQ', 2)
  .interval("DAY")
  .query();

You can add additional .filter() and .groupBy() queries to further break down the data.