Logo

Application collectors

Bitmovin Media Player

For the Android Collector

The Bitmovin Media Player Extension is a configuration option for the Android Collector by Datazoom that makes the following additional data points automatically collectable in real time.

Integration Instructions

Maven Central

The Datazoom Bitmovin Adapter enables seamless tracking of playback events from Bitmovin Player and sends them to our data collection platform. This library simplifies integration by providing shared utilities and abstraction layers, making it easy to incorporate Datazoom's tracking capabilities into Bitmovin Player-powered applications.

📦 Dependency

Add the following to your build.gradle.kts or build.gradle:

Kotlin DSL

1implementation("io.datazoom.sdk:bitmovin:{latest-version}")

Groovy DSL

1implementation 'io.datazoom.sdk:bitmovin:{latest-version}'

Usage

To integrate the Bitmovin Collector into your project:

Add the Bitmovin dependency to your project's Gradle file. Initialize the Bitmovin Collector by providing your Datazoom configurationId. Integrate the Bitmovin Collector with your Bitmovin Player implementation using the provided API methods for tracking video events and interacting with Datazoom's backend services.

Initialization

API
1import io.datazoom.sdk.Datazoom2import io.datazoom.sdk.Config34fun Datazoom.init(config: Config)
Example
1import io.datazoom.sdk.Datazoom2import io.datazoom.sdk.logs.LogLevel3import io.datazoom.sdk.Config.Builder45Datazoom.init(6    build(7        configurationId = {YOUR_API_KEY},8        block = {9            logLevel(LogLevel.VERBOSE)10        }11    )12)

Create Context

If you want to track events from your Bitmovin Player, you need to create a context and assign your player to it so that the SDK can track events and metadata from your specified player.

API
1import com.bitmovin.player.api.Player2import io.datazoom.sdk.BaseContext3import io.datazoom.sdk.Datazoom4import io.datazoom.sdk.DzAdapter56/**7 * Creates a player context. A player context is used to embed the player with Datazoom and is responsible for player-specific events.8 *9 * @param player The Bitmovin Player instance.10 * @param eventSpace The base context to be used to create the player context. This parameter is optional. If not provided, a default base context will be created.11 * @return The player context.12 * @see <a href=&quot;https://cdn.bitmovin.com/player/android/3/docs/player/index.html&quot;>Player</a>13 * @see <a href=&quot;https://help.datazoom.io/&quot;>Datazoom Help</a>14 */15fun Datazoom.createContext(player: Player, eventSpace: BaseContext) : DzAdapter
Example

1import io.datazoom.sdk.bitmovin.createContext2import io.datazoom.sdk.Datazoom3import io.datazoom.sdk.DzAdapter45/* BaseContext is optional, meant for special usecase */67val adapter: DzAdapter = Datazoom.createContext(player)

Custom Metadata - Context

Context custom metadata is used to attach metadata, which is a HashMap of your choice, to each event sent from the given context you created using the Datazoom object. For more information, please refer to the Datazoom documentation on metadata.

API
1import io.datazoom.sdk.DzAdapter23/**4 * Sends metadata to Context.5 *6 * @param metadata a Map that will be attached to each event being sent from SDK, for more information on this topic, please visit our7 *   documentation.8 */910fun DzAdapter.setMetadata(metadata: Map<String, Any>)
Example
1import io.datazoom.sdk.DzAdapter23yourAdapter.setMetadata(4    hashMapOf(5        &quot;property&quot; to &quot;custom property&quot;,6        &quot;property2&quot; to &quot;custom property2&quot;,7    )8)
Get metadata

You can also retrieve your current metadata by calling the following

API
1import io.datazoom.sdk.DzAdapter23/**4 * Returns the metadata that is being sent with each event in given context.5 *6 * @return The metadata that is being sent with each event in given context.7 */89fun DzAdapter.getMetadata(): Map<String, Any>
Example
1import io.datazoom.sdk.DzAdapter23val metdata: Map<String, Any> = yourAdapter.getMetadata()
Delete metadata
API
1import io.datazoom.sdk.DzAdapter23fun DzAdapter.clearMetadata()
Example
1import io.datazoom.sdk.DzAdapter23yourAdapter.clearMetadata()

Casting

We have ability to fire casting events however we don't track any communication you have with chromecast receiver. You'll need to integrate our Chromecast Collector on your receiver in order to collect events from the cast session. We expect you to invoke context/adapter following function with a boolean sending casting state.

1import io.datazoom.sdk.DzAdapter23fun DzAdapter.sendCastEvent(isCasting: Boolean)
Example
1import io.datazoom.sdk.DzAdapter23yourAdapter.sendCastEvent(isCasting = {castingState})

Fullscreen

Datazoom supports tracking of Fullscreen/Exit Fullscreen events. You can send the fullscreen event by calling following function with a boolean sending fullscreen state.

API
1import io.datazoom.sdk.DzAdapter23/**4  * Sends fullscreen event to Datazoom.5  *6  * @param isFullScreen A boolean value indicating whether the player is in fullscreen mode.7  */89fun DzAdapter.sendFullScreenEvent(isFullScreen: Boolean)
Example
1import io.datazoom.sdk.DzAdapter23yourAdapter.sendFullScreenEvent(isFullScreen = {playerScreenMode})

Set player version

Datazoom supports collecting the player version. You can send the player version by calling following function with a String sending player version.

API
1import io.datazoom.sdk.DzAdapter23/**4  * Set &#39;versionName&#39; as metadata to the player context.5  *6  * @param versionName The version of the player.7  */89fun DzAdapter.setPlayerVersion(versionName: String)
Example
1import io.datazoom.sdk.DzAdapter23yourAdapter.setPlayerVersion(versionName = &quot;1.0.0&quot;)

Custom Events - Context

To send events in the global scope, you can use the following method, with each parameter explained below.

1import io.datazoom.sdk.DzAdapter23/**4 * Sends an event to given context.5 *6 * @param name The name of the event.7 * @param payload a Map that will be attached to each event being sent from given context, for more information on this topic, please visit our documentation.8 */910fun DzAdapter.generateEvent(name: String, payload: Map<String, Any>)
Example
1import io.datazoom.sdk.DzAdapter23yourAdapter.generateEvent(4    name = &quot;test&quot;,5    payload =6        hashMapOf(7            &quot;property&quot; to &quot;abc&quot;,8            &quot;property2&quot; to &quot;xyz&quot;,9        )10)

Custom Events - Global

To send events in the global scope, you can use the following method, with each parameter explained below.

1import io.datazoom.sdk.Datazoom23/**4 * Sends an event to Datazoom.5 *6 * @param name The name of the event.7 * @param payload a Map that will be attached to each event being sent from SDK, for more information on this topic, please visit our documentation.8 */910fun Datazoom.generateEvent(name: String, payload: Map<String, Any>)
Example
1import io.datazoom.sdk.Datazoom23Datazoom.generateEvent(4    name = &quot;test&quot;,5    payload =6        hashMapOf(7            &quot;property&quot; to &quot;abc&quot;,8            &quot;property2&quot; to &quot;xyz&quot;,9        )10)

Custom Metadata - Global

Global metadata is used to attach metadata, which is a HashMap of your choice, to each event sent from any context you created using the Datazoom object. For more information, please refer to the Datazoom documentation on metadata.

API
1import io.datazoom.sdk.Datazoom23/**4 * Sends metadata to Datazoom.5 *6 * @param metadata a Map that will be attached to each event being sent from SDK, for more information on this topic, please visit our7 *   documentation.8 */910fun Datazoom.setMetadata(metadata: Map<String, Any>)
Example
1import io.datazoom.sdk.Datazoom23Datazoom.setMetadata(4    hashMapOf(5        &quot;property&quot; to &quot;custom property&quot;,6        &quot;property2&quot; to &quot;custom property2&quot;,7    )8)

Get all player context

Datazoom support having multiple contexts, you can create multiple contexts, Datazoom keep track of all created context and give ability to get if you need anytime of your app lifecycle.

API
1import io.datazoom.sdk.Datazoom23/**4 * Returns a list of all player contexts.5 *6 * @return A list of all player contexts. You can retrieve list of all player contexts at anytime in player lifecycle.7 */89fun Datazoom.playerContexts(): List<DzAdapter>
Example
1import io.datazoom.sdk.Datazoom23Datazoom.playerContexts()

Destroy Context

If you want to destroy a context, there are multiple ways to do it. Ideally, you should ask the Datazoom object to destroy the context by either providing your context ID or the context/adapter itself.

1import io.datazoom.sdk.Datazoom23/**4 * Removes a player context.5 *6 * @param adapter The adapter to be used to remove the context.7 */8fun Datazoom.removeContext(adapter: DzAdapter)

or 

1import io.datazoom.sdk.Datazoom23/**4 * Removes a player context.5 *6 * @param id The id of the player context to be removed. its the same id returned by7 * @sample createContext(adapter: DzAdapter): DzAdapter8 */910fun Datazoom.removeContext(id: String)

Please make sure that once the context is removed from Datazoom, you do not use it for communication because it will no longer be able to communicate with the server, and you might miss critical events.

Example
1import io.datazoom.sdk.Datazoom23Datazoom.removeContext(&quot;contextId&quot;)

or

1import io.datazoom.sdk.Datazoom23Datazoom.removeContext(context)

Listening SDK events

1import io.datazoom.sdk.Datazoom23lifecycle.coroutineScope.launch {4    Datazoom.sdkEvents.watch {5        when (it) {6            is SdkEvent.SdkInit -> {7                // SDK initialized8            }9            is SdkEvent.SdkError -> {10                // SDK error11            }12        }13    }14}

Supported Client Events

SdkInit

The "SdkInit" event signals the successful initialization of the SDK and the receipt of the API key used during initialization. Upon receiving this event, users can confidently proceed with utilizing the SDK's functionalities, knowing that the SDK is ready for use with the provided API key. Ensure to handle this event appropriately in your application code to synchronize operations requiring the SDK's readiness

SdkError

The "SdkError" event is triggered when an error occurs during the operation of the SDK. This event provides crucial information about the nature of the error, such as error codes or descriptive messages, allowing users to identify and handle errors effectively within their applications.

🐛 Issues & Feedback

If you encounter any issues, bugs, or have suggestions, please contact the Datazoom support team at support@datazoom.io. Your feedback is valuable and helps improve the SDK.

Ad Frameworks Extensions

If your Android application has a media player with an ad framework, Datazoom’s Android Collector with a Bitmovin Media Player can be extended with the following ad framework extensions.

Previous
Media3 Media Player
Next
Google IMA Ad Framework