Platform X Documentation Welcome to Success

Video events

PreviousE-commerce events NextCampaign Tracking events

Last updated 4 months ago

Commanders Act's video specification lets you define how a customer engages with your videos and the related ad content.

This documentation details the conventions and best practices for sending events when tracking videos. The document clarifies the structure and classification of these events, which fall into four categories: Playback, Content, Ads and Video Settings.

Playback

Playback events are tied to the actual playback of video content and track information about the video player.

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

If a web page has two video players, there will be two separate sessions and associated session_ids. However, if two separate videos are played on the same video player, they will still be considered a single session with two associated pieces of content.

Playback Events Properties

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

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

Property

Type

Required

Description

Playback Events

This section details all the video playback events.

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:

{
    "event_name": "video_start",
    "user": {},
    "video_session_id": "98765",
    "content_asset_id": ["0133370", "123456"],
    "content_pod_id": ["CAA", "CAB", "CAD"],
    "ad_asset_id": ["ad1", "ad0", "ad2"],
    "ad_pod_id": ["adCAA", "adCAB", "adCAD"],
    "ad_type": "pre-roll",
    "cursor_position": 0,
    "total_length": 600,
    "bitrate": 128,
    "framerate": 60.00,
    "video_player": "vimeo",
    "sound": 100,
    "full_screen": false,
    "ad_enabled": false,
    "image_quality": "hd720",
    "livestream": true
}

val playbackVideoEvent = TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_start, "YOUR_VIDEO_SESSION_ID")
playbackVideoEvent.contentAssetID = listOf("456", "223")
playbackVideoEvent.cursorPosition = 0
playbackVideoEvent.totalLength = 500
serverSide.execute(playbackVideoEvent)

TCVideoPlaybackEvent playbackVideoEvent = new TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_start, "YOUR_VIDEO_SESSION_ID");
playbackVideoEvent.contentAssetID = Arrays.asList("456", "223");
playbackVideoEvent.cursorPosition = 0;
playbackVideoEvent.totalLength = 500;
serverSide.execute(playbackVideoEvent);

    TCVideoPlaybackEvent *playbackVideoEvent = [[TCVideoPlaybackEvent alloc] initWithMode: video_start andSessionId: @"YOUR_VIDEO_SESSION_ID"];
    playbackVideoEvent.contentAssetID =  [@[@"456", @"223"] mutableCopy];
    playbackVideoEvent.cursorPosition = [[NSDecimalNumber alloc] initWithInt: 0];
    playbackVideoEvent.totalLength = [[NSDecimalNumber alloc] initWithInt: 500];;
    [serverside execute: playbackVideoEvent];

let playbackVideoEvent = TCVideoPlaybackEvent(mode: video_start, andSessionId: "YOUR_VIDEO_SESSION_ID")
    playbackVideoEvent?.contentAssetID = ["456", "223"]
    playbackVideoEvent?.cursorPosition = 0
    playbackVideoEvent?.totalLength = 500
    serverSide?.execute(playbackVideoEvent)

Video Playback Paused

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

A sample event is as shown:

{
    "event_name": "video_pause",
    "user": {},
    "video_session_id": "98765",
    "content_asset_id": ["0123370", "123456"],
    "content_pod_id": ["CAA", "CAB", "CAD"],
    "cursor_position": 10,
    "total_length": 600,
    "bitrate": 256,
    "framerate": 60.00,
    "video_player": "vimeo",
    "sound": 100,
    "full_screen": false,
    "ad_enabled": false,
    "image_quality": "hd720",
    "livestream": true
}

val playbackVideoEvent = TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_pause, "YOUR_VIDEO_SESSION_ID")
playbackVideoEvent.contentAssetID = listOf("456", "223")
playbackVideoEvent.cursorPosition = 0
playbackVideoEvent.totalLength = 500
serverSide.execute(playbackVideoEvent)

TCVideoPlaybackEvent playbackVideoEvent = new TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_pause, "YOUR_VIDEO_SESSION_ID");
playbackVideoEvent.contentAssetID = Arrays.asList("456", "223");
playbackVideoEvent.cursorPosition = 0;
playbackVideoEvent.totalLength = 500;
serverSide.execute(playbackVideoEvent);

    TCVideoPlaybackEvent *playbackVideoEvent = [[TCVideoPlaybackEvent alloc] initWithMode: video_pause andSessionId: @"YOUR_VIDEO_SESSION_ID"];
    playbackVideoEvent.contentAssetID =  [@[@"456", @"223"] mutableCopy];
    playbackVideoEvent.cursorPosition = [[NSDecimalNumber alloc] initWithInt: 0];
    playbackVideoEvent.totalLength = [[NSDecimalNumber alloc] initWithInt: 500];;
    [serverside execute: playbackVideoEvent];

let playbackVideoEvent = TCVideoPlaybackEvent(mode: video_pause, andSessionId: "YOUR_VIDEO_SESSION_ID")
    playbackVideoEvent?.contentAssetID = ["456", "223"]
    playbackVideoEvent?.cursorPosition = 0
    playbackVideoEvent?.totalLength = 500
    serverSide?.execute(playbackVideoEvent)

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 interruption_method.

A sample event is as shown:

{
    "event_name": "video_error",
    "user": {},
    "video_session_id": "12345",
    "content_asset_id": ["0144370"],
    "content_pod_id": ["CAA", "CAB"],
    "cursor_position": 0,
    "total_length": 300,
    "bitrate": 128,
    "framerate": 30.00,
    "video_player": "youtube",
    "sound": 68,
    "full_screen": true,
    "ad_enabled": true,
    "image_quality": "hd1080",
    "livestream": false,
    "interruption_method":"network_loss"
}

val playbackVideoEvent = TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_error, "YOUR_VIDEO_SESSION_ID")
playbackVideoEvent.contentAssetID = listOf("456", "223")
playbackVideoEvent.cursorPosition = 0
playbackVideoEvent.totalLength = 500
serverSide.execute(playbackVideoEvent)

TCVideoPlaybackEvent playbackVideoEvent = new TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_error, "YOUR_VIDEO_SESSION_ID");
playbackVideoEvent.contentAssetID = Arrays.asList("456", "223");
playbackVideoEvent.cursorPosition = 0;
playbackVideoEvent.totalLength = 500;
serverSide.execute(playbackVideoEvent);

    TCVideoPlaybackEvent *playbackVideoEvent = [[TCVideoPlaybackEvent alloc] initWithMode: video_error andSessionId: @"YOUR_VIDEO_SESSION_ID"];
    playbackVideoEvent.contentAssetID =  [@[@"456", @"223"] mutableCopy];
    playbackVideoEvent.cursorPosition = [[NSDecimalNumber alloc] initWithInt: 0];
    playbackVideoEvent.totalLength = [[NSDecimalNumber alloc] initWithInt: 500];;
    [serverside execute: playbackVideoEvent];

let playbackVideoEvent = TCVideoPlaybackEvent(mode: video_error, andSessionId: "YOUR_VIDEO_SESSION_ID")
    playbackVideoEvent?.contentAssetID = ["456", "223"]
    playbackVideoEvent?.cursorPosition = 0
    playbackVideoEvent?.totalLength = 500
    serverSide?.execute(playbackVideoEvent)

Video Playback Buffer Started

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

A sample event is as shown:

{
    "event_name": "video_buffer_start",
    "user": {},
    "video_session_id": "54321",
    "content_asset_id": ["098765"],
    "content_pod_id": ["CAD", "CAE"],
    "cursor_position": 10,
    "total_length": 600,
    "bitrate": 256,
    "framerate": 60.00,
    "video_player": "vimeo",
    "sound": 100,
    "full_screen": false,
    "ad_enabled": false,
    "image_quality": "hd720",
    "livestream": true
}

val playbackVideoEvent = TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_buffer_start, "YOUR_VIDEO_SESSION_ID")
playbackVideoEvent.contentAssetID = listOf("456", "223")
playbackVideoEvent.cursorPosition = 0
playbackVideoEvent.totalLength = 500
serverSide.execute(playbackVideoEvent)

TCVideoPlaybackEvent playbackVideoEvent = new TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_buffer_start, "YOUR_VIDEO_SESSION_ID");
playbackVideoEvent.contentAssetID = Arrays.asList("456", "223");
playbackVideoEvent.cursorPosition = 0;
playbackVideoEvent.totalLength = 500;
serverSide.execute(playbackVideoEvent);

    TCVideoPlaybackEvent *playbackVideoEvent = [[TCVideoPlaybackEvent alloc] initWithMode: video_buffer_start andSessionId: @"YOUR_VIDEO_SESSION_ID"];
    playbackVideoEvent.contentAssetID =  [@[@"456", @"223"] mutableCopy];
    playbackVideoEvent.cursorPosition = [[NSDecimalNumber alloc] initWithInt: 0];
    playbackVideoEvent.totalLength = [[NSDecimalNumber alloc] initWithInt: 500];;
    [serverside execute: playbackVideoEvent];

let playbackVideoEvent = TCVideoPlaybackEvent(mode: video_buffer_start, andSessionId: "YOUR_VIDEO_SESSION_ID")
    playbackVideoEvent?.contentAssetID = ["456", "223"]
    playbackVideoEvent?.cursorPosition = 0
    playbackVideoEvent?.totalLength = 500
    serverSide?.execute(playbackVideoEvent)

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:

{
    "event_name": "video_buffer_complete",
    "user": {},
    "video_session_id": "56789",
    "content_asset_id": ["123456"],
    "content_pod_id": ["CAF", "CAG"],
    "cursor_position": 20,
    "total_length": 400,
    "bitrate": 512,
    "framerate": 60.00,
    "video_player": "dailymotion",
    "sound": 100,
    "full_screen": false,
    "ad_enabled": false,
    "image_quality": "hd720",
    "livestream": true
}

val playbackVideoEvent = TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_buffer_complete, "YOUR_VIDEO_SESSION_ID")
playbackVideoEvent.contentAssetID = listOf("456", "223")
playbackVideoEvent.cursorPosition = 0
playbackVideoEvent.totalLength = 500
serverSide.execute(playbackVideoEvent)

TCVideoPlaybackEvent playbackVideoEvent = new TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_buffer_complete, "YOUR_VIDEO_SESSION_ID");
playbackVideoEvent.contentAssetID = Arrays.asList("456", "223");
playbackVideoEvent.cursorPosition = 0;
playbackVideoEvent.totalLength = 500;
serverSide.execute(playbackVideoEvent);

    TCVideoPlaybackEvent *playbackVideoEvent = [[TCVideoPlaybackEvent alloc] initWithMode: video_buffer_complete andSessionId: @"YOUR_VIDEO_SESSION_ID"];
    playbackVideoEvent.contentAssetID =  [@[@"456", @"223"] mutableCopy];
    playbackVideoEvent.cursorPosition = [[NSDecimalNumber alloc] initWithInt: 0];
    playbackVideoEvent.totalLength = [[NSDecimalNumber alloc] initWithInt: 500];;
    [serverside execute: playbackVideoEvent];

let playbackVideoEvent = TCVideoPlaybackEvent(mode: video_buffer_complete, andSessionId: "YOUR_VIDEO_SESSION_ID")
    playbackVideoEvent?.contentAssetID = ["456", "223"]
    playbackVideoEvent?.cursorPosition = 0
    playbackVideoEvent?.totalLength = 500
    serverSide?.execute(playbackVideoEvent)

Video Playback Seek Started

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

A sample event is as shown:

{
    "event_name": "video_seek_start",
    "user": {},
    "video_session_id": "abcdef",
    "content_asset_id": ["123456"],
    "content_pod_id": ["XYZ", "XYA"],
    "cursor_position": 59,
    "seek_position": 150,
    "total_length": 360,
    "bitrate": 256,
    "framerate": 60.00,
    "video_player": "vimeo",
    "sound": 80,
    "full_screen": false,
    "ad_enabled": false,
    "image_quality": "hd720",
    "livestream": true
}

val playbackVideoEvent = TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_seek_start, "YOUR_VIDEO_SESSION_ID")
playbackVideoEvent.contentAssetID = listOf("456", "223")
playbackVideoEvent.cursorPosition = 0
playbackVideoEvent.totalLength = 500
serverSide.execute(playbackVideoEvent)

TCVideoPlaybackEvent playbackVideoEvent = new TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_seek_start, "YOUR_VIDEO_SESSION_ID");
playbackVideoEvent.contentAssetID = Arrays.asList("456", "223");
playbackVideoEvent.cursorPosition = 0;
playbackVideoEvent.totalLength = 500;
serverSide.execute(playbackVideoEvent);

    TCVideoPlaybackEvent *playbackVideoEvent = [[TCVideoPlaybackEvent alloc] initWithMode: video_seek_start andSessionId: @"YOUR_VIDEO_SESSION_ID"];
    playbackVideoEvent.contentAssetID =  [@[@"456", @"223"] mutableCopy];
    playbackVideoEvent.cursorPosition = [[NSDecimalNumber alloc] initWithInt: 0];
    playbackVideoEvent.totalLength = [[NSDecimalNumber alloc] initWithInt: 500];;
    [serverside execute: playbackVideoEvent];

let playbackVideoEvent = TCVideoPlaybackEvent(mode: video_seek_start, andSessionId: "YOUR_VIDEO_SESSION_ID")
    playbackVideoEvent?.contentAssetID = ["456", "223"]
    playbackVideoEvent?.cursorPosition = 0
    playbackVideoEvent?.totalLength = 500
    serverSide?.execute(playbackVideoEvent)

Video Playback Seek Completed

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

A sample event is as shown:

{
    "event_name": "video_seek_complete",
    "user": {},
    "video_session_id": "abcdef",
    "content_asset_id": ["123456"],
    "content_pod_id": ["XYZ", "XYA"],
    "cursor_position": 59,
    "seek_position": 150,
    "total_length": 360,
    "bitrate": 256,
    "framerate": 60.00,
    "video_player": "vimeo",
    "sound": 80,
    "full_screen": false,
    "ad_enabled": false,
    "image_quality": "hd720",
    "livestream": true
}

val playbackVideoEvent = TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_seek_complete, "YOUR_VIDEO_SESSION_ID")
playbackVideoEvent.contentAssetID = listOf("456", "223")
playbackVideoEvent.cursorPosition = 0
playbackVideoEvent.totalLength = 500
serverSide.execute(playbackVideoEvent)

TCVideoPlaybackEvent playbackVideoEvent = new TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_seek_complete, "YOUR_VIDEO_SESSION_ID");
playbackVideoEvent.contentAssetID = Arrays.asList("456", "223");
playbackVideoEvent.cursorPosition = 0;
playbackVideoEvent.totalLength = 500;
serverSide.execute(playbackVideoEvent);

    TCVideoPlaybackEvent *playbackVideoEvent = [[TCVideoPlaybackEvent alloc] initWithMode: video_seek_start andSessionId: @"YOUR_VIDEO_SESSION_ID"];
    playbackVideoEvent.contentAssetID =  [@[@"456", @"223"] mutableCopy];
    playbackVideoEvent.cursorPosition = [[NSDecimalNumber alloc] initWithInt: 0];
    playbackVideoEvent.totalLength = [[NSDecimalNumber alloc] initWithInt: 500];;
    [serverside execute: playbackVideoEvent];

let playbackVideoEvent = TCVideoPlaybackEvent(mode: video_seek_complete, andSessionId: "YOUR_VIDEO_SESSION_ID")
    playbackVideoEvent?.contentAssetID = ["456", "223"]
    playbackVideoEvent?.cursorPosition = 0
    playbackVideoEvent?.totalLength = 500
    serverSide?.execute(playbackVideoEvent)

Video Playback Resumed

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

A sample event is as shown:

{
    "event_name": "video_resume",
    "user": {},
    "video_session_id": "abcdef",
    "content_asset_id": ["123456"],
    "content_pod_id": ["XYZ", "XYA"],
    "cursor_position": 150,
    "total_length": 360,
    "bitrate": 256,
    "framerate": 60.00,
    "video_player": "vimeo",
    "sound": 80,
    "full_screen": false,
    "ad_enabled": false,
    "image_quality": "hd720",
    "livestream": true
}

val playbackVideoEvent = TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_resume, "YOUR_VIDEO_SESSION_ID")
playbackVideoEvent.contentAssetID = listOf("456", "223")
playbackVideoEvent.cursorPosition = 0
playbackVideoEvent.totalLength = 500
serverSide.execute(playbackVideoEvent)

TCVideoPlaybackEvent playbackVideoEvent = new TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_resume, "YOUR_VIDEO_SESSION_ID");
playbackVideoEvent.contentAssetID = Arrays.asList("456", "223");
playbackVideoEvent.cursorPosition = 0;
playbackVideoEvent.totalLength = 500;
serverSide.execute(playbackVideoEvent);

    TCVideoPlaybackEvent *playbackVideoEvent = [[TCVideoPlaybackEvent alloc] initWithMode: video_resume andSessionId: @"YOUR_VIDEO_SESSION_ID"];
    playbackVideoEvent.contentAssetID =  [@[@"456", @"223"] mutableCopy];
    playbackVideoEvent.cursorPosition = [[NSDecimalNumber alloc] initWithInt: 0];
    playbackVideoEvent.totalLength = [[NSDecimalNumber alloc] initWithInt: 500];;
    [serverside execute: playbackVideoEvent];

let playbackVideoEvent = TCVideoPlaybackEvent(mode: video_resume, andSessionId: "YOUR_VIDEO_SESSION_ID")
    playbackVideoEvent?.contentAssetID = ["456", "223"]
    playbackVideoEvent?.cursorPosition = 0
    playbackVideoEvent?.totalLength = 500
    serverSide?.execute(playbackVideoEvent)

Video Playback Completed

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

A sample event is as shown:

{
    "event_name": "video_complete",
    "user": {},
    "video_session_id": "abcdef",
    "content_asset_id": ["123456"],
    "content_pod_id": ["XYZ", "XYA"],
    "cursor_position": 150,
    "total_length": 360,
    "bitrate": 256,
    "framerate": 60.00,
    "video_player": "vimeo",
    "sound": 80,
    "full_screen": false,
    "ad_enabled": false,
    "image_quality": "hd720",
    "livestream": true
}

val playbackVideoEvent = TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_complete, "YOUR_VIDEO_SESSION_ID")
playbackVideoEvent.contentAssetID = listOf("456", "223")
playbackVideoEvent.cursorPosition = 0
playbackVideoEvent.totalLength = 500
serverSide.execute(playbackVideoEvent)

TCVideoPlaybackEvent playbackVideoEvent = new TCVideoPlaybackEvent(ETCVideoPlaybackMode.video_complete, "YOUR_VIDEO_SESSION_ID");
playbackVideoEvent.contentAssetID = Arrays.asList("456", "223");
playbackVideoEvent.cursorPosition = 0;
playbackVideoEvent.totalLength = 500;
serverSide.execute(playbackVideoEvent);

    TCVideoPlaybackEvent *playbackVideoEvent = [[TCVideoPlaybackEvent alloc] initWithMode: video_resume andSessionId: @"YOUR_VIDEO_SESSION_ID"];
    playbackVideoEvent.contentAssetID =  [@[@"456", @"223"] mutableCopy];
    playbackVideoEvent.cursorPosition = [[NSDecimalNumber alloc] initWithInt: 0];
    playbackVideoEvent.totalLength = [[NSDecimalNumber alloc] initWithInt: 500];;
    [serverside execute: playbackVideoEvent];

let playbackVideoEvent = TCVideoPlaybackEvent(mode: video_complete, andSessionId: "YOUR_VIDEO_SESSION_ID")
    playbackVideoEvent?.contentAssetID = ["456", "223"]
    playbackVideoEvent?.cursorPosition = 0
    playbackVideoEvent?.totalLength = 500
    serverSide?.execute(playbackVideoEvent)

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

All of these events within the flow happen within one video playback.

Content Events 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 the properties of this playback event object in detail:

Content Events

This section details all the video content events.

For more information on each of the properties associated with these events, refer to the Content Events 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:

{
    "event_name": "video_content_start",
    "video_session_id": "98765",
    "content_asset_id": "456",
    "content_pod_id": "XYZ",
    "program": "The Lion King",
    "video_title": "Act 1",
    "video_description": "Invented description",