Overview: Data Collection API v2

Product(s)
Video Cloud
Role(s)
API Developer
Topic(s)
Analytics
API Overviews
API(s)
Analytics API

In this topic, you will get an overview of the Analytics Data Collection API v2, which allows you to add events to your Video Cloud Analytics data in situations where Brightcove cannot track the events directly. This topic primarily addresses changes from the v1 to the v2 version of the API.

Note: You should NOT use this API to track events for the Brightcove Player, or for the Android and iOS SDK players, because that already happens automatically, and you would be adding duplicate data.

This feature is for Video Cloud customers only.

Introduction

Analytics data is sent automatically by the Brightcove Players, including those provided by the Native Player SDKs. If you are not using a Brightcove Player to deliver Video Cloud videos, you need to instrument the player you are using to send the data to the Data Collector.

Data Collection API v2 is the current standard. The v1 version is deprecated. If you have a v1 implementation, see the Changes from v1 section below.

In addition to this overview and the API Reference, also see this sample implementation.

The Analytics Data Collection API is the endpoint for realtime analytics events. Event data is sent to Brightcove via a series of parameters submitted via HTTP requests, such as:

http://metrics.brightcove.com/v2/tracker?event=video_view&domain=videocloud&account=123&video=789

These parameters describe a fact about the state of the system when an event occurred. The example above describes the fact that a video_view event occurred for video 789 for account 123 (or: a user started watching account 123's video 789. See below for a description of the current analytics events tracked).

Dimensions

Dimensions are qualitative facts about the state of the system when an event occurs. For example, if the request is:

http://metrics.brightcove.com/tracker?event=video_view&session=581136_2018-07-03T18:34:46.214Z&domain=videocloud&account=123&video=789

The video ID ( 789) and account ID ( 123), and any device and location information gleaned from the request itself are all dimensions related to the video_view event. The Analytics system will record that a video_view event occurred when this request was made, with these dimensions.

Event and domain parameters

The event parameter describes which event has occurred. The domain parameter provides a namespace for events. The event, domain, and session are required parameters (the value of domain is always videocloud).

Additional parameters

Certain parameters must be included with events so that the Analytics system can successfully analyze them

Response types

The response to an analytics data collection API request includes an HTTP response code and a human-readable message.

HTTP Status Code Description Example
200 The request was successfully received by the collector and has been persisted. (returns a 1x1 pixel transparent GIF image)
400 The request sent by the client is missing a required parameter: domain, account or event. (This status will not be returned if domain-specific parameters are missing.) "Invalid 'event' parameter"
50x This is error code indicates a problem on the server side. Your event may or may not have been successfully recorded by the analytics system. "Server-side failure, please retry."

Minimal data

At a minimum, you should send a session id and video_view event for every video played during a session. The video_view should sent after any pre-roll ads complete.

session

This is the session identifier. The session is essentially one view of a page or app view that has a player in it, for as long as that lasts. The value should be constant for the duration of the session and sent for all events. It should be as close as is possible to a globally unique identifier (GUID). If there are collisions, the two sessions may be discarded as invalid if they cannot be disentangled.

There are various schemes for creating GUIDs in JavaScript. One example is in this GitHub respository. Please be aware that third-party scripts are not supported by Brightcove.

Best practices

To be sure that you are sending the correct data to the Collector, you should test your data collection script before generally deploying it. We recommend:

  1. Build the data collection script for your player.
  2. Test in a controlled environment for at least a day.
  3. Check the analytics data either through the Analytics Module or the Analytics API to ensure that what was collected matches your expectations.

Sending the request - avoiding CORS issues

Junk data

In general, data sent to the Collector will be recorded as truth by the Analytics system. If an event contains inappropriate or incorrect information, the Analytics system will interpret the data incorrectly.

For example, if you accidentally send the timestamp as the video ID, your analytics data will be skewed in ways that affect the overall summarization.

URI Encoding

Any strings you send to the Data Collection API that might contain spaces or special characters must be URI encoded for the request to be successful. If you are submitting the request via JavaScript, you can use the encodeURI() method the encode the request string. For example:

urlStr += "&video=" + currentVideo.id + "&video_name=" + encodeURI(currentVideo.video_name);

Events

The events listed below are processed by the Analytics system.

event Intent/Meaning Example
player_load A player session has been initiated by an end-user. This marks the beginning of the analytics session, and should be sent before any other events.
http://metrics.brightcove.com/tracker
?event=player_load&session=581136_2018-07-03T18:34:46.214Z&destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
&source=http%3A-%2F%2Fwww.google.com
%2Furl%3Fsa%3D-t%26rct%3Dj%26q%3D%26esrc%3Ds%26source
%3Dweb-%26cd%3D1%26ved%3D0CDYQFjAA%26url
%3Dhttp%253A-%252F%252Fsupport.brightcove.com%252F%26ei%3DoEYWUtCgEIXq9ATzn-oCgCQ
%26usg%3DAFQjCNEtLodOdxWZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
&domain=videocloud&account=1749339200&time=1377191644796

error Sent when fatal errors which disrupt the playback experience are encountered.
http://metrics.brightcove.com/tracker
?event=error&error_code=MEDIA_ERR_SRC_NOT_SUPPORTED&session=581136_2018-07-03T18:34:46.214Z&destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
&source=http%3A-%2F%2Fwww.google.com
%2Furl%3Fsa%3D-t%26rct%3Dj%26q%3D%26esrc%3Ds%26source
%3Dweb-%26cd%3D1%26ved%3D0CDYQFjAA%26url
%3Dhttp%253A-%252F%252Fsupport.brightcove.com%252F%26ei%3DoEYWUtCgEIXq9ATzn-oCgCQ
%26usg%3DAFQjCNEtLodOdxWZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
&domain=videocloud&account=1749339200&time=1377191644796

catalog_request Sent when a request to the videocloud catalog api is made.
http://metrics.brightcove.com/tracker
?event=catalog_request&session=581136_2018-07-03T18:34:46.214Z&catalog_url=https%3A%2F%2Fedge.api.brightcove.com%2Fplayback%2Fv1%2Faccounts%2F57838016001%2Fvideos%2F23823423800
&destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
&source=http%3A-%2F%2Fwww.google.com
%2Furl%3Fsa%3D-t%26rct%3Dj%26q%3D%26esrc%3Ds%26source
%3Dweb-%26cd%3D1%26ved%3D0CDYQFjAA%26url
%3Dhttp%253A-%252F%252Fsupport.brightcove.com%252F%26ei%3DoEYWUtCgEIXq9ATzn-oCgCQ
%26usg%3DAFQjCNEtLodOdxWZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
&domain=videocloud&account=1749339200&time=1377191644796

catalog_response Sent when a response to a prior catalog_request is received.
http://metrics.brightcove.com/tracker
?event=catalog_response&session=581136_2018-07-03T18:34:46.214Z&catalog_url=https%3A%2F%2Fedge.api.brightcove.com%2Fplayback%2Fv1%2Faccounts%2F57838016001%2Fvideos%2F23823423800&response_time_ms=243&destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
&source=http%3A-%2F%2Fwww.google.com
%2Furl%3Fsa%3D-t%26rct%3Dj%26q%3D%26esrc%3Ds%26source
%3Dweb-%26cd%3D1%26ved%3D0CDYQFjAA%26url
%3Dhttp%253A-%252F%252Fsupport.brightcove.com%252F%26ei%3DoEYWUtCgEIXq9ATzn-oCgCQ
%26usg%3DAFQjCNEtLodOdxWZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
&domain=videocloud&account=1749339200&time=1377191644796

play_request Sent when the playback is initiated either by the user expressly clicking the play button, or automatically when the platform triggers playback in an auto-play scenario.
http://metrics.brightcove.com/tracker
?event=play_request&session=581136_2018-07-03T18:34:46.214Z&destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
&source=http%3A-%2F%2Fwww.google.com
%2Furl%3Fsa%3D-t%26rct%3Dj%26q%3D%26esrc%3Ds%26source
%3Dweb-%26cd%3D1%26ved%3D0CDYQFjAA%26url
%3Dhttp%253A-%252F%252Fsupport.brightcove.com%252F%26ei%3DoEYWUtCgEIXq9ATzn-oCgCQ
%26usg%3DAFQjCNEtLodOdxWZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
&domain=videocloud&account=1749339200&time=1377191644796

ad_mode_begin Sent when control is handed over to an advertising agent by the playback platform.
http://metrics.brightcove.com/tracker
?event=ad_mode_begin&session=581136_2018-07-03T18:34:46.214Z&destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
&source=http%3A-%2F%2Fwww.google.com
%2Furl%3Fsa%3D-t%26rct%3Dj%26q%3D%26esrc%3Ds%26source
%3Dweb-%26cd%3D1%26ved%3D0CDYQFjAA%26url
%3Dhttp%253A-%252F%252Fsupport.brightcove.com%252F%26ei%3DoEYWUtCgEIXq9ATzn-oCgCQ
%26usg%3DAFQjCNEtLodOdxWZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
&domain=videocloud&account=1749339200&time=1377191644796

ad_mode_complete Sent when control is handed over to an advertising agent by the playback platform.
http://metrics.brightcove.com/tracker
?event=ad_mode_complete&session=581136_2018-07-03T18:34:46.214Z&destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
&source=http%3A-%2F%2Fwww.google.com
%2Furl%3Fsa%3D-t%26rct%3Dj%26q%3D%26esrc%3Ds%26source
%3Dweb-%26cd%3D1%26ved%3D0CDYQFjAA%26url
%3Dhttp%253A-%252F%252Fsupport.brightcove.com%252F%26ei%3DoEYWUtCgEIXq9ATzn-oCgCQ
%26usg%3DAFQjCNEtLodOdxWZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
&domain=videocloud&account=1749339200&time=1377191644796

video_impression The metadata for a video added to the player has finished loading and the player is ready to trigger the view event, either via auto-play or user interaction.
http://metrics.brightcove.com/tracker
?event=video_impression&session=581136_2018-07-03T18:34:46.214Z&destination=http%3A%2F%2Fwww.current-times.com%2F
&time=1377191644801&source=http%3A%2F%2Fwww.google.com
%2Furl%3Fsa-%3Dt%26rct%3Dj%26q%3D%26esrc%3Ds
%26source%3Dweb-%26cd%3D1%26ved%3D0CD-YQFjAA
%26url%3Dhttp%253A%252-F%252Fwww.currenttimes.com
%252-F%26ei%3DoEYWUtCgEIXq9ATznoCgCQ
%26usg%3DAFQjCNEtLod-OdxWZSGdJpL7WJaEeUJVlnw%26bvm%3Dbv.5115-6542%2Cd.dmg
&video=2621468623001
&video_name=Democratic-Rivals%20Target%20Bill%20de%20Blasio
&domain=videocloud&account=1749339200

video_view A video has started playing back (either auto-play after loading, or due to user interaction).

Note: If your video has a pre-roll advertisement then this should be sent after the ad completes.

http://metrics.brightcove.com/tracker
?event=video_view&session=581136_2018-07-03T18:34:46.214Z&destination=http%3A%2F%2Fwww.current-times.com%2F
&video=2621468623001&video_name=Debate-2&video_duration=189
&time=1377191666432
&source=http%3A%2F%2Fwww.google.com%2Furl%3Fsa%3Dt%26rct%3Dj%26-q
%3D%26esrc%3Ds%26source%3Dweb%26cd%3D1%26ved%3D-0CDYQFjAA%26url
%3Dhttp%253A%252F%252Fwww.current-times.com
%252F%26ei%3DoEYWUtCgEIXq9ATznoCgCQ%26us-g
%3DAFQjCNEtLodOdxWZSGdJpL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
&domain=videocloud&account=1749339200

video_engagement A user watched a range of seconds of a video's timeline. This event is a heartbeat for tracking video engagement and will likely be sent many times during playback, depending on the user interaction and the length of the video. The Brightcove player instrumentation sends this event every 10 seconds, if playback is not interrupted. Events describing ranges over 20 seconds are discarded by the Analytics system.
http://metrics.brightcove.com/tracker
?event=video_engagement&session=581136_2018-07-03T18:34:46.214Z&destination=http%3A%2F%2Fwww.current-times.com%2F
&video=2621468623001&video_name=Debate-2&video_duration=189
&time=1377191676589&range=0..9
&source=http%3A%2F%2Fwww.google.com
%2Furl%3Fsa%3Dt-%26rct%3Dj%26q%3D%26esrc%3Ds
%26source%3Dweb%26cd%3D1%26ved%3D0CDYQFjAA
%26url%3Dhttp%253A%252F%252Fwww.current-times.com
%252F%26ei%3DoEYWUtC-gEIXq9ATznoCgCQ
%26usg%3DAFQjCNEtLodOdxWZSGdJpL7WJ-aEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
&domain=videocloud&account=1749339200

Parameters for all events

Parameters for these events should include any information relevant to the current state of the system when the event occurred, and be as specific as possible. This section details parameters that can be sent with all events, and the following sections show parameters for specific events.

Field Type Description
account String

account id

domain String

always equal to videocloud

Allowed values: "videocloud"

session String A session id that is as universally unique as possible - see the Minimal Data section above for more information
device_os optional String

Override to specify the OS of the device that originated the event in cases where the User Agent is unreliable (ignored unless both device os and device type are included or if the value submitted is not in the list of values shown here. Not typically included)

Allowed values: "android", "bada", "ios", "linux", "mac", "tv", "os_x", "rim", "sybian", "windows", "other"

device_os_version optional String

The version of os being used by the device. When not specified, this will be calculated by parsing the user agent string for the tracking request

device_type optional String

Override to specify the type of the device that originated the event in cases where the User Agent is unreliable (ignored unless both device os and device type are included or if the value submitted is not in the list of values shown here. Not typically included)

Allowed values: "direct", "mobile", "tablet", "tv", "desktop", "other"

event String

the event type

Allowed values: "player_load", "catalog_request", "catalog_response", "play_request", "ad_mode_begin", "ad_mode_complete", "video_impression", "video_view", "video_engagement", "error"

destination optional String

URI that originated the event

source optional String

URI that sent the end-user to the destination URI

time optional Number

the timestamp for the event in epoch time (milliseconds)

country optional String

ISO-3166 (alpha 2) region cISO-3166 (alpha 2) region code (override in case the system can not detect geographic information from the IP address) Not typically included

country_name optional String

Human readable country name (override in case the system can not detect geographic information from the IP address) Not typically included

region optional String

ISO-3166 (alpha 2) region code (override in case the system can not detect geographic information from the IP address) Not typically included

region_name optional String

Human readable region name (override in case the system can not detect geographic information from the IP address) Not typically included

city optional String

City name Not typically included

user optional String

A unique user identifier - if not provided or blank, Video Cloud uses the fallback method of using the Source IP address + the User-Agent String as the unique identifier; Note that Brightcove uses this information only to calculate unique users. The user data itself cannot retrieved via the API or Analytics module

User parameter

  • If the player/client application wants to track the unique viewer it should send a unique Id for the user as the user parameter to the collector.
  • If the user is not provided or is blank, we use the fallback method of using the Source IP address + the User-Agent String as the unique identifier.
  • The value of the user parameter is never stored in the logs/database, only a hash (using SHA-256) is stored.
  • No cookies are set by the collector.

Unique user

You can use Brightcove Player's plugin functionality to add unique video viewer data to the reported analytics. To do this, you will add a unique identifier to the settings object of the analytics functionality.

Of course, how a unique user ID is captured varies from application to application, but for an example this code assumes a login URL is captured that contains unique user data, such as http://exampledomain.com/users/912389123. This unique URL is passed to the plugin.

The plugin's code below performs the following tasks:

  • Uses the standard syntax to create a Brightcove Player plugin with the plugin name defined as uniqueUserForAnalyticsPlugin. The plugin also accepts an options object, which contains data passed to the plugin.
  • The myPlayer variable is assigned a reference to the player. As well, two other variables are created.
  • The userPath variable is assigned the path passed to the plugin via the options object.
  • The uniqueViewer variable is assigned the parsed version of the userPath, so only the user ID digits are assigned to the variable.
  • A user property is added to the Analytics plugin's settings object.
videojs.registerPlugin('uniqueUserForAnalyticsPlugin', function(options) {
var myPlayer = this,
userPath = '',
uniqueViewer = '';
//Assign uniqueViewer a value according to your app and business rules
//In this example, parsing the path passed to the plugin in the options object
userPath = options.path;
uniqueViewer = userPath.substring( userPath.lastIndexOf('/') + 1 );
//Assign a user variable to Analytic's settings object
myPlayer.bcAnalytics.client.user(USER) = uniqueViewer;
});

This code would need to be altered to suit your application logic, then saved to an Internet accessible URL.

From Studio, use the Plugins section to load the plugin in the player, as shown.

Studio Plugin Section
Studio Plugin Section

Instead of the JSON that follows, you would pass to the plugin the string containing user data. Of course, the plugin code would need to be updated accordingly to extract the unique user ID.

{
"path": "http://exampledomain.com/users/912389123"
}

For more information on plugin development see the Quick Start: Plugin Development document.

device_type, device_os, device_os_version, device_manufacturer, and browser_type parameters

By default, the Analytics system will attempt to detect device type and OS information from the User-Agent header. If both device_type and device_os are sent, the information from the User-Agent header will be ignored in favor of device_type and device_os. In most cases, you do not need to send device, OS, and browser information -- this override should only be used if the User-Agent is unreliable or otherwise not available.

The Analytics system will record other if a request includes unrecognized values for device parameter overrides.

Geographic data Parameters

By default, the Analytics system will attempt to detect geographic information from the remote IP address. This behavior can be overridden by passing country, country_name, region, region_name, city and dma parameters. In most cases, these parameters are not required -- this override should only be used if the remote IP address is unreliable or otherwise not available.

The Analytics system will record ZZ or unknown if a request includes unrecognized values for overrides.

destination and source Parameters

The destination and source parameters provide the URI that originated the event ( destination) and the URI that sent the user there ( source).

The source parameter is used to determine traffic source information. If source is not specified, the Analytics system will treat events as being initiated by direct traffic.

The destination parameter will be used to determine traffic destination information -- that is, where the video is being watched. If the URI does not contain an authority, the API will not record a destination_domain. The destination_path will be recorded as the path in the URI.

During web playback, the URL in the address bar of the page where the video is playing is the destination), and the source is the referrer ( top.document.referrer).

For example, when searching for "live streaming wirecast" on the Brightcove Support site and watching a video that comes up in the results:

Parameter Value
source
https://support.brightcove.com/en/video-cloud/search/live%20streaming%20wirecast

destination
https://support.brightcove.com/en/video-cloud/training-videos/live-streaming-wirecast

If there is no URL (as in the case of native playback, for example), both destination and source should be valid URIs that identify where the video is playing back and how the user got there, respectively.

Assuming the destination is a valid URI:

<scheme name> : <hierarchical part> [ ? <query> ] [ # <fragment> ]
ex. https://www.example.com/foo/bar/baz
--------------/----------/
|             |
authority        path
---/    -------------------------/
|                |
scheme       hierarchical part

the Analytics system will handle it as follows:

If the URI contains an authority, the API response will use that authority as the destination_domain and any path provided as the destination_path. If the URI does not contain an authority, the API will not record a destination_domain. The destination_path will be recorded as the path in the URI. A destination without a hierarchical part (e.g. just a scheme) is considered invalid, as is any value without a scheme.

Parameters for specific events

error event parameters

The following parameters should be sent with error events.

Field Type Description
error_code optional Number

A platform specific error code associated with the event

catalog_request event parameters

The following parameters should be sent with catalog_request events.

Field Type Description
catalog_url optional String

The destination url associated with the catalog_request event

catalog_response event parameters

The following parameters should be sent with catalog_response events.

Field Type Description
catalog_url optional String

The destination url associated with the catalog_request event that initiated this response

response_time_ms optional Number

The time, in milliseconds, between the catalog_request event and the catalog_response event

video_impression event parameters

The following parameters should be sent with video_impression events.

Field Type Description
video optional String

the video id

video_name optional String

the video name

video_view event parameters

The following parameters should be sent with video_view events.

Field Type Description
video optional String

the video id

video_name optional String

the video name

start_time_ms optional String

The time, in milliseconds, between initiation of playback and the first frame of the video being rendered. This can be different depending on the experience, for instance, if there are no pre-roll ads configured, this measurement is the time between the play_request and video_view events. If there is a preroll ad, the time between ad_mode_begin and ad_mode_complete should not be included

video_engagement event parameters

The following parameters should be sent with video_engagement events.

Field Type Description
video optional String

the video id

video_name optional String

the video name

range optional String

the range of the video viewed for video_engagement events in the format StartSecond..EndSecond (the StartSecond and EndSecond values must be whole numbers [integers]) - range can be left out of an engagement event to show that during the period covered by the event, there was no viewing activity. (for example, when there is only re-buffering activity)

rendition_url optional String

The url to the most recently selected rendition. For example, for an HLS stream this would be the url to the most recently selected variant

rendition_indicated_bps optional String

The indicated bitrate, in bits per second, of the most recently selected rendition

rendition_mime_type optional String

The mime type of the most recently selected rendition

rendition_height optional String

The encoded height of the video rendition in pixels

rendition_width optional String

The encoded width of the video rendition in pixels

rebuffering_seconds optional String

The number of seconds the user spent waiting for video to playback due to un-requested delay during the engagement period

rebuffering_count optional String

The number of times playback stopped due to re-buffering during the represented engagement period delay during the engagement period

forward_buffer_seconds optional String

The number of seconds of video currently residing in the forward buffer

measured_bps optional String

The ratio of the number of bits included in the most recently downloaded segment to the time spend downloading that segment, in bits per second

player_width optional String

The current pixel width of the player at the end of the engagement range

player_height optional String

The current pixel height of the player at the end of the engagement range

dropped_frames optional String

dropped_frames

video_duration optional Number

the duration of the video in seconds

video_seconds_viewed optional Number

count of watched seconds since the last update for video_engagement events

The video_engagement event is a means of tracking video engagement while a video is playing back, and will likely be sent many times during playback. (The Flash/HTML5 player instrumentation sends this event every 10 seconds, if playback is not interrupted.) At present, events describing ranges over 20 seconds are discarded by the Analytics system, so it is necessary to send these events more frequently.

There are two forms that a video_engagement event can take (other parameters omitted for brevity):

Example Meaning
event=video_engagement&video=123&video_duration=75&range=0..9

Video 123 with a duration of 75 seconds played seconds 0 through 9 (for a total of 10 seconds viewed).
event=video_engagement&video=123&video_seconds_viewed=10 10 seconds of video 123 were viewed.

While both versions track viewed seconds, the version that includes video_duration and range also contains information necessary to calculate additional engagement data, and is the preferred way to send video_engagement event data to the Analytics system. In cases where the video's timeline is continually changing during playback or is otherwise unreliable (e.g. live video playback, but not initial duration instability that may happen when a VOD video first loads), video_seconds_viewed may be the only data available, but in all other cases the video_engagement event should include video_duration and range.

Parameters Derived engagement metrics (API)
video_duration, range video_seconds_viewed, video_percent_viewed, engagement_score; engagement curve data
video_seconds_viewed video_seconds_viewed

If all three parameters ( video_duration, range and video_seconds_viewed) are sent along with a video_engagement event, the Analytics system will calculate engagement metrics from the video_duration+ range parameters.

V2 Changes

This section provides a summary of changes from v1 to v2 of the Data Collector for those who have been using v1.

Base url for tracker

http(s)://metrics.brightcove.com/v2

Additional Fields Supported on All Events:

device_os_version: The version of os being used by the device. When not specified, this will be calculated by parsing the user agent string for the tracking request.

platform_version: Used to indicate that a new release of the specified platform is being used to send the events.

New Events For V2

catalog_request: Sent when a request to the videocloud catalog api is made

  • catalog_url: The destination url associated with the catalog_request event.

catalog_response: Sent when a response to a prior catalog_request is received

  • catalog_url: The destination url associated with the catalog_request event that initiated this response.
  • response_time_ms: The time, in milliseconds, between the catalog_request event and the catalog_response event.

play_request: Sent when the playback is initiated either by the user expressly clicking the play button, or automatically when the platform triggers playback in an auto-play scenario.

ad_mode_begin: [Replaces ad_start] Sent when control is handed over to an advertising agent by the playback platform.

ad_mode_complete: [Replaces ad_end]Sent when control is handed back from the advertising agent to the playback platform.

error: Sent when fatal errors which disrupt the playback experience are encountered.

  • error_code: A platform specific error code associated with the event.

Updated Events for V2

video_view: Includes new latency measurements

  • load_time_ms: The time, in milliseconds, between initiating data load for the video and the video becoming playable.
  • start_time_ms: The time, in milliseconds, between initiation of playback and the first frame of the video being rendered. This can be different depending on the experience, for instance, if there are no pre-roll ads configured, this measurement is the time between the 'play_request' and video_view events. If there is a preroll ad, the time between ad_mode_begin and ad_mode_complete should not be included.

video_engagement: Includes additional rendition selection, bitrate measurements, and buffering information. A subtle change to video engagement was also made in that it should be sent periodically even if no viewing occurred during the engagement period. This change is to enable tracking re-buffering delays and counts that cause users to wait for playback.

  • range: The range parameter is now optional, range can be left out of an engagement event to show that during the period covered by the event, there was no viewing activity. (for example, when there is only re-buffering activity)
  • rendition_url: The url to the most recently selected rendition. For example, for an HLS stream this would be the url to the most recently selected variant.
  • rendition_indicated_bps: The indicated bitrate, in bits per second, of the most recently selected rendition.
  • rendition_mime_type: The mime type of the most recently selected rendition.
  • rendition_height: The encoded height of the video rendition in pixels
  • rendition_width: The encoded width of the video rendition in pixels
  • rebuffering_seconds: The number of seconds the user spent waiting for video to playback due to un-requested delay during the engagement period.
  • rebuffering_count: The number of times playback stopped due to re-buffering during the represented engagement period.
  • forward_buffer_seconds: The number of seconds of video currently residing in the forward buffer.
  • measured_bps: The ratio of the number of bits included in the most recently downloaded segment to the time spend downloading that segment, in bits per second.
  • player_width The current pixel width of the player at the end of the engagement range.
  • player_height The current pixel height of the player at the end of the engagement range.
  • dropped_frames: The number of frames that were dropped from video playback during this engagement period