SSAI (Server-Side Ad Insertion)

SSAI Overview

Server-Side Ad Insertion (SSAI) is a process where ads are stitched into the content stream on the server before being delivered to the client. This approach is also known as dynamic ad insertion or ad stitching.

DAI (Dynamic Ad Insertion)

import { createPlayer, PlayerConfig } from '@quickplay/rn-qp-nxg-player';

let contentAuthToken = await contentAuthorizer.authorizePlayback(platformAsset);

// For LIVE Content
let playerConfig: PlayerConfig = {
  ...
  assetKey: contentAuthToken.assetKey,
  isSSAIEnabled: contentAuthToken.isSSAIEnabled // Set to true to enable SSAI
}

// For VOD Content
let playerConfig: PlayerConfig = {
  ...
  contentSourceID: contentAuthToken.contentSourceId,
  isSSAIEnabled: contentAuthToken.isSSAIEnabled, // Set to true to enable SSAI
  videoID: contentAuthToken.contentID,
}

let player = await createPlayer(playerConfig);

Note: For testing, you can hard code assetKey with value "sN_IYUG8STe1ZzhIIE_ksA".

Configure IMA DAI Stream URL Fetch Timeout (Android Only)

On Android, fetching the stream URL (with ads stitched) is asynchronous. You can configure the wait time for retrieving the stream URL:

let playerConfig: PlayerConfig = {
  ...
  imaDAIStreamURLLoadTimeoutMs: 10000 // Custom timeout in milliseconds
}

let player = await createPlayer(playerConfig);

Note: This parameter is optional and only applicable on Android. If not set, defaults to 10000 ms.

Brightcove SSAI

Brightcove SSAI is supported via the same SSAI configuration, but you must use Brightcove-specific asset keys and configuration as provided by your Brightcove integration. Please refer to your Brightcove documentation or integration guide for the required parameters. The general approach is the same as DAI, but with Brightcove-specific values for assetKey/contentSourceID.

MediaTailor SSAI

QP player supports playback of AWS Elemental MediaTailor curated streams with advertisements. To build a MediaTailor player, configure the following properties:

Required Configuration

Property	Type	Required	Description
mediaTailorSessionURL	String	True	URL to create remote session with AWS Elemental MediaTailor.
mediaURL	String	True	Fallback URL to content playback when MediaTailor session fails.
ssaiAdProvider	String	True	SSAI provider for ad delivery. Set to "mediatailor".

Basic Setup

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

Advanced Integration

You can configure ad delivery and playback behavior by passing optional parameters through the player configuration using mtSessionConfiguration.

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>,
    retryAttempts: <number>, // iOS only
  },
}

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 — add to your Podfile:

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

ENV['USE_DZMEDIATAILOR'] = '1'

⚠️ Important: Datazoom MediaTailor cannot run on x86_64 architecture. Add the following post_install 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 to app/build.gradle:

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

Client mode requires two additional parameters:

Parameter	Type	Description
configID	string	Datazoom configuration identifier for tracking.
playerViewID	number	View ID of the player container, obtained via findNodeHandle().

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 (root container must match QpNxgPlaybackView dimensions):

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

Step 3 — Obtain the view ID:

const playerViewId = findNodeHandle(playerContainerRef.current);

Step 4 — Configure reporting mode:

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 QpNxgPlaybackView exactly for accurate ad tracking.

PAL (Programmatic Access Libraries) Configuration

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.

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 Playback Policies

The following ad playback policies represent default MediaTailor behavior for VOD content. They define how ads are enforced when users fast-forward, rewind, repeat, interrupt playback, or auto-seek to a bookmarked position.

Property	Type	Default	Description
fastForwardRule	String	AUTO_SEEK_SKIP_ALL	Ad policy for fast-forward operations
rewindRule	String	TRICK_FW_PLAY_LAST	Ad policy for rewind operations
repeatRule	String	INTERRUPT_RESUME	Ad policy for repeated playback in one session
interruptRule	String	REPEAT_PLAY_ONCE	Ad policy when playback is interrupted
autoSeekRule	String	TRICK_RW_SKIP_ALL	Ad policy on auto-seek to a bookmarked position

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

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

ℹ️ Note: Ad playback policies apply to VOD content only.

---

Ad Interaction APIs

Send Ad Click

Invoke sendAdClick when the user interacts with an ad click tracking event. If the ad contains a videoClickThroughURL, the application can open it in a browser.

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

On Video View Touch

Call onVideoViewTouch for every touch interaction with the player view to allow the player to handle ad interactions.

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 = (e: any) => handleTouch(MotionEventAction.ACTION_DOWN, e);
const onTouchMove = (e: any) => handleTouch(MotionEventAction.ACTION_MOVE, e);
const onTouchEnd = (e: any) => handleTouch(MotionEventAction.ACTION_UP, e);
const onTouchCancel = (e: any) => handleTouch(MotionEventAction.ACTION_CANCEL, e);

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

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