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.
Contents
Schema
The following table describes the MediaTailor client-side ad-tracking schema. Where applicable, the table maps the schema to VAST data.
| Key | Data type | Child keys | Mapping from VAST 2.0/3.0 | Mapping from VAST 4.0 | Description |
|---|---|---|---|---|---|
| Response JSON | |||||
| - | Object | avails, nonLinearAvails | |||
/avails
|
Array |
||||
| MediaTailor creates one object for each avail (ad break) inside the manifest window. | ads, adType, availID, duration, durationInSeconds, startTime, startTimeInSeconds, dateTime | ||||
/ads
|
Array | ||||
| MediaTailor creates one object for each ad inside the avail period. | Object | adID, adType, adParameters, adVerifications, companionAds, duration, durationInSeconds, extensions, icons, mediaFile, startTime, startTimeInSeconds, dateTime, adBreakTrackingEvents | |||
/adId
|
String |
|
|||
/adParameters
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/AdParameters
|
String of ad parameters from the VAST VPAID that MediaTailor passes to the player |
||
/adVerifications
|
Array |
VAST/Ad/InLine/AdVerifications
|
Contains the resources and metadata required to execute third-party measurement code in order to verify creative playback |
||
| MediaTailor creates an object for each ad-verification element. | Object | executableResource, javaScriptResource, vendor, verificationParameters | |||
/executableResource
|
Array |
VAST/Ad/InLine/AdVerifications/Verification/ExecutableResource
|
|||
MediaTailor creates an object for each executableResource
element. |
Object | apiFramework, adType, uri, language | |||
/apiFramework
|
String |
VAST/Ad/InLine/AdVerifications/Verification/ExecutableResource/@apiFramework
|
|||
/type
|
String | ||||
/uri
|
String |
VAST/Ad/InLine/AdVerifications/Verification/ExecutableResource/#CDATA
|
|||
/language
|
String |
VAST/Ad/InLine/AdVerifications/Verification/ExecutableResource/@language
|
VAST/Ad/InLine/AdVerifications/Verification/ExecutableResource/@language
|
||
/javaScriptResource
|
Array |
VAST/Ad/InLine/AdVerifications/Verification/JavaScriptResource
|
|||
MediaTailor creates an object for each javaScriptResource
element. |
Object | apiFramework, browserOptional, uri | |||
/apiFramework
|
String |
VAST/Ad/InLine/AdVerifications/Verification/JavaScriptResource/@apiFramework
|
|||
/browserOptional
|
String |
VAST/Ad/InLine/AdVerifications/Verification/JavaScriptResource/@browserOptional
|
|||
/uri
|
String |
VAST/Ad/InLine/AdVerifications/Verification/JavaScriptResource/#CDATA
|
|||
/trackingEvents
|
Array |
||||
| MediaTailor creates an object for each ad-verification element tracking-event type. | Object | event, uri | |||
/event
|
String |
VAST/Ad/InLine/AdVerifications/Verification/TrackingEvents/Tracking/@event
|
|||
/uri
|
String |
VAST/Ad/InLine/AdVerifications/Verification/TrackingEvents/Tracking/#CDATA
|
|||
/vendor
|
String |
VAST/Ad/InLine/AdVerifications/Verification/@vendor
|
|||
/verificationParameters
|
String |
VAST/Ad/InLine/AdVerifications/Verification/VerificationParameters
|
|||
/companionAds
|
Array |
Companion ads, which accompany the ad avail, provide content like a frame around the ad or a banner to display near the video. |
|||
| MediaTailor creates an object for each companion-ad element. | Object | adParameters, altText, attributes, companionClickThrough, companionClickTracking, htmlResource, sequence, staticResource, trackingEvents |
VAST/Ad/InLine/Creatives/Creative/CompanionAds
|
||
/adParameters
|
String | ||||
/altText
|
String | ||||
/attributes
|
Object |
adSlotId, apiFramework, assetHeight, assetWidth, expandedHeight, expandedWidth, height, id, pxratio, renderingMode, width | |||
/adSlotId
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/@adSlotId
|
|||
/apiFramework
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/@apiFramework
|
|||
/assetHeight
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/@assetHeight
|
|||
/assetWidth
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/@assetWidth
|
|||
/expandedHeight
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/@expandedHeight
|
|||
/expandedWidth
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/@expandedWidth
|
|||
/height
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/@height
|
|||
/id
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/@id |
|||
/pxratio
|
String |
||||
/renderingMode
|
String |
||||
/width
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/@width |
|||
/companionClickThrough
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/CompanionClickThrough |
|||
/companionClickTracking
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/CompanionClickTracking |
|||
/htmlResource
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/HTMLResource |
|||
/iFrameResource
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/iFrameResource |
|||
/sequence
|
String |
||||
/staticResource
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/StaticResource |
|||
/trackingEvents
|
Array |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/TrackingEvents |
|||
|
MediaTailor creates an object for each companion-ad element-tracking event type. |
|||||
/tracking
|
Object |
>event, uri | |||
/event
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/TrackingEvents/Tracking/@event
|
|||
/uri
|
String |
VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/TrackingEvents/Tracking/#CDATA
|
|||
/duration
|
String |
Length, in ISO 8601 seconds format |
|||
/durationInSeconds
|
Number |
Length, in seconds format |
|||
/extensions
|
Array |
Ad servers can use custom VAST extensions |
|||
|
MediaTailor creates an object for each child extension of the
|
VAST/Ad/InLine/Extensions
|
||||
/extension
|
Object | type, content |
VAST/Ad/InLine/Extensions/Extension
|
||
/type
|
String |
VAST/Ad/InLine/Extensions/Extension/@type
|
|||
/content
|
String | ||||
/icons
|
Array |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons
|
|||
|
MediaTailor creates an object for each |
Object | attributes, dateTime, duration, durationInSeconds, htmlResource, iconClicks, iconViewTracking, iFrameResource, staticResource, startTime, startTimeInSeconds |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon
|
||
/attributes
|
Object | apiFramework, duration, height, offset, program, pxratio, width, xPosition, yPosition | |||
/apiFramework
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/@apiFramework
|
|||
/duration
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/@duration
|
|||
/height
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/@height
|
|||
/offset
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/@offset
|
|||
/program
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/@program
|
|||
/pxratio
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/@pxratio
|
|||
/width
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/@width
|
|||
/xPosition
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/@xPosition
|
|||
/yPosition
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/@yPosition
|
|||
/dateTime
|
String | ||||
/duration
|
String | ||||
/durationInSeconds
|
Number | ||||
/htmlResource
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/HTMLResource
|
|||
/iconClicks
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/IconClicks
|
|||
/iconClickThrough
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/IconClicks/IconClickThrough
|
|||
/iconClickTracking
|
Object | id |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/IconClicks/IconClickTracking
|
||
/id
|
String | ||||
/iconClickFallbackImages
|
Array |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/IconClicks/IconClickFallbackImages
|
|||
|
MediaTailor creates an object for each icon-click fallback-image node. |
|||||
/altText
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/IconClicks/IconClickFallbackImages/IconClickFallbackImage/AltText
|
|||
/height
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/IconClicks/IconClickFallbackImages/IconClickFallbackImage/@height
|
|||
/width
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/IconClicks/IconClickFallbackImages/IconClickFallbackImage/@width
|
|||
/staticResource
|
Object | creativeType, uri |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/IconClicks/IconClickFallbackImages/IconClickFallbackImage/StaticResource
|
||
/creativeType
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/IconClicks/IconClickFallbackImages/IconClickFallbackImage/StaticResource/@creativeType
|
|||
/uri
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/IconClicks/IconClickFallbackImages/IconClickFallbackImage/StaticResource/#CDATA
|
|||
/iconViewTracking
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/IconViewTracking
|
|||
/iFrameResource
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/iFrameResource
|
|||
/statidResource
|
Object | creativeType, uri |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/StaticResource
|
||
/creativeType
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/StaticResource/@type
|
|||
/uri
|
String |
VAST/Ad/InLine/Creatives/Creative/Linear/Icons/Icon/StaticResource/#CDATA
|
|||
/startTime
|
String | ||||
/startTimeInSeconds
|
Number | ||||
/mediaFiles
|
Object | adParameters, duration, durationInSeconds, mediaFilesList, mezzanine, startTime, startTimeInSeconds, trackingEvents |
Video and other assets that the player needs for the ad avail |
||
/adParameters
|
String | ||||
/duration
|
String | ||||
/durationInSeconds
|
Number | ||||
/mediaFilesList
|
Array | ||||
|
MediaTailor creates an object for each companion-ad element-tracking event type |
apiFramework, delivery, height, maintainAspectRatio, mediaFileUri, mediaType, scalable, width | ||||
/apiFramework
|
String | ||||
/delivery
|
String | ||||
/height
|
String | ||||
/maintainAspectRatio
|
String | ||||
/mediaFileUri
|
String | ||||
/mediaType
|
String | ||||
/scalable
|
String | ||||
/width
|
String | ||||
/mezzanine
|
String | ||||
/startTime
|
String | ||||
/startTimeInSeconds
|
String | ||||
/trackingEvents
|
Array | ||||
|
MediaTailor creates an object for each tracking event for the creative |
beaconUrls, duration, durationInSeconds, dateTime, eventId, eventType, startTime, startTimeInSeconds | ||||
/beaconUrls
|
Array | ||||
|
A comma-separated list of all tracking URLs for this event |
|||||
/duration
|
String | ||||
/durationInSeconds
|
Number | ||||
/dateTime
|
String | ||||
/eventId
|
String | ||||
/eventType
|
String | ||||
/startTime
|
String | ||||
/startTimeInSeconds
|
Number | ||||
/startTime
|
String |
Time position, in ISO 8601 seconds format, relative to the beginning of the playback session |
|||
/startTimeInSeconds
|
Number |
Time position, in seconds format, relative to the beginning of the playback session |
|||
/dateTime
|
String |
Program date time, in ISO 8601 seconds format, for the start of the ad avail |
|||
/trackingEvents
|
Array |
Contains all tracking-event data that was received in the VAST response, along with timing information |
|||
/adType
|
String | ||||
/availId
|
String | ||||
/dateTime
|
String | ||||
/duration
|
String | ||||
/durationInSeconds
|
Number | ||||
/startTime
|
String | ||||
/startTimeInSeconds
|
Number | ||||
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
|
|
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 |
String |
[]
|
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. |
String | |
adProgramDateTime
|
|
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. |
Array |
[]
|
adSystem
|
The name of the system that serves the ad. ImportantMake 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 |
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. |
String |
video sequence advertising sneakers
|
attributes
|
Includes keys defined in the VAST specification for companion ads,
such as |
Object |
{}
|
apiFramework
|
Set to |
String |
VPAID
|
availID
|
|
String |
|
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. |
Array |
[]
|
beaconUrls
|
The URL where MediaTailor sends the ad beacon. |
String | |
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. |
Array |
[]
|
companionClickThrough
|
A URL to the advertiser’s page that the media player opens when the viewer clicks the companion ad. |
String |
https://aws.amazon.com/
|
companionClickTracking
|
The tracking URL for the |
String |
https://myads.com/beaconing/event=clicktracking
|
creativeId
|
The |
String |
creative-1
|
creativeSequence
|
The sequence in which an ad should play, according to the
|
String |
1
|
dashAvailabilityStartTime
|
For live/dynamic DASH, the |
String |
2022-10-05T19:38:39.263Z
|
delivery
|
Indicates whether a |
String |
progressive
|
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. |
Number |
15.015
|
eventId
|
|
String |
23
|
eventType
|
The type of beacon. |
String |
impression
|
extensions
|
Custom extensions of VAST that ad servers use. For more
information about extensions, see section 3.18 of the VAST 4.2
specification |
Array |
[]
|
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
|
htmlResource
|
The CDATA-encoded HTML that's inserted directly within the streaming provider's HTML page. |
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. |
String | |
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. |
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
|
|||
mezzanine
|
The URL of the mezzanine MP4 asset, specified if the VPAID ad includes one. |
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
|
Array |
[]
|
|
nonLinearAdsList
|
Array |
[]
|
|
nonLinearAvails
|
Array | ||
scalable
|
Indicates whether to scale the video to other dimensions. |
Boolean |
true
|
sequence
|
The sequence value specified for the creative in the VAST response. |
String |
1
|
skipOffset
|
The time value that identifies when the player makes skip controls available to the user. |
String |
00:00:05
|
startTime
|
The time position, in ISO 8601 seconds format, relative to the beginning of the playback session. The response includes start times for the entire ad avail and for each ad and beacon. |
String |
PT9.943S
|
startTimeInSeconds
|
The time position, in seconds format, relative to the beginning of the playback session. The response includes start times for the entire ad avail and for each ad and beacon. |
Number |
9.943
|
staticResource
|
The URL to a static creative file that's used for the ad component. |
String |
https://very-interactive-ads.com/campaign1/file.json?c=1019113602
|
vastAdId
|
The |
String |
ad1
|
width
|
The width, in pixels, of the video asset. |
String |
640
|
