We introduced our new v3 API with breaking changes. Together with the major version release, we also integrated our Analytics collector directly into Bitmovin Player (starting with player version `3.41.0`).

This guide explains how to migrate from our v2 collector to the new v3 API which is pre-integrated into the Bitmovin Player. This guide also explains how to migrate our ExoPlayer collector to the latest API.

For more information about the reason behind these changes see [Native Collector API v3](🔗).

# Overview of changes

Bitmovin Player introduced a new Analytics API to simplify the setup and configuration of Analytics.

All public data classes used by the v3 API have been moved into the package `com.bitmovin.analytics.api` and are immutable.

The old `BitmovinAnalyticsConfig` is now split within `AnalyticsConfig`, holding all config information, and `DefaultMetadata` and `SourceMetadata` which holds metadata to enrich the analytics data. `DefaultMetadata` contains source independent metadata (e.g.: `customUserId`) and `SourceMetadata` contains source related metadata.

`SourceMetadata` moved to different package, is immutable and has a customData object with all customData fields (customData1-30).

Old Collector classes with constructors are deprecated and should be replaced by the player-specific factories.

# Migrating to the new API

## Bitmovin Player

Starting with version `3.41.0`, the Bitmovin Player for Android includes Analytics out of the box. This section describes how to migrate from the standalone v2 Analytics collector to the pre-integrated collector in the Player.

### Step 1: Remove dependency to standalone collector

The player has a direct dependency on the analytics collector, and therefore there's no explicit dependency to the collector needed anymore.

### Step 2: Move to the integrated collector

#### Configure Player with Analytics and remove the standalone collector

The new configuration class `AnalyticsConfig` only contains behavioural settings for the collector, and no metadata. For a minimal setup, only the analytics license needs to be specified. The integrated analytics simplifies usage compared to the standalone collector since there is no explicit attaching and detaching needed anymore.

#### Move metadata from `BitmovinAnalyticsConfig` to `SourceMetadata` and add it to the source

#### Move metadata from `BitmovinAnalyticsConfig` to `DefaultMetadata`

Metadata that is independent of the source can be set through the `DefaultMetadata` parameter when creating the player. If certain fields are specified in both, `SourceMetadata` and `DefaultMetadata` (e.g.: `customData1`, `experimentName`, `cdnProvider`), `SourceMetadata` takes precedence.

#### Use the Player API to modify `CustomData`

## ExoPlayer

#### Replace `BitmovinAnalyticsConfig` with `AnalyticsConfig`

The new configuration class `AnalyticsConfig` only contains behavioural settings for the collector, and no metadata. For a minimal setup, only the analytics license needs to be specified.

#### Add `DefaultMetadata` (Optional)

Metadata that is independent of the source can be set through the `DefaultMetadata` parameter when creating the player. If certain fields are specified in both objects, `SourceMetadata` and `DefaultMetadata` (e.g.: `customData1`, `experimentName`, `cdnProvider`), `SourceMetadata` takes precedence.

#### Replace old constructor call with new factory method call

Create the analytics collector with the player specific factory. `defaultMetadata` is an optional parameter.

#### Move metadata from `BitmovinAnalyticsConfig` to `SourceMetadata` (Optional)

The video specific metadata is now provided by `SourceMetadata`.

# Appendix: Mappings

## Classes

### Config and Metadata classes

### Interfaces / Factories

## Fields

### Config

### Metadata

#### DefaultMetadata

#### SourceMetadata

## Methods

### All Collectors

### Bitmovin Player Collector / Player Integrated Analytics