npm package: @qualabs/bitmovin-analytics-collector-theoplayer
Description: Instruments THEOPlayer and collects information to be sent to the Bitmovin Analytics service.
Latest version: 1.0.4

# Bitmovin Analytics Collector Plugin for THEOPlayer

Instruments THEOPlayer 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://bitmovin.com/dashboard/signup).

## Installation
### Using npm
```bash
npm install @qualabs/bitmovin-analytics-collector-theoplayer
```

### Using a CDN
```html
<script src="https://cdn.jsdelivr.net/npm/@qualabs/bitmovin-analytics-collector-theoplayer@latest/dist/bitmovin-analytics-collector-theoplayer.min.js"></script>
```

## Usage
Before integrating the plugin, make sure you have a working installation of THEOPlayer. For more details on installing and using THEOPlayer, please refer to the [THEOPlayer Getting Started Guide](https://www.theoplayer.com/docs/open-video-ui/web/getting-started/).

### Using the Plugin via Module Import
If you are using a module bundler, import the plugin as follows:
```javascript
import { TheoCollector } from "theo-bitmovin-collector-plugin";

// The player configuration
const analyticsConfig = {
    licenseKey: 'your_bitmovin_analytics_license',
};

// Create the player instance
collector = new TheoCollector(analyticsConfig, player);
```
### Using the Plugin via Script Tag
Alternatively, if you prefer using a script tag, include the plugin from the CDN and initialize it:

```html
<script src="https://cdn.jsdelivr.net/npm/@qualabs/bitmovin-analytics-collector-theoplayer@latest/dist/bitmovin-analytics-collector-theoplayer.min.js"></script>
<script>
    const analyticsConfig = {
        licenseKey: 'your_bitmovin_analytics_license',
    };
    var collector = new bitmovin.TheoCollector(analyticsConfig, player);
</script>
```
**Note:** The collector plugin supports both the *standard* and *chromeless* versions of *THEOPlayer*.

## Full Analytics Config
Below is an example of the complete configuration object for Bitmovin Analytics:
```ts
const fullConfig = {
    // Your Bitmovin Analytics config
    licenseKey: string, 
    // Optional: Use a different userId each session. If enabled overrides cookiesEnabled to false. Deafults to false
    randomizeUserId: boolean, 
    // Optional: URL to send analytics to
    backendUrl: string, 
    // Optional: CDN Provider used to deliver the video
    cdnProvider: string, 
    // Optional: User-ID in the customer system
    customUserId: string, 
    // Optional: Metadata for this source. Should manually be updated on source change.
    sourceMetadata: { 
        // Optional: Human readable title of the video, provided by customer */
        title: string, 
        // Optional: ID of the video, provided by customer
        videoId: string, 
        // Optional: CDN Provider used to deliver the video. Overrides config.cdnProvider
        cdnProvider: string,
        // Optional: HTTP path e.g. .../about 
        path: string, 
        // Optional: Used as a fallback to determine if stream is live.
        isLive: boolean, 
    },
    // Optional: Whether to use cookies to persist userId across multiple sessions in the same browser. Defaults to true
    cookiesEnabled: boolean,
    // Optional: Domain to be used for userId cookie. Defaults to "bitmovin_analytics_uuid"
    cookiesDomain: string,
    // Optional: Cookie max age in seconds. Defaults to 1 year
    cookiesMaxAge: number,
    // Optional: CustomDataX 1 through 50. Optional free-form data
    customData1: string,
    // ...
    customData50: string,
}
```