Video events

Learn the syntax and general conventions for sending events when tracking videos.

RudderStack’s video specification lets you define how a customer engages with your videos and the related ad content.

This documentation lists the conventions and best practices for sending events in case of video tracking videos. It will also clarify the overall structure and classification of these events.

warning
Not all RudderStack destinations support video tracking. Refer to the individual destination’s documentation to check if it supports this feature.

This guide is organized into the following three event categories:

  • Playback
  • Content
  • Ads

Playback

The playback events are associated with the actual playback of the video content and track the information about the video player.

For example, when a customer plays a video on your app, a Video Playback Started event is sent along with a unique session_id. All subsequent events generated from this session are tied to this same session_id.

Suppose if you have a web page with two video players, you would have two separate sessions and session_id associated with them. On the other hand, two separate videos played on the same video player would still constitute a single session with two contents associated with it.

info
All the playback events are tracked and recorded at the session level.

Playback events

This section details all video playback events.

info
For more information on each of the properties associated with these events, refer to the Playback Event Properties section.

Video Playback Started

This event is associated with the user action of pressing the play button on the video player to initiate the video playback.

A sample event is as shown below:

{
    "type": "track",
    "event": "Video Playback Started",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "content_asset_ids": ["0129370"],
      "content_pod_ids": ["RudderA", "RudderB"],
      "ad_asset_id": ["ad1", "ad0"],
      "ad_pod_id": ["adRudderA", "adRudderB"],
      "ad_type": ["mid-roll", "post-roll"],
      "position": 0,
      "total_length": 300,
      "bitrate": 128,
      "framerate": 30.00,
      "video_player": "youtube",
      "sound": 68,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}

Video Playback Paused

This event corresponds to the user action of pausing the video playback.

A sample event is as shown:

{
    "type": "track",
    "event": "Video Playback Paused",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "content_asset_ids": ["0129370"],
      "content_pod_ids": ["RudderA", "RudderB"],
      "position": 0,
      "total_length": 300,
      "bitrate": 128,
      "framerate": 30.00,
      "video_player": "youtube",
      "sound": 68,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}

Video Playback Interrupted

This event is sent when the video playback stops unintentionally. Network loss, user closing the browser, redirect, etc. are some of the common reasons. You can pass the cause within the property method.

A sample event is as shown:

{
    "type": "track",
    "event": "Video Playback Interrupted",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "content_asset_ids": ["0129370"],
      "content_pod_ids": ["RudderA", "RudderB"],
      "position": 0,
      "total_length": 300,
      "bitrate": 128,
      "framerate": 30.00,
      "video_player": "youtube",
      "sound": 68,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false,
      "method":"network loss"
    }
}

Video Playback Buffer Started

This corresponds to the event of buffering content or an advertisement.

A sample event is as shown:

{
    "type": "track",
    "event": "Video Playback Buffer Started",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "content_asset_ids": ["0129370"],
      "content_pod_ids": ["RudderA", "RudderB"],
      "position": 0,
      "total_length": 300,
      "bitrate": 128,
      "framerate": 30.00,
      "video_player": "youtube",
      "sound": 68,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}

Video Playback Buffer Completed

This corresponds to the event when the playback finishes buffering the content or an advertisement.

A sample event is as shown:

{
    "type": "track",
    "event": "Video Playback Buffer Completed",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "content_asset_ids": ["0129370"],
      "content_pod_ids": ["RudderA", "RudderB"],
      "position": 0,
      "total_length": 300,
      "bitrate": 128,
      "framerate": 30.00,
      "video_player": "youtube",
      "sound": 68,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}

Video Playback Seek Started

This event is sent when a user manually seeks a certain position of the video content or an advertisement in the playback. The position property indicates where the user is seeking from (time in seconds) and the seek_position indicates the position in the playback where the user is seeking to.

A sample event is as shown:

{
    "type": "track",
    "event": "Video Playback Seek Started",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "content_asset_ids": ["0129370"],
      "content_pod_ids": ["RudderA", "RudderB"],
      "position": 47,
      "seek_position": 120,
      "total_length": 300,
      "bitrate": 128,
      "framerate": 30.00,
      "video_player": "youtube",
      "sound": 68,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}

Video Playback Seek Completed

This event is sent after a user manually seeks to a certain position of the video or ad in the playback. The position property indicates where the user resumes the playback.

A sample event is as shown:

{
    "type": "track",
    "event": "Video Playback Seek Completed",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "content_asset_ids": ["0129370"],
      "content_pod_ids": ["RudderA", "RudderB"],
      "position": 120,
      "total_length": 300,
      "bitrate": 128,
      "framerate": 30.00,
      "video_player": "youtube",
      "sound": 68,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}

Video Playback Resumed

This event is sent after the user resumes the video playback after it was paused.

A sample event is as shown:

{
    "type": "track",
    "event": "Video Playback Resumed",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "content_asset_ids": ["0129370"],
      "content_pod_ids": ["RudderA", "RudderB"],
      "position": 120,
      "total_length": 300,
      "bitrate": 128,
      "framerate": 30.00,
      "video_player": "youtube",
      "sound": 68,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}

Video Playback Completed

This event is sent after the playback is complete and when the session is finished. Note that the position property has the same value as the total_length property.

A sample event is as shown:

{
    "type": "track",
    "event": "Video Playback Resumed",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "content_asset_ids": ["0129370"],
      "content_pod_ids": ["RudderA", "RudderB"],
      "position": 300,
      "total_length": 300,
      "bitrate": 128,
      "framerate": 30.00,
      "video_player": "youtube",
      "sound": 68,
      "full_screen": true,
      "ad_enabled": true,
      "quality": "hd1080",
      "livestream": false
    }
}

Playback event properties

All playback events share the same properties that describe the current state of the video player.

The following table lists the properties of this playback event object in detail:

PropertyTypeDescription
session_idStringA unique ID that ties all events generated from a specific playback session. These events include playback, content, and ad events.
content_asset_id or content_asset_idsString or Array [String]Content asset ID/s of the video/s playing or about to be played. For Video Playback Started events, an array of unique asset IDs should be sent. For other playback events, a singular content asset ID at the time of the event should be sent.
content_pod_id or content_pod_idsString or Array [String]Content pod ID/s of the video/s playing or about to be played. For Video Playback Started events, an array of unique pod IDs should be sent. For other playback events, a singular content pod ID associated with the current content pod at the time of the event should be sent.
ad_asset_idString or Array [String]Ad asset ID/s of the video/s playing or about to be played. For Video Playback Started events, an array of unique ad asset IDs should be sent. For other playback events, a singular ad asset ID at the time of the event should be sent.
ad_pod_idString or Array [String]Ad pod ID/s of the video/s playing or about to be played. For Video Playback Started events, an array of unique ad pod IDs should be sent. For other playback events, a singular ad pod ID at the time of the event should be sent.
ad_typeEnumDenotes the type of ad playing at the time of the event. The values can be pre-roll, mid-roll, and post-roll.
positionIntegerDenotes the current index position of the playhead in seconds. It includes the duration of any seen ads. If the playback is a livestream, refer to the documentation of the relevant destination for steps on correctly passing the playhead position.
seek_positionIntegerDenotes the index position of the playhead where the user is seeking to. Only applicable on the Video Playback Seek Started events. On Video Playback Seek Completed events, the seek_position should be equal to position.
total_lengthIntegerDenotes the total duration of the video playback in seconds. Includes the whole duration of all content and ads included in the session. Set to null in case of a livestream playback.
bitrateIntegerBit rate of the video playback, denoted in kbps.
framerateFloatDenotes the average frame rate of the video playback in fps.
video_playerStringDenotes the name of the video player used for playback. Example: youtube, vimeo, etc.
soundIntegerDenotes the sound level of the video playback. Range is from 0-100, where 0 represents mute and 100 is full volume.
full_screenBooleanSet to true if the playback is in fullscreen mode.
ad_enabledBooleanSet to false if the user has any ad blockers. If the user can view your video ads, it is set to true.
qualityStringSpecifies the quality of the video. Examples: hd1080, highres
methodStringFor the Video Playback Interrupted events, you can send this property denoting how the playback was interrupted. Some examples include device lock, call, and browser redirect.
livestreamBooleanSet to true in case the playback is a live stream, else set to false.

Content

A content pod refers to a part / group / segment of the video content or the advertisement within the playback.

Suppose a video playback session has a video and one mid-roll advertisement. This means that the mid-roll ad splits the playback in two separate content pods. The mid-roll ad is included within a single ad pod.

The flow is as follows:

  • User starts and completes the first content pod
  • User starts and completes the ad
  • User starts and completes the second content pod
info
All of these events within the flow happen within one video playback.

Content events

This section details all video content events.

info
For more information on each of the properties associated with these events, refer to the Content Event Properties section.

Video Content Started

This event is sent once the user starts playing video content segment within a playback.

A sample event is as shown:

{
    "type": "track",
    "event": "Video Content Started",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "asset_id": "123",
      "pod_id": "RudderA",
      "program": "Planet of the Apes",
      "title": "Introduction",
      "description": "Sample description",
      "season": "3",
      "position": 0,
      "total_length": 300,
      "genre": "Fantasy",
      "publisher": "Amazon",
      "full_episode": true,
      "keywords": ["apes", "forests", "zoo"]
    }
}

Video Content Playing

These events are sent as heartbeats every after a set interval to indicate the length of video viewed by the user, determined by the position property.

A sample event is as shown:

{
    "type": "track",
    "event": "Video Content Playing",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "asset_id": "123",
      "pod_id": "RudderA",
      "program": "Planet of the Apes",
      "title": "Introduction",
      "description": "Sample description",
      "season": "3",
      "position": 234,
      "total_length": 300,
      "genre": "Fantasy",
      "publisher": "Amazon",
      "full_episode": true,
      "keywords": ["apes", "forests", "zoo"]
    }
}

Video Content Completed

This event is sent once the video segment within the playback is completed. Note that the position property has the same value as the total_length property.

A sample event is as shown:

{
    "type": "track",
    "event": "Video Content Completed",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "asset_id": "123",
      "pod_id": "RudderA",
      "program": "Planet of the Apes",
      "title": "Introduction",
      "description": "Sample description",
      "season": "3",
      "position": 300,
      "total_length": 300,
      "genre": "Fantasy",
      "publisher": "Amazon",
      "full_episode": true,
      "keywords": ["apes", "forests", "zoo"]
    }
}

Content event properties

All the content events share the same properties that describe the current state of the video content that is viewed by the user during the playback.

The following table lists all properties of this playback event object in detail:

PropertyTypeDescription
session_idStringA unique ID that ties all events generated from a specific playback session. These events include playback, content, and ad events.
asset_idStringDenotes the unique ID of the video content asset.
pod_idStringDenotes the unique ID of the video content pod.
titleStringDenotes the title of the video content.
descriptionStringDescribes the video content asset in short.
keywordsArray [String]Denotes the relevant keywords associated with the categorizing the video content
seasonStringDenotes the season number, if applicable.
episodeStringDenotes the episode number, if applicable.
genreStringDenotes the genre of the video content asset.
programStringDenotes the name of the program / show of which the video content is a part.
publisherStringDenotes the publisher / creator / author of the video content asset.
channelStringDenotes the channel in which the video content is playing.
full_episodeBooleanSet to true the video content asset is a full episode.
livestreamBooleanIf the video content is a live stream, this is set to true.
airdateISO 8601 Date StringDenotes the original date of airing / publishing the video content.
positionIntegerDenotes the current playhead position into the video content in seconds. This does not include any ads played in this duration. In case of live streams, refer to the relevant destination’s documentation for details on how to pass this property.
total_lengthIntegerThe total duration of the video content in seconds. This does not include any ads included in the playback of this content asset. For livestream playback, this should be set to null.
bitrateIntegerDenotes the current bit rate in kbps.
framerateFloatDenotes the frame rate in fps.

Ads

Ad events

This section details all ad events.

info
For more information on each of the properties associated with these events, refer to the Ad Event Properties section.

Video Ad Started

This event is sent when an advertisement starts playing within the video playback.

A sample event is as shown:

{
    "type": "track",
    "event": "Video Ad Started",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "asset_id": "123",
      "pod_id": "RudderA",
      "type": "mid-roll",
      "title": "Our Planet",
      "position": 0,
      "total_length": 25,
      "publisher": "BBC",
      "load_type": "linear"
    }
}

Video Ad Playing

This event is sent between set intervals when the video ad is playing and is determined by the position property.

A sample event is as shown:

{
    "type": "track",
    "event": "Video Ad Playing",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "asset_id": "123",
      "pod_id": "RudderA",
      "type": "pre-roll",
      "title": "Our Planet",
      "position": 3,
      "total_length": 25,
      "publisher": "BBC",
      "load_type": "linear"
    }
}

Video Ad Completed

This event is sent after the user has viewed the video ad completely. Note that the position property has the same value as the total_length property.

{
    "type": "track",
    "event": "Video Ad Completed",
    "userId": "user12345",
    "properties": {
      "session_id": "12345",
      "asset_id": "123",
      "pod_id": "RudderA",
      "type": "pre-roll",
      "title": "Our Planet",
      "position": 25,
      "total_length": 25,
      "publisher": "BBC",
      "load_type": "linear"
    }
}

Ad event properties

All the ad events share the same properties that describe the current state of the video ad content that a user is interacting with during the playback.

The following table lists all properties of this playback event object in detail:

PropertyTypeDescription
session_idStringA unique ID that ties all events generated from a specific playback session. These events include playback, content, and ad events.
asset_idStringDenotes the unique ID of the ad asset.
pod_idStringDenotes the unique ID of the ad pod.
pod_positionIntegerDenotes the position of the ad asset relative to other ads in the same pod.
pod_lengthIntegerDenotes the number of ad assets in the current ad pod.
typeEnumDenotes the type of ad. Values can be either of pre-roll, mid-roll, or post-roll.
titleStringDenotes the title of the ad.
publisherStringDenotes the author/ creator/ publisher of the ad.
positionIntegerThe current playhead position in relation to the total length of the ad, in seconds.
total_lengthIntegerDenotes the total length of the ad asset in seconds.
load_typeEnumDenotes if the ads are loaded dynamically or if they are the same for all users. Values can be either dynamic or linear.
contentObjectSome destinations require the content metadata to be sent with the ad events. You can send all metadata as a Content Event Object under this property.
quartileIntegerFor the Video Ad Playing event, this property can be used to indicate when a specific ad quartile is reached. If you are using a client-side library to track your video events, this property is optional as RudderStack automatically tracks the ad quartiles.

Resuming playback

Every Video Playback Resumed the event should be followed by a heartbeat event (Video Content Playing or a Video Ad Playing event, depending on what asset the playback resumes to.

Video quality

RudderStack also lets you track and analyze the performance and quality of your video content during the playback.

Whenever a user changes the video quality during playback, you can track a Video Quality Updated event along with the following properties:

  • bitrate: Denotes the updated bit rate in kbps.
  • framerate: Denotes the updated frame rate in fps.
  • startupTime: Denotes the time when the video quality was changed by the user.
  • droppedFrames: Indicates if any frames were dropped during the video quality change.

Events lifecycle

The following event flow demonstrates how you can implement the RudderStack video specification:

1. User presses play on a video player

rudderanalytics.track("Video Playback Started", {
  session_id: "12345",
  content_asset_ids: ["123"],
  content_pod_ids: ["RudderA"],
  ad_asset_ids: ["ad1"],
  ad_pod_ids: ["adRudderA"],
  ad_types: ["mid-roll"],
  position: 0,
  total_length: 300,
  bitrate: 128,
  video_player: "youtube",
  sound: 66,
  full_screen: true,
  ad_enabled: false,
  quality: "hd1080",
})

2. Video playback starts playing the content

rudderanalytics.track("Video Content Started", {
  session_id: "12345",
  asset_id: "123",
  pod_id: "RudderA",
  title: "Our Planet!",
  description: "Sample description",
  keywords: ["nature", "entertainment"],
  season: "1",
  episode: "90",
  genre: "entertainment",
  program: "BBC",
  publisher: "BBC",
  position: 0,
  total_length: 300,
  channel: "ten",
  full_episode: true,
  livestream: false,
  airdate: "2020-04-23",
})

3. User views the content for 10 seconds followed by a 10 second heartbeat

rudderanalytics.track("Video Content Playing", {
  session_id: "12345",
  asset_id: "123",
  pod_id: "RudderA",
  title: "Our Planet!",
  description: "Sample description",
  keywords: ["nature", "entertainment"],
  season: "1",
  episode: "90",
  genre: "entertainment",
  program: "BBC",
  publisher: "BBC",
  position: 10,
  total_length: 300,
  channel: "ten",
  full_episode: true,
  livestream: false,
  airdate: "2020-04-23",
})

4. Video playback is paused

rudderanalytics.track("Video Playback Paused", {
  session_id: "12345",
  content_asset_id: "123",
  content_pod_id: "RudderA",
  ad_asset_id: null,
  ad_pod_id: null,
  ad_type: null,
  position: 11,
  total_length: 300,
  video_player: "youtube",
  sound: 66,
  bitrate: 128,
  full_screen: true,
  ad_enabled: false,
  quality: "hd1080",
})

5. User resumes the video playback

rudderanalytics.track("Video Playback Resumed", {
  session_id: "12345",
  content_asset_id: "123",
  content_pod_id: "RudderA",
  ad_asset_id: null,
  ad_pod_id: null,
  ad_type: null,
  position: 11,
  total_length: 300,
  video_player: "youtube",
  sound: 66,
  bitrate: 128,
  full_screen: true,
  ad_enabled: false,
  quality: "hd1080",
})

6. Ad (mid-roll) starts playing after user resumes playback

rudderanalytics.track("Video Ad Started", {
  session_id: "12345",
  asset_id: "ad1",
  pod_id: "adRudderA",
  type: "mid-roll",
  title: "Thums Up",
  publisher: "Coca Cola",
  position: 0,
  total_length: 15,
  load_type: "linear",
})

7. User watches the complete 15 second advertisement. RudderStack also tracks the 10 second heartbeats

rudderanalytics.track("Video Ad Playing", {
  session_id: "12345",
  asset_id: "ad1",
  pod_id: "adRudderA",
  type: "mid-roll",
  title: "Thums Up",
  publisher: "Coca Cola",
  position: 10,
  total_length: 15,
  load_type: "linear",
})

8. Video ad plays completely

rudderanalytics.track("Video Ad Completed", {
  session_id: "12345",
  asset_id: "ad1",
  pod_id: "adRudderA",
  type: "mid-roll",
  title: "Thums Up",
  publisher: "Coca Cola",
  position: 15,
  total_length: 15,
  load_type: "linear",
})

9. Video content resumes playing. Heartbeats are sent every 10 seconds

rudderanalytics.track("Video Content Playing", {
  session_id: "12345",
  asset_id: "123",
  pod_id: "RudderA",
  title: "Our Planet!",
  description: "Sample description",
  keywords: ["nature", "entertainment"],
  season: "1",
  episode: "90",
  genre: "entertainment",
  program: "BBC",
  publisher: "BBC",
  position: 11,
  total_length: 300,
  channel: "ten",
  full_episode: true,
  livestream: false,
  airdate: "2020-04-23",
})

10. User finishes watching the entire video content.

rudderanalytics.track("Video Content Completed", {
  session_id: "12345",
  asset_id: "123",
  pod_id: "RudderA",
  title: "Our Planet!",
  description: "Sample description",
  keywords: ["nature", "entertainment"],
  season: "1",
  episode: "90",
  genre: "entertainment",
  program: "BBC",
  publisher: "BBC",
  position: 300,
  total_length: 300,
  channel: "ten",
  full_episode: true,
  livestream: false,
  airdate: "2020-04-23",
})

11. Video playback finishes

rudderanalytics.track("Video Playback Completed", {
  session_id: "12345",
  content_asset_id: null,
  content_pod_id: null,
  ad_asset_id: "ad1",
  ad_pod_id: "adRudderA",
  ad_type: null,
  position: 300,
  total_length: 300,
  sound: 66,
  bitrate: 128,
  full_screen: true,
  video_player: "youtube",
  ad_enabled: false,
  quality: "hd1080",
})

FAQ

What are pre-roll, mid-roll, and post-roll ads?

  • Ads that appear before the start of the video playback are called pre-roll ads.
  • Ads that appear in the middle of the playback are mid-roll ads.
  • Ads that appear after the video playback are called post-roll ads.

These ads can be a promotional video by the sponsors or a piece of content offered by the content provider.

Questions? Contact us by email or on Slack