Video Spec
Segment’s video spec helps you define how customers engage with your video and ad content. This document covers the naming syntax and conventions for how you should send events when tracking video analytics.
Note: not all destinations support video tracking, and you should always check with the individual destination documentation to confirm.
Getting started
Before you start implementing the Segment video spec, you should understand the overall structure and classification of events. The video spec will be organized into three distinct event categories:
Playback
You can think of playback events being related to the actual playback of the video content. This means that these events are meant to track information about the video player (such as pause, resume, or play). Thus, you can think of playback events to be at the session level. For example, when a customer presses play on your video, you would start by sending a Video Playback Started event with a unique session_id
. In particular, this event should fire after the last user action required for playback to begin.
Then, for the duration of that user’s session with that specific video player, all
subsequent events generated from this session/playback should be tied with the same aforementioned session_id
. So if you had a web page that had two video players, you would have two separate sessions and session_ids
while contrastingly if you only had one video player on the page but the playback played two video contents in a row, you would only have one session but two contents tied to it.
Playback event object
All playback events share the same event properties that describe information about the current state of the player. Below is a table of the supported properties of this object.
Property | Type | Description |
---|---|---|
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. |
content_asset_id , content_asset_ids |
String, Array[string] | The Content Asset Id(s) of the video/videos playing or about to be played in the video player. For Video Playback Started events only, you should send the plural form with an Array of unique asset IDs. For all other playback events, you should send the singular form with the ID of the current content asset playing at the time of the event. |
content_pod_id , content_pod_ids |
String, Array[string] | The Content Pod Id(s) of the video/videos playing or about to be played in the video player. For Video Playback Started events only, you should send the plural form with an Array of unique pod IDs. For all other playback events, you should send the singular form with the ID of the current content pod playing at the time of the event. |
ad_asset_id |
String, Array[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_pod_id |
String, Array[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 |
Enum {pre-roll , mid-roll , post-roll } |
The type of ad playing at the time of the event. Values can include pre-roll , mid-roll , and post-roll . |
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. |
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 . |
bitrate |
Integer | The current kbps . |
framerate |
Float | The average fps . |
video_player |
String | The name of the video player (for example, youtube or vimeo ). |
sound |
Integer | The sound level of the playback represented in a 0 to 100 scale where 0 is muted and 100 is full volume. |
full_screen |
Boolean | true if playback is currently in full screen mode and false otherwise. |
ad_enabled |
Boolean | false if the user has adblock or any other ad blockers, otherwise true if they can view your video ads. |
quality |
String | The quality of the video, for example, highres , hd1080 , or 480p . |
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 ). |
livestream |
Boolean | If the playback will be a livestream, send true , otherwise false . |
Playback events
Below is the full list of Video Playback Events.
Video playback started
When a user presses Play; after the last user action required for playback to begin (for example, after user login/authentication).
{
"action": "track",
"event": "Video Playback Started",
"userId": "userId",
"properties": {
"session_id": "12345",
"content_asset_ids": ["0129370"],
"content_pod_ids": ["segA", "segB"],
"ad_asset_id": ["ad123", "ad097"],
"ad_pod_id": ["adSegA", "adSegB"],
"ad_type": ["mid-roll", "post-roll"],
"position": 0,
"total_length": 392,
"bitrate": 100,
"framerate": 29.00,
"video_player": "youtube",
"sound": 88,
"full_screen": false,
"ad_enabled": true,
"quality": "hd1080",
"livestream": false
}
}
Video playback paused
When a user presses Pause.
{
"action": "track",
"event": "Video Playback Paused",
"userId": "userId",
"properties": {
"session_id": "12345",
"content_asset_id": "0129370",
"content_pod_id": "segA",
"position": 278,
"total_length": 392,
"bitrate": 100,
"framerate": 29.00,
"video_player": "youtube",
"sound": 55,
"full_screen": false,
"ad_enabled": false,
"quality": "hd1080",
"livestream": false
}
}
Video playback interrupted
When the playback stops unintentionally (such as from network loss, browser close/redirect, or app crash). With this event you can pass method
as a property to denote the cause of the interruption.
{
"action": "track",
"event": "Video Playback Interrupted",
"userId": "userId",
"properties": {
"session_id": "12345",
"content_asset_id": "0129370",
"content_pod_id": "segA",
"position": 278,
"total_length": 392,
"bitrate": 100,
"framerate": 29.00,
"video_player": "youtube",
"sound": 55,
"full_screen": false,
"ad_enabled": false,
"quality": "hd1080",
"livestream": false,
"method": "network loss"
}
}
Video playback buffer started
When playback starts buffering content or an ad.
{
"action": "track",
"event": "Video Playback Buffer Started",
"userId": "userId",
"properties": {
"session_id": "12345",
"content_asset_id": "0129370",
"content_pod_id": "segA",
"position": 278,
"total_length": 392,
"bitrate": 100,
"framerate": 29.00,
"video_player": "youtube",
"sound": 55,
"full_screen": false,
"ad_enabled": false,
"quality": "hd1080",
"livestream": false
}
}
Video playback buffer completed
When playback finishes buffering content or an ad.
{
"action": "track",
"event": "Video Playback Buffer Completed",
"userId": "userId",
"properties": {
"session_id": "12345",
"content_asset_id": "0129370",
"content_pod_id": "segA",
"position": 278,
"total_length": 392,
"bitrate": 100,
"framerate": 29.00,
"video_player": "youtube",
"sound": 55,
"full_screen": false,
"ad_enabled": false,
"quality": "hd1080",
"livestream": false
}
}
Video playback seek started
When a user manually seeks a certain position of the content or ad in the playback. Pass in the seek_position
to denote where the user is seeking to, and pass in the position
property to denote where the user is seeking from.
{
"action": "track",
"event": "Video Playback Seek Started",
"userId": "userId",
"properties": {
"session_id": "12345",
"content_asset_id": "0129370",
"content_pod_id": "segA",
"position": 278,
"seek_position": 320,
"total_length": 392,
"bitrate": 100,
"framerate": 29.00,
"video_player": "youtube",
"sound": 55,
"full_screen": false,
"ad_enabled": false,
"quality": "hd1080",
"livestream": false
}
}
Video playback seek completed
After a user manually seeks to a certain position of the content or ad in the playback. Pass in the position
property to denote where the user desires to begin the playback from.
{
"action": "track",
"event": "Video Playback Seek Completed",
"userId": "userId",
"properties": {
"session_id": "12345",
"content_asset_id": "0129370",
"content_pod_id": "segA",
"position": 320,
"total_length": 392,
"bitrate": 100,
"framerate": 29.00,
"video_player": "youtube",
"sound": 55,
"full_screen": false,
"ad_enabled": false,
"quality": "hd1080",
"livestream": false
}
}
Video playback resumed
When playback is resumed, by the user, after being paused.
{
"action": "track",
"event": "Video Playback Resumed",
"userId": "userId",
"properties": {
"session_id": "12345",
"content_asset_id": "0129370",
"content_pod_id": "segA",
"position": 278,
"total_length": 392,
"bitrate": 100,
"framerate": 29.00,
"video_player": "youtube",
"sound": 55,
"full_screen": false,
"ad_enabled": false,
"quality": "hd1080",
"livestream": false
}
}
Video playback completed
When playback is complete and only when the session is finished.
{
"action": "track",
"event": "Video Playback Completed",
"userId": "userId",
"properties": {
"session_id": "12345",
"content_asset_id": "0129370",
"content_pod_id": "segA",
"position": 392,
"total_length": 392,
"bitrate": 100,
"framerate": 29.00,
"video_player": "youtube",
"sound": 55,
"full_screen": false,
"ad_enabled": false,
"quality": "hd1080",
"livestream": false
}
}
Video playback exited
When user navigates away from a playback/stream.
{
"action": "track",
"event": "Video Playback Exited",
"userId": "userId",
"properties": {
"session_id": "12345",
"content_asset_id": "0129370",
"content_pod_id": "segA",
"position": 392,
"total_length": 392,
"bitrate": 100,
"framerate": 29.00,
"video_player": "youtube",
"sound": 55,
"full_screen": false,
"ad_enabled": false,
"quality": "hd1080",
"livestream": false
}
}
Content
Underneath the playback level, we now have the pod level. A pod can be seen as a “group” or “segment” of either the content or advertisement.
Consider, for example, a playback session that might have some content and one mid-roll advertisement. This would mean that you would have two content pods (since the mid-roll ad split the content playback into two sections) while you might have one ad pod for the mid-roll ad. 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.
Content event object
All content events share the same event properties that describe information about the current video content the user is interacting with. Below is a table of the supported properties of this object.
Property | Type | Description |
---|---|---|
session_id |
String | The unique ID of the overall session used to tie all events generated from a specific playback. This value should be same across all playback, content, and ad events if they are from the same playback session. |
asset_id |
String | The unique ID of the content asset. |
pod_id |
String | The unique ID of the content pod. |
title |
String | The title of the video content. |
description |
String | Short description of the video content. |
keywords |
Array[string] | An array of arbitrary keywords or tags that describe or categorize the video content. |
season |
String | The season number if applicable. |
episode |
String | The episode number if applicable. |
genre |
String | The genre of the content. For example,comedy or action . |
program |
String | The name of the content program or show if applicable. |
publisher |
String | The content creator, author, producer, or publisher. |
position |
Integer | The current index position in seconds of the playhead into the content/asset. This position must exclude the duration of any ads played. If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position. |
total_length |
Integer | The total duration of the content/asset in seconds. This should exclude the duration of any ads included in the playback of this asset. For livestream playback, send null . |
channel |
String | The channel in which the video content is playing, such as espn or my blog . |
full_episode |
Boolean | true if content is a full episode and false otherwise. |
livestream |
Boolean | If the playback is a livetream, send true , otherwise false . |
airdate |
ISO 8601 Date String | An ISO 8601 Date String representing the original air date or published date. |
bitrate |
Integer | The current kbps . |
framerate |
Float | The average fps . |
Content events
Below is the full list of Video Content Events.
Video content started
When a video content segment starts playing within a playback.
{
"action": "track",
"event": "Video Content Started",
"userId": "userId",
"properties": {
"session_id": "12345",
"asset_id": "0129370",
"pod_id": "segA",
"program": "Planet Earth",
"title": "Seasonal Forests",
"description": "David Attenborough reveals the greatest woodlands on earth.",
"season": "1",
"position": 0,
"total_length": 3600,
"genre": "Documentary",
"publisher": "BBC",
"full_episode": true,
"keywords": ["nature", "forests", "earth"]
}
}
Video content playing
Heartbeats that you can fire every n seconds to track how far into the content the user is currently viewing as indicated by the position
.
{
"action": "track",
"event": "Video Content Playing",
"userId": "userId",
"properties": {
"session_id": "12345",
"asset_id": "0129370",
"pod_id": "segA",
"program": "Planet Earth",
"title": "Seasonal Forests",
"description": "David Attenborough reveals the greatest woodlands on earth.",
"season": "1",
"position": 10,
"total_length": 3600,
"genre": "Documentary",
"publisher": "BBC",
"full_episode": true,
"keywords": ["nature", "forests", "earth"]
}
}
Video content completed
When a video content segment completes playing within a playback. That is, position
and total_length
are equal.
{
"action": "track",
"event": "Video Content Completed",
"userId": "userId",
"properties": {
"session_id": "12345",
"asset_id": "0129370",
"pod_id": "segA",
"program": "Planet Earth",
"title": "Seasonal Forests",
"description": "David Attenborough reveals the greatest woodlands on earth.",
"season": "1",
"position": 3600,
"total_length": 3600,
"genre": "Documentary",
"publisher": "BBC",
"full_episode": true,
"keywords": ["nature", "forests", "earth"]
}
}
Ads
Just like Content events, Ad Events also live underneath the playback level and at the pod level. A given ad pod can have multiple ad assets (or just one) and a playback session might have multiple ad pods. For example, if your video playback has two pre-roll, one mid-roll, and one post-roll ads, you would have 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
Ad event object
All ad events share the same event properties that describe information about the current ad content the user is interacting with. Below is a table of the supported properties of this object.
Property | Type | Description |
---|---|---|
session_id |
String | The unique ID of the overall session used to tie all events generated from a specific playback. This value should be same across all playback, content, and ad events if they are from the same playback session. |
asset_id |
String | The unique ID of the ad asset. |
pod_id |
String | The unique ID of the ad pod. |
pod_position |
Integer | The position of the ad asset relative to other assets in the same pod. |
pod_length |
Integer | The number of ad assets the current ad pod contains. |
type |
Enum {pre-roll , mid-roll , post-roll } |
The ad type. You can send either pre-roll , mid-roll , or post-roll . |
title |
String | The title of the video ad. |
publisher |
String | The ad creator, author, producer, or publisher. |
position |
Integer | The current index position, in seconds, of the playhead with respect to the length of the ad. |
total_length |
Integer | The total duration of the current ad asset in seconds. |
load_type |
Enum {linear , dynamic } |
dynamic if ads are loaded dynamically and linear if ads are same for all users. |
content |
Object[ContentEventObject] | For video destinations that require content metadata to be sent with ad events, you can send all the content metadata nested under this property (such as content.asset_id or content.title ) as a Content Event Object. |
quartile |
Integer | For Video Ad Playing events, this property can be set to indicate when a specific ad quartile has been reached (1,2, or 3). If you are using a Segment client-side library to track your video events you don’t need to send this property as Segment’s libraries will automatically track quartiles. |
Since some video destinations require sending Content metadata along with Ad metadata, you may need to send your content properties also in all your ad events under properties.content
depending on the video destination you’re using.
Ad events
Video ad started
{
"action": "track",
"event": "Video Ad Started",
"userId": "userId",
"properties": {
"session_id": "12345",
"asset_id": "0129370",
"pod_id": "segA",
"type": "pre-roll",
"title": "The New New Thing!",
"position": 0,
"total_length": 30,
"publisher": "Apple",
"load_type": "dynamic"
}
}
Video ad playing
{
"action": "track",
"event": "Video Ad Playing",
"userId": "userId",
"properties": {
"session_id": "12345",
"asset_id": "0129370",
"pod_id": "segA",
"type": "pre-roll",
"title": "The New New Thing!",
"position": 5,
"total_length": 30,
"publisher": "Apple",
"load_type": "dynamic"
}
}
Video ad completed
{
"action": "track",
"event": "Video Ad Completed",
"userId": "userId",
"properties": {
"session_id": "12345",
"asset_id": "0129370",
"pod_id": "segA",
"type": "pre-roll",
"title": "The New New Thing!",
"position": 30,
"total_length": 30,
"publisher": "Apple",
"load_type": "dynamic"
}
}
Resuming playback
When you fire a Video Playback Resumed event, you should immediately call a Segment heartbeat event (Video Content Playing or Video Ad Playing depending on what the playback resumed to). This should effectively mean that you are also resuming your 10 second heartbeats (since they should’ve been paused after sending Video Playback Paused event).
Video quality event
It’s important to analyze the performance of your video content. To keep track of quality changes, you can track a Video Quality Updated
event when there is a change in video quality with the following properties:
bitrate |
framerate |
startupTime |
droppedFrames |
Example event lifecycle
Below is an example of how one might implement the video spec:
1) User presses play on a video:
analytics.track('Video Playback Started', {
session_id: '12345',
content_asset_ids: ['0129370'],
content_pod_ids: ['segA', 'segB'],
ad_asset_ids: [ 'ad123', 'ad097' ],
ad_pod_ids: ['adSegA', 'adSegB'],
ad_types: ['mid-roll', 'post-roll'],
position: 0,
total_length: 392,
bitrate: 100,
video_player: 'youtube',
sound: 88,
full_screen: false,
ad_enabled: false,
quality: 'hd1080'
});
2) Playback starts to play content:
analytics.track('Video Content Started', {
session_id: '12345',
asset_id: '0129370',
pod_id: 'segA',
title: 'Interview with Tony Robbins',
description: 'short description',
keywords: ['entrepreneurship', 'motivation'],
season: '2',
episode: '177',
genre: 'entrepreneurship',
program: 'Tim Ferris Show',
publisher: 'Tim Ferris',
position: 0,
total_length: 360,
channel: 'espn',
full_episode: true,
livestream: false,
airdate: '1991-08-13'
});
3) User views content for 20 seconds and we have 10 second heartbeats:
analytics.track('Video Content Playing', {
session_id: '12345',
asset_id: '0129370',
pod_id: 'segA',
title: 'Interview with Tony Robbins',
description: 'short description',
keywords: ['entrepreneurship', 'motivation'],
season: '2',
episode: '177',
genre: 'entrepreneurship',
program: 'Tim Ferris Show',
publisher: 'Tim Ferris',
position: 10,
total_length: 360,
channel: 'espn',
full_episode: true,
livestream: false,
airdate: '1991-08-13'
});
analytics.track('Video Content Playing', {
session_id: '12345',
asset_id: '0129370',
pod_id: 'segA',
title: 'Interview with Tony Robbins',
description: 'short description',
keywords: ['entrepreneurship', 'motivation'],
season: '2',
episode: '177',
genre: 'entrepreneurship',
program: 'Tim Ferris Show',
publisher: 'Tim Ferris',
position: 20,
total_length: 360,
channel: 'espn',
full_episode: true,
livestream: false,
airdate: '1991-08-13'
});
4) Playback is paused and resumed:
analytics.track('Video Playback Paused', {
session_id: '12345',
content_asset_id: '0129370',
content_pod_id: 'segA',
ad_asset_id: null,
ad_pod_id: null,
ad_type: null,
position: 21,
total_length: 392,
video_player: 'youtube',
sound: 88,
bitrate: 100,
full_screen: false,
ad_enabled: false,
quality: 'hd1080'
});
analytics.track('Video Playback Resumed', {
session_id: '12345',
content_asset_id: '0129370',
content_pod_id: 'segA',
ad_asset_id: null,
ad_pod_id: null,
ad_type: null,
position: 21,
total_length: 392,
sound: 88,
bitrate: 100,
full_screen: false,
video_player: 'youtube',
ad_enabled: false,
quality: 'hd1080'
});
5) Mid-roll ad starts playing:
analytics.track('Video Ad Started', {
session_id: '12345',
asset_id: 'ad123',
pod_id: 'adSegA',
type: 'mid-roll',
title: 'Segment Connection Modes',
publisher: 'Segment',
position: 0,
total_length: 21,
load_type: 'dynamic'
});
6) User watches the full 21 second ad and we have 10 second heartbeats:
analytics.track('Video Ad Playing', {
session_id: '12345',
asset_id: 'ad123',
pod_id: 'adSegA',
type: 'pre-roll',
title: 'Segment Connection Modes',
publisher: 'Segment',
position: 10,
total_length: 21,
load_type: 'dynamic'
});
analytics.track('Video Ad Playing', {
session_id: '12345',
asset_id: 'ad123',
pod_id: 'adSegA',
type: 'pre-roll',
title: 'Segment Connection Modes',
publisher: 'Segment',
position: 20,
total_length: 21,
load_type: 'dynamic'
});
analytics.track('Video Ad Completed', {
session_id: '12345',
asset_id: 'ad123',
pod_id: 'adSegA',
type: 'pre-roll',
title: 'Segment Connection Modes',
publisher: 'Segment',
position: 21,
total_length: 21,
load_type: 'dynamic'
});
7) Content resumes, user finishes the full content:
analytics.track('Video Content Playing', {
session_id: '12345',
asset_id: '0129370',
pod_id: 'segB',
title: 'Interview with Tony Robbins',
description: 'short description',
keywords: ['entrepreneurship', 'motivation'],
season: '2',
episode: '177',
genre: 'entrepreneurship',
program: 'Tim Ferris Show',
publisher: 'Tim Ferris',
position: 31,
total_length: 360,
channel: 'espn',
full_episode: true,
livestream: false,
airdate: '1991-08-13'
});
(Video Content Playing
hearbeats every 10 seconds)
analytics.track('Video Content Completed', {
session_id: '12345',
asset_id: '0129370',
pod_id: 'segB',
title: 'Interview with Tony Robbins',
description: 'short description',
keywords: ['entrepreneurship', 'motivation'],
season: '2',
episode: '177',
genre: 'entrepreneurship',
program: 'Tim Ferris Show',
publisher: 'Tim Ferris',
position: 360,
total_length: 360,
channel: 'espn',
full_episode: true,
livestream: false,
airdate: '1991-08-13'
});
8) 11 second post-roll ad plays after content finishes:
analytics.track('Video Ad Started', {
session_id: '12345',
asset_id: 'ad097',
pod_id: 'adSegB',
type: 'post-roll',
title: 'Segment Cross Domain IDs',
publisher: 'Segment',
position: 0,
total_length: 11,
load_type: 'dynamic'
});
analytics.track('Video Ad Playing', {
session_id: '12345',
asset_id: 'ad097',
pod_id: 'adSegB',
type: 'post-roll',
title: 'Segment Cross Domain IDs',
publisher: 'Segment',
position: 10,
total_length: 11,
load_type: 'dynamic'
});
analytics.track('Video Ad Completed', {
session_id: '12345',
asset_id: 'ad097',
pod_id: 'adSegB',
type: 'post-roll',
title: 'Segment Cross Domain IDs',
publisher: 'Segment',
position: 11,
total_length: 11,
load_type: 'dynamic'
});
9) Playback finishes:
analytics.track('Video Playback Completed', {
session_id: '12345',
content_asset_id: null,
content_pod_id: null,
ad_asset_id: 'ad907',
ad_pod_id: 'adSegB',
ad_type: null,
position: 392,
total_length: 392,
sound: 88,
bitrate: 100,
full_screen: false,
video_player: 'youtube',
ad_enabled: false,
quality: 'hd1080'
});
Below is an example of how a playback that has three mid-roll ads interspersed within the content:
This page was last modified: 25 Oct 2023
Need support?
Questions? Problems? Need more info? Contact Segment Support for assistance!