Contact support
    • Serverside.ai
    • Video player and app

    VAST tracking: Live - DASH

    Table of Contents

    Overview DASH live stream request flow with client-side VAST tracking DASH live playback and VAST tracking integration 1. Manifest API request. GET request Response body VAST loading 2. Player call with mediaURL. HTML JavaScript 3. Load VAST data. GET request Response body 4. Detect the start of an ad in the stream. JavaScript - Shaka Player 5. Keep track of the ad playback and send beacons. Javascript - Shaka Player Example implementation

    Overview

    This document provides an overview of client-side VAST tracking for Serverside.ai DASH live streams. It explains how to fetch VAST data, track ad playback events, and integrate with the player timeline. The instructions cover both DASH event timeline events and standard HTML5 video element events for comprehensive tracking.

    DASH live stream request flow with client-side VAST tracking

    The process for requesting a Serverside.ai DASH live stream with client-side tracking can be divided into the following steps:

    1. The app sends a request to the Serverside.ai endpoint for a channel and retrieves the URLs for the DASH manifest (mediaURL) and VAST data (vastURL).
    2. The mediaURL initializes the player and starts playback. 
    3. In parallel, the app can request the vastURL to load the current VAST information for the live channel.
    4. While the player continuously loads sub-manifests and media chunks, the app initializes VAST handling and waits for the player to reach an ad.
    5. When an ad signaled in the VAST tag starts playback, the app compares the player timeline or timeline-region-enter events and sends requests to all tracking URLs (beacons) defined in the VAST response for the start event. The same logic applies to the events: pause, resume, finish, firstQuartile, midpoint, thirdQuartile, and complete.

    The following diagram shows client-side VAST tracking integration with Serverside.ai for DASH live streams using Shaka Player:

    DASH live playback and VAST tracking integration

    The following steps cover the end-to-end process of integrating VAST ad tracking with DASH live playback using Serverside.ai.

    1. Manifest API request.

    The initial request to retrieve a DASH manifest and VAST tracking information creates a DASH live session for the requesting client. The URL for the ad-insertion–enabled channel, called outputUrl, can be viewed in Serverside.ai or via the API endpoint: https://mydomain.com/api/v2/channels/:channelId.

    GET request

    https://mydomain.com/dash/view/:channelId?api-key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
     
     

    Response body

    {
    "mediaURL": "https://mydomain.com/dash/:channelId/sessionId.mpd",
    "vastURL": "https://mydomain.com/dash/:channelId/sessionId/vast"
}
     
     

    VAST loading

    Before calling the vastUrl, you must provide the adId, which can be found in the response from the mediaURL.

    The full URL schema is:

    https://mydomain.com/dash/:channelId/:sessionId/vast/:adId.xml

    2. Player call with mediaURL.

    This example shows how to play back a Serverside.ai DASH live stream in a browser. For other players or environments, load and initialize the player of your choice, then pass it the mediaURL, and start playback.

    HTML

    <!DOCTYPE html>
<html>
  <head>
    <title>Test Player</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/shaka-player/2.5.6/shaka-player.compiled.js"></script>
  </head>
  <body>
    <h1>Serverside.ai Test</h1>
    <video id="video" controls autoplay></video>
  </body>
</html>
     
     

    JavaScript

    (async () => {
  const response = await fetch('https://mydomain.com/dash/view/:channelId?api-key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
  const {mediaURL, vastURL} = await response.json()
  const video = document.getElementById("video");
  const player = new shaka.Player(video);
  player.load(mediaURL);
})()
     
     

    3. Load VAST data.

    To retrieve VAST-related data, call the vastURL obtained in Step 1. 

    Construct the URL as follows: ${vastURL}/${adId}.xml.

    GET request

    https://mydomain.com/dash/:channelId/:sessionId/vast/:adId.xml
     
     

    Response body

    <Period>
  ...    
  <EventStream schemeIdUri="urn:ssai:vast:event:2020" timescale="1000">
    <Event id="0" presentationTime="0" duration="5000">vast:a2363da8-2331-4483-995d-5286220005d8</Event>
    <Event id="1" presentationTime="500">beacon:start</Event>
    <Event id="2" presentationTime="1250">beacon:firstQuartile</Event>
    <Event id="3" presentationTime="2500">beacon:midpoint</Event>
    <Event id="4" presentationTime="3750">beacon:thirdQuartile</Event>
    <Event id="5" presentationTime="4500">beacon:complete</Event>
  </EventStream>
  ...
</Period>
     
     

    Each period in the DASH manifest that represents an inserted ad clip includes an event stream for VAST tracking.

    The first event, id=vast:adId, identifies the VAST response for the clip, including all tracking event information. This response can be retrieved from the SSAI API using the vastURL provided in the initial session response. Subsequent events, such as id=beacon:start, trigger VAST quartile reporting at the corresponding points in the clip’s playback timeline.

    Each time a new ad appears in the DASH manifest, which is continuously pulled by the player, the app must load the VAST information for that ad.

    4. Detect the start of an ad in the stream.

    When an ad is detected in the DASH stream, fetch the VAST information for that ad from the URL: ${vastBaseUrl}/${adId}.xml.

    Access to timeline events depends on the player you are using.

     

    JavaScript - Shaka Player

    // If a new timeline-region (or segment) is added load the related VAST data
player.addEventListener("timelineregionadded", evt => {
  
  // evt.detail.id is e.g. vast:f295a0cc-9d2b-4014-9858-87fb28fc6ec1
  const [type, id] = evt.detail.id.split(":");

  if (type === "vast") {
    const response = await fetch(`${this.vastBaseUrl}/${id}.xml`)
    const vastXML = await response.text()
    const vast = document.createElement("div");
    // remove xml document declaration as required by xhtml
    vast.innerHTML = vastXml.substr(vastXml.indexOf("?>") + 2);
    // work with the vast response
    // ...
  }
})
     
     

    5. Keep track of the ad playback and send beacons.

    Once the VAST information for an upcoming ad is loaded, the client must monitor the player for predefined timeline positions and trigger the corresponding events.

    This example handles only the start of an ad. You also need to implement handling for pause, resume, finish, firstQuartile, midpoint, thirdQuartile, and complete events. For a complete DASH VAST tracking setup, see Example implementation.

    Javascript - Shaka Player

    // start of dash event
player.addEventListener("timelineregionenter", evt => {
    const [type, arg] = evt.detail.id.split(":")

    // 'id' and 'vast' from the request at 4 above
    // fire the impression or beacon
    if(type === 'vast) fire('Impression', vast)
    if(type === 'beacon) fire(`Tracking[event='${arg}']`, vast)
});

function fire(selector, vast) {
  $(vast) // this requires jQuery
    .find(selector)
    .each((n, elem) => {
      const url = elem.firstChild.textContent.replace(/\[/g, "").replace(/\]/g, "").replace(/CDATA/g, "")
      fetch(url, { mode: "no-cors" }).catch(err =>
        // Error handling
      );
    });
}
     
     

    Example implementation

    This example implementation handles impression and progress (beacon) events based on the DASH event timeline. It also tracks the following events using HTML5 video element events:

    • mute and unmute
    • pause
    • resume
    • expand and collapse

    https://static.helpjuice.com/helpjuice_production/uploads/upload/image/16110/direct/1755080547161/dash-live_v2.zip

    RELATED ARTICLES