Overview: Data Collection API v2

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 real-time analytics events. Event data is sent to Brightcove via a series of parameters submitted via HTTP requests, such as:

  https://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:

  https://metrics.brightcove.com/v2/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.

VOD and Live Events

Live Events

The following conditions must be met in order for the Data Collection API to classify an event as Live:

• Request must not have video_duration parameter.
• Request must have account parameter.
• Request must have video parameter.
• The event type must be one of the following:
  • play_request
  • video_impression
  • video_view
  • video_engagement
  • alive_ss_ad_start
• The Account must be enabled by Brightcove Support for Live Video Streaming.

VOD

• You must include the video_duration with requests for VOD only. Never send a video_duration for Live streams.
• Any request that contains a video_duration parameter will be classified as VOD.

Minimal data

At a minimum, you should send a session id, video_view event, and video_duration for every video played during a session. The video_view event should be sent after any pre-roll ads are 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 close 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 repository. Please be aware that third-party scripts are not supported by Brightcove.

Minimal Data for Performance (Play Rate & Engagement scoring)

Events

• video_impression
• play_request
• video_view
• video_engagement

Attributes (all Events)

• account
• video

Additional Attributes (video_engagement Event only)

VOD

• range
• video_duration

Live

• video_seconds_viewed

HTTP Headers

• User-Agent - Required for Device reporting

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

player_load

Intent/Meaning

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.

Example

https://metrics.brightcove.com/v2/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
  %253A-%252F%252Fsupport.brightcove.com%252F%26ei%3D
  OdxWZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200
  &time=1377191644796

error

Intent/Meaning

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

Example

https://metrics.brightcove.com/v2/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
  %3Dhttp%253A-%252F%252Fsupport.brightcove.com
  %26usgWZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200
  &time=1377191644796

catalog_request

Intent/Meaning

Sent when a request to the Video Cloud Playback API is made.

Example

https://metrics.brightcove.com/v2/tracker
  ?event=catalog_request
  &session=581136_2018-07-03T18:34:46.214Z
  &catalog_url=https%3A%2F%2Fedge.api.brightcove.com%2Fplayback
  &destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
  &source=http%3A-%2F%2Fwww.google.com
  %3Dhttp%253A-%252F%252Fsupport.brightcove.com
  WZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
  &domain=videocloud&account=1749339200
  &time=1377191644796

catalog_response

Intent/Meaning

Sent when a response to a prior catalog_request is received.

Example

https://metrics.brightcove.com/v2/tracker
  ?event=catalog_response
  &session=581136_2018-07-03T18:34:46.
  &catalog_url=https%3A%2F%2Fedge.api.brightcove.com%2Fp2F23823423800
  &response_time_ms=243
  &destination=http%3A-%2F%2Fsup-port.brightcove.com%2F
  &source=http%3A-%2F%2Fwww.google.com
  53A-%252F%252Fsupport.brightcove.com%252F%2Tzn-oCgCQ
  AFQjCNJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200
  &time=1377191644796

play_request

Intent/Meaning

Player V7 only sends a play_request once per session per media stream. play_request describes the action of requesting playback either manually from the viewer by clicking play or automatically by an autoplay mechanism. This event always happens in a moment between the video_impression and video_view event.

Example

https://metrics.brightcove.com/v2/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
  %3Dhttp%253A-%252F%252Fsupport.brightcove.com%252F%2
  dJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200
  &video_duration=189
  &time=1377191644796

ad_mode_begin

Intent/Meaning

Sent when control is handed over to an advertising agent by the playback platform.

Example

https://metrics.brightcove.com/v2/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
  %3Dhttp%253A-%252F%252Fsupport.brightcove.com%252
  %26usg%3DAFQjCNEtLod%3Dbv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200
  &time=1377191644796

ad_mode_complete

Intent/Meaning

Sent when control is handed over to an advertising agent by the playback platform.

Example

https://metrics.brightcove.com/v2/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
  %3Dhttp%253A-%252F%252Fsupport.brightcove.com%252F%2
  WZSGdJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200
  &time=1377191644796

video_impression

Intent/Meaning

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.

Example

https://metrics.brightcove.com/v2/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
  %252-F%26ei%3DoEYWUtCgEIXq9ATznoCgCQ
  %26usg%3DAFQjCNEtLod-Odx6bvm%3Dbv.5115-6542%2Cd.dmg
  &video=2621468623001
  &video_name=Democratic-Rivals%20Target%20Bill
  &video_duration=189
  &domain=videocloud
  &account=1749339200

video_view

Intent/Meaning

A video has started playing back (either auto-play after loading, or due to user interaction). Note that only one video_view event is recorded during a viewing session even if the viewer stops and restarts or replays the video.

Example

https://metrics.brightcove.com/v2/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%
  %252F%26ei%3DoEYWUtCgEIXq9ATznoCgCQ%26us-g
  %3DAFQjCNEtv.51156542%2Cd.dmg
  &domain=videocloud
  &account=1749339200

video_engagement

Intent/Meaning

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, unless the viewer has intentionally paused playback, either through the player controls or through a player event such as backgrounding the player. In this scenario of the viewer intentionally pausing playback, video_engagement reporting should resume when the viewer intentionally resumes playback, either through the player controls or through a player event such as foregrounding the player. This change is to enable tracking re-buffering delays and counts that cause users to wait for playback. Events describing ranges over 20 seconds are discarded by the Analytics system.

Example

https://metrics.brightcove.com/v2/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.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.

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 https://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.

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": "https://exampledomain.com/users/912389123"
  }
  
  

For more information on plugin development see the Step-by-Step: 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:

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

  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.

catalog_request event parameters

The following parameters should be sent with catalog_request events.

catalog_response event parameters

The following parameters should be sent with catalog_response events.

video_impression event parameters

The following parameters should be sent with video_impression events.

video_view event parameters

The following parameters should be sent with video_view events.

video_engagement event parameters

The following parameters should be sent with 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 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):

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

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. For live streams, or in cases where the video's timeline is continually changing during playback or is otherwise unreliable, video_seconds_viewed will be the only data available. For VOD, unless duration is unavailable, the video_engagement event should include video_duration and range.

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.

Fields and events for QoE

The following parameters can be sent with events for QoE metrics. For details about viewing QoE tables and metrics in Video Cloud Studio, see the Quality of Experience (QoE) Analytics document.

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 - note that this event is for internal use, and not exposed in the Analytics Module or via the Analytics API.

• catalog_url: The destination url associated with the catalog_request event - note that this event is for internal use, and not exposed in the Analytics Module or via the Analytics API..

catalog_response: Sent when a response to a prior catalog_request is received - note that this event is for internal use, and not exposed in the Analytics Module or via the Analytics API.

• catalog_url: The destination url associated with the catalog_request event that initiated this response - note that this event is for internal use, and not exposed in the Analytics Module or via the Analytics API..
• response_time_ms: The time, in milliseconds, between the catalog_request event and the catalog_response event - note that this event is for internal use, and not exposed in the Analytics Module or via the Analytics API..

play_request: Player V7 only sends aplay_request once per session per media stream. play_request describes the action of requesting playback either manually from the viewer by clicking play or automatically by an autoplay mechanism. This event always happens in a moment between the video_impression and video_view event.

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, unless the viewer has intentionally paused playback, either through the player controls or through a player event such as backgrounding the player. In this scenario of the viewer intentionally pausing playback, video_engagement reporting should resume when the viewer intentionally resumes playback, either through the player controls or through a player event such as foregrounding the player. This change is to enable tracking re-buffering delays and counts that cause users to wait for playback. Events describing ranges over 20 seconds are discarded by the Analytics system.

• 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