Client-side tracking - AWS Elemental MediaTailor
Enabling client-side trackingAd server parametersOrigin interaction query parametersSession-configured featuresBest practices for client-side tracking

Client-side tracking

Using the AWS Elemental MediaTailor client-side tracking API, you can incorporate player controls during ad breaks in streaming workflows. In client-side tracking, the player or client emits tracking events, such as impression and quartile ad beaconing, to the Ad Decision Server (ADS) and other ad-verification entities. For more information about impression and quartile ad beaconing, see Client-side beaconing. For more information about ADS and other ad-verification entities, see Client-side ad-tracking integrations.

Client-side tracking enables functionality like the following:

Using the MediaTailor client-side tracking API, you can send metadata to the playback device that enables functionality in addition to client-side tracking:

Topics

Enabling client-side tracking

You enable client-side tracking for each session. The player makes an HTTP POST to the MediaTailor configuration's session-initialization prefix endpoint. Optionally, the player can send additional metadata for MediaTailor to use when making ad calls, calling the origin for a manifest, and invoking or disabling MediaTailor features at the session level.

The following example shows the structure of the JSON metadata:

{
  "adsParams": {                  # 'adsParams' is case sensitive
    "param1": "value1",           # key is not case sensitive
    "param2": "value2",           # Values can contain spaces. For example, 'value 2' is an allowed value. 
    },
  "origin_access_token":"abc123", # this is an example of a query parameter designated for the origin
  "overlayAvails":"on"            # 'overlayAvails' is case sensitive. This is an example of a feature that is enabled at the session level.
}

Use the MediaTailor console or API to configure the ADS request template URL to reference these parameters. In the following example, player_params.param1 are the player parameters for param1, and player_params.param2 are the player parameters for param2.

https://my.ads.com/path?param1=[player_params.param1]&param2=[player_params.param2]

Ad server parameters

At the topmost level of the JSON structure is an adsParams JSON object. Inside this object are key/value pairs that MediaTailor can read and send to the ad server in all session requests. MediaTailor supports the following ad servers:

  • Google Ad Manager

  • SpringServe

  • FreeWheel

  • Publica

Origin interaction query parameters

Any reserved key/value pairs within the topmost level of the JSON structure, such as adParams, availSuppression, and overlayAvails, aren’t added to the origin request URL in the form of query parameters. Every session manifest request that MediaTailor makes to the origin contains these query parameters. The origin ignores extraneous query parameters. For example, MediaTailor can use the key/value pairs to send access tokens to the origin.

Session-configured features

Use the session-initialization JSON structure to enable, disable, or override MediaTailor features such as overlayAvails, availSuppression, and adSignaling. Any feature configurations passed during session initialization override the setting at the MediaTailor configuration level.

Note

The metadata submitted to MediaTailor at session initialization is immutable, and additional metadata cannot be added for the duration of the session. Use SCTE-35 markers to carry data that changes during the session. For more information, see Using session variables.

Example : Performing client-side ad tracking for HLS
POST mediatailorURL/v1/session/hashed-account-id/origin-id/asset-id.m3u8

        {
            "adsParams": {
               "deviceType": "ipad"   # This value does not change during the session.
               "uid": "abdgfdyei-2283004-ueu"                     
           }
        }
Example : Performing client-side ad tracking for DASH
POST mediatailorURL/v1/session/hashed-account-id/origin-id/asset-id.mpd

        {
            "adsParams": {
               "deviceType": "androidmobile",
               "uid": "xjhhddli-9189901-uic" 
           }
        }

A successful response is an HTTP 200 with a response body. The body contains a JSON object with a manifestUrl and a trackingUrl key. The values are relative URLs that the player can use for both playback and ad-event tracking purposes.

{
  "manifestUrl": "/v1/dashmaster/hashed-account-id/origin-id/asset-id.m3u8?aws.sessionId=session-id",
  "trackingUrl": "/v1/tracking/hashed-account-id/origin-id/session-id"
}

For more information on the client-side tracking schema, see Client-side ad-tracking schema.

Best practices for client-side tracking

This section outlines the best practices for client-side tracking in MediaTailor for both live and VOD workflows.

Live workflows

Poll the tracking endpoint at an interval matching every target duration for HLS, or minimum update period for DASH, in order to always have the most current ad-tracking metadata. Matching this interval is especially important in workflows where the creatives might have an interactive or overlay component.

Note

Some players support event listeners, which could be used as an alternative to polling. For example, the MediaTailor ad ID decoration feature would need to be enabled for each session. For more information, see Ad ID decoration. Using this feature puts a date range (HLS) or event element (DASH) identifier over each ad in the avail. Players can use these manifest tags as a prompt to call the MediaTailor tracking endpoint for the session.

VOD workflows

Following a successful session initialization, and after MediaTailor receives the first manifest containing media, you only need to call the tracking endpoint once.

Call flow for VOD workflows. Call the client-side tracking endpoint after the session initializes and MediaTailor receives the first manifest that contains media.