Dimension: viewer

Introduction

The viewer dimension allows you to look at analytics by viewer. If viewer ids are not sent to the analytics data collector from the player, we will try to construct a viewer id from the viewer's IP address and user-agent - this method is prone to error, however. Viewer analytics are most useful if you have logged in viewers and therefore can identify them reliably.

URL parameters

Analytics API reports support the following URL parameters.

URL Parameters
Parameter	Description	Required	Values	Default
`account`	The accounts you want to report on	yes	one or more account ids as a comma-delimited list	none
`dimensions`	The dimension(s) to report on	yes	one or more dimensions as a comma-delimited list (some combinations are not valid - use the interactive tool here to determine if a combination is valie)	none
`where`	Used to specify filters for reports	no	{dimension}=={value} - one or more as a semi-colon-delimited list. The value will be one or more values for the primary metric of that dimension. For example: `video==video_id`, `country=country-code`, or `viewer=viewer_id` (in the last case, the form of the viewer_id will vary depending on whether you are capturing and sending some kind of viewer_id yourself or depending on the value generated by the analytics system).	none
`limit`	Number of items to return	no	positive integer	10
`offset`	Number of items to skip	no	positive integer	0
`sort`	Field to sort items on	no	any field that is being returned by the request	video_view
`fields`	Fields to return	no	varies according to the dimension you are reporting on	video,video_view
`format`	Format to return results in	no	json (default) \| csv \| xlxs	json
`reconciled`	If included, will limit results to either historical or realtime data. Analytics data is derived from multiple sources: some is sent by the player, but other data is collected from CDNs and the Video Cloud system. In order to deliver analytics as quickly as possible, we start delivering "real-time" data as soon as it is available, and then adjust the analytics later when data from all sources has been collected and processed. The fully processed data is called reconciled	no	true \| false	true
`from`	The beginning of the date range for the request	no	One of the following: An ISO 8601 date (YYYY-MM-DD) Epoch time in milliseconds (example: 1659641316719 [= Thursday, August 4, 2022 7:28:36.719 PM GMT]). See the Epoch time converter. A string: `from=alltime` +/- relative dates in days (d), weeks (w), or months (m) - example: `from=-6m&to=%2B2w` (the period from 6 months ago to 2 weeks after that -- note that the + sign needs to be URI encoded as `%2B`) Only dates within the past 32 days are allowed for engagement endpoints or if reconciled=false.	-30d
`to`	The end of the date range for the request	no	One of the following: An ISO 8601 date (YYYY-MM-DD) Epoch time in milliseconds (example: 1659641316719 [= Thursday, August 4, 2022 7:28:36.719 PM GMT]). See the Epoch time converter. A string: `to=now` +/- relative dates in days (d), weeks (w), or months (m) - example: `from=-6m&to=%2B2w` (the period from 6 months ago to 2 weeks after that -- note that the + sign needs to be URI encoded as `%2B`) Only dates within the past 32 days are allowed for engagement endpoints or if reconciled=false.	now

Fields available

The following fields can be returned for the dimension.

application - the virtual event experience id. If not passed, will be null
engagement_score - engagement score
video_engagement_1 - video engagement at 1% of the duration
video_engagement_25 - video engagement at 25% of the duration
video_engagement_50 - video engagement at 50% of the duration
video_engagement_75 - video engagement at 75% of the duration
video_engagement_100 - video engagement at 100% of the duration
time - the epoch time of the last event received
video_view - the number of times viewer playback began
viewer^[1] - Event viewer (SSO ID or device id or unique string based on user-agent and IP)

Additional fields are available if the query also includes the relevant dimension(s):

city - the city the viewer was in (requires the city dimension)
country - the country (code) the viewer was in (requires the country dimension)
country_name - the country name the viewer was in (requires the country dimension)
region - the region (code) the viewer was in (requires the region dimension)
region_name - the region name the viewer was in (requires the region dimension)
rebuffering_seconds - the total time that the players spent rebuffering (requires that the country or region be included)
device_type - the device type the viewer was using (requires the device_type dimension)

Sending the viewer id

To send a viewer id to to the analytics system, you must create the logic to construct a unique id that will identify the viewer at runtime and then send it to the analytics data collector from the player. The logic to construct the id will depend on how viewers authenticate to see your content.The Brightcove web player and both the iOS and Android SDK players can send the user id to analytics. the following sections show you how to do this for the web and SDK players.

Send viewer id - Brightcove player

First, you need to set the user identifier to store their viewing activity.

Brightcove Player

If you are using Brightcove Player, follow these steps:

Even though viewer data is sent to Brightcove analytics automatically, you need to set the user identifier. To do this, use the setUser() method. For example:
```
myPlayer.bcAnalytics.client.setUser('viewer id');
```
On your websites that host Brightcove Player, you can use an authentication gateway or some identity management solution to keep track of viewers. Use this viewer id as the viewer identifier to pass to Brightcove analytics.

The viewer id value must be a unique string. An invalid value, such as a number, will be ignored.

It is important to set the viewer id before any source is set on the player. It should be called immediately after initializing the player.

<video-js
  id="myPlayerID"
  data-account="1752604059001"
  data-player="hyQW6GByl"
  data-embed="default"
  controls=""
  data-video-id="6156696074001"
  data-playlist-id=""
  data-application-id=""
  width="640" height="360"></video-js>
<script src="https://players.brightcove.net/1752604059001/hyQW6GByl_default/index.min.js"></script>

<script>
  videojs.getPlayer('myPlayerID').ready(function() {
    var myPlayer = this;

    // Set the viewer id for Brightcove analytics
    myPlayer.bcAnalytics.client.setUser('viewer id');
  });
</script>

When the setUser() method is used, the value is not hashed and will be sent in the clear with all subsequent beacons.
Note that the player_init event will not include the user field in this case, but all video_* events should include it.

Custom web player

If you are building a custom implementation that does not use Brightcove Player, add the user parameter to your Data Collection API requests. For details, see the Overview: Data Collection API v2 document.

On your websites that host your player, you can use an authentication gateway or some identity management solution to keep track viewers. Use this viewer id as the viewer identifier to pass to Brightcove analytics.

For the Brightcove Native SDK players, you also need to send a viewer id unless you are depending on the one generated by Brightcove.

Android

For the Android player, add this code:

HashMap<String, String> baseParams = new HashMap<>();
  baseParams.put(Analytics.Fields.USER, "viewer id");
  baseParams.put(Analytics.Fields.APPLICATION_ID, "application id");
  
  HashMap<String, Object> eventParams = new HashMap<>();
  eventParams.put(Analytics.Fields.BASE_PARAMS, baseParams);
  eventEmitter.emit(EventType.ADD_ANALYTICS_BASE_PARAMS, eventParams);

iOS

For iOS or tvOS, add the following code:

@try
  {
    [BCOVGlobalConfiguration.sharedConfig setValue:@{
      @"privateUser": self.viewer id,
      @"privateApplication": @"application id"
    }
    forKey:@"privateSessionAnalytics"];
  }
  @catch (NSException *e)
  {
    NSLog(@"%@", e.description);
  }

Filter values

Used as a filter, a dimension allows you to narrow the results.

Filter values: viewer ids

Combining dimensions

The viewer dimension can be combined with several others, which add addition fields that can be retrieved. The details are in the table below. (Bold items are included in the response by default if the dimension is included.)

Supported Dimension Combinations
Dimension	Additional Fields
`video`	`video` `video_engagement_1` `video_engagement_25` `video_engagement_50` `video_engagement_75` `video_engagement_100` `video_percent_viewed` `video_seconds_viewed` `video_view` `video.tags` `video.reference_id` `video.name` `video.description` `video.long_description` `video.duration`
`country`	`country` `country_name`
`region`	`region` `region_name`
`city`	`city` `dma`
`device_type`	`device_type`

Request Examples

Dimension request sample

    https://analytics.api.brightcove.com/v1/data?accounts=3365624256001&dimensions=viewer&limit=10&fields=viewer,time,video_view,engagement_score

Sample Response

{
  "item_count": 8,
  "items": [
    {
      "engagement_score": null,
      "viewer": "6798840584846290049",
      "time": 1623870475157,
      "video_view": 0
    },
    {
      "engagement_score": 100,
      "viewer": "-1094565064376617663",
      "time": 1623870472882,
      "video_view": 1
    },
    {
      "engagement_score": 100,
      "viewer": "8997125557862445199",
      "time": 1623870433989,
      "video_view": 1
    },
    {
      "engagement_score": 39.13,
      "viewer": "-8839675754655082792",
      "time": 1623872904633,
      "video_view": 1
    },
    {
      "engagement_score": 143.48,
      "viewer": "-6771654281667224776",
      "time": 1623869869930,
      "video_view": 2
    }
  ],
  "summary": {
    "engagement_score": 110.51,
    "time": 1623875119506,
    "video_view": 12
  }
}

Multi-dimension request sample

    https://analytics.api.brightcove.com/v1/data?accounts=3365624256001&dimensions=viewer,country,region,city,video,device_type&limit=10&fields=viewer,time,video_view,engagement_score,video_percent_viewed,video_seconds_viewed,video_engagement_1,video_engagement_25,video_engagement_50,video_engagement_75,video_engagement_100,video.tags,video.reference_id,video.name,video.description,video.duration,video.long_description,dma,country_name,region_name

Sample Response

{
  "item_count": 8,
  "items": [
    {
      "country": "MX",
      "viewer": "6798840584846290049",
      "video.name": "Bison",
      "video_seconds_viewed": 23,
      "video_engagement_75": 1,
      "city": "Zapopan",
      "device_type": "desktop",
      "video": "5754204614001",
      "video_engagement_50": 1,
      "video.description": "Bison in Yellowstone National Park",
      "video.reference_id": null,
      "video_percent_viewed": 100,
      "country_name": "Mexico",
      "region_name": null,
      "video_engagement_25": 1,
      "video.long_description": "Bison in Yellowstone National Park. This is the long description.  This was filmed in Yellowstone National Park.",
      "video.duration": 23295,
      "video_engagement_100": 1,
      "engagement_score": null,
      "video_engagement_1": 1,
      "video.tags": [
        "animals",
        "simulive",
        "yellowstone"
      ],
      "dma": "0",
      "time": 1623870475157,
      "video_view": 0,
      "region": "MX-JAL"
    },
    {
      "country": "US",
      "viewer": "-8839675754655082792",
      "video.name": "Bison",
      "video_seconds_viewed": 9,
      "video_engagement_75": 0,
      "city": "Safety Harbor",
      "device_type": "desktop",
      "video": "5754204614001",
      "video_engagement_50": 0,
      "video.description": "Bison in Yellowstone National Park",
      "video.reference_id": null,
      "video_percent_viewed": 39.13,
      "country_name": "United States",
      "region_name": "Florida",
      "video_engagement_25": 1,
      "video.long_description": "Bison in Yellowstone National Park. This is the long description.  This was filmed in Yellowstone National Park.",
      "video.duration": 23295,
      "video_engagement_100": 0,
      "engagement_score": 39.13,
      "video_engagement_1": 1,
      "video.tags": [
        "animals",
        "simulive",
        "yellowstone"
      ],
      "dma": "539",
      "time": 1623872904633,
      "video_view": 1,
      "region": "US-FL"
    },
    {
      "country": "US",
      "viewer": "-1094565064376617663",
      "video.name": "Bison",
      "video_seconds_viewed": 23,
      "video_engagement_75": 1,
      "city": "Boulder",
      "device_type": "desktop",
      "video": "5754204614001",
      "video_engagement_50": 1,
      "video.description": "Bison in Yellowstone National Park",
      "video.reference_id": null,
      "video_percent_viewed": 100,
      "country_name": "United States",
      "region_name": "Colorado",
      "video_engagement_25": 1,
      "video.long_description": "Bison in Yellowstone National Park. This is the long description.  This was filmed in Yellowstone National Park.",
      "video.duration": 23295,
      "video_engagement_100": 1,
      "engagement_score": 100,
      "video_engagement_1": 1,
      "video.tags": [
        "animals",
        "simulive",
        "yellowstone"
      ],
      "dma": "751",
      "time": 1623870472882,
      "video_view": 1,
      "region": "US-CO"
    },
    {
      "country": "US",
      "viewer": "8997125557862445199",
      "video.name": "Bison",
      "video_seconds_viewed": 23,
      "video_engagement_75": 1,
      "city": "Boulder",
      "device_type": "desktop",
      "video": "5754204614001",
      "video_engagement_50": 1,
      "video.description": "Bison in Yellowstone National Park",
      "video.reference_id": null,
      "video_percent_viewed": 100,
      "country_name": "United States",
      "region_name": "Colorado",
      "video_engagement_25": 1,
      "video.long_description": "Bison in Yellowstone National Park. This is the long description.  This was filmed in Yellowstone National Park.",
      "video.duration": 23295,
      "video_engagement_100": 1,
      "engagement_score": 100,
      "video_engagement_1": 1,
      "video.tags": [
        "animals",
        "simulive",
        "yellowstone"
      ],
      "dma": "751",
      "time": 1623870433989,
      "video_view": 1,
      "region": "US-CO"
    },
    {
      "country": "US",
      "viewer": "-4530870087560842176",
      "video.name": "Bison",
      "video_seconds_viewed": 46,
      "video_engagement_75": 2,
      "city": "Newton Center",
      "device_type": "desktop",
      "video": "5754204614001",
      "video_engagement_50": 2,
      "video.description": "Bison in Yellowstone National Park",
      "video.reference_id": null,
      "video_percent_viewed": 200,
      "country_name": "United States",
      "region_name": "Massachusetts",
      "video_engagement_25": 2,
      "video.long_description": "Bison in Yellowstone National Park. This is the long description.  This was filmed in Yellowstone National Park.",
      "video.duration": 23295,
      "video_engagement_100": 2,
      "engagement_score": 100,
      "video_engagement_1": 2,
      "video.tags": [
        "animals",
        "simulive",
        "yellowstone"
      ],
      "dma": "506",
      "time": 1623875061754,
      "video_view": 2,
      "region": "US-MA"
    },
    {
      "country": "MX",
      "viewer": "-6771654281667224776",
      "video.name": "Bison",
      "video_seconds_viewed": 66,
      "video_engagement_75": 1,
      "city": "Zapopan",
      "device_type": "desktop",
      "video": "5754204614001",
      "video_engagement_50": 1,
      "video.description": "Bison in Yellowstone National Park",
      "video.reference_id": null,
      "video_percent_viewed": 286.96,
      "country_name": "Mexico",
      "region_name": null,
      "video_engagement_25": 1,
      "video.long_description": "Bison in Yellowstone National Park. This is the long description.  This was filmed in Yellowstone National Park.",
      "video.duration": 23295,
      "video_engagement_100": 1,
      "engagement_score": 143.48,
      "video_engagement_1": 1,
      "video.tags": [
        "animals",
        "simulive",
        "yellowstone"
      ],
      "dma": "0",
      "time": 1623869869930,
      "video_view": 2,
      "region": "MX-JAL"
    }
  ],
  "summary": {
    "video_seconds_viewed": 305,
    "video_engagement_75": 10,
    "video_engagement_25": 11,
    "video_engagement_50": 10,
    "video_engagement_100": 10,
    "engagement_score": 110.51,
    "video_engagement_1": 11,
    "video_percent_viewed": 1326.09,
    "country_name": null,
    "region_name": null,
    "time": 1623875119506,
    "video_view": 12,
    "account": "3365624256001"
  }
}