Bitmovin Player Conviva Analytics Integration

Limitations

Currently we don't support ad tracking.

Compatibility

This version of the Conviva Analytics Integration works only with Bitmovin Player Version >= 1.7.x. The recommended and tested version of the Conviva SDK is 2.151.0.36990.

Getting Started

Clone Git repository

Running the example

Run npm i to install dependencies
Fetch conviva SDK

Download conviva SDK
Copy all conviva files and Put it into ./ConvivaIntegration/components/conviva

Ensure that you are in the same network as the roku device
Run npm run serve:example (This will copy all needed files from ./ConvivaIntegration to the ./demo folder)
Enter your Conviva customer key and gateway URL in demo/PlayerExample.brs
Enter your Bitmovin player ID in demo/manifest
Zip and deploy the demo to the roku device

Usage

Use with Source Code

Fetch conviva SDK

Download conviva SDK files
Create a folder in your components folder called conviva
Put the ConvivaClient.brs, ConvivaCoreLib.brs, ConvivaTask.brs & ConvivaTask.xml into the newly created ./components/conviva folder. If you want to create a different folder structure you need to change the import of the ConvivaSDK within the ConvivaAnalyticsTask.xml

Copy following files to your components folder:

./ConvivaIntegration/components/bitmovinConviva/ConvivaAnalytics.brs
./ConvivaIntegration/components/bitmovinConviva/ConvivaAnalytics.xml
./ConvivaIntegration/components/bitmovinConviva/ConvivaAnalyticsTask.brs
./ConvivaIntegration/components/bitmovinConviva/ConvivaAnalyticsTask.xml
./ConvivaIntegration/components/bitmovinConviva/ContentMetadataBuilder.brs
./ConvivaIntegration/components/bitmovinConviva/ContentMetadataBuilder.xml
./ConvivaIntegration/components/bitmovinConviva/helper

Create a instance of ConvivaAnalytics

m.convivaAnalytics = CreateObject("roSGNode", "ConvivaAnalytics")

Use as Component Library

Fetch conviva SDK

Download conviva SDK files
Create a folder in your components folder called conviva
Put the ConvivaClient.brs, ConvivaCoreLib.brs, ConvivaTask.brs & ConvivaTask.xml into the newly created ./components/conviva folder.

run npm install && npm run build:component
Include the created ZIP from the ./dist folder into your channel as a component library

m.conviva = CreateObject("roSGNode", "ComponentLibrary")
m.conviva.id = "conviva"
m.conviva.uri = "http://PATH_TO_YOUR_ZIP.zip"
m.top.appendChild(m.conviva)
m.conviva.observeField("loadStatus", "YOUR_CALLBACK") ' Ensure the library is loaded before using it

Create an instance of ConvivaAnalytics within the callback

m.convivaAnalytics = CreateObject("roSGNode", "bitmovinPlayerIntegrationConviva:ConvivaAnalytics")

Setup

Setting up the instance of ConvivaAnalytics

Ensure that the bitmovinPlayer exists here as well

customerKey = "YOUR_CUSTOMER_KEY"
config = {
  debuggingEnabled : true
  gatewayUrl : "YOUR_GATEWAY_URL" ' optional and only for testing
}
m.convivaAnalytics.callFunc("setup", m.bitmovinPlayer, customerKey, config)

' Initialize ConvivaAnalytics before calling setup or load on the bitmovinPlayer
m.bitmovinPlayer.callFunc(m.BitmovinFunctions.SETUP, m.playerConfig)

Advanced Usage

Custom Deficiency Reporting (VPF)

If you want to track custom VPF (Video Playback Failures) events when no actual player error happens (e.g. endless stalling due to network condition) you can use following API to track those deficiencies:

m.convivaAnalytics.callFunc("reportPlaybackDeficiency", "MY_ERROR_MESSAGE", true, true)

See ConvivaAnalytics.brs for more details about the parameters.

Custom Events

If you want to track custom events you can do so by adding the following:

For an event not bound to a session, use:

m.convivaAnalytics.callFunc("sendCustomApplicationEvent", "MY_EVENT_NAME", {
  eventAttributeKey: "eventAttributeValue"
})

For an event bound to a session, use:

m.convivaAnalytics.callFunc("sendCustomPlaybackEvent", "MY_EVENT_NAME", {
  eventAttributeKey: "eventAttributeValue"
})

See ConvivaAnalytics.brs for more details.

Content Metadata Handling

If you want to monitor video session you can do so by adding the following:

contentMetadataOverrides = {
  playerName: "Conviva Integration Test Channel",
  viewerId: "MyAwesomeViewerId",
  tags: {
    "CustomKey": "CustomValue"
  }
}
m.convivaAnalytics.callFunc("monitorVideo", contentMetadataOverrides)

If you want to override some content metadata attributes during current session you can do so by adding the following:

contentMetadataOverrides = {
  playerName: "Conviva Integration Test Channel",
  viewerId: "MyAwesomeViewerId",
  tags: {
    "CustomKey": "CustomValue"
  }
}
m.convivaAnalytics.callFunc("updateContentMetadata", contentMetadataOverrides)

End a Session

If you want to end a session manually you can do so by adding the following:

m.convivaAnalytics.callFunc("endSession")

TurnerOpenPlatform/bitmovin-player-roku-analytics-conviva