Client-side ad-tracking schema and properties

With the MediaTailor client-side ad-tracking feature, you can integrate detailed client-side ad tracking data into your player environment. The following sections cover the overall ad-tracking schema, as well as the specific properties and values that make up the schema.

Schema

The following JSON structure shows the MediaTailor client-side ad-tracking schema. This representation illustrates the nesting structure of the schema to help you understand the relationships between different parts.

For detailed information about each property, see Properties.


{
  "avails": [
    {
      "ads": [
        {
          "adID": "string",
          "adParameters": "string",
          "adSystem": "string",
          "adTitle": "string",
          "adVerifications": [
            {
              "executableResource": [
                {
                  "apiFramework": "string",
                  "type": "string",
                  "uri": "string",
                  "language": "string"
                }
              ],
              "javaScriptResource": [
                {
                  "apiFramework": "string",
                  "browserOptional": "string",
                  "uri": "string"
                }
              ],
              "trackingEvents": [
                {
                  "event": "string",
                  "uri": "string"
                }
              ],
              "vendor": "string",
              "verificationParameters": "string"
            }
          ],
          "companionAds": [
            {
              "adParameters": "string",
              "altText": "string",
              "attributes": {
                "adSlotId": "string",
                "apiFramework": "string",
                "assetHeight": "string",
                "assetWidth": "string",
                "expandedHeight": "string",
                "expandedWidth": "string",
                "height": "string",
                "id": "string",
                "pxratio": "string",
                "renderingMode": "string",
                "width": "string"
              },
              "companionClickThrough": "string",
              "companionClickTracking": "string",
              "htmlResource": "string",
              "iFrameResource": "string",
              "sequence": "string",
              "staticResource": "string",
              "trackingEvents": [
                {
                  "event": "string",
                  "uri": "string"
                }
              ]
            }
          ],
          "creativeId": "string",
          "creativeSequence": "string",
          "duration": "string",
          "durationInSeconds": number,
          "extensions": [
            {
              "type": "string",
              "content": "string"
            }
          ],
          "icons": [
            {
              "attributes": {
                "apiFramework": "string",
                "duration": "string",
                "height": "string",
                "offset": "string",
                "program": "string",
                "pxratio": "string",
                "width": "string",
                "xPosition": "string",
                "yPosition": "string"
              },
              "htmlResource": "string",
              "iconClicks": {
                "iconClickThrough": "string",
                "iconClickTracking": {
                  "id": "string"
                },
                "iconClickFallbackImages": [
                  {
                    "altText": "string",
                    "height": "string",
                    "width": "string",
                    "staticResource": {
                      "creativeType": "string",
                      "uri": "string"
                    }
                  }
                ]
              },
              "iconViewTracking": "string",
              "iFrameResource": "string",
              "staticResource": {
                "creativeType": "string",
                "uri": "string"
              }
            }
          ],
          "mediaFiles": {
            "adParameters": "string",
            "duration": "string",
            "durationInSeconds": number,
            "mediaFilesList": [
              {
                "apiFramework": "string",
                "delivery": "string",
                "height": "string",
                "maintainAspectRatio": "string",
                "mediaFileUri": "string",
                "mediaType": "string",
                "scalable": "string",
                "width": "string",
                "bitrate": "string"
              }
            ],
            "mezzanine": "string",
            "startTime": "string",
            "startTimeInSeconds": number,
            "trackingEvents": [
              {
                "beaconUrls": ["string"],
                "duration": "string",
                "durationInSeconds": number,
                "dateTime": "string",
                "eventId": "string",
                "eventType": "string",
                "startTime": "string",
                "startTimeInSeconds": number
              }
            ]
          },
          "startTime": "string",
          "startTimeInSeconds": number,
          "dateTime": "string",
          "adBreakTrackingEvents": [...],
          "vastAdId": "string"
        }
      ],
      "adType": "string",
      "availID": "string",
      "duration": "string",
      "durationInSeconds": number,
      "startTime": "string",
      "startTimeInSeconds": number,
      "dateTime": "string",
      "adMarkerDuration": "string",
      "adProgramDateTime": "string",
      "dashAvailabilityStartTime": "string",
      "hlsAnchorMediaSequenceNumber": "string"
    }
  ],
  "nonLinearAvails": [
    {
      "nonLinearAds": [...],
      "nonLinearAdsList": [...]
    }
  ],
  "nextToken": "string",
  "meta": {}
}

Properties

The following table lists the properties in the client-side tracking API, their definitions, value types, and examples.

Property	Definition	Value type	Example
`adID`	HLS - the sequence number associated with the beginning of the ad DASH - the period ID of the ad Path: `/avails/ads/adId` VAST mapping: None	String	`10`
`adBreakTrackingEvents`	An array that carries VMAP tracking events from the VAST response. For more information, see section 2.3.3 of the VMAP 1.0 specification. Path: `/avails/ads/adBreakTrackingEvents`	Array	`[]`
`adMarkerDuration`	The avail duration observed from the ad marker in the manifest.	String	`30`
`adParameters`	A string of ad parameters, from the VAST VPAID, that MediaTailor passes to the player. Path: `/avails/ads/adParameters` VAST mapping: `VAST/Ad/InLine/Creatives/Creative/Linear/AdParameters`	String
`adProgramDateTime`	HLS - the date, in ISO/IEC 8601:2004 format, that represents the first media sequence of the ad. DASH - [Not specified]	String
`ads`	An array containing the ad objects that make up the avail. The ads are listed in the order they appear in the manifest. Path: `/avails/ads`	Array	`[]`
`adSystem`	The name of the system that serves the ad. Important Make sure to provide a value. If you don't provide a value, issues can arise.	String	`myADS`
`adTitle`	The title of the ad.	String	`ad1`
`adVerifications`	Contains the resources and metadata required to execute third-party measurement code in order to verify creative playback. For more information about this property, see section 3.16 of the VAST 4.2 specification. MediaTailor supports `adVerifications` as VAST 3 extension nodes. Path: `/avails/ads/adVerifications` VAST mapping: `VAST/Ad/InLine/AdVerifications`	Array	`[]`
`altText`	The alternative text for an image of a companion ad. This text enables players with descriptive-audio support for the visually impaired to read back a description of the image. Path: `/avails/ads/companionAds/altText`	String	`video sequence advertising sneakers`
`apiFramework`	Set to `VPAID` to tell the player that this ad is a VPAID ad. Can appear in multiple locations in the schema.	String	`VPAID`
`availID`	HLS - the sequence number associated with the start of the ad avail. DASH - the period ID of the ad avail, which is usually the period ID of the content that is to be replaced with an ad. Path: `/avails/availID`	String	`34` `PT34S_1`
`avails`	An array containing ad-break objects, or avails, that are presented in the active manifest window. The avails are listed in the order they appear in the manifest. Path: `/avails`	Array	`[]`
`adType`	The type of the ad. Path: `/avails/adType` and `/avails/ads/adType`	String
`dateTime`	Program date time, in ISO 8601 seconds format, for the start of the ad avail or ad. Path: `/avails/dateTime` and `/avails/ads/dateTime`	String
`duration`	Length, in ISO 8601 seconds format. The response includes durations for the entire ad avail and for each ad and beacon, though beacon durations are always zero. Path: `/avails/duration` and `/avails/ads/duration`	String	`15.015`
`durationInSeconds`	Length, in seconds format. Path: `/avails/durationInSeconds` and `/avails/ads/durationInSeconds`	Number
`extensions`	Custom extensions of VAST that ad servers use. For more information about extensions, see section 3.18 of the VAST 4.2 specification. Path: `/avails/ads/extensions` VAST mapping: `VAST/Ad/InLine/Extensions`	Array	`[]`
`icons`	Icon elements for the ad. Path: `/avails/ads/icons` VAST mapping: `VAST/Ad/InLine/Creatives/Creative/Linear/Icons`	Array
`mediaFiles`	Video and other assets that the player needs for the ad avail. Path: `/avails/ads/mediaFiles`	Object
`nonLinearAvails`	Array of non-linear ad avail objects. Path: `/nonLinearAvails`	Array
`executableResource`	Executable resources for verification. Path: `/avails/ads/adVerifications/executableResource` VAST mapping: `VAST/Ad/InLine/AdVerifications/Verification/ExecutableResource`	Array
`javaScriptResource`	JavaScript resources for verification. Path: `/avails/ads/adVerifications/javaScriptResource` VAST mapping: `VAST/Ad/InLine/AdVerifications/Verification/JavaScriptResource`	Array
`trackingEvents`	Tracking events for verification or companion ads. Path: `/avails/ads/adVerifications/trackingEvents` or `/avails/ads/companionAds/trackingEvents`	Array
`vendor`	Verification vendor. Path: `/avails/ads/adVerifications/vendor` VAST mapping: `VAST/Ad/InLine/AdVerifications/Verification/@vendor`	String
`uri`	URI that points to either an executable asset, a video asset, or a tracking endpoint. Path: Various locations in the schema VAST mapping: Various CDATA elements in VAST	String	`https://tracking.example.com/impression`
`verificationParameters`	Verification parameters. Path: `/avails/ads/adVerifications/verificationParameters` VAST mapping: `VAST/Ad/InLine/AdVerifications/Verification/VerificationParameters`	String
`attributes`	Companion ad attributes like dimensions and rendering mode. Path: `/avails/ads/companionAds/attributes`	Object
`companionClickThrough`	A URL to the advertiser's page that the media player opens when the viewer clicks the companion ad. Path: `/avails/ads/companionAds/companionClickThrough` VAST mapping: `VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/CompanionClickThrough`	String	`https://aws.amazon.com/`
`companionClickTracking`	The tracking URL for the `companionClickThrough` property. Path: `/avails/ads/companionAds/companionClickTracking` VAST mapping: `VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/CompanionClickTracking`	String	`https://myads.com/beaconing/event=clicktracking`
`htmlResource`	The CDATA-encoded HTML that's inserted directly within the streaming provider's HTML page. Path: `/avails/ads/companionAds/htmlResource` VAST mapping: `VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/HTMLResource`	String	`<![CDATA[<!doctype html><html><head><meta name=\"viewport\" content=\"width=1, initial-scale=1.0, minimum-scale=1.0,...]]>`
`iFrameResource`	The URL to an HTML resource file that the streaming provider loads into an iframe. Path: `/avails/ads/companionAds/iFrameResource` VAST mapping: `VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/iFrameResource`	String
`sequence`	The sequence value specified for the creative in the VAST response. Path: `/avails/ads/companionAds/sequence`	String	`1`
`startTime`	The time position, in ISO 8601 seconds format. For HLS, this is relative to the beginning of the playback session. For DASH, this is relative to the manifest's AST (Availability Start Time). The response includes start times for the entire ad avail and for each ad and beacon. Path: `/avails/startTime` and `/avails/ads/startTime`	String	`PT18.581355S`
`startTimeInSeconds`	The time position, in seconds format. For HLS, this is relative to the beginning of the playback session. For DASH, this is relative to the manifest's AST (Availability Start Time). The response includes start times for the entire ad avail and for each ad and beacon. Path: `/avails/startTimeInSeconds` and `/avails/ads/startTimeInSeconds`	Number	`18.581`
`eventId`	HLS - the sequence number associated with the beacon. DASH - the `ptsTime` of the start of the ad.	String
`event`	The name of the tracking event. Path: `/avails/ads/adVerifications/trackingEvents/event` or `/avails/ads/companionAds/trackingEvents/event`	String	`impression`, `start`, `firstQuartile`, `midpoint`, `thirdQuartile`, `complete`
`beaconUrls`	The URL where MediaTailor sends the ad beacon. Path: `/avails/ads/mediaFiles/trackingEvents/beaconUrls`	Array
`bitrate`	The bitrate of the video asset. This property is not typically included for an executable asset.	String	`2048`
`companionAds`	One or more companion ad-content specifications, each of which specifies a resource file to use. Companion ads accompany the ad avail and provide content, like a frame around the ad or a banner, to display near the video. Path: `/avails/ads/companionAds`	Array	`[]`
`creativeId`	The `Id` attribute value of the `Creative` tag for the ad.	String	`creative-1`
`creativeSequence`	The sequence in which an ad should play, according to the `Ad@id` value in the VAST response.	String	`1`
`dashAvailabilityStartTime`	For live/dynamic DASH, the `MPD@availabilityStartTime` of the origin manifest.	String	`2022-10-05T19:38:39.263Z`
`delivery`	Indicates whether a `progressive` or `streaming` protocol is being used.	String	`progressive`
`eventType`	The type of beacon. Path: `/avails/ads/mediaFiles/trackingEvents/eventType`	String	`impression`
`height`	The height, in pixels, of the video asset.	String	`360`
`hlsAnchorMediaSequenceNumber`	The media-sequence number of the first/oldest media sequence seen in the HLS origin manifest.	String	`77`
`maintainAspectRatio`	Indicates whether to maintain the video's aspect ratio while scaling.	Boolean	`true`
`mediaFilesList`	Specifies the video and other assets that the player needs for the ad avail. Path: `/avails/ads/mediaFiles/mediaFilesList`	Array	`[]`
`mediaFileUri`	URI that points to either an executable asset or a video asset.	String	`https://myad.com/ad/ad134/vpaid.js`
`mediaType`	The MIME type of the creative or companion asset.	String	`video/mp4`
`meta`	Additional metadata for the ad.	Object
`mezzanine`	The URL of the mezzanine MP4 asset, specified if the VPAID ad includes one. Path: `/avails/ads/mediaFiles/mezzanine`	String	`https://gcdn.2mdn.net/videoplayback/id/itag/ck2/file/file.mp4`
`nextToken`	The value of the token that points to the next page of results, when such a value exists.	String	`UFQzOS44NzNTXzIwMjMtMDctMzFUMTY6NTA6MDYuMzUwNjI2ODQ1Wl8x`
`nonLinearAds`	Non-linear ads that appear alongside the video content.	Array	`[]`
`nonLinearAdsList`	List of non-linear ads.	Array	`[]`
`scalable`	Indicates whether to scale the video to other dimensions.	Boolean	`true`
`skipOffset`	The time value that identifies when the player makes skip controls available to the user.	String	`00:00:05`
`staticResource`	The URL to a static creative file that's used for the ad component. Path: `/avails/ads/companionAds/staticResource`	String	`https://very-interactive-ads.com/campaign1/file.json?c=1019113602`
`vastAdId`	The `Id` attribute value of the `Ad` tag.	String	`ad1`
`width`	The width, in pixels, of the video asset.	String	`640`
`xPosition`	The horizontal position of an icon within the video player. Can be a specific pixel value or a position like "left" or "right". Path: `/avails/ads/icons/attributes/xPosition`	String	`left` or `10`
`yPosition`	The vertical position of an icon within the video player. Can be a specific pixel value or a position like "top" or "bottom". Path: `/avails/ads/icons/attributes/yPosition`	String	`top` or `10`
`iconClicks`	Contains click-through and tracking information for an icon. Path: `/avails/ads/icons/iconClicks`	Object
`iconClickThrough`	A URL to the advertiser's page that the media player opens when the viewer clicks the icon. Path: `/avails/ads/icons/iconClicks/iconClickThrough`	String	`https://advertiser.com/landing-page`
`iconClickTracking`	The tracking URL for the `iconClickThrough` property. Path: `/avails/ads/icons/iconClicks/iconClickTracking`	Object
`iconClickFallbackImages`	An array of fallback images to display if the icon cannot be displayed. Path: `/avails/ads/icons/iconClicks/iconClickFallbackImages`	Array
`iconViewTracking`	The URL for tracking when an icon is viewed. Path: `/avails/ads/icons/iconViewTracking`	String	`https://tracking.example.com/icon-view`
`offset`	The time offset for when an icon should appear during ad playback. Path: `/avails/ads/icons/attributes/offset`	String	`00:00:05`
`program`	The program or initiative associated with the icon, such as "AdChoices". Path: `/avails/ads/icons/attributes/program`	String	`AdChoices`
`pxratio`	The pixel ratio for the icon or companion ad, used for high-DPI displays. Path: `/avails/ads/icons/attributes/pxratio` or `/avails/ads/companionAds/attributes/pxratio`	String	`1` or `2`
`type`	The type of resource or extension. Path: `/avails/ads/extensions/type` or `/avails/ads/adVerifications/executableResource/type`	String	`text/javascript`
`content`	The content of an extension. Path: `/avails/ads/extensions/content`	String
`language`	The programming language of an executable resource. Path: `/avails/ads/adVerifications/executableResource/language`	String	`javascript`
`browserOptional`	Indicates whether browser support is required for the JavaScript resource. Path: `/avails/ads/adVerifications/javaScriptResource/browserOptional`	String	`true` or `false`
`id`	An identifier for various elements in the schema. Path: `/avails/ads/companionAds/attributes/id` or `/avails/ads/icons/iconClicks/iconClickTracking/id`	String	`companion-1`
`assetHeight`	The height of the companion ad asset. Path: `/avails/ads/companionAds/attributes/assetHeight`	String	`250`
`assetWidth`	The width of the companion ad asset. Path: `/avails/ads/companionAds/attributes/assetWidth`	String	`300`
`expandedHeight`	The height of the companion ad when expanded. Path: `/avails/ads/companionAds/attributes/expandedHeight`	String	`600`
`expandedWidth`	The width of the companion ad when expanded. Path: `/avails/ads/companionAds/attributes/expandedWidth`	String	`600`
`renderingMode`	The rendering mode for the companion ad. Path: `/avails/ads/companionAds/attributes/renderingMode`	String	`default` or `transparent`
`adSlotId`	The ID of the ad slot where the companion ad should be displayed. Path: `/avails/ads/companionAds/attributes/adSlotId`	String	`banner-1`
`creativeType`	The MIME type of the creative asset. Path: `/avails/ads/icons/staticResource/creativeType`	String	`image/png`

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Client-side tracking

Activity timing

Client-side ad-tracking schema and properties

Schema

Properties

Important