Exporting Virtual Event Viewer Data

Introduction

You can see reporting events for your virtual events by aggregated by device and location, in addition to the account, viewer and video analytics for a particular account. This information can help you better organize your upcoming virtual events to maximize the viewer engagement.

This data can be downloaded using the Analytics API, and can be returned in JSON, CSV, or XLXS format. The next section provides a brief introduction to the Analytics API. If you already know how to use it, you may skip to the following section for information on getting analytics data for virtual events.

The Analytics API

Like other platform APIs, the Analytics API is a RESTful API that allows you to interact with the Video Cloud platform programmatically. It returns analytics data based on various URL parameters that you include with the request. By default the data is returned in JSON format, but you can request CSV or XLXS data to be opened in spreadsheet app instead.

How to make requests

Requests to RESTful APIs are made to a URL, the same way that a browser makes a request to a URL to retrieve a web page. However, you cannot simply paste the API request into a browser, because the request must be authenticated (we are getting to that) to show that you are authorized to get the data. There are many tools to help you do it, however. Here is a short list:

• Insomnia (a popular cross-platform app)
• Postman (another popular cross-platform app)
• Online API Tester created by Brightcove Learning Services
• api-tester.sh (a curl-based shell script created by Brightcove Learning Services)

Authenticating requests

To protect your data, Analytics API requests must include an Authorization header that contains an access token:

Authorization: bearer your access token

How do you get the access token? You can read all about it in Getting an Access Token, but the short answer is that after you do a little preparation, any of the tools listed above (and many others) will get it for you.

The preparation consists of getting client credentials, which consist of a client_id and a client_secret. You can get these using the Studio Admin page (you have to be an Admin on your account or get an admin to do it):

1. In the primary navigation, click Admin > API Authentication.
2. Click Register New Application.
3. In the dialog that opens enter "Analytics" for the name.
4. Select the account(s) you want to use the API for.
5. Under Exposed Brightcove APIs, select Read under Analytics and Video Read under CMS:

   

6. Click Save.
7. A new dialog will display the Client ID Client Secret. Copy and save them both in a secure place where you can find them again.

The access token

The access token is retrieved from another Brightcove API using the client credentials. You can do that yourself, but again, any of the tools listed in the previous section will take your client credentials and get the access token for you, and put it into the request header sent with your Analytics API request.

The Analytics API request

Here is the form of the Analytics API request:

http://analytics.api.brightcove.com/v1/data?accounts={account1_id,account2_id}
&from={yyyy-mm-dd}
&to={yyyy-mm-dd}
&dimensions=viewer,video,country,city,region,device_type,protocol
&fields=video,video.name,viewer,country,region,city,device_type,time,video_view,video_percent_viewed,video_seconds_viewed
&sort=-video_view&limit=20&format=csv

Required parameters

See Parameters for some additional optional parameters that can be used to the set the date range, sort the results, set the response format, etc.

Where filters

You can filter the results using the where parameter. See Where filters for details

Fields

Collected directly from the player

• viewer: Event viewer(SSO ID or device id or unique string based on user-agent and IP), taken from the user field
• time: timestamp of the last event received
• video
• country
• region
• city
• device_type

Aggregated metrics

• video_view: the total number of times video_view was sent by the player (note that video_view is not sent when the viewer pauses and restarts a video, or watches the video multiple times without refreshing the page)

Calculated fields

• video_seconds_viewed:
  • Highest range value received by Collector API irrespective of order
  • Note that events describing ranges over 20 seconds are discarded by the Analytics system, which could result in an inaccurate value if the player was not correctly instrumented to send ranges of 20 seconds or less - see Overview: Data Collection API
• video_percent_viewed: video_seconds_viewed/video_duration *100 (this value will be missing or inaccurate if the video duration was not sent to the data collector)
• video_engagement_xx: the total number of views at the xx video_percent_viewed (xx = 1, 25, 50, 75, or 100)

{
	4    "item_count": 1,
	5    "items": [
	6        {
	7            "viewer": "test@brightcove.com",
	8            "country": "GB",
	9            "video_seconds_viewed": 253,
	10            "city": "London",
	11            "video_percent_viewed": 527.08,
	12            "device_type": "other",
	13            "video": "70701475639202",
	14            "video_view": 46,
	15            "region": "GB-ENG"
	16        }
	17    ],
	18    "summary": {
	19        "video_seconds_viewed": 253,
	20        "video_percent_viewed": 527.08,
	21        "video_view": 46
	22    }
	23}