[object Object] Icon

Learn how to create, start, manage and modify Encodings

[object Object] Icon

Learn how to create, start, manage and modify Players

[object Object] Icon

Learn how to create, start, manage and modify Analyticss

Docs Home
User shortcuts for search
Focus by pressing f
Hide results by pressing Esc
Navigate via   keys

Thu Sep 13 2018

How to build your own video analytics dashboard

OverviewLink Icon

Once you have set up your Bitmovin Player to track analytics, it’s time to get some insights from the collected data.

In this tutorial we will walk you through a boilerplate analytics dashboard and we’ll show you how to customize it to your needs. This dashboard compares video metrics for different countries, browsers or players. The dashboard is built with React.

Getting startedLink Icon

To get the boilerplate dashboard up and running on your computer, clone the repository and follow the steps in the README.

After you’ve entered your Bitmovin API key, the dashboard will look like this: analytics comparison app

There are 3 main areas on the page:

  1. Period selection
  2. Filters
  3. Comparison

Period selectionLink Icon

The period selection is located in the top-right corner of the dashboard. It determines the start and end date of the analytics data considered in the comparison. These date values will be used in the between clause of the API request:

1.between(fromDate, toDate)

In the period selection you can either choose predefined periods like “Last 7 days” or specify a custom date range. Feel free to customize the predefined periods in the PeriodSelection React component.

Bitmovin retains your analytics data for 90 days, so it won’t be sensible to define start dates earlier than 90 days ago.

FiltersLink Icon

You can filter your analytics data by various attributes like the viewer’s country or browser. All filters in the dashboard work the same way: You add a filter attribute and select the value you’re interested in. For example, you can add a “Browser” filter and select “Chrome”. Hence only analytics data from views in Google Chrome will be considered.

Under the hood, for each filter you add, a filter statement is added to the query:

1.filter(attribute, 'eq', value)

In our example, attribute would be 'BROWSER' and value would be 'Chrome‘.

Adding a custom filterLink Icon

You can filter for every attribute tracked in your analytics data. To add a filter to the dashboard, just add a line to the attributes array in src/lib/attributes.js.

We could add a filter for the domain the video was played at by appending the following line to the attributes array:

1{ collectionName: 'domains', singleName: 'domain', attribute: 'DOMAIN' },

The collectionName and singleName are used for display purposes only, you can assign them any text you like. The attribute must match one of the attribute names in the API. There’s an extensive list of attribute names in the Bitmovin Analytics API docs.

Once you’ve added your filter attribute, you can use it as a filter right away.

ComparisonLink Icon

In the comparison table it’s possible to compare video metrics for several attribute values. When you open the comparison dashboard, metrics are compared by country. You can remove countries by clicking on the – button next to the country name. Moreover you can add an arbitrary amount of countries to the comparison using the + button in the top-right corner of the table.

Customizing comparable attributes

In the top-left corner you can select an attribute to compare. We added a few default attributes, but you can customize them the way you want: In src/lib/attributes.js make sure the attribute is in the attributes array and add the property comparable: true to the attribute object. As soon as you save the file, the attribute will appear in the dropdown.

Metrics and queriesLink Icon

Each table row contains several values for a specific metric. We already predefined some useful metrics for you, but – like with every other aspect – we encourage you to customize them to your needs.


Every metric has an associated query meant to retrieve a scalar value. A query looks like this:

1 {
2 label: 'Total impressions',
3 dimension: 'IMPRESSION_ID',
4 aggregation: 'count',
5 filters: [['VIDEO_STARTUPTIME', 'GT', 0]],
6 type: 'amount',
7 }
8 ```
9This query counts the impressions of videos with a startup time greater than zero. The filter condition ensures that only impressions are counted where the video was actually played.
11A query can have the following properties:
14| Property name | Description | Allowed values |
15| ---------- | ---------- | ---------- |
16| `label` | The metric name displayed in the table. | Any string. |
17| `dimension` | The attribute to aggregate. | All attributes of your analytics data. |
18| `aggregation` | How to aggregate your data to a scalar value. | `'count'`, `'sum'`, `'avg'`, `'min'`, `'max'`, `'stddev'`, `'percentile'`, `'variance'` or `'median'`. |
19| `aggregationParam` | Additional information for the aggregation. | Only necessary for `percentile`. Pass a number, for example `95`, if you’re interested in the 95th percentile. |
20| `filters` | Restrict aggregated data with conditions. | An array of filters. Each filter is an array of 3 elements: `[attributeName, operator, value]`. Please consult the [Bitmovin Analytics API](https://bitmovin.com/encoding-documentation/bitmovin-api/#/reference/analytics/) for a list of valid attribute names and operators. These filters are merged with the filters specified in the user interface |
21| `type` | What type of result you expect. This influences display format as well as what are considered the best and worst values. | `'amount'` or `'time'`. |
23## Query groups
24In order to structure the comparison table, queries are organized into groups. A query group looks like this:
28 label: 'Impressions',
29 queries: [query1, query2, query3],

The label will appear as separating header in the comparison table above all queries listed in the queries array.

Defining your own queries

In src/lib/queries.js you can define your own query groups and queries. Define the queries of one query group as an array, like the impressionQueries already in the file. Then add the group to the queryGroups at the bottom of the page, assigning a label and the queries array.

Give us feedback