Google ExoPlayer Project

The Google ExoPlayer project is designed to provide integration support for the latest Google based ExoPlayer implementations. It aims to simplify the integration process for developers who are using ExoPlayer libraries in their projects.

Description

The Google ExoPlayer project offers a set of utilities and functionalities to facilitate seamless integration with Google based ExoPlayer implementations. It provides common code and abstraction layers to streamline the integration of Datazoom's tracking capabilities into ExoPlayer-powered applications.

Dependency

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

dependencies {
    implementation 'com.datazoom.android:google-exo:1.0.0-alpha2'
}

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 Google ExoPlayer project into your project:

Add the Google ExoPlayer dependency to your project's Gradle file. Initialize Google ExoPlayer by providing your Datazoom API key and configuring necessary settings. Integrate Google ExoPlayer with your Google ExoPlayer based ExoPlayer implementation using the provided API methods for tracking video events and interacting with Datazoom's backend services. Refer to the documentation or code comments for detailed instructions on integrating Google ExoPlayer into your project.

Initialization

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

Create Context

If you want to track events from your Google 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.

/**
 * 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 Google 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://mvnrepository.com/artifact/com.google.android.exoplayer/exoplayer">ExoPlayer</a>
 * @see <a href="https://help.datazoom.io/">Datazoom Help</a>
 */
fun Datazoom.createContext(exoPlayer: ExoPlayer, base: BaseContext) : DzAdapter

Example

Datazoom.createContext(yourExoplayer, **optional**)

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 looks like

/**
 * 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 setMetadata(metadata: Map<String, Any>)

Example

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

You can also retrieve your current metadata by calling the following API:

/**
 * 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 getMetadata(): Map<String, Any>

Example

yourExoplayerContext.getMetadata()

Casting

We have ability to send casting event, we don't track any communication you have with chromecast receiver. We expect you to invoke context/adapter following function with a boolean sending casting state.

fun sendCastEvent(isCasting: Boolean)

Example

yourExoplayerContext.sendCastEvent(isCasting = {castingState})

Custom Events - Context

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

/**
 * 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 generateEvent(name: String, payload: Map<String, Any>)

Example

Datazoom.generateEvent(
    name = "login",
    eventMap =
        hashMapOf(
            "property" to "custom property",
            "property2" to "custom property2",
        )
)

Custom Events - Global

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

/**
 * 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 generateEvent(name: String, payload: Map<String, Any>)

Example

Datazoom.generateEvent(
    name = "login",
    eventMap =
        hashMapOf(
            "property" to "custom property",
            "property2" to "custom property2",
        )
)

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 looks like

/**
 * 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 setMetadata(metadata: Map<String, Any>)

Example

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 looks like

/**
 * 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 playerContexts(): List<DzAdapter>

Example

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.

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

or

/**
 * 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): String
 */
fun 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

  Datazoom.removeContext("contextId")

or

  Datazoom.removeContext(context)

Listening SDK events

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

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.

AdapterCreated

The "AdapterCreated" event signifies the successful creation of an adapter within the SDK. This event provides notification to users that the adapter, responsible for interfacing with external systems or components, is ready for use. Utilize this event to synchronize operations dependent on the availability of the adapter within your application code.

Issues

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