🚧

This API is currently in beta and is subject to changes

As with any API, the SessionTracking API can be modified over time, including through addition or removal of parameters in the payloads, or changes to property names or values.

API

The API has a single endpoint for retrieving metadata about a session, including ad metadata.

It returns a JSON payload, whose schema is defined at this link

Versions

To retrieve this tracking file, the client application appends a specific query parameter bk-ml to the regular manifest request URL.

There are two possible values for this query parameter, which trigger different workflows with slightly different behaviors.

• Fast-start workflow: bk-ml=1.0
  In this workflow, the first session tracking call is made after the streaming session has started and the first manifest (or variant playlist in HLS) has already been served to the player.
  If the session tracking API is called earlier, the response will not contain any ads, even if ads are inserted at the next manifest request.
• Metadata-first workflow: bk-ml=2.0
  In this workflow, the session tracking call is made first, before the first request to the manifest. This ensures that broadpeak.io immediately initiates the session and triggers the call to the ad server, even before a manifest is requested.
  This workflow is useful in scenarios where ad information is needed before the player starts streaming. For example, this may be required for implementing anti-ad-skipping features, particularly for streams with pre-rolls. It is also necessary when a user is allowed to resume at a specific point in a stream, as the actual resume position might depend on the ads inserted in the new session.
  Note, however, that this workflow may increase the startup time.

The choice of workflow primarily affects the first response returned to the player. However, all subsequent calls for the same session (in a live stream) must continue using the same value.

Usage

The client application must make session tracking calls:

• At the start of the session, either before or after the first manifest call, depending on the workflow used (as controlled by the value of bk-ml).
• On a regular basis thereafter for live services. The suggested refresh frequency is provided in the API response (refresh_delay_ms), but you could also decide to synchronise it with the player’s manifest refreshes.

At the start of the session, the call can only be made after the initial service URL has been resolved. This steps generates the session ID (bpkio_sessionid query parameter) and returns an HTTP 307 redirection.

The following diagrams illustrate a typical flow of data at the start of the session. They are extensions on the diagrams presented in Session management.

• Fast-start workflow
  

• Metadata-first workflow
  

💡

Note that in the metadata-first workflow, you can also make the session tracking call (2) and the first manifest call (3) at the same time. You should however wait until you get the response from the session tracking call (and can process that data) before initiating playback.

Session tracking calls must always include the service ID (bpkio_serviceid) and session ID (bpkio_sessionid) query parameters, along with any other required parameters for the ad server (particularly in the metadata-first workflow). For simplicity, it is recommended to just append the bk-ml query parameter to the manifest URL that the player calls.

❗️

CDN routing

Remember that the bk-ml parameter, just like the other parameters must be forwarded to broadpeak.io through the CDN. You may need to alter your routing rules accordingly - see Ad insertion with a CDN for details

Ad Metadata

Ad pod

Ad metadata is represented in the top-level adpods field. Each adpod object corresponds to:

• VOD: An ad break defined in the VMAP response from the ad server.
• Live Pre-roll: A group of pre-roll ads displayed before the live content begins.
• Live Ad Replacement: An ad break (eg. identified through SCTE35 markers)
• Virtual Channel: ad break slots scheduled with the API

Within each adpod, the ads array contains the list of ads that were inserted in that ad break.

This structure ensures consistent representation of ads across different contexts, whether they are part of on-demand content, live events, or virtual channels.

Ad

Each ad contains information extracted from the VAST response sent by the ad server, with among others:

• The list of tracking beacons: impression, quartiles, complete...
• Specific details for client-side interactions, such as video clicks.
• Skippability status and skip timing.
• Ad verifications.

Timing

Timestamps and durations in the response, particularly within adpods and ads, are provided in milliseconds and refer to the stream time:

• VOD: Times are relative to the start of the stream (0 ms).
• Live: Times are based on the date and time of the original live stream’s clock.

These timestamps can be compared to the player’s playhead time (usually accessible via player APIs) to determine ad positions within the stream. For VOD, playhead time typically corresponds directly to stream time. For Live content, the playhead time must account for the live stream’s offset relative to the original clock.

This information is used to trigger tracking events and create user experiences, such as:

• ad markers in the playback timeline.
• custom overlays indicating progress within ad breaks,
• enforcement of ad-related business rules (e.g., preventing or facilitating ad skipping).

Coverage

AVOD

For AVOD services, the response covers the entire stream, with an adpod for each ad break. Thus, the call only needs to be made once (in the same way as the request to the manifest is only made once).

Live

For Live streams, the response contains an adpod for each ad break present in the current manifest, whether partial or complete, including for the whole of the DVR WINDOW.

Information about the last ad break remains in the response for a few seconds after any segment corresponding to the ad break disappears from the manifest.

For an ad break at the LIVE EDGE, information is added gradually as the manipulation engine inserts ads:

• Any new ad added will be complete (with all trackers and duration), even if only some of its segments have been served in the manifest.
• The duration of the adpod itself reflects the total duration of the ads inserted up to that point. This duration increases incrementally in subsequent responses. It reflects the total duration of the ad break only after the last ad has been inserted.