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.

The SSAI Signalling Flow

In order for Bitmovin Analytics to be aware of SSAI Ads being played in the stream you need to signal to the Analytics Collector when an AdBreak is starting as well as the start of the subsequent Ads in the break. Once the Ad Break is over you call adBreakEnd to signal the end of currently playing Ad and that normal content resumes.

Once Ad Tracking is set up you will see SSAI Ad Breaks and Ads displayed in the Session Detail view as green bars and can inspect the passed Ad metadata through SSAI Tab in the Session Detail screen.

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 have to be called before the transition from regular playback to ad playback. See this section for more details about the method call timing.

Integration

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.

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.
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!
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:

Navigate to Audience > Latest Sessions in our Dashboard.
Select a session that includes ads.
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.

Ad Quartile Tracking / Abandonment

Bitmovin Analytics also supports the tracking of Ad Engagement/Abandonment through additional signalling of the played Ad Quartiles to the collector.

This is a premium feature associated with additional cost and not part of our default analytics plan
If you are interested in purchasing Engagement Tracking please reach out to your Account Manager.

Client Side Integration

Ad Quartiles have to be signalled using the adQuartileFinished collector API available on all collector platforms.
As indicated in the diagram above it's meant to be called whenever a quartile event has passed.

adQuartileFinished takes the name of the quartile (first|midpoint|third|completed) as it's first parameter and optionally adQuartileMetadata.

adQuartileMetadata currently contains only the failedBeaconUrl string which should be set if a quartile signalling beacon failed to load and can then be used for debugging failed beacon URLs.

Once the adQuartileFinished() API is integrated you also have to enable sending of Ad Engagement Metrics via the Analytics Configuration by setting the configuration flag ssaiEngagementTrackingEnabled to true.

Important: If a viewer joins during an Ad is already playing you should not call the adQuartileFinished methods as that will skew the abandonment metrics. If a viewer joins during an ad that ad should not be tracked.