Articles in this section

See more

Media3 Media Player ##Extension of the Android Collector

Avatar
Tony Gentile
  • Updated
Follow

##dz-db-collector-details

Media3 Collector

Our Media3 Collector offers a set of utilities and capabilities to facilitate seamless integration with your Media3 ExoPlayer implementation. It provides common code and abstraction layers to streamline the integration of Datazoom's tracking capabilities into Media3 ExoPlayer-powered applications.

Dependency

To use the Media3 Collector in your application, include the following dependency in your project's Gradle file:

dependencies {
    implementation 'com.datazoom.android:media3:1.0.2-alpha9'
}

Additionally, ensure that your project's dependency resolution management includes the Datazoom Maven repository:

groovy

dependencyResolutionManagement {
    repositories {
        // Other repositories...
        maven {
            url = uri("https://gitlab.com/api/v4/projects/18323233/packages/maven")
        }
    }
}

Usage

To integrate the Media3 Collector into your project:

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

Initialization

API
import com.datazoom.sdk.Datazoom
import com.datazoom.sdk.Config

fun Datazoom.init(config: Config)
Example
import com.datazoom.sdk.Datazoom
import com.datazoom.sdk.logs.LogLevel
import com.datazoom.sdk.Config.Builder

Datazoom.init(
    build(
        configurationId = {YOUR_API_KEY},
        block = {
            logLevel(LogLevel.VERBOSE)
        }
    )
)

Create Context

If you want to track events from your Media3 ExoPlayer, 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
import androidx.media3.exoplayer.ExoPlayer
import com.datazoom.sdk.BaseContext
import com.datazoom.sdk.Datazoom
import com.datazoom.sdk.DzAdapter

/**
 * Creates a player context. A player context is used to embed the player with Datazoom and is responsible for player-specific events.
 *
 * @param exoPlayer The Media3 ExoPlayer instance.
 * @param baseContext 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.
 * @return The player context.
 * @see <a href="https://developer.android.com/reference/androidx/media3/exoplayer/ExoPlayer">ExoPlayer</a>
 * @see <a href="https://help.datazoom.io/">Datazoom Help</a>
 */
fun Datazoom.createContext(exoPlayer: ExoPlayer, base: BaseContext) : DzAdapter
Example

import com.datazoom.media3.createContext
import com.datazoom.sdk.Datazoom
import com.datazoom.sdk.DzAdapter

/* BaseContext is optional, meant for special usecase */

val adapter: DzAdapter = Datazoom.createContext(exoPlayer)

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
import com.datazoom.sdk.DzAdapter

/**
 * Sends metadata to Context.
 *
 * @param metadata a Map that will be attached to each event being sent from SDK, for more information on this topic, please visit our
 *   documentation.
 */

fun DzAdapter.setMetadata(metadata: Map<String, Any>)
Example
import com.datazoom.sdk.DzAdapter

yourAdapter.setMetadata(
    hashMapOf(
        "property" to "custom property",
        "property2" to "custom property2",
    )
)
Get metadata

You can also retrieve your current metadata by calling the following

API
import com.datazoom.sdk.DzAdapter

/**
 * Returns the metadata that is being sent with each event in given context.
 *
 * @return The metadata that is being sent with each event in given context.
 */

fun DzAdapter.getMetadata(): Map<String, Any>
Example
import com.datazoom.sdk.DzAdapter

val metdata: Map<String, Any> = yourAdapter.getMetadata()
Delete metadata
API
import com.datazoom.sdk.DzAdapter

fun DzAdapter.clearMetadata()
Example
import com.datazoom.sdk.DzAdapter

yourAdapter.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.

import com.datazoom.sdk.DzAdapter

fun DzAdapter.sendCastEvent(isCasting: Boolean)
Example
import com.datazoom.sdk.DzAdapter

yourAdapter.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
import com.datazoom.sdk.DzAdapter

/**
  * Sends fullscreen event to Datazoom.
  *
  * @param isFullScreen A boolean value indicating whether the player is in fullscreen mode.
  */

fun DzAdapter.sendFullScreenEvent(isFullScreen: Boolean)
Example
import com.datazoom.sdk.DzAdapter

yourAdapter.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
import com.datazoom.sdk.DzAdapter

/**
  * Set 'versionName' as metadata to the player context.
  *
  * @param versionName The version of the player.
  */

fun DzAdapter.setPlayerVersion(versionName: String)
Example
import com.datazoom.sdk.DzAdapter

yourAdapter.setPlayerVersion(versionName = "1.0.0")

Custom Events - Context

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

import com.datazoom.sdk.DzAdapter

/**
 * Sends an event to given context.
 *
 * @param name The name of the event.
 * @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.
 */

fun DzAdapter.generateEvent(name: String, payload: Map<String, Any>)
Example
import com.datazoom.sdk.DzAdapter

yourAdapter.generateEvent(
    name = "test",
    payload =
        hashMapOf(
            "property" to "abc",
            "property2" to "xyz",
        )
)

Custom Events - Global

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

import com.datazoom.sdk.Datazoom

/**
 * Sends an event to Datazoom.
 *
 * @param name The name of the event.
 * @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.
 */

fun Datazoom.generateEvent(name: String, payload: Map<String, Any>)
Example
import com.datazoom.sdk.Datazoom

Datazoom.generateEvent(
    name = "test",
    payload =
        hashMapOf(
            "property" to "abc",
            "property2" to "xyz",
        )
)

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
import com.datazoom.sdk.Datazoom

/**
 * Sends metadata to Datazoom.
 *
 * @param metadata a Map that will be attached to each event being sent from SDK, for more information on this topic, please visit our
 *   documentation.
 */

fun Datazoom.setMetadata(metadata: Map<String, Any>)
Example
import com.datazoom.sdk.Datazoom

Datazoom.setMetadata(
    hashMapOf(
        "property" to "custom property",
        "property2" to "custom property2",
    )
)

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
import com.datazoom.sdk.Datazoom

/**
 * Returns a list of all player contexts.
 *
 * @return A list of all player contexts. You can retrieve list of all player contexts at anytime in player lifecycle.
 */

fun Datazoom.playerContexts(): List<DzAdapter>
Example
import com.datazoom.sdk.Datazoom

Datazoom.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.

import com.datazoom.sdk.Datazoom

/**
 * Removes a player context.
 *
 * @param adapter The adapter to be used to remove the context.
 */
fun Datazoom.removeContext(adapter: DzAdapter)

or

import com.datazoom.sdk.Datazoom

/**
 * Removes a player context.
 *
 * @param id The id of the player context to be removed. its the same id returned by
 * @sample createContext(adapter: DzAdapter): DzAdapter
 */

fun 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
import com.datazoom.sdk.Datazoom

Datazoom.removeContext("contextId")

or

import com.datazoom.sdk.Datazoom

Datazoom.removeContext(context)

Listening SDK events

import com.datazoom.sdk.Datazoom

lifecycle.coroutineScope.launch {
    Datazoom.sdkEvents.watch {
        when (it) {
            is SdkEvent.SdkInit -> {
                // SDK initialized
            }
            is SdkEvent.SdkError -> {
                // SDK error
            }
        }
    }
}

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

If you encounter any issues or have suggestions for improvements, please open an issue on the GitHub repository.

Related articles

Comments

0 comments

Article is closed for comments.