Product Updates | Contact Support | System Status
Page Contents

    Dimension: viewer

    In this topic, you will learn about the Analytics API viewer dimension. The viewer dimension provides analytics by viewer.

    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 - viewer can be combined with the following dimensions:
    • account
    • date
    • date_hour
    • country
    • region
    • city
    • video
    		 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 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)

    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:

    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"
  }
}
    Page last updated on 09 May 2022