Advertising & Monetization

Monetization

For details on ad integration, see the following sections:

• SSAI (Server-Side Ad Insertion)
• CSAI (Client-Side Ad Insertion)

MediaTailor Integration

QP player now supports playback of AWS Elemental MediaTailor curated streams with advertisements. To build a MediaTailor player, the following properties need to be configured:

Required Configuration

Property	Type	Required	Description
mediaTailorSessionURL	String	True	Sets the URL to create remote session with AWS Elemental MediaTailor.
mediaURL	String	True	Sets the fallback URL to content playback when MediaTailor session fails.
ssaiAdProvider	String	True	Specifies the Server-Side Ad Insertion (SSAI) provider for ad delivery. Set to "mediatailor".

Basic Setup

Creation of MediaTailor player is simple by just providing content's URL along with session URL to create remote session with AWS Elemental MediaTailor:

let playerConfig: PlayerConfig = { 
    ...
    mediaURL: <Content url>,
    mediaTailorSessionURL: <MediaTailor Session url>,
    ssaiAdProvider: "mediatailor"
}

Advanced Integration

Applications can configure ad delivery and playback behavior by passing optional parameters through the player configuration. Below are few such optional configurations

MediaTailorSessionConfiguration

The MediaTailorSessionConfiguration interface provides advanced configuration options for MediaTailor sessions:

Property	Type	Required	Description
reportingMode	ReportingMode	False	Enables hybrid tracking mode for ad events ('server', 'client')
playerParams	{ [key: string]: string }	False	Parameters for player session configuration
originParams	{ [key: string]: string }	False	Additional parameters for session initialization
manifestParams	{ [key: string]: string }	False	Parameters included in manifest and tracking URLs
overlayAvails	OverlayAvailsMode	False	Enables overlay ad support ('on' or 'off')
availSuppression	AvailSuppression	False	Controls ad personalization suppression for live content
adSignaling	boolean	False	Enables ad ID signaling

let playerConfig: PlayerConfig = { 
    ...
    mtSessionConfiguration: {
        playerParams: <key value pair>,
        originParams: <key value pair>,
        manifestParams: <key value pair>,
        overlayAvails: <boolean>,
        availSuppression: {
            mode: <boolean>,
            value: <string>
        },
        adSignaling: <boolean>,
    },
}

Reporting Mode

type ReportingMode = 
  | { mode: 'server' } 
  | { mode: 'client'; configID: string; playerViewID: number };

Server Mode Configuration

playerConfig.mtSessionConfiguration = {
  ...playerConfig.mtSessionConfiguration,
  reportingMode: { mode: 'server' }
};

Client Mode Configuration

iOS setup

To enable client mode, add the following to your Podfile:

source 'https://gitlab.com/datazoom/pod-specs.git' // Top of the Podfile

ENV['USE_DZMEDIATAILOR'] = '1'

⚠️ Important: Datazoom Media Tailor has a limitation where it cannot run on x86_64 architecture. To address this, add the following post_install configuration at the end of your Podfile:

post_install do |installer|
  # Ensure the config variable is available
  config = use_native_modules!

  # Apply the standard React Native post-install steps
  react_native_post_install(
    installer,
    config[:reactNativePath],
    :mac_catalyst_enabled => false
  )
  
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      xcconfig = config.build_settings
      xcconfig['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = ''
    end
  end
end

Android setup

To enable client mode, add the following in app/build.gradle

implementation "io.datazoom.sdk:mediatailor:<version>"

Required Parameters

Client mode requires two additional parameters:

Parameter	Type	Description
configID	string	A unique configuration identifier for tracking purposes (datazoom config ID).
playerViewID	number	The view ID of the player container, obtained using findNodeHandle().

playerConfig.mtSessionConfiguration = {
  ...playerConfig.mtSessionConfiguration,
  reportingMode: {
    mode: 'client',
    configID: '<config-id>',
    playerViewID: playerViewId
  }
};

Obtaining playerViewID

The playerViewID must be obtained from the root container view that wraps QpNxgPlaybackView. Use React Native's findNodeHandle to get the native view reference.

Step 1: Create a ref for the player container

import { findNodeHandle } from 'react-native';

const playerContainerRef = useRef<View>(null);

Step 2: Set up the view hierarchy

The root container view must have the same dimensions as the playback view. Structure your view hierarchy as follows:

<View
  ref={playerContainerRef}
  style={styles.containerStyle}
>
  {/* Playback View */}
  <View style={styles.playerView}>
    <QpNxgPlaybackView playerID={state.playerID} style={styles.playerView} />
  </View>
  
  {/* Controls Overlay */}
  <View style={styles.controlsOverlay}>
    {showControls()}
  </View>
</View>

Step 3: Obtain the view ID

 const playerViewId = findNodeHandle(playerContainerRef.current);

Step 4: Configure reporting mode with the obtained viewId

if (playerViewId) {
  playerConfig.mtSessionConfiguration = {
    ...playerConfig.mtSessionConfiguration,
    reportingMode: {
      mode: 'client',
      configID: '<your-analytics-config-id>',
      playerViewID: playerViewId
    }
  };
}

⚠️ Important: Ensure the root container view's dimensions match the QpNxgPlaybackView dimensions exactly for accurate ad tracking measurements.

Configure PAL (Programatic Access Libraries)

The Programmatic Access Libraries (PAL) are small-scale libraries that let you request programmatic ads in environments.

Property	Type	Required	Description
palConfiguration	PALConfiguration	False	Sets the PALConfiguration instance that is used in the PALSession initialization. Optionally sets the permission to store user data like cookies, device IDs, and advertising IDs when using PALSession calls.

Configure Ad playback policies

The following ad playback policies represent the default MediaTailor player behavior for VOD (Video on Demand) content. These defaults define how ads are enforced when users perform actions such as fast-forwarding, rewinding, repeating playback, interrupting playback, or auto-seeking to a bookmarked position.

Property	Type	Required	Default	Description
fastForwardRule	String	False	AUTO_SEEK_SKIP_ALL	Rules that enforce ad playback policy when a user performs fast forward operation.
rewindRule	String	False	TRICK_FW_PLAY_LAST	Rules that enforce ad playback policy when a user performs rewind operation.
repeatRule	String	False	INTERRUPT_RESUME	Rules that enforce ad playback for repeated ad playback in a single playback session.
interruptRule	String	False	REPEAT_PLAY_ONCE	Rules that enforce ad playback policy when the playback is interrupted.
autoSeekRule	String	False	TRICK_RW_SKIP_ALL	Rules that enforce ad playback policy when a user has a "bookmarked" time for a piece of content, then plays the content again, and the player auto-seeking to the bookmark triggers the ads.

Customizing Playback Policies

If you need to override the default MediaTailor playback policies, you can do so by explicitly configuring them in PlayerConfig:

let playerConfig: PlayerConfig = { 
    ...
    fastForwardRule: <fast-forward rule>,
    rewindRule: <rewind rule>,
    repeatRule: <repeat rule>,
    interruptRule: <interrupt rule>,
    autoSeekRule: <auto seek rule>
}

⚠️ Important: Any change from the default MediaTailor playback policy values must undergo full regression testing. Modifying these rules can impact ad delivery, measurement, and compliance behavior during VOD playback.

ℹ️ Note: playback policies applicable only for VOD

Ad Interaction APIs

send Ad Click

The sendAdClick method should be invoked when the user interacts with an ad click tracking event. This notifies the player about the ad click. If the ad contains a videoClickThroughURL, the application can use it to open the URL in a browser or handle it as needed.

onAdStart(adInfo: AdPlayerAdInfo): void {
  let videoClickThroughURL = adInfo.vastProperties?.videoClickThroughURL;
}
// This method should be used only when videoClickThroughURL exists
player.sendAdClick();

On Video View Touch

The onVideoViewTouch method should be called for every touch interaction with the player. This allows the player to handle touch events for ad interactions.

• action: The type of motion event (e.g., ACTION_DOWN, ACTION_UP, etc.).
• x: The x-coordinate of the touch event.
• y: The y-coordinate of the touch event.

Example:

enum MotionEventAction {
  ACTION_DOWN = 0,
  ACTION_UP = 1,
  ACTION_MOVE = 2,
  ACTION_CANCEL = 3,
}

const handleTouch = (touchType: number, gestureResponderEvent: any) => {
  const { locationX, locationY } = gestureResponderEvent.nativeEvent;
  player?.onVideoViewTouch(touchType, locationX, locationY);
};

const onTouchStart = (gestureResponderEvent: any) => handleTouch(MotionEventAction.ACTION_DOWN, gestureResponderEvent);
const onTouchMove = (gestureResponderEvent: any) => handleTouch(MotionEventAction.ACTION_MOVE, gestureResponderEvent);
const onTouchEnd = (gestureResponderEvent: any) => handleTouch(MotionEventAction.ACTION_UP, gestureResponderEvent);
const onTouchCancel = (gestureResponderEvent: any) => handleTouch(MotionEventAction.ACTION_CANCEL, gestureResponderEvent);

// This Pressable must be part of the player view to receive touch events
<Pressable
  onTouchStart={onTouchStart}
  onTouchMove={onTouchMove}
  onTouchEnd={onTouchEnd}
  onTouchCancel={onTouchCancel}
  >
</Pressable>
 

Note: These APIs are critical for tracking user interactions with ads and ensuring proper ad behavior.

PALConfiguration: Ad Targeting & Reporting Parameters

The following parameters can be set in palConfiguration (type: PALConfiguration) for accurate ad targeting, reporting, and ad playback customization:

Property	Type	Description
willAdAutoPlay	boolean	Defines whether the ad will be auto played without waiting for user interaction or not. Default: true.
willAdPlayMuted	boolean	Defines whether the ad will be played while muted or not. Default: false.
continuousPlayback	boolean	Defines whether the player intends to continuously play the content videos one after another similar to TV.
iconsSupported	boolean	Defines whether VAST icons are supported by the video player.
nonceLengthLimit	number	Defines the length limit of the generated nonce.
omidPartnerName	string	The name of the partner integrating OMID measurement.
omidPartnerVersion	string	The version of the partner integrating OMID measurement.
omidVersion	string	The version of OMID that the player responsible for ad.
playerType	string	The partner provided player type.
playerVersion	string	The partner provided player version.
ppid	string	The publisher provided ID.
videoHeight	number	The height of the ad video element.
videoWidth	number	The width of the ad video element.
descriptionURL	string	Defines the description URL of the content during which the ad will be played.
sessionId	string	Unique session identifier (should be a UUID, used for frequency capping across the user session).

Example usage:

let palConfig: PALConfiguration = {
  willAdAutoPlay: true,
  willAdPlayMuted: false,
  continuousPlayback: true,
  iconsSupported: true,
  nonceLengthLimit: 16,
  omidPartnerName: "MyPartner",
  omidPartnerVersion: "2.1.0",
  omidVersion: "1.4.5",
  playerType: "customPlayer",
  playerVersion: "1.0.0",
  ppid: "user-12345",
  videoHeight: 720,
  videoWidth: 1280,
  descriptionURL: "https://example.com/content-desc",
  sessionId: "550e8400-e29b-41d4-a716-446655440000",
}

let playerConfig: PlayerConfig = {
  palConfiguration: palConfig,
}

Ad Events

The client app will be observing the events like AD_BREAK_STARTED_EVENT - when the Ad Break playback starts
ALL_ADS_LOADED_EVENT, AD_STARTED_EVENT, AD_PERIOD_STARTED_EVENT, AD_ENDED_EVENT, AD_BREAK_ENDED_EVENT

from IMA-PlAYER.

Friendly Obstruction

We can register the view on top of Google IMA ads as friendly obstruction by sending the views as array with playerConfig. This is applicable for both Android and iOS platforms.

   let friendlyObstruction: Array<AdOverlayUIScope> = [{
       obstructionID: {
          type: 'nativeID', 
          id: string
       },
       purpose: AdOverlayPurpose,
       reason: string
    }]
   playerConfig.friendlyObstructions = friendlyObstruction
   let player = await createPlayer(playerConfig);

The obstructionID type can be viewID/nativeID and id should be number for viewID and string for nativeID.

The following are the list of AdOverlayPurpose,

AdOverlayPurpose	Description
playbackControls	UIScope for playback controls overlaying the player
notVisible	UIScope for overlays that are not visible
closeAd	UIScope for ad close buttons overlaying the player
other	UIScope for other overlays

Note: The views that needs to be added as friendly obstruction should be available before calling createPlayer API itself. Dont remove the view from the parentView which is added as friendly obstruction until the end of the playback.

On top of it, iOS provides the leverage of adding the friendly obstructions lazily via registerFriendlyObstruction API and unregistering it via unregisterAllFriendlyObstruction API.

   let friendlyObstruction = await player.registerFriendlyObstruction(viewID: number, purpose: string, reason: string)
   await player.unregisterAllFriendlyObstruction()

Note: These registerFriendlyObstruction and unregisterAllFriendlyObstruction APIs works only on iOS platform.

For more details, please refer

Android: register_video_controls_overlay_obstructions

iOS: register_video_controls_overlay_obstructions

Amazon Publisher Services Integration

Amazon Publisher Services (APS) allows publishers to use a Client to Server (C2S) call that returns the bid information to be passed to publisher ad server.

The client application, deployed on Amazon FireTV or Fire tablet devices, would construct APSBidRequest as an request object for APS service, below is the sample snippet

import {
  APSVideoImpression,
  APSDeviceInfo,
  APSContent,
  APSApplication,
  APSBidRequest,
  bidService,
} from '@quickplay/rn-qp-nxg-player';

let videoImpressions: Array<APSVideoImpression> = [
          {
            width: 540,
            height: 960,
            slotID: "<slotID>"
          },
          {
            width: 540,
            height: 960,
            slotID: "<slotID>"
          },
        ];

        let deviceInfo: APSDeviceInfo = {
          userAgent: "<Application's user-agent>",
          privacyRule: 'TRACKING_UNRESTRICTED',
          advertisingID: "<advertisingID>",
          language: "en",
        }

        let contentInfo: APSContent = {
          id: "2903",
          rating: "TV-G",
          genre: "Adventure",
          channel: "Top Movies - Rakuten TV",
          length: "3600",
          language: "es"
        }

        let applicationInfo: APSApplication = {
          id: "caf20e9c4cd8420bbc33aacc8ca27d33",
          name: "Univision",
          domain: "tv.univision.com",
          bundle: "B07ZP9DFM7",
          storeURL: "https://www.amazon.com/Univision-App-Unimas-Free/dp/B07ZP9DFM7",
          content: contentInfo,
          inventoryPartnerDomain: "ipd.com"
        }

        let request: APSBidRequest = {
          id: "6a7c7089-efba-43d8-81a7-0d880f353594-1682102853981",
          application: applicationInfo,
          device: deviceInfo,
          videoImpressions: videoImpressions,
          privacyToken: "1---",
        }

after constructing the APSBidRequest objects as above, call getAmazonPublisherServicesBids and send it as input.

VOD

on receiving response from getAmazonPublisherServicesBids which is a key-value pair, send it as adTagParameters value in PlayerConfig

let url = "https://aax-ott-c2s.amazon-adsystem.com/e/c2s/ads"

let response = await bidService.getAmazonPublisherServicesBids(url, request)

let playerConfig: PlayerConfig = { 
    ...
    adTagParameters: response
}

LIVE

on receiving response from getAmazonPublisherServicesBids which is a key-value pair, replace adTagParameters using replaceAdTag API as below

let url = "https://aax-ott-c2s.amazon-adsystem.com/e/c2s/ads"

let response = await bidService.getAmazonPublisherServicesBids(url, request)

await player.replaceAdTag(response)
}

Note: Do not reuse bids from APS. Once you’ve passed bids to your ad server or SSAI (Server Side Ad Insertion) provider, always call getAmazonPublisherServicesBids on every playback start for VOD and every ad break start for LIVE.