Video events reference

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:

PropertyTypeRequiredDescription

video_session_id

String

Yes

A unique ID that ties all the events generated from a specific playback session. These events include playback, content, and ad events.

video_title

String

No

Denotes the title of the video content.

video_category

String

No

Denotes the genre of the video content asset.

publisher

String

No

Denotes the publisher / creator / author of the

video content asset.

content_asset_id

String

Array [String]

Yes

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

String

Array [String]

No

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_id

String

Array [String]

No

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_id

String

Array [String]

No

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 content pod ID associated with the current ad pod at the time of the event should be sent.

ad_type

String

No

Denotes the type of ad playing at the time of the

event. The values can be 'pre-roll', ' mid-roll', or

'post-roll'.

cursor_position

Integer

Yes

Denotes the current index position of the playhead in seconds. It includes the duration of any seen ads. Not required in video_buffer_start and video_buffer_complete events If the playback is a livestream, refer to the documentation of the relevant destination for steps on correctly passing the playhead position.

seek_position

Integer

No

Denotes the index position of the playhead where the

user is seeking to.

Only applicable on the video_seek_start and video_seek_complete events. On video_seek_complete events,

the seek_position should be equal to cursor_position.

total_length

Integer

Yes

Denotes the total duration of the video playback

in seconds. Includes the whole duration of all

the content and ads included in the session.

Set to null in case of a livestream playback.

bitrate

Integer

No

Bit rate of the video playback, denoted in kbps

framerate

Float

No

Denotes the average frame rate of the video playback in fps.

video_player

String

No

Denotes the name of the video player used for

playback. Example: youtube, vimeo, etc.

sound

Integer

No

Denotes the sound level of the video playback.

Range is from 0-100, where 0 represents mute

and 100 is full volume.

full_screen

Boolean

No

Set to true if the playback is in fullscreen mode.

ad_enabled

Boolean

No

Set to false if the user has any ad blockers.

If the user can view your video ads, it is set to

true.

image_quality

String

No

Specifies the quality of the video. Examples: 'hd1080', 'highres'

interruption_method

String

No

For 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'.

livestream

Boolean

No

Set to true in case the playback is a live stream, else set to false.

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
}

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
}

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"
}

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
}

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
}

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
}

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
}

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
}

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
}

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:

PropertyTypeRequiredDescription

video_session_id

String

Yes

A unique ID that ties all the events generated from a specific playback session. These events include playback, content, and ad events.

content_asset_id

String

Yes

Denotes the unique ID of the video content asset.

content_pod_id

String

No

Denotes the unique ID of the video content pod.

video_title

String

No

Denotes the title of the video content.

video_description

String

No

Describes the video content asset in short.

keywords

Array [String]

No

Denotes the relevant keywords associated with the

categorizing the video content

season

String

No

Denotes the season number, if applicable.

episode

String

No

Denotes the episode number, if applicable.

video_category

String

No

Denotes the genre of the video content asset.

program

String

No

Denotes the name of the program / show of which

the video content is a part.

publisher

String

No

Denotes the publisher / creator / author of the

video content asset.

channel

String

No

Denotes the channel in which the video content

is playing.

full_episode

Boolean

No

Set to true the video content asset is a full episode.

livestream

Boolean

No

If the video content is a live stream, this is set to

true.

airdate

ISO 8601

Date String

No

Denotes the original date of airing / publishing

the video content.

cursor_position

Integer

Yes

Denotes 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_length

Integer

Yes

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

bitrate

Integer

No

Denotes the current bit rate in kbps.

framerate

Float

No

Denotes the frame rate in fps.

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",
    "season": "1",
    "episode":"14",
    "channel":"NBC",
    "livestream":false,
    "airdate":"2022-12-20",
    "cursor_position": 5,
    "total_length": 200,
    "video_category": "Animation",
    "publisher": "Disney",
    "full_episode": false,
    "keywords": ["lion", "savannah", "circle of life"],
    "user": {}
}

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 cursor_position property.

A sample event is as shown:

{
    "event_name": "video_content_playing",
    "video_session_id": "56789",
    "content_asset_id": "789",
    "content_pod_id": "ABC",
    "program": "The Jungle Book",
    "video_title": "Act 2",
    "video_description": "Invented description",
    "season": "2",
    "cursor_position": 123,
    "total_length": 400,
    "video_category": "Adventure",
    "publisher": "Disney",
    "full_episode": false,
    "framerate": 60,
    "bitrate": 4500,
    "keywords": ["jungle", "animals", "mowgli"],
    "user": {}
}

Video Content Quarter Reached

These events are sent when a quarter of the video is reached, determined by the cursor_position property.

A sample event is as shown:

{
    "event_name": "video_content_quarter_reached",
    "video_session_id": "56789",
    "content_asset_id": "789",
    "content_pod_id": "ABC",
    "program": "The Jungle Book",
    "video_title": "Act 2",
    "video_description": "Invented description",
    "season": "2",
    "cursor_position": 123,
    "total_length": 400,
    "video_category": "Adventure",
    "publisher": "Disney",
    "full_episode": false,
    "keywords": ["jungle", "animals", "mowgli"],
    "user": {}
}