For the Amazon IVS IOS Media Player

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

Google PAL SDK

Make sure to integrate Google PAL SDK for ios and tvos.

Note:

To successfully build and run the project, it is required to integrate the Google Programmatic Access Library (PAL) SDK for both iOS and tvOS. These dependencies are not optional. Without them, the project will fail to compile.

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:

MPEG-DASH:

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 platform guide. Then follow the collector initialization tutorial to initialize the collector in your application.

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 AmazonIVS is the chosen media 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.

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:

To enable Google PAL SDK integration:

For Google PAL for iOS versions earlier than 3.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 demonstrated 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):

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

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:

For the omidPartnerName and omidPartnerVersion parameters, as shown in the example above, the corresponding values can be retrieved from

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:

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.
• Set up playback of the content.
• Listen to UI events related to the MediaTailor session.

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:

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: