Customer.io

Video playback events

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 integrations that rely on video playback events. See Video Playback Events if you want to download the specification or try out video playback events.

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

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
    }
}
{
    "action": "track",
    "event": "Video Playback Resumed",
    "userId": "userId",
    "properties": {
      "session_id": "12345",
      "content_asset_id": "0129370",
      "content_pod_id": "episode1",
      "position": 20,
      "total_length": 3600,
      "bitrate": 100,
      "framerate": 29.00,
      "video_player": "youtube",
      "sound": 42,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}
{
    "action": "track",
    "event": "Video Playback Completed",
    "userId": "userId",
    "properties": {
      "session_id": "12345",
      "content_asset_id": "0129370",
      "content_pod_id": "episode1",
      "position": 3600,
      "total_length": 3600,
      "bitrate": 100,
      "framerate": 29.00,
      "video_player": "youtube",
      "sound": 42,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}
{
    "action": "track",
    "event": "Video Playback Buffer Started",
    "userId": "userId",
    "properties": {
      "session_id": "12345",
      "content_asset_id": "0129370",
      "content_pod_id": "episode1",
      "position": 1800,
      "total_length": 3600,
      "bitrate": 100,
      "framerate": 29.00,
      "video_player": "youtube",
      "sound": 42,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}
{
    "action": "track",
    "event": "Video Playback Buffer Completed",
    "userId": "userId",
    "properties": {
      "session_id": "12345",
      "content_asset_id": "0129370",
      "content_pod_id": "episode1",
      "position": 1800,
      "total_length": 3600,
      "bitrate": 100,
      "framerate": 29.00,
      "video_player": "youtube",
      "sound": 42,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}
{
    "action": "track",
    "event": "Video Playback Seek Started",
    "userId": "userId",
    "properties": {
      "session_id": "12345",
      "content_asset_id": "0129370",
      "content_pod_id": "episode1",
      "seek_position": 1900,
      "position": 1800,
      "total_length": 3600,
      "bitrate": 100,
      "framerate": 29.00,
      "video_player": "youtube",
      "sound": 42,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}
{
    "action": "track",
    "event": "Video Playback Seek Completed",
    "userId": "userId",
    "properties": {
      "session_id": "12345",
      "content_asset_id": "0129370",
      "content_pod_id": "episode1",
      "position": 1900,
      "total_length": 3600,
      "bitrate": 100,
      "framerate": 29.00,
      "video_player": "youtube",
      "sound": 42,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}
{
    "action": "track",
    "event": "Video Playback Seek Interrupted",
    "userId": "userId",
    "properties": {
      "session_id": "12345",
      "content_asset_id": "0129370",
      "content_pod_id": "episode1",
      "position": 1800,
      "total_length": 3600,
      "bitrate": 100,
      "framerate": 29.00,
      "video_player": "youtube",
      "sound": 42,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false,
      "method": "network loss"
    }
}
{
    "action": "track",
    "event": "Video Playback Exited",
    "userId": "userId",
    "properties": {
      "session_id": "12345",
      "content_asset_id": "0129370",
      "content_pod_id": "episode1",
      "position": 3600,
      "total_length": 3600,
      "bitrate": 100,
      "framerate": 29.00,
      "video_player": "youtube",
      "sound": 42,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false,
    }
}
  • methodstring
    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 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 profiles 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"]
    }
}
{
    "action": "track",
    "event": "Video Content Playing",
    "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": 800,
      "total_length": 3600,
      "genre": "Documentary",
      "publisher": "ESPN",
      "full_episode": true,
      "keywords": ["NBA", "Basketball", "Jordan", "Chicago Bulls"]
    }
}
{
    "action": "track",
    "event": "Video Content Completed",
    "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": 3600,
      "total_length": 3600,
      "genre": "Documentary",
      "publisher": "ESPN",
      "full_episode": true,
      "keywords": ["NBA", "Basketball", "Jordan", "Chicago Bulls"]
    }
}
  • session_idstring
    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.
  • asset_idstring
    The ID of the video a user interacted with.
  • pod_idstring
    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.
  • programstring
    The name of the program or show the content belongs to (if applicable).
  • titlestring
    The title of the video content/pod.
  • descriptionstring
    The description of the video content/pod.
  • seasonstring
    The season the video content/pod belongs to, if applicable.
  • positioninteger
    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.
  • total_lengthinteger
    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.
  • genrestring
    The genre of the video content/pod.
  • publisherstring
    The publisher of the video content/pod.
  • channelstring
    The channel the video content/pod belongs to or is aired on, like hgtv or my_youtube_channel.
  • full_episodeboolean
    Set to true if the content is a full episode of a show.
  • livestreamboolean
    Set to true if the content is a livestream.
  • airdatestring(date-time)
    The ISO-8601 date-time when the video content/pod originally aired or was published.
  • bitrateinteger
    The current kbps.
  • framerateinteger
    The average frames per second (fps).
  • keywordsarray of [ strings ]
    Keywords associated with the video content/pod.

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"
    }
}
{
    "action": "track",
    "event": "Video Ad Playing",
    "userId": "userId",
    "properties": {
      "session_id": "abcde",
      "asset_id": "8675309",
      "pod_id": "segment1",
      "type": "pre-roll",
      "title": "The New New Thing!",
      "position": 10,
      "total_length": 30,
      "publisher": "Apple",
      "load_type": "dynamic"
    }
}
{
    "action": "track",
    "event": "Video Ad Completed",
    "userId": "userId",
    "properties": {
      "session_id": "abcde",
      "asset_id": "8675309",
      "pod_id": "segment1",
      "type": "pre-roll",
      "title": "The New New Thing!",
      "position": 30,
      "total_length": 30,
      "publisher": "Apple",
      "load_type": "dynamic"
    }
}
  • session_idstring
    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.
  • asset_idstring
    The ID of the video a user interacted with.
  • pod_idstring
    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_positioninteger
    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.
  • pod_lengthinteger
    The number of ad assets in the ad-pod
  • typestring
    The ad type. Values can include pre-roll, mid-roll, and post-roll.
    Accepted values: pre-roll, mid-roll, post-roll
  • titlestring
    The title of the ad.
  • positioninteger
    The current index position in seconds of the playhead, with respect to the length of the ad.
  • total_lengthinteger
    The total duration of the ad in seconds.
  • publisherstring
    The ad's publisher.
  • load_typestring
    Set to dynamic if you insert ads dynamically and linear if ads are the same for all viewers.
    Accepted values: dynamic, linear
  • contentobject
    For video destinations that require you to send content metadata with ad events, you can send all the content metadata in this object—like content.title, etc.
  • quartileinteger
    Specifies the quartile of the ad that a viewer reached. If you use our client-side libraries, we'll automatically track this for you.

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:

  • session_idstring
    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.
  • asset_idstring
    The ID of the video a user interacted with.
  • pod_idstring
    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.
  • programstring
    The name of the program or show the content belongs to (if applicable).
  • titlestring
    The title of the video content/pod.
  • descriptionstring
    The description of the video content/pod.
  • seasonstring
    The season the video content/pod belongs to, if applicable.
  • positioninteger
    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.
  • total_lengthinteger
    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.
  • genrestring
    The genre of the video content/pod.
  • publisherstring
    The publisher of the video content/pod.
  • channelstring
    The channel the video content/pod belongs to or is aired on, like hgtv or my_youtube_channel.
  • full_episodeboolean
    Set to true if the content is a full episode of a show.
  • livestreamboolean
    Set to true if the content is a livestream.
  • airdatestring(date-time)
    The ISO-8601 date-time when the video content/pod originally aired or was published.
  • bitrateinteger
    The current kbps.
  • framerateinteger
    The average frames per second (fps).
  • keywordsarray of [ strings ]
    Keywords associated with the video content/pod.
  • session_idstring
    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.
  • asset_idstring
    The ID of the video a user interacted with.
  • pod_idstring
    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_positioninteger
    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.
  • pod_lengthinteger
    The number of ad assets in the ad-pod
  • typestring
    The ad type. Values can include pre-roll, mid-roll, and post-roll.
    Accepted values: pre-roll, mid-roll, post-roll
  • titlestring
    The title of the ad.
  • positioninteger
    The current index position in seconds of the playhead, with respect to the length of the ad.
  • total_lengthinteger
    The total duration of the ad in seconds.
  • publisherstring
    The ad's publisher.
  • load_typestring
    Set to dynamic if you insert ads dynamically and linear if ads are the same for all viewers.
    Accepted values: dynamic, linear
  • contentobject
    For video destinations that require you to send content metadata with ad events, you can send all the content metadata in this object—like content.title, etc.
  • quartileinteger
    Specifies the quartile of the ad that a viewer reached. If you use our client-side libraries, we'll automatically track this for you.

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.

  • bitrateinteger
    The current kbps.
  • framerateinteger
    The average frames per second (fps).
  • startupTimeinteger
    The time it takes for the video to start playing.
  • droppedFramesinteger
    The number of frames dropped during playback.
Updated August 20, 2026