For the Amazon IVS Android Media Player

The MediaTailor Ad Framework Extension is a configuration option for the Amazon IVS Android Media Player by Datazoom when it is configured with the undefined to make the following additional data points automatically collectable in real time.

Integration Instructions

Prerequisites

Add dependencies.
Procure a MediaTailor session-init URL or ad-tracking URL.
Configure the Datazoom collector.

Add dependencies

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

Kotlin DSL

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

Groovy DSL

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

Procure a MediaTailor session-init URL or ad-tracking URL

⚠️ Important: The IVS player supports a special kind of Live stream from the IVS server where the MediaTailor sessions are initialized implicitly on the server side. Therefore, the procurement of MediaTailor session-init URLs or ad-tracking URLs aren't needed. If that is the case, skip the steps in this section.

In most common cases the client application initiates the initialization of MediaTailor playback sessions using a session-init URL (specific to a given content) procured through MediaTailor's services. The session-init URLs are in the following format:

HLS:

https://<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>.m3u8

MPEG-DASH:

https://<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>.mpd

Alternatively, the client application may utilize a third-party web service to handle the MediaTailor session initialization on its behalf. In such a case, the client application will receive both a content-playback URL and an ad-tracking URL from the web service. The former should be handed to a player to start playback, while the latter should be used in a step described later in this document.

Please refer to MediaTailor's ad-reporting-client-side page for detailed information.

⚠️ Important: The Datazoom implementation of the MediaTailor client uses playerParams instead of adsParams as referenced in the MediaTailor documentation.

Configure the Datazoom collector

A valid Datazoom configuration ID is required to initialize the collector and enable Datazoom functionality.

To create a Collector and retrieve its configuration ID, see Datazoom’s Add, edit, delete a collector. Then follow the Android collector initialization tutorial to initialize the collector in your application. Optionally, if you are also collecting data from a video player, review the media player adapter tutorial for your specific video player.

Configure the MediaTailor SDK

The MediaTailor SDK provides some global configuration options, such as:

The log-level can be changed (with the MediaTailor.setLogLevel() method) to output more or less debug log information.
Optionally, invoke the MediaTailor.initPal() method to enable Google PAL SDK integration if desired.

For example, to output more debug log information:

MediaTailor.setLogLevel(LogLevel.DEBUG)

To enable Google PAL SDK integration:

import com.amazon.mediatailorsdk.PalConsentSettings

val palConsentSettings = PalConsentSettings.Builder()
    .allowStorage(true)  // Supported only in Google PAL for Android versions earlier than 23.0.0; based on user consent.
    .directedForChildOrUnknownAge(false)
    .build()

MediaTailor.initPal(getApplicationContext(), palConsentSettings)

For Google PAL versions for Android earlier than 23.0.0, the application is responsible for obtaining user consent and setting allowStorage accordingly.

MediaTailor Session Initialization

The process to initialize a MediaTailor playback session (with client-side ad tracking support) involves the following steps:

Prepare a MediaTailor SessionConfiguration builder.
Add Google PAL nonce-request parameters (optional).
Add other optional configurations.
Create a MediaTailor Session object.

Prepare a MediaTailor `SessionConfiguration` builder

The MediaTailor session initialization can be done through either a session-init URL or an ad-tracking URL. In both cases, a SessionConfiguration builder should be created with the corresponding method invoked to set the URL procured through MediaTailor's services as shown below.

⚠️ Important: The IVS player supports a special kind of Live stream from the IVS server where the MediaTailor sessions are initialized implicitly on the server side. If that is the case, create the SessionConfiguration without setting either a session-init URL or an ad-tracking URL.

With session-init URL (common use cases):

import com.amazon.mediatailorsdk.SessionConfiguration

val configBuilder = SessionConfiguration.Builder().sessionInitUrl(sessionInitUrl)

With ad-tracking URL (use cases with third-party web services):

import com.amazon.mediatailorsdk.SessionConfiguration

val configBuilder = SessionConfiguration.Builder().trackingUrl(trackingUrl)

Add Google PAL nonce-request parameters (optional)

Optionally, to leverage the Google PAL SDK, add Google PAL nonce-request parameters to the MediaTailor SessionConfiguration builder as demonstrated below:

val palNonceRequestParams = PalNonceRequestParams.Builder()
    .adWillAutoPlay(true)
    .adWillPlayMuted(false)
    .descriptionUrl("https://example.com/content1")
    .iconsSupported(true)
    .playerType("ExamplePlayerType")
    .playerVersion("1.0.0")
    .ppid("12JD92JD8078S8J29SDOAKC0EF230337")
    .videoHeight(480)
    .videoWidth(640)
    .omidPartnerName("amazon2")
    .omidPartnerVersion("1.0.0")
    .build()

configBuilder.palNonceRequestParams(palNonceRequestParams)

For the omidPartnerName and omidPartnerVersion parameters, as shown in the example above, the corresponding values can be retrieved from player context as mentioned, respectively.

Please note that it's important to invoke the MediaTailor.initPal() method before creating MediaTailor sessions that are intended to be integrated with Google PAL SDK.

If the MediaTailor SessionConfiguration builder was created with an ad-tracking URL (instead of a session-init URL), enabling Google PAL SDK and adding nonce-request parameters will not have any effects since the actual session initialization request (to which the PAL SDK nonce is attached) was performed outside the control of the MediaTailor SDK.

Add other optional configurations

The MediaTailor SessionConfiguration builder has more configuration methods defined as documented in the API reference of SessionConfiguration.

Create a MediaTailor `Session` object

With the MediaTailor SessionConfiguration builder prepared in the steps above, create a MediaTailor Session object as demonstrated below:

import com.amazon.mediatailorsdk.Session
import com.amazon.mediatailorsdk.SessionError

val configBuilder = ....

fun onSessionCreationOK(session: Session) {
    ....
}

fun onSessionCreationError(error: SessionError) {
    ....
}

MediaTailor.createSession(configBuilder.build()) { session, error ->
    if (error == null) {
        onSessionCreationOK(session)
    }
    else {
        onSessionCreationError(error)
    }
}

When the asynchronous process is completed, the MediaTailor.createSession() method invokes the callback function specified by the caller. If successful, a Session object is created and passed as an argument to the callback function. Otherwise, an error object is provided (also as a callback function argument). The Session object represents a MediaTailor playback session and provides methods to interact with the session and observe session status.

Please note that the callback function invocation is always through the main UI thread.

Manage the MediaTailor Session

Once the MediaTailor session is created, the following steps should be taken to manage the session:

Create a media player instance and the associated Datazoom collector context.
Link the MediaTailor session object with the Datazoom collector context.
Start the IAB Open Measurement SDK (OM SDK) session client (optional).
Set up playback of the content.
Listen to UI events related to the MediaTailor session.

Create a media player instance and the associated Datazoom collector context

The process of creating a media player instance and the associated Datazoom collector context is specific to the kind of media player chosen by the client application. Please refer to Datazoom's player integration tutorial shown in the left nav for instructions.

For example, if ExoPlayer is the chosen media player:

val player = ExoPlayer.Builder(getApplicationContext()).build()
val datazoomContext = Datazoom.createContext(player)

Some media players require the content playback URL being passed as a parameter for creating instances. If so, use the value of the session.playbackUrl property for this purpose.

Link the MediaTailor session object with the Datazoom collector context

For the MediaTailor SDK to track ads effectively, it needs to have timely access to the media player's playback progress and other information. The Datazoom collector context serves an essential role in facilitating this communication. Therefore, it's important to link the MediaTailor session object with the Datazoom collector context, by invoking the Datazoom context's setupAdSession() method, as demonstrated below:

import io.datazoom.sdk.mediatailor.setupAdSession

fun onSessionCreationOK(session: Session) {
    ....
    datazoomContext.setupAdSession(session, playerView, contentUrl)
    ....
}

Set up playback of the content

The process of setting the content playback URL and initiate playback is specific to the kind of media player chosen by the client application. In all cases, the content playback URL is retrieved from the session.playbackUrl property, but the method of playback URL assignment differs among player vendors. Please refer to the player vendor's documentation or Datazoom's player integration tutorial for instructions.

Please note that if a third-party web service is used to perform session initialization, the session.playbackUrl property will be null and the application should set up content playback based on information derived from the third-party web service.

Likewise, when playing the special Live streams from the IVS server (where the MediaTailor sessions were initialized implicitly on the server side), the session.playbackUrl property will be null and the application should set up content playback based on information derived from the IVS server.

Listen to UI events related to the MediaTailor session

The MediaTailor SDK defines several listener events observable from a MediaTailor session object. They are useful for implementing ad-related UI features. Each listener event callback is invoked with a SessionUiEventData argument which provides detailed information about the current ad. The listener event definitions are listed in the API reference of SessionUiEvent.

As demonstrated below, the client application can register various callback functions for these listener events:

import com.amazon.mediatailorsdk.SessionUiEvent

fun onSessionCreationOK(session: Session) {
    ....
    session.addUiEventListener(SessionUiEvent.AD_START) { event, eventData ->
        ....
    }
    session.addUiEventListener(SessionUiEvent.AD_END) { event, eventData ->
        ....
    }
    session.addUiEventListener(SessionUiEvent.AD_PROGRESS) { event, eventData ->
        ....
    }
    session.addUiEventListener(SessionUiEvent.AD_CLICK) { event, eventData ->
        ....
    }
    session.addUiEventListener(SessionUiEvent.AD_CAN_SKIP) { event, eventData ->
        ....
    }
    session.addUiEventListener(SessionUiEvent.AD_INCOMING) { event, eventData ->
        ....
    }
    session.addUiEventListener(SessionUiEvent.NONLINEAR_AD_START) { event, eventData ->
        ....
    }
    session.addUiEventListener(SessionUiEvent.NONLINEAR_AD_END) { event, eventData ->
        ....
    }
    session.addUiEventListener(SessionUiEvent.AD_TRACKING_INFO_RESPONSE) { event, eventData ->
        ....
    }
    ....
}

Supported Data Points

Events

Discrete occurrences driven by user interactions or system actions

Metadata

Ad

Fluxdata

Metrics measuring changing parameters over time