viewer
dimension. The viewer
dimension provides analytics by viewer.URL parameters
Analytics API reports support the following 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 - viewer can be combined with the following dimensions:
|
none |
where |
Used to specify filters for reports | no | {dimension}=={value} - one or more as a semi-colon-delimited list | 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 | a valid field for the request | viewer_view |
fields |
Fields to return | no | varies according to the dimension you are reporting on - see fields below for fields available. | viewer_view |
format |
Format to return results in | no | json | csv | xlxs | json |
from |
The beginning of the date range for the request | no | An ISO 8601 date (YYYY-MM-DD), epoch time in milliseconds, the string alltime, or relative date (-1m); only dates within the past 32 days are allowed for engagement endpoints or if reconciled=false. | 30 days prior to now |
to |
The end of the date range for the request | no | An ISO 8601 date (YYYY-MM-DD), epoch time in milliseconds, the string now, or relative data (+7d); 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 nullengagement_score
- engagement scorevideo_engagement_1
- video engagement at 1% of the durationvideo_engagement_25
- video engagement at 25% of the durationvideo_engagement_50
- video engagement at 50% of the durationvideo_engagement_75
- video engagement at 75% of the durationvideo_engagement_100
- video engagement at 100% of the durationtime
- the epoch time of the last event receivedvideo_view
- the number of times viewer playback beganviewer[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 thecity
dimension)country
- the country (code) the viewer was in (requires thecountry
dimension)country_name
- the country name the viewer was in (requires thecountry
dimension)region
- the region (code) the viewer was in (requires theregion
dimension)region_name
- the region name the viewer was in (requires theregion
dimension)rebuffering_seconds
- the total time that the players spent rebuffering (requires that thecountry
orregion
be included)device_type
- the device type the viewer was using (requires thedevice_type
dimension)
Setting 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. See the following documents for details:
- Brightcove web player: Set the user identifier
- iOS: iOS Implementation
- Android: Android Implementation
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.)
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"
}
}