SSAI (Server-Side Ad Insertion)

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

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)

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

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

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

To obtain playerViewID, use React Native's findNodeHandle on the root container view wrapping QpNxgPlaybackView.

import { findNodeHandle } from 'react-native';
const playerContainerRef = useRef<View>(null);
const playerViewId = findNodeHandle(playerContainerRef.current);

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

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