# Bitmovin Analytics Collector

[![npm version](https://badge.fury.io/js/bitmovin-analytics.svg)](https://badge.fury.io/js/bitmovin-analytics)
[![install size](https://packagephobia.com/badge?p=bitmovin-analytics)](https://packagephobia.com/result?p=bitmovin-analytics)

Instruments adaptive streaming video players and collects information to be sent to the Bitmovin Analytics service.

To get started collecting data with Bitmovin Analytics you need a License-Key which you can get for free by signing up for a [free Bitmovin account](https://dashboard.bitmovin.com/signup).

## Supported Players, Platforms and Devices

The supported video players are shown here: [Analytics Collectors - HTML5](https://developer.bitmovin.com/playback/docs/supported-platforms-analytics#html5-collectors)

The supported platforms and devices are shown here: [Analytics Collectors - Platforms & Devices](https://developer.bitmovin.com/playback/docs/supported-platforms-analytics#overview)

## Usage

[A getting started guide](https://developer.bitmovin.com/playback/docs/setup-analytics-web#bitmovin-player) on how to integrate Bitmovin Analytics Collector with the Bitmovin Player is available on our homepage.

For more comprehensive integration documentation, please consult the [Bitmovin Analytics documentation](https://developer.bitmovin.com/playback/docs/setup-analytics).

### Integrating Bitmovin 8

Bitmovin Player v8 comes with Analytics pre-installed and just requires an `analytics` section containing your license key in the player configuration.

A minimal example:

```js
const configWithAnalytics = {
  key: '<YOUR PLAYER KEY>',
  analytics: {
    key: '<YOUR ANALYTICS KEY>',
    videoId: 'VIDEO_ID',
  },
};

const container = document.getElementById('my-player');
const player = bitmovin.player.Player(container, configWithAnalytics);
```

To ensure you are running a specific version (e.g. when including the `bitmovin-analytics` package from NPM) override the built-in analytics module:

Using `script` tag:

```js
<script type="text/javascript" src="https://cdn.bitmovin.com/analytics/web/2/bitmovin-analytics.js"></script>;
bitmovin.player.Player.addModule(bitmovin.analytics.PlayerModule);
```

Using `npm`:

```js
import {Player} from 'bitmovin-player/modules/bitmovinplayer-core';
import {PlayerModule as AnalyticsModule} from 'bitmovin-analytics';
Player.addModule(AnalyticsModule);
```

### Integrating 3rd Party Players

To integrate other players pick the appropriate adapter (`AmazonIVSAdapter`, `BitmovinPwxAnalyticsPackage`, `CAFv3Adapter`, `DashjsAdapter`, `HlsAdapter`, `ShakaAdapter`, `VideojsAdapter` or `HTMLVideoElementAdapter`) and instantiate the adapter by passing the player instance.

An example for HLS.js:

```js
const analyticsConfig = {
  key: '<YOUR ANALYTICS KEY>',
  videoId: 'VIDEO_ID',
};

const player = new Hls();
const analytics = new bitmovin.analytics.HlsAdapter(analyticsConfig, player);

player.loadSource('https://path.to/your/stream.m3u8');
player.attachMedia(document.getElementById('video'));
```

Before changing the video source in the player, you need to call `sourceChange()` on the associated analytics adapter. You can pass new configuration properties to this method like `videoId` or `videoTitle`

```js
analytics.sourceChange({
  videoId: 'new-video-id',
  title: 'New Video',
});

// Load the new source into player
```