support Contact Support | system status System Status
Page Contents

    Overview: Data Collection API v2

    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.

    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 repository. Please be aware that third-party scripts are not supported by Brightcove.

    Minimal Data for Performance (Play Rate & Engagement scoring)

    Events

    • video_impression
    • 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 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.

    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
    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
      %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
    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
      %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
    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
      &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
    http://metrics.brightcove.com/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

    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.

    Example
    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
      %3Dhttp%253A-%252F%252Fsupport.brightcove.com%252F%2
      dJ-pL7WJaEeUJVlnw%26bvm%3Dbv.51156542%2Cd.dmg
      &domain=videocloud
      &account=1749339200
      &time=1377191644796
    ad_mode_begin
    Intent/Meaning

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

    Example
    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
      %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
    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
      %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
    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
      %252-F%26ei%3DoEYWUtCgEIXq9ATznoCgCQ
      %26usg%3DAFQjCNEtLod-Odx6bvm%3Dbv.5115-6542%2Cd.dmg
      &video=2621468623001
      &video_name=Democratic-Rivals%20Target%20Bill
      &domain=videocloud
      &account=1749339200
    video_view
    Intent/Meaning

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

    Example
    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%
      %252F%26ei%3DoEYWUtCgEIXq9ATznoCgCQ%26us-g
      %3DAFQjCNEtv.51156542%2Cd.dmg
      &domain=videocloud
      &account=1749339200
    video_engagement
    Intent/Meaning

    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.

    Example
    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.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 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:

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

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

    Page last updated on 12 Jun 2020