For the Android Collector

The Amazon IVS Android 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

The Datazoom IVS Adapter enables seamless tracking of playback events from Amazon Interactive Video Service (IVS) 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 Amazon IVS Player-powered applications.

📦 Dependency

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

Kotlin DSL

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

Groovy DSL

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

Usage

To integrate the IVS Collector into your project:

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

Initialization

API

import io.datazoom.sdk.Datazoom
import io.datazoom.sdk.Config

fun Datazoom.init(config: Config)

Example

import io.datazoom.sdk.Datazoom
import io.datazoom.sdk.logs.LogLevel
import io.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 Amazon IVS 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

import com.amazonaws.ivs.player.Player
import io.datazoom.sdk.BaseContext
import io.datazoom.sdk.Datazoom
import io.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 player The Amazon IVS Player 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://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/android.html">Amazon IVS Player</a>
 * @see <a href="https://help.datazoom.io/">Datazoom Help</a>
 */
fun Datazoom.createContext(player: Player, base: BaseContext) : DzAdapter

Example

import io.datazoom.sdk.ivs.createContext
import io.datazoom.sdk.Datazoom
import io.datazoom.sdk.DzAdapter

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

val 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

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

val metdata: Map<String, Any> = yourAdapter.getMetadata()

Delete metadata

API

import io.datazoom.sdk.DzAdapter

fun DzAdapter.clearMetadata()

Example

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

fun DzAdapter.sendCastEvent(isCasting: Boolean)

Example

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

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

Get global metadata

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

API

import io.datazoom.sdk.Datazoom

/**
 * Returns the global metadata that is being sent with each event.
 *
 * @return The global metadata that is being sent with each event.
 */
fun Datazoom.getMetadata(): Map<String, Any>

Example

import io.datazoom.sdk.Datazoom

val metadata: Map<String, Any> = Datazoom.getMetadata()

Delete global metadata

API

import io.datazoom.sdk.Datazoom

fun Datazoom.clearMetadata()

Example

import io.datazoom.sdk.Datazoom

Datazoom.clearMetadata()

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

Datazoom.removeContext("contextId")

or

import io.datazoom.sdk.Datazoom

Datazoom.removeContext(context)

Listening SDK events

import io.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 & 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 Amazon IVS Android Media Player can be extended with the following ad framework extensions.

MediaTailor Ad Framework

Supported Data Points

Events

Discrete occurrences driven by user interactions or system actions

Metadata

Player

Video

Attributes

User

Content Session ID

Fluxdata

Metrics measuring changing parameters over time