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:
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.
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.
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.
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.
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 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.
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.
This event is sent once the video segment within the playback is completed. Note that the cursor_position property has the same value as the total_length property.
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 the properties of this ad event object in detail:
Ad Events
This section details all the ad events.
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 roll starts playing within the video playback.
This event is sent after the user has viewed a video ad completely. Note that the cursor_position property has the same value as the total_length property.
This event is sent after the user has viewed the video ad roll completely. Note that the cursor_position property has the same value as the total_length property.
This event is sent after the user has viewed the video ad break pod completely. Note that the cursor_position property has the same value as the total_length property.
All the settings events share the same properties that describe the current state of the video content that a user is interacting with during the playback.
Resuming Playback
Setting Events
This section details all the video settings events.
For more information on each of the properties associated with these events, refer to the Settings Event Properties section.
Video Volume
This event is sent when the user modify the audio volume of the video player.
Every Video Playback Resumed the event should be followed by an event Video Content Playing or a Video Ad Playing event, depending on what asset the playback resumes to.
Video Quality
Commanders Act 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 Commanders Act video specification:
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.
Property
Type
Required
Description
Property
Type
Required
Description
Property
Type
Required
Description
Property
Type
Required
Description
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.
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.
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.
ad_asset_id
String
Yes
Denotes the unique ID of the ad asset.
ad_pod_id
String
Yes
Denotes the unique ID of the ad pod.
pod_position
Integer
No
Denotes the position of the ad asset relative
to other ads in the same pod.
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'.
pod_length
Integer
No
Denotes the number of ad assets in the current
ad pod.
video_title
String
No
Denotes the title of the ad.
publisher
String
No
Denotes the author/ creator/ publisher of the ad.
cursor_position
Integer
Yes
The current playhead position in relation to the
total length of the ad, in seconds.
total_length
Integer
Yes
Denotes the total length of the ad asset in seconds.
load_type
Enum
No
Denotes if the ads are loaded dynamically or if
they are the same for all the users.
Values can be either 'dynamic' or ' linear '.
ad_quartile
Integer
No
For 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 Commanders Act
automatically tracks the ad quartiles.
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.
ad_asset_id
String
No
Denotes the unique ID of the ad asset.
ad_pod_id
String
No
Denotes the unique ID of the ad pod.
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'.
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
Yes
Denotes the current bit rate in kbps.
framerate
Float
No
Denotes the frame rate in fps.
sound
Integer
Yes
Denotes the current video sound level
Required in video_volume event
full_screen
Boolean
Yes
Denotes the current video screen mode.
Required in video_fullscreen_on and video_full_screen_off events
ad_enabled
Boolean
No
Denotes if ad were enabled
image_quality
String
Yes
Denotes the current video queity resolution.
Required in video_quality event