Configuration Guide

Bitmovin Analytics allows for extensive customisation of your data architecture. This means data can be easily extended and enriched with information that is not collected through the player integration.

Required Configuration

The only field required on the configuration is your license key which you can find in our Dashboard. Checkout this page to learn more about how to setup the collector How to Set Up

var config = {
val analyticsConfig = AnalyticsConfig("<YOUR LICENSE KEY>")
let config = AnalyticsConfig(licenseKey: "<YOUR LICENSE KEY>")
analyticsConfig = {

With the analytics key set in the config you are ready to go. But we recommend to take a look at the other possible configuration fields to enhance the quality of the tracked data even more.

Optional Configuration

Some configuration fields are only available on certain platforms. Here is a list of them to give you an overview.

NameDescriptionavailable Platforms
retryPolicyDefault: NO_RETRY
Configuration to specify retry behaviour when samples cannot be sent to the backend. This also allows to enable offline tracking of analytics events (RetryPolicy.LONG_TERM).
iOS, Android
adTrackingDisabledDefault: false
Flag to disable Ad tracking.
iOS, Android
randomizeUserIdDefault: false
If false we use a device specific value in our data. This value is either retrieved from the system itself and is the same all the time or saved as a random UUID on the system. This allows you to connect sessions happening on the same device.
If true we use a randomly generated UUID on every session. If users of your platform don't want to be tracked we recommend to set this to true
iOS, Android
cookiesEnabledDefault: true
Very similar to randomizeUserId if this is true we save a random UUID in a cookie for cross referencing sessions .

Optional Metadata Fields

The optional fields below are not required to be set, but we recommend to set them to improve the quality of the tracked data by adding more information to the current session. This enables better analysis of your data in the analytics dashboard.

Here is a list of possible metadata fields available on all platforms:

NameUse CasePre-requisite for
titleConfiguring the title will allow you to efficiently compare the performance of different content pieces in the Bitmovin Analytics Dashboard. You will see names and titles instead of just numbers and IDs.Video Title Filter
Video Title Breakdown
Bitrate Heatmap
videoIdConfiguring the videoId is important to ensure consistency within your data framework. We use the videoId to enable filtering and breaking down by videoTitle, hence setting the videoId is a pre-requisite to enable this feature. If no videoId is set, the videoTitle filter cannot be applied to the data.
In case there are multiple videoTitle values with the same videoId, we assign the data to each of the different video titles.
Video Title Filter
Video Title Breakdown
Bitrate Heatmap
cdnProviderSetting the CDN provider in the configuration allows you to use CDN as a breakdown or global filter in the Bitmovin Analytics Dashboard and API. This will enable you to compare the performance of the different CDN providers that you’re using.CDN Filter
CDN Breakdown
isLiveDifferentiating between Live and VOD content is important, as both are often distributed through different workflows. Auto-detection is only possible once stream metadata is received so explicitly providing this information is helpful in certain cases and improves the accuracy of your data.Live Filter
Live Breakdown
experimentNameFor testing purposes, Bitmovin Analytics provides an Experiment field to differentiate between testing groups.
A popular application for this data field is to use it for testing a new player version, before rolling it out to all your viewers.
Experiment Filter
Experiment Breakdown
customUserIdThe customUserId field can be used to integrate a subscriber or user ID into Bitmovin Analytics.
Features such as Session Tracking will only work if a customUserId is configured. Otherwise, all impressions will be assigned to a single null user.

A consistent ID for a specific user is important to enable use-cases such as cross-device tracking.

For privacy reasons we advise you to send c`ustomUserIds not as emails or otherwise personally identifiable form but either as IDs or in a hashed form.

In case you want to tie your video Analytics data with other data sets, it is important to pass customUserIds in a format that is consistent across your different data sources.
Session Tracking
customDataXThe customData fields can be freely configured. The data sent through these fields can be used as a filter or as a breakdown to segment the data according to your needs.
Common use-cases for customData are sending the app version used, a cross-domain or profile ID, to track viewers across different platforms, or assigning a high-level content category to order content assets. But the options are more or less unlimited.

In the dashboard, under the license settings, customData fields can be labeled according to your liking.

Note: For customData field queries we allow a cardinality of maximum of 15,000 distinct values per customData field within the selected time-frame.
Each customData field has a limit of 160 characters and there are 5 customData Fields available for every subscription.
Additional customData fields can be activated, up to 30 in total. These additional fields may incur a cost depending on the type of data stored. Please reach out to us via the support form in the dashboard if you'd like more information.
Custom Filters
Custom Breakdowns

Some metadata fields are only available on certain platforms. Here is a list of them to give you an overview

NameDescriptionavailable Platforms
pathBreadcrumb path to show where in the app the user is.iOS, Android