Video playback events

Updated

How it works

Video events help you observe and report how customers engage with your videos and ad content. Using the specification outlined on this page will help you take advantage of out-of-the-box actions for destinations that rely on video playback.

Playback events occur in three areas:

  1. Video: this represents the complete movie, program, or video that a person watches.
  2. Content: often referred to as a “pod,” this is a group of content within the video—like a video segment with a mid-roll ad would be considered 2 pods (one before the ad and one after).
  3. Ads: these are the ads that play within the video.

You’ll send events across all three areas to track how people engage with your video content.

Playback lifecycle

Remember that a “video” itself represents all of the content (pods) and ads in a session. You’ll want to send playback events not only when a user starts a video, but also when each content pod or ad starts.

Beyond that, you’ll also want to send “heartbeat” events on a regular interval that a content pod or ad plays, helping you determine how long people watch your content. We recommend sending a heartbeat event every 10 seconds.

flowchart LR A(Video Playback
Started)-->b(Video Content
Started)-->|send every
10 seconds|c c(Video Content
Playing) c-.->|User pauses video|f(Video Playback
Paused) f-.->|User resumes video|m(Video Playback
Resumed)-.->c c-->|content ends|n(Video Content
Completed) n-->p{Is this the end
of the video?} p-->|yes|r(Video Playback
Completed) p-.->|no|s{What plays next?} s-.->|Content|b s-.->|Ads|t(Video Ad
Started)

Video Playback events

Playback events represent the playback events related to the video player itself. Some of these events are things your audience explicitly triggers—play, pause, resume, and so on, but these also cover buffering and other events that affect the player.

When a user presses play, you’ll start with a Video Playback Started event containing a session_id that you’ll use for subsequent events in the session. The session ID helps you track a user’s session with a specific video player and group of content/ads.

So if a page on your website contains two video players, each player should have a separate session and session ID. But, if the page only contained one player and it contained two “video contents” in a row, you’d have one session ID with two “Video Content” events.

When you send a Video Playback Started event, you’ll send arrays of content_asset_ids, content_pod_ids, ad_asset_id, and ad_pod_id—indicating all the potential assets in the playback session. For all other events, you’ll send the individual IDs as strings—indicating the specific pod or asset a person interacts with.

EventDescription
Video Playback StartedSent when a user starts a video.
Video Playback PausedSent when a user pauses a video.
Video Playback ResumedSent when a user resumes a video.
Video Playback CompletedSent when a user completes a video.
Video Playback Buffer StartedSent when a video starts buffering.
Video Playback Buffer CompletedSent when a video stops buffering.
Video Playback Seek StartedWhen a user manually seeks to a position in the content or ad in the playback session. Use seek_position to denote where the user is seeking to position to denote where the user’s original position.
Video Playback Seek CompletedSent when a user stops seeking through a video.
Video Playback InterruptedSent when playback stops unintentionally (from network loss, browser close/redirect, or app crash). With this event you can pass a property to denote the cause of the interruption.
Video Playback ExitedSent when a user navigates away from a playback/stream.

Video Playback Started

When a user starts a video, you’ll send a Video Playback Started event. This event should contain the following properties. When you start video playback, you’ll define arrays of content_asset_ids and content_pod_ids potentially in the session; these help you understand all the content that could possibly be contained within the session.

All other playback events list an individual content_asset_id and/or content_pod_id.

{
    "action": "track",
    "event": "Video Playback Started",
    "userId": "userId",
    "properties": {
      "session_id": "12345",
      "content_asset_ids": ["0129370"],
      "content_pod_ids": ["episode1", "episode2"],
      "ad_asset_id": ["ad123", "ad097"],
      "ad_pod_id": ["adSegment1", "adSegment2"],
      "ad_type": ["pre-roll", "mid-roll"],
      "position": 0,
      "total_length": 3600,
      "bitrate": 100,
      "framerate": 29.00,
      "video_player": "youtube",
      "sound": 42,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}
  • content_asset_ids array of [ strings ]
    The ID of the videos a user started. The array indicates a potential playlist of videos/content IDs a person is starting.
  • content_pod_ids array of [ strings ]
    The IDs of the content “pods” in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. The array indicates a potential playlist of content pod IDs a person is starting.
  • ad_asset_id string
    The Ad Asset Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad asset IDs. For all other playback events, you should send a string with the ID of the current ad asset playing at the time of the event.
  • ad_enabled boolean
    Set to true if a viewer can see your ads. You’d set false if a viewer has ad block or other blockers enabled.
  • ad_pod_id string
    The Ad Pod Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad pod IDs. For all other playback events, you should send a string with the ID of the current ad pod playing at the time of the event.
  • ad_type string
    The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

    Accepted values:pre-roll,mid-roll,post-roll

  • bitrate integer
    The current kbps.
  • framerate integer
    The average frames per second (fps).
  • full_screen boolean
    If true, playback is in fullscreen mode.
  • livestream boolean
    Set to true if the playback is a livestream.
  • position integer
    The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.
  • quality string
    The video quality of playback, like 480p or highres.
  • session_id string
    The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.
  • sound integer
    The current volume of the video player as a value between 1 and 100.
  • total_length integer
    The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.
  • video_player string
    The name of the video player the client uses, like youtube or vimeo.

Other Playback Events

All playback events aside from Video Playback Started include a content_asset_id and content_pod_id to help you track the relevant content and ad when playback events occur.

The Video Playback Interrupted event includes a method parameter to help you define the method by which playback was interrupted.

{
    "action": "track",
    "event": "Video Playback Paused",
    "userId": "userId",
    "properties": {
      "session_id": "12345",
      "content_asset_id": "0129370",
      "content_pod_id": "episode1",
      "position": 0,
      "total_length": 3600,
      "bitrate": 100,
      "framerate": 29.00,
      "video_player": "youtube",
      "sound": 42,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}
  • method string
    For Video Playback Interrupted events only, you can send this property denoting how the playback was interrupted (such as browser redirect, device lock, or call).
  • content_asset_id string
    The ID of the video a user interacted with.
  • content_pod_id string
    The ID of the content “pod” in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.
  • ad_asset_id string
    The Ad Asset Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad asset IDs. For all other playback events, you should send a string with the ID of the current ad asset playing at the time of the event.
  • ad_enabled boolean
    Set to true if a viewer can see your ads. You’d set false if a viewer has ad block or other blockers enabled.
  • ad_pod_id string
    The Ad Pod Id(s) of the ad/ads playing or about to be played in the video player. For Video Playback Started events only, you should send an Array of unique ad pod IDs. For all other playback events, you should send a string with the ID of the current ad pod playing at the time of the event.
  • ad_type string
    The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

    Accepted values:pre-roll,mid-roll,post-roll

  • bitrate integer
    The current kbps.
  • framerate integer
    The average frames per second (fps).
  • full_screen boolean
    If true, playback is in fullscreen mode.
  • livestream boolean
    Set to true if the playback is a livestream.
  • position integer
    The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.
  • quality string
    The video quality of playback, like 480p or highres.
  • session_id string
    The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.
  • sound integer
    The current volume of the video player as a value between 1 and 100.
  • total_length integer
    The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.
  • video_player string
    The name of the video player the client uses, like youtube or vimeo.

Content events

Within a playback session, videos contain “pods” of content. A pod is a group or segment of content or an advertisement.

Imagine you have a playback session that with a single piece of video content and one mid-roll advertisement. This means that your video contains two content pods—one before the mid-roll ad and one after. In this instance, you’d start and complete the first pod of content; you’d start and complete the ad; you’d start and complete the second pod of content. All of this would happen within one playback start.

You should also Video Content Playing on a regular interval as a heartbeat event. This helps you track how long people watch your content.

EventDescription
Video Content StartedSent when a user starts a new piece of video content.
Video Content PlayingSent when a user is playing a piece of video content.
Video Content CompletedSent when a user completes a piece of video content.

Below are some sample events with definitions for each property you might send in these events.

{
    "action": "track",
    "event": "Video Content Started",
    "userId": "userId",
    "properties": {
      "session_id": "abcde",
      "asset_id": "8675309",
      "pod_id": "segment1",
      "program": "The Last Dance",
      "title": "Episode 1",
      "description": " Flashbacks chronicle Michael Jordan's college and early NBA days. The Bulls make a preseason trip to Paris amid tensions with GM Jerry Krause.",
      "season": "1",
      "position": 0,
      "total_length": 3600,
      "genre": "Documentary",
      "publisher": "ESPN",
      "full_episode": true,
      "keywords": ["NBA", "Basketball", "Jordan", "Chicago Bulls"]
    }
}
  • airdate string  (date-time)
    The ISO-8601 date-time when the video content/pod originally aired or was published.
  • asset_id string
    The ID of the video a user interacted with.
  • bitrate integer
    The current kbps.
  • channel string
    The channel the video content/pod belongs to or is aired on, like hgtv or my_youtube_channel.
  • description string
    The description of the video content/pod.
  • framerate integer
    The average frames per second (fps).
  • full_episode boolean
    Set to true if the content is a full episode of a show.
  • genre string
    The genre of the video content/pod.
  • keywords array of [ strings ]
    Keywords associated with the video content/pod.
  • livestream boolean
    Set to true if the content is a livestream.
  • pod_id string
    The ID of the content “pod” in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.
  • position integer
    The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.
  • program string
    The name of the program or show the content belongs to (if applicable).
  • publisher string
    The publisher of the video content/pod.
  • season string
    The season the video content/pod belongs to, if applicable.
  • session_id string
    The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.
  • title string
    The title of the video content/pod.
  • total_length integer
    The total duration of the content/asset in seconds. Note that this is not the duration of the video itself or the playback, but a piece of a complete “pod” of content. If the content is an ad in the video, this is the length of the ad.

Ad events

Ad events are similar to content events, but they represent the ads that play within a video. Ads can also be “pods”—like a group of ads For example, imagine that your video has two pre-roll ads, one mid-roll ad, and one post-roll ad. This results in three ad “pods”:

  • ad pod 1: plays the two pre-roll ads
  • ad pod 2: plays the one mid-roll ad
  • ad pod 3: plays the one post-roll ad
EventDescription
Video Ad StartedSent when a user starts a new ad.
Video Ad PlayingSent when a user is playing an ad.
Video Ad CompletedSent when a user finishes an ad.

Below are some sample events with definitions for each property you might send in these events.

{
    "action": "track",
    "event": "Video Ad Started",
    "userId": "userId",
    "properties": {
      "session_id": "abcde",
      "asset_id": "8675309",
      "pod_id": "segment1",
      "type": "pre-roll",
      "title": "The New New Thing!",
      "position": 0,
      "total_length": 30,
      "publisher": "Apple",
      "load_type": "dynamic"
    }
}
  • asset_id string
    The ID of the video a user interacted with.
  • load_type string
    Set to dynamic if you insert ads dynamically and linear if ads are the same for all viewers.

    Accepted values:dynamic,linear

  • pod_id string
    The ID of the content “pod” in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.
  • pod_length integer
    The number of ad assets in the ad-pod
  • pod_position integer
    The position of the pod/asset relative to other assets in the same pod. If your ad pod plays 3 ads, you would indicate if this is add number 1, 2, or 3.
  • position integer
    The current index position in seconds of the playhead, with respect to the length of the ad.
  • publisher string
    The ad’s publisher.
  • quartile integer
    Specifies the quartile of the ad that a viewer reached. If you use our client-side libraries, we’ll automatically track this for you.
  • session_id string
    The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.
  • title string
    The title of the ad.
  • total_length integer
    The total duration of the ad in seconds.
  • type string
    The ad type. Values can include pre-roll, mid-roll, and post-roll.

    Accepted values:pre-roll,mid-roll,post-roll

Heartbeat events

You should send a “heartbeat” event called Video Content Playing or Video Ad Playing every 10 seconds to indicate that a video (or ad) is still playing. This event contains the following properties:

  • airdate string  (date-time)
    The ISO-8601 date-time when the video content/pod originally aired or was published.
  • asset_id string
    The ID of the video a user interacted with.
  • bitrate integer
    The current kbps.
  • channel string
    The channel the video content/pod belongs to or is aired on, like hgtv or my_youtube_channel.
  • description string
    The description of the video content/pod.
  • framerate integer
    The average frames per second (fps).
  • full_episode boolean
    Set to true if the content is a full episode of a show.
  • genre string
    The genre of the video content/pod.
  • keywords array of [ strings ]
    Keywords associated with the video content/pod.
  • livestream boolean
    Set to true if the content is a livestream.
  • pod_id string
    The ID of the content “pod” in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.
  • position integer
    The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.
  • program string
    The name of the program or show the content belongs to (if applicable).
  • publisher string
    The publisher of the video content/pod.
  • season string
    The season the video content/pod belongs to, if applicable.
  • session_id string
    The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.
  • title string
    The title of the video content/pod.
  • total_length integer
    The total duration of the content/asset in seconds. Note that this is not the duration of the video itself or the playback, but a piece of a complete “pod” of content. If the content is an ad in the video, this is the length of the ad.
  • asset_id string
    The ID of the video a user interacted with.
  • load_type string
    Set to dynamic if you insert ads dynamically and linear if ads are the same for all viewers.

    Accepted values:dynamic,linear

  • pod_id string
    The ID of the content “pod” in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. This is the specific piece of content that the user interacted with.
  • pod_length integer
    The number of ad assets in the ad-pod
  • pod_position integer
    The position of the pod/asset relative to other assets in the same pod. If your ad pod plays 3 ads, you would indicate if this is add number 1, 2, or 3.
  • position integer
    The current index position in seconds of the playhead, with respect to the length of the ad.
  • publisher string
    The ad’s publisher.
  • quartile integer
    Specifies the quartile of the ad that a viewer reached. If you use our client-side libraries, we’ll automatically track this for you.
  • session_id string
    The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.
  • title string
    The title of the ad.
  • total_length integer
    The total duration of the ad in seconds.
  • type string
    The ad type. Values can include pre-roll, mid-roll, and post-roll.

    Accepted values:pre-roll,mid-roll,post-roll

Resuming playback

When you send a Video Playback Resumed event, you should also send a heartbeat event (Video Content Playing or Video Ad Playing). Make sure you resume your 10 second heartbeats when users resume video playback (likely after you sent a Video Playback Paused event).

Video quality event

As with pausing and resuming video, you should also send events when your audience changes video quality settings. We don’t have actions that hinge specifically on playback quality changes, but tracking quality can help you figure out the performance of your video content—whether your users can stream it in its original resolution or if they need to change it.

A quality change event should contain the following properties.

  • bitrate integer
    The current kbps.
  • droppedFrames integer
    The number of frames dropped during playback.
  • framerate integer
    The average frames per second (fps).
  • startupTime integer
    The time it takes for the video to start playing.
Copied to clipboard!
  Contents
Is this page helpful?