Data dictionaries

Ad Framework Data Dictionary

The Datazoom Ad Framework Data Dictionary defines the events, metadata, and fluxdata associated with advertising playback within the media player (i.e., when Media Type equals “ad”).

Designed for Datazoom Application Collectors configured with both Media Player and Ad Framework Extensions, this dictionary automatically tracks the user's interaction with ad breaks—including pre-roll, mid-roll, and post-roll scenarios.

Key Features:

Ad-Specific: These data points are distinct from the Media Player Data Dictionary; they specifically monitor ad performance and ad-related user behavior.
Configurable: Collection of these ad events can be enabled or disabled via the Datazoom Console without changing your code.
Extensible: As with other dictionaries, the Datazoom SDK allows for the collection of unlimited custom events and metadata alongside these standard ad metrics.

Events

Discrete occurrences driven by user interactions or system actions

Metadata

Attributes describing the context of an event

Fluxdata

Metrics measuring changing parameters over time

Events

Ad Break End

ad_break_end

When an advertising break ends and content resumes.

Ad Break Start

ad_break_start

When content halts and an advertising break begins.

Ad Click

ad_click

When the user invokes the ad click URL associated with an advertisement.

Ad Impression

ad_impression

When an ad impression is recorded by the video player or ad framework. https://help.datazoom.io/hc/en-us/sections/360000536792-How-to-enable-ad-data-collection

Ad Skip

ad_skip

When the user chooses to skip the currently playing ad.

Audio Track Changed

audio_track_changed

When the user has chosen to switch to a different audio track in the video player.

Supported Collectors	2
Supported Media Types	Ad
Notes	For the HTML5 collector, this is currently only supported by Safari.

Beacon Response

ad_beacon_response

Fired whenever a beacon delivery response was received. This event can include (if selected) three ad metadata data points: ad_beacon_status (e.g., 200) ad_beacon_type (e.g., “impression”) ad_beacon_url

Supported Collectors	1
Notes	Fired whenever a beacon delivery response was received. This event can include (if selected) three ad metadata data points: ad_beacon_status (e.g., 200) ad_beacon_type (e.g., “impression”) ad_beacon_url

Buffer End

buffer_end

When media plays after Buffer Start or when the player state changes during buffer due to user action or an error.

Supported Collectors	27
Supported Media Types	Ad
Notes	A buffering event has just completed. The player fires this event which returns a value of 1 to indicate that playback has resumed.

Buffer Start

buffer_start

When the player has to wait for the video buffer to fill with video segments.

Supported Collectors	27
Supported Media Types	Ad
Notes	When the Buffer Start event is thrown and a value received, it is correlated to a specific playback time by comparing it to the playback length within the manifest. Once the Buffer End event has thrown, the delta between the two can be used to forensically analyze a series of chunks to determine the veracity of the content files. If the issue is corrupt chunks, a new encode can be produced.

Error

error

This event fires if a error causes content or ad playback or retrieval of the video to fail.

Supported Collectors	40
Supported Media Types	Ad

Media Loaded

media_loaded

Triggered when player is ready to begin playback after playback is invoked.

Supported Collectors	38
Supported Media Types	Ad

Media Object Request

media_object_request

Fired after the player has requested an object related to video playback. This object may be a manifest, audio / video segment or subtitle file. The player will fire this event after the full roundtrip of request and response has completed.

Supported Collectors	1
Supported Media Types	Ad
Notes	Primarily intended for open tracing via CMCD.

Media Request

media_request

When media type is 'content', this is triggered when media_request is invoked. This could happen automatically in auto-play situations or when a user presses the play button. When the media type is 'ad', this is triggered when VAST request is made.

Supported Collectors	29
Supported Media Types	Ad
Notes	Identify problems that may be occurring in the video player which prevent successful playback after a user requests playback.

Milestone

milestone

When the playhead position plays through a customer configurable percentile milestone of the video's duration (seeking through the milestone does not trigger the event). The event fires no more than once for each percentile milestone per ad session.

Supported Collectors	46
Supported Media Types	Ad
Notes	Configure milestones by visiting your collector configurations pages from the Collectors page, scroll to the Milestones setting in the Event Control section. By default, for content, milestones fire when the user passes 5%, 10%, 25%, 50%, 75%, 90%, & 95% point in the content playback timeline and, for ads, when the user passes 25%, 50%, & 75% point in the ad playback timeline.

OM Session Created

ad_om_session_created

Fired when the client is able to create an OM ad-session for the ad, which means that at least all the prerequisite for OM are in place. This event can include (if selected) one ad metadata data point: ad_om_session_data (prerequisite resources for OM)

Supported Collectors	1
Notes	Fired when the client is able to create an OM ad-session for the ad, which means that at least all the prerequisite for OM are in place. This event can include (if selected) one ad metadata data point: ad_om_session_data (prerequisite resources for OM)

OM Session Omitted

ad_om_session_omitted

Fired when the client is unable to create an OM ad-session for the ad. This may be an issue or an expected result. This event can include (if selected) metadata data points: ad_om_session_data (prerequisite resources for OM) error_msg (reason the OM session was omitted - such as “Resources not found" or “Unsupported”.)

Supported Collectors	1
Notes	Fired when the client is unable to create an OM ad-session for the ad. This may be an issue or an expected result. This event can include (if selected) metadata data points: ad_om_session_data (prerequisite resources for OM) error_msg (reason the OM session was omitted - such as “Resources not found" or “Unsupported”.)

Pause

pause

When playback is intentionally halted.

Supported Collectors	46
Supported Media Types	Ad

Playback Complete

playback_complete

When the video player reaches the end of the currently playing content. The event can be triggered multiple times if the user reaches the end of the currently playing content, scrubs back and then reaches the end of the content again.

Supported Collectors	48
Supported Media Types	Ad

Playback Start

playback_start

When the video starts playing for the user, also known as "first frame".

Supported Collectors	49
Supported Media Types	Ad

Playing

playing

The media is no longer blocked from playback, and has started playing. Fired when playback resumes from Stall, Buffering or Seek.

Supported Collectors	40
Supported Media Types	Ad

Qualified View

qualified_view

When playback duration surpasses customer configurable thresholds of time in seconds.

Supported Collectors	49
Supported Media Types	Ad
Notes	Configure qualified view thresholds by visiting your collector configurations pages from the Collectors page, scroll to the Qualified View setting in the Event Control section. By default, for content, qualified view thresholds are 30 seconds and 60 seconds and, for ads, the qualified view threshold is 5 seconds.

Rendition Change

rendition_change

When the player's Adaptive Bitrate Streaming upshifts or downshifts during playback to a different quality level available in the manifest. This event includes absShift attribute identifying the direction of the change.

Supported Collectors	11
Supported Media Types	Ad

Resume

resume

When the user begins playing again after pausing the video during playback.

Supported Collectors	44
Supported Media Types	Ad

Seek End

seek_end

When a user stops seeking.

Supported Collectors
Supported Media Types	Ad
Notes	This event includes attributes Seek Start Point & Seek End Point to mark the starting & ending points of a seek event.

Seek Start

seek_start

When a user begins seeking.

Supported Collectors
Supported Media Types	Ad

Stall End

stall_end

Event fired when video starts playing again after a stall

Supported Collectors	14
Supported Media Types	Ad

Stall Start

stall_start

When there is an unexpected playback interruption because the buffer has been depleted.

Supported Collectors	14
Supported Media Types	Ad

Stop

stop

Triggered when: 1. A playback error results in the termination of content playback. 2. The context (or the logical equivalent) corresponding to a specific player is destroyed: 2(a). The application may destroy the context when playback is stopped by the user. 2(b). The application may destroy the context after playback has reached the end of content (and the player isn’t going to be reused any further). 2(c). The collector (in certain cases) may be able to detect when the application is terminated (e.g., user closes the browser tab) and destroy all player contexts automatically. 3. If a change in the content URL is detected by the collector, a new content session should begin and a `stop` event should be triggered for the previous content session.

Supported Collectors	3
Supported Media Types	Ad
Notes	Notable condition where the `stop` events is not triggered: When playback reaches the end of the content timeline (i.e., the same condition for triggering `playback_complete`), the content session remains open, unaffected by the fact that playback has reached the end of content so if post-roll ads are played or play-head is rewinded afterward, the subsequent events belong to the same content session.

Subtitle Change

subtitle_change

When the user enables or disables subtitles or closed captioning.

Supported Collectors	2
Supported Media Types	Ad

Metadata

Ad Break ID

ad_break_id

Datazoom genertated UUID to denote the specific ad break. To collect this data point, Datazoom collectors require ad framework integration unless media player supports ad framework natively.

Supported Collectors	48
Data type	string
Number Type	Not set
Notes	This can be used to tie events together that occurred during a specific ad break.
Permitted Values	UUID

Ad Click URL

ad_click_url

URL opened when the user interacts with an ad during playback. To collect this data point, Datazoom collectors require ad framework integration unless media player supports ad framework natively.

Supported Collectors	18
Data type	string
Number Type	Not set
Permitted Values	URL

Ad Creative ID

ad_creative_id

The ad server’s unique identifier for the creative. To collect this data point, Datazoom collectors require ad framework integration unless media player supports ad framework natively.

Supported Collectors	47
Data type	string
Number Type	Not set

Ad Duration

ad_duration_sec

The length of the advertisement in seconds. To collect this data point, Datazoom collectors require ad framework integration unless media player supports ad framework natively.

Supported Collectors	47
Data type	number
Number Type	Not set
Unit	seconds

Ad ID

ad_id

An ad server-defined identifier for the ad. To collect this data point, Datazoom collectors require ad framework integration unless media player supports ad framework natively.

Supported Collectors	52
Data type	string
Number Type	Not set

Ad Partner

ad_partner

The name of the ad server that returned the ad. To collect this data point, Datazoom collector requires ad framework integration unless media player supports ad framework natively.

Supported Collectors	3
Data type	string
Number Type	Not set

Ad Position

ad_position

Where the ad break appears in relation to the video content. -- Pre-roll ads run before the content -- Mid-roll ads run during the middle of the content -- Post-roll ads run after the content has completed To collect this data point, Datazoom collectors require ad framework integration unless media player supports ad framework natively.

Supported Collectors	47
Data type	string
Number Type	Not set
Notes	Datazoom identifies pre, mid, post values of Ad Position because ad systems, depending on the implementation (e.g., when not using VMAP), don’t standardize ad position consistently.
Permitted Values	value list

Ad Session ID

ad_session_id

A Datazoom generated UUID to denote a playback session of a single ad. To collect this data point, Datazoom collectors require ad framework integration unless media player supports ad framework natively.

Supported Collectors	48
Data type	string
Number Type	Not set
Notes	This can be used to tie events together that occurred during a specific ad.
Permitted Values	UUID

Ad System

ad_system

The source ad server information included in the ad response. Datazoom collector will require ad framework integration unless media player supports ad framework natively.

Supported Collectors	45
Data type	string
Number Type	Not set

Ad Time Offset

ad_time_offset_sec

The point in time during the content playback at which the current ad break was scheduled to appear. For ad breaks in VOD streams with dynamically inserted ads, playhead position in the content timeline is returned. To collect this data point, Datazoom collectors require ad framework integration unless media player supports ad framework natively.

Supported Collectors	46
Data type	number
Number Type	Not set
Unit	seconds

Advertiser Name

advertiser_name

The advertiser name as defined and supported by the integrated ad framework. To collect this data point, Datazoom collectors require ad framework integration unless media player supports ad framework natively.

Supported Collectors	12
Data type	string
Number Type	Not set

Beacon Status

ad_beacon_status

HTTP status code for the ad_beacon_response event

Supported Collectors	1
Data type	string
Number Type	Not set
Notes	HTTP status code for the ad_beacon_response event

Beacon Type

ad_beacon_type

The beacon type for the ad_beacon_response event. (e.g., “impression”)

Supported Collectors	1
Data type	string
Number Type	Not set
Notes	The beacon type for the ad_beacon_response event. (e.g., “impression”)

Beacon URL

ad_beacon_url

The URL of the ad beacon

Supported Collectors	1
Data type	string
Number Type	Not set
Permitted Values	URL

Beacons

ad_beacons

The list of beacons that the ad server has asked the client to manage as included in the VAST response.

Supported Collectors	1
Data type	string
Number Type	Not set
Notes	The list of beacons that the ad server has asked the client to manage as included in the VAST response.

Beacons Rejected

ad_beacons_rejected

The ad beacons (for the specific ad) that have been rejected

Supported Collectors	1
Data type	string
Number Type	Not set
Notes	The ad beacons (for the specific ad) that have been rejected

Beacons Sent

ad_beacons_sent

The ad beacons (for the specific ad) that have been successfully sent.

Supported Collectors	1
Data type	string
Number Type	Not set
Notes	The ad beacons (for the specific ad) that have been successfully sent.

Deal ID

deal_id

The first deal ID present in the wrapper chain for the current ad, starting from the top. To collect this data point, Datazoom collectors require ad framework integration unless media player supports ad framework natively.

Supported Collectors	13
Data type	string
Number Type	Not set

OM Session Data

ad_om_session_data

The prerequisite resources for OM

Supported Collectors	1
Data type	string
Number Type	Not set
Notes	prerequisite resources for OM

OM Session Events

ad_om_session_events

The OM session events (for the specific ad) that have been triggered

Supported Collectors	1
Data type	string
Number Type	Not set
Notes	The OM session events (for the specific ad) that have been triggered

Skip Time Offset

skip_time_offset_sec

The number of seconds of playback before the ad becomes skippable. -1 is returned for non skippable ads or if this is unavailable.

Supported Collectors	40
Data type	number
Number Type	Short
Unit	seconds

Wrapper Creative IDs

wrapper_creative_ids

Selected creative IDs used for wrapper ads. The creative IDs returned starts at the inline ad and traverses to the outermost wrapper ad. To collect this data point, Datazoom collectors require ad framework integration unless media player supports ad framework natively.

Supported Collectors	14
Data type	array of string
Number Type	Not set

Wrapper ID

wrapper_id

Ad IDs used for wrapper ads. The IDs returned starts at the inline ad (innermost) and traverses to the outermost wrapper ad. To collect this data point, Datazoom collectors require ad framework integration unless media player supports ad framework natively.

Supported Collectors	14
Data type	array of string
Number Type	Not set

Wrapper Systems

wrapper_systems

Ad systems used for wrapper ads. The ad systems returned starts at the inline ad and traverses to the outermost wrapper ad. To collect this data point, Datazoom collectors require ad framework integration unless media player supports ad framework natively.

Supported Collectors	14
Data type	array of string
Number Type	Not set

Fluxdata

Ad Break Start Recency (Content Session)

time_since_last_ad_break_start_ms

Time since last "Ad Break Start" event where "Media Type" equals "ad".

Supported Collectors	39
Device Platforms	Browser,Console,DTV,Mobile

Ad Buffer Duration (Content Session)

buffer_duration_ads_ms

Cumulative buffering time during a content session when 'media type' equals 'ad'

Supported Collectors	27
Device Platforms	Browser,Console,DTV,Mobile

Ad Buffer Start Recency (Content Session)

time_since_last_buffer_start_ad_ms

Time since last "Buffer Start" event where "Media Type" equals "ad" for the current content session

Supported Collectors	47
Device Platforms	Browser,Console,DTV,Mobile

Ad Error Count (App Session)

num_errors_ads

Count of errors during an app session where 'media type' equals 'ad'

Supported Collectors	30
Device Platforms	Browser,Console,DTV,Mobile

Ad Media Request Recency (Content Session)

time_since_last_request_ad_ms

Time since last "Media Request" event where "Media Type" equals "ad" for the current content session

Supported Collectors	28
Device Platforms	Browser,Console,DTV,Mobile

Ad Milestone Recency (Content Session)

time_since_last_milestone_ad_ms

Time since last "Milestone" event where "Media Type" equals "ad".

Supported Collectors	49
Device Platforms	Browser,Console,DTV,Mobile

Ad Pause Duration (Content Session)

pause_duration_ads_ms

The cumulative amount of time elapsed where the player was in a paused state during ad playback of content session.

Supported Collectors	34
Device Platforms	Browser,Console,DTV,Mobile

Ad Playback Complete Recency (Content Session)

time_since_last_ad_completed_ms

Time since the last "Playback Complete" event where "Media Type" equals "ad" for the current content session

Supported Collectors	39
Device Platforms	Browser,Console,DTV,Mobile

Ad Playback Duration (App Session)

playback_duration_ads_app_ms

Elapsed time spent watching ads within an app session, regardless of playback rate, excluding stalls, buffers or pauses.

Supported Collectors

Ad Playback Duration (Content Session)

playback_duration_ads_ms

Cumulative playback time where media type equals 'ad' during the current content session regardless of playback rate, excluding stalls, buffers or pauses.

Supported Collectors	47
Device Platforms	Browser,Console,DTV,Mobile

Ad Playback Start Count (Ad Break)

num_ad_break_plays

Count of 'playback start' events where 'media type' equals 'ad' during an ad break

Supported Collectors	42
Device Platforms	Browser,DTV,Mobile

Ad Playback Start Count (App Session)

num_ad_plays

Count of 'playback start' events where 'media type' equals 'ad' during an app session

Supported Collectors	48
Device Platforms	Browser,Console,DTV,Mobile

Ad Playback Start Recency (Content Session)

time_since_last_started_ad_ms

Time since last "Playback Start" event where "Media Type" equals "ad" for the current content session

Supported Collectors	48
Device Platforms	Browser,Console,DTV,Mobile

Ad Stall Count (Content Session)

stall_count_ads

Count of stall events in a content session where 'media type' equals 'ad'

Supported Collectors	13
Device Platforms	Browser,Console,DTV,Mobile

Ad Stall Duration (Content Session)

stall_duration_ads_ms

Cumulative stall time during a content session when 'media type' equals 'ad'

Supported Collectors	13
Device Platforms	Browser,Console,DTV,Mobile

Ad Stall Start Recency (Content Session)

time_since_last_stall_start_ad_ms

Time since last "Stall Start" event where "Media Type" equals "ad"

Supported Collectors	47
Device Platforms	Browser,Console,DTV,Mobile

Audible Ad Playback Duration (App Session)

playback_duration_ads_audible_app_ms

Elapsed time spent watching ads with the volume on within an app session, regardless of playback rate, excluding stalls, buffers or pauses.

Supported Collectors

Playback Duration (Ad Session)

playback_duration_ad_session_ms

Cumulative playback time of an ad session regardless of playback rate, excluding stalls, buffers or pauses.

Supported Collectors	39
Device Platforms	Browser,Console,DTV,Mobile

Viewable Ad Playback Duration (App Session)

playback_duration_ads_viewable_app_ms

Elapsed time spent watching ads with the player viewable within an app session, regardless of playback rate, excluding stalls, buffers or pauses.

Supported Collectors