Show Menu

Overview of non-TVSDK client-side tracking

Publishers can build HLS-compliant video players that work with the Primetime manifest server client-side ad tracking workflows. The interfaces to the manifest server for the live stream and video on demand (VOD) cases are slightly different.
The manifest server provides an API to enable custom players to request the following URLs, which they can use to report ad tracking events:
  • Ad impression
  • Ad quartile
  • Ad pod progress
  • Content pod progress
The manifest server API assumes that any video player using it meets the minimum requirements. See Video Player Requirements for more details.

Client-side tracking workflow

  1. Player obtains a manifest server URL from the publisher.
  2. Player appends query parameters specific to its ad insertion requirements and sends an HTTP GET request to the resulting Bootstrap URL. The Bootstrap URL has the following syntax:
    http{s}://{manifest-server:port}/auditude/variant/{PublisherAssetID}/{urlSafeBase64({Content URL})}.m3u8?{query parameters}
    For example:
    The URL includes the elements described in Send a command to the Manifest Server .
  3. The manifest server establishes a session for that player and generates a unique session ID. It creates a new variant M3U8 playlist URL, which it returns to the player as a JSON response. The JSON has the following syntax:
     "Master-M3U8": "https://{manifest-server:port}/auditude/variant/{PublisherAssetID}/{SessionID}/
        {urlSafeBase64(content URL)}.m3u8?u={Asset ID}&z={Zone ID}&pttrackingmode=simple&pttrackingversion=v2
        &{Any other query parameters}"
    For example:
  4. Player uses the URL from the JSON response to request the new variant M3U8 master playlist from the manifest server .
  5. The manifest server returns a new variant M3U8 containing stream-level playlist URLs with a syntax similar to the following:
      {rendition}/{groupID}/{urlSafeBase64(bit rate stream URL)}.m3u8?u={Ad Request Id}&z={Ad Zone Id}&{Any other query parameters}
    For example:
  6. The player selects the appropriate single bit rate, stream-level manifest URL for playing the ad-stitched content. For example:
  7. The manifest server returns a stream-level manifest containing links to the content and ad TS segment links. For example:
    The player selects the stream-level playlist URL to obtain the content stream. The manifest server retrieves the original playlist from the CDN. Some encoders may inject additional details into the #EXTINF title attribute, for example:
    Since the manifest server cannot infer the meaning of non-standard attributes to modify them for ad-stitched playlist, the manifest server removes all additional attributes beyond the duration information in this tag. See the EXTINF entry in the HLS spec for more details.
  8. To request tracking information, the player appends the query parameter pttrackingposition with any alphanumeric value to the stream-level playlist URL for the selected bit rate. For example:
  9. The manifest server returns the playlist file populated with either a JSON or VMAP object containing the ad tracking data for the stream-level m3u8 file currently requested.
    The manifest server will only generate ad tracking objects if ads were inserted in the currently requested stream-level playlist. If player is playing a playlist that does not contain inserted ads, the manifest server returns an HTTP Status 201 for the ad tracking playlist request. If the player makes the ad tracking request for a stream it is not playing, manifest server will return an HTTP Status 500. For example, if the current play request is for 500.m3u8, the manifest server returns a JSON|VMAP in the 500.m3u8 for the ad tracking request. However, if the player subsequently switches streams to play the 800.m3u8, the ad tracking information in the 500.m3u8 becomes invalid, leading to a 404 error.
    The manifest server generates the ad tracking object based on the pttrackingversion value in the Bootstrap URL. If the pttrackingversion is omitted or has an invalid value, then the manifest server will automatically populate the ad tracking information in the #EXT-X-MARKER tags in each requested stream-level playlist. See for more details .
  10. The player requests each ad tracking URL for each ad tracking event at the appropriate time.
For Live streams, the player must repeat steps 6 through 10 as the packager constantly updates the playlist throughout the duration of the live event.
As the video plays, the player must track the playhead position and use this position in conjunction with tracking URLs it received from Primetime ad insertion. The tracking URLs are grouped by time offset from the beginning of play. For each time offset, there is a URL for each ad system to which to send tracking information. Additional details of the format differ between live video and video on demand.