MediaTailor integration

Overview

Use this guide to configure AWS Elemental MediaTailor with rn-qp-nxg-player. It covers required setup, advanced session options, reporting mode, and MediaTailor-specific ad interaction APIs.

Required configuration

To create a MediaTailor player, configure the required properties in PlayerConfig.

Property	Type	Required	Description
mediaTailorSessionURL	String	Yes	URL used to create a MediaTailor session.
mediaURL	String	Yes	Fallback content URL if session creation fails.
ssaiAdProvider	String	Yes	Set to "mediatailor".

Basic setup

Use this basic configuration to create a MediaTailor-enabled player.

let playerConfig: PlayerConfig = {
  ...
  mediaURL: <content url>,
  mediaTailorSessionURL: <MediaTailor session url>,
  ssaiAdProvider: 'mediatailor',
  adCuepointsSyncInterval: 0.3, // Optional. iOS only.
};

adCuepointsSyncInterval is optional and applies only to iOS. Supported range is 0.1 to 1.0 seconds, and the default is 0.3 seconds.

Advanced integration

Use mtSessionConfiguration when you need to customize ad session behavior.

MediaTailor session configuration

The MediaTailorSessionConfiguration interface provides advanced control over session setup and ad tracking.

Property	Type	Required	Description
reportingMode	ReportingMode	No	Enables server or client-side ad event tracking.
playerParams	{ [key: string]: string }	No	Player session parameters.
originParams	{ [key: string]: string }	No	Additional session initialization parameters.
manifestParams	{ [key: string]: string }	No	Extra parameters added to manifest and tracking URLs.
overlayAvails	OverlayAvailsMode	No	Controls overlay ad support ('on' or 'off').
availSuppression	AvailSuppression	No	Controls ad personalization suppression for live content.
adSignaling	boolean	No	Enables ad ID signaling.
retryAttempts	number	No	Maximum retries for session initialization failures (iOS only).
logMode	LogMode	No	Enables debug logs. Current supported value is 'DEBUG'.
liveAdTrackingMode	MediaTailorAdTrackingMode	No	Controls how ad tracking events are fetched for live streams.

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>,
    retryAttempts: <number>, // iOS only
    logMode: 'DEBUG',
    liveAdTrackingMode: <MediaTailorAdTrackingMode>,
  },
};

Live ad tracking mode

Use liveAdTrackingMode when reportingMode is set to client mode.

export type MediaTailorAdTrackingMode = 'FULL' | 'PAGINATION' | 'PLAYHEAD';

Value	Description
FULL	Fetches all ad tracking events for live streams.
PAGINATION	Fetches ad tracking events in a paginated mode (default).
PLAYHEAD	Fetches ad tracking events based on playhead position.

Reporting mode

Set reportingMode to choose server or client tracking.

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

Server mode configuration

Use server mode when your tracking is handled by MediaTailor backend signals.

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

Client mode configuration

Use client mode when your app reports ad tracking with Datazoom.

iOS setup

Add this to your Podfile:

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

ENV['USE_DZMEDIATAILOR'] = '1'

Warning: Datazoom MediaTailor cannot run on x86_64 architecture. Add the following post_install block at the end of your Podfile.

post_install do |installer|
  config = use_native_modules!
  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

Add this dependency in app/build.gradle:

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

Required client mode parameters

Provide these parameters when using client mode.

Parameter	Type	Description
configID	string	Datazoom configuration ID used for tracking.
playerViewID	number	View ID of the player container from findNodeHandle().

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

Obtain playerViewID

Get playerViewID from the root view that wraps QpNxgPlaybackView.

1. Create a ref for the player container.
2. Attach the ref to the root player container view.
3. Read the view ID with findNodeHandle.
4. Pass that ID in reportingMode.

import { findNodeHandle } from 'react-native';

const playerContainerRef = useRef<View>(null);
const playerViewId = findNodeHandle(playerContainerRef.current);

Note: Keep the root container dimensions equal to QpNxgPlaybackView dimensions so client ad tracking remains accurate.

PAL configuration

Use palConfiguration to control ad targeting and ad measurement metadata.

Property	Type	Required	Description
palConfiguration	PALConfiguration	No	Optional PAL session configuration.

Ad playback policies

MediaTailor playback policies apply to VOD streams and define how ad playback is enforced during seek and interruption scenarios.

Property	Type	Required	Default	Description
fastForwardRule	String	No	AUTO_SEEK_SKIP_ALL	Ad policy for fast-forward behavior.
rewindRule	String	No	TRICK_FW_PLAY_LAST	Ad policy for rewind behavior.
repeatRule	String	No	INTERRUPT_RESUME	Ad policy for repeated playback in one session.
interruptRule	String	No	REPEAT_PLAY_ONCE	Ad policy when playback is interrupted.
autoSeekRule	String	No	TRICK_RW_SKIP_ALL	Ad policy for bookmark-based auto-seek.

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

Warning: Regression test ad playback when you change any default playback policy values.

Ad interaction APIs

Use these APIs to handle click and touch interactions during ad playback.

Send ad click

Call sendAdClick when the user interacts with an ad click target.

onAdStart(adInfo: AdPlayerAdInfo): void {
  let videoClickThroughURL = adInfo.vastProperties?.videoClickThroughURL;
}
// Call only when videoClickThroughURL exists.
player.sendAdClick();

Handle video view touch

Call onVideoViewTouch for player touch events so ad interaction handling continues to work correctly.

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