Handle live client ad tracking

When client ad tracking is enabled, the player is responsible for triggering ad tracking events. Ad metadata provided by the Video Stitcher API includes ad tracking and companion ads information. The Video Stitcher API parses this information from the ad tag response.

Before you begin

Make sure you are familiar with the steps to create a live session using the Video Stitcher API. For more information, see the how-to guide.

Get the HLS ad metadata URI from manifest

In an HLS rendition manifest, an AdMetadataURI is encoded in attribute X-VAST-META of tag #EXT-X-DATERANGE. The #EXT-X-DATERANGE tag can be found before the first stitched segment of each ad.

The following is an example HLS timed metadata tag:

#EXT-X-DATERANGE:ID="id123",START-DATE=2014-03-05T11:15:00Z,DURATION=15,X-VAST-META="eyJBZE1ldGFkYXRhVXJpIjogImh0dHBzOi8vZXhhbXBsZS5jb20vdjFhbHBoYS9wcm9qZWN0cy8xMjMvbG9jYXRpb25zL3VzLWNlbnRyYWwxL2xpdmVTZXNzaW9ucy9hYmMzMjEvYWRNZXRhZGF0YS9pZDEyMyJ9"

The value of an X-VAST-META attribute is a base64-encoded JSON string. After decoding, you could extract the AdMetadataURI from the JSON.

The following example shows the decoded X-VAST-META:

{
  "AdMetadataUri": "https://example.com/v1/projects/123/locations/us-central1/liveSessions/abc321/adMetadata/id123"
}

Get the DASH ad metadata URI from the manifest

In a DASH manifest, each stitched ad period contains one VAST ad, and its ad metadata URI can be extracted from within the EventStream tag. AdMetadataURI is encoded in attribute messageData of the Event element. Event is an element inside tag EventStream with a schemeIdUri of urn:videostitcher:admetadata:202008.

The following is an example DASH event stream tag:

<EventStream schemeIdUri="urn:videostitcher:admetadata:202008" timescale="1000">
  <Event duration="5000" messageData="eyJBZE1ldGFkYXRhVXJpIjogImh0dHBzOi8vZXhhbXBsZS5jb20vdjFhbHBoYS9wcm9qZWN0cy8xMjMvbG9jYXRpb25zL3VzLWNlbnRyYWwxL2xpdmVTZXNzaW9ucy9hYmMzMjEvYWRNZXRhZGF0YS9pZDEyMyJ9"></Event>
</EventStream>

Use base64 to decode the messageData to JSON.

The following example shows the decoded messageData:

{
  "AdMetadataUri": "https://example.com/v1/projects/123/locations/us-central1/liveSessions/abc321/adMetadata/id123"
}

Retrieving and processing ad tracking events

After you get AdMetadataURI, you can fetch ad metadata.

The following example shows the ad metadata:

{
  "activityEvents": [
    {
      "type": "PAUSE",
      "uri": "https://example.com/pause"
    }
  ],
  "progressiveEvents": [
    {
      "timeOffset": "0s",
      "events": [
        {
          "type": "IMPRESSION",
          "uri": "https://example.com/impression"
        },
        {
          "type": "START",
          "uri": "https://example.com/start"
        }
      ]
    },
    {
      "timeOffset": "2.500s",
      "events": [
        {
          "type": "FIRST_QUARTILE",
          "uri": "https://example.com/firstquartile"
        }
      ]
    }
  ],
  "adDuration": "10s"
}

In the preceding example, the client should do the following:

• Request https://example.com/start at the start of the ad video.
• Request https://example.com/impression at the start of the ad video.
• Request https://example.com/pause whenever the viewer pauses the ad video.
• Request https://example.com/firstQuartile 2.5 seconds into the ad video.