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

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.

Configure the Datazoom collector

The Datazoom collector must be initialized, with a Datazoom configuration ID, before its functionalities become available. Please refer to Datazoom's platform guide on how to set up a configuration and receive the ID. Once the Datazoom configuration ID is procured, follow Datazoom's collector initialization tutorial to finish configuring the collector.

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) // Note that this value must be based on user consents
    .directedForChildOrUnknownAge(false)
    .build()

MediaTailor.initPal(getApplicationContext(), palConsentSettings)

Please note that it's the application's responsibility to obtain user consent in order to set the settings like 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 demonstrated below.

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 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)
    ....
}

Start the IAB Open Measurement SDK (OM SDK) session client (optional)

While calling setupAdSession(), you can pass the omEnabled parameter with a false flag. This is a temporary workaround and will soon be replaced with a more configuration-driven approach.

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.

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