Brightcove Integration

The rn-qp-nxg-player SDK provides comprehensive support for Brightcove playback with Server-Side Ad Insertion (SSAI). This guide covers setup, configuration, and implementation details for integrating Brightcove content.

Overview

Brightcove integration enables:

• Server-Side Ad Insertion (SSAI) for monetization
• Brightcove Video Cloud analytics via Data Collection API v2
• Ad playback policies and controls
• DRM content protection
• Thumbnail previews with keyframe scrubbing

Required Configuration

To create a Brightcove player, the following properties are required:

Property	Type	Required	Description
mediaURL	String	Yes	Content URL for playback
vmapURL	String	Yes	VMAP URL for Server-Side Ad Insertion
contentType	String	Yes	Content type: 'VOD' or 'LIVE'
mediaType	String	Yes	Media type: 'HLS'

Basic Setup

To create and play Brightcove content:

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

const playerConfig: PlayerConfig = {
  mediaURL: '<Content URL for playback>',
  useCustomPlayerControls: '<true/ false>',
  vmapURL: '<VMAP URL returned by the Brightcove SSAI session>',
  contentType: '<VOD or LIVE>',
  mediaType: 'HLS',
};

const player = await createPlayer(playerConfig);
await player.play();

DRM Configuration

For protected content, configure DRM license URLs and types:

const playerConfig: PlayerConfig = {
  mediaURL: '<Content URL for playback>',
  vmapURL: '<VMAP URL returned by the Brightcove SSAI session>',
  mediaType: 'HLS',
  drmLicenseURL: '<license server URL provided by your DRM vendor>',
  drmType: '<DRM scheme: WIDEVINE | FAIRPLAY | PLAYREADY | NONE>',
  drmLicenseRefreshToken: '<token used to refresh the DRM license before expiry>',
};

Supported DRM Schemes:

• WIDEVINE — Android
• FAIRPLAY — iOS
• PLAYREADY — Windows/Xbox
• NONE — No DRM

PAL Configuration

Configure Google PAL (Privacy and Audience Management) for ad targeting and measurement:

const playerConfig: PlayerConfig = {
  mediaURL: '<Content URL for playback>',
  vmapURL: '<VMAP URL returned by the Brightcove SSAI session>',
  mediaType: 'HLS',
  palConfiguration: {
    descriptionURL: '<URL of the page where the video is embedded>',
    omidPartnerName: '<name of the OMID measurement partner>',
    omidPartnerVersion: '<version of the OMID partner SDK>',
    omidVersion: '<OMID API version in use>',
    playerType: '<type identifier of the player (e.g., "rn-qp-nxg-player")>',
    playerVersion: '<version of the player SDK>',
    ppid: '<publisher-provided user identifier for ad targeting>',
    videoPlayerHeight: 480,
    videoPlayerWidth: 720,
  },
};

Subtitle and Audio Configuration

Configure preferred subtitles and audio tracks (Android only):

const playerConfig: PlayerConfig = {
  mediaURL: '<Content URL for playback>',
  vmapURL: '<VMAP URL returned by the Brightcove SSAI session>',
  mediaType: 'HLS',
  preferredSubtitleLanguage: 'en',
  preferredAudioLanguage: { language: 'en', region: 'US' },
  preferredMimeTypes: ['video/mp4', 'audio/aac'],
};

Thumbnail Preview

Retrieve thumbnail URLs for keyframe-based scrubbing:

const getThumbnailUrl = async (currentPosition: number): Promise<string | undefined> => {
  return await player.getThumbnailUrl(currentPosition);
};

Brightcove Data Collection API v2

Enable analytics collection for Brightcove Video Cloud. The rn-qpnxg-player package now supports analytics reporting to Brightcove's Data Collection API v2.This enables tracking of playback events, user engagement, and optional QoE metrics. Below are the parameters reported to the data collection API, along with details on which values are auto-collected and which require explicit configuration. Apps can also override these properties from their default or auto-collected values.

Data Collection Configuration

Config Parameters

Parameter	Type	Required	Default	Description
account	String	Yes	N/A	Brightcove Video Cloud account ID.
video	String	Yes*	N/A	Video ID. Required for most video-related events.
event	String	No	N/A	Event type (e.g., player_load, video_view, etc.).
session	String	No	Auto-gen (if not passed by you)	Unique session identifier. Should remain constant per playback session.
videoName (video_name)	String	No	null	Human-readable video name.
videoDuration (video_duration)	Number	No (VOD)	null	Required for VOD events. Must NOT be sent for Live streams.
engagementEventInterval	Int	No	10000	Interval (ms) between engagement events. Recommended: 5000–20000 (events >20s ignored).
user (user)	String	No	Derived (IP + UA)	Unique user identifier (hashed internally using SHA-256).
deviceType (device_type)	String	No	Auto-detected	Override device type (mobile, tv, desktop, etc.). Only used if paired with device_os.
deviceOs (device_os)	String	No	Auto-detected	Override OS (android, ios, etc.).
deviceOsVersion (device_os_version)	String	No	Auto-detected	OS version.
deviceManufacturer	String	No	Auto-detected	Not officially required; typically inferred via User-Agent.
deviceModel	String	No	Auto-detected	Not officially required; typically inferred via User-Agent.
country	String	No	Auto-detected	ISO-3166 alpha-2 country code. Override only if IP unreliable.
countryName (country_name)	String	No	Auto-detected	Human-readable country name.
region	String	No	Auto-detected	ISO-3166 region code.
regionName (region_name)	String	No	Auto-detected	Human-readable region name.
city	String	No	Auto-detected	City name.
dma	String	No	null	DMA code (US only).
destination	String	No	null	Current page/app URI where playback occurs.
source	String	No	null	Referrer URI (traffic source).
player (playerId)	String	No	Auto-detected	Player ID.
playerName (player_name)	String	No	Auto-detected	Player name.
application	String	No	null	Custom application identifier.
time	Number	No	Auto-generated	Event timestamp (epoch ms).
debugLogging	Boolean	No	false	SDK-side only (not sent to Brightcove).
includeQoEMetrics	Boolean	No	false	SDK-side flag to include QoE fields in engagement events.

Example Implementation

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

const playerConfig: PlayerConfig = {
  mediaURL: config.mediaUrl,
  vmapURL: config.vmapUrl,
  useCustomPlayerControls: false,
  contentType: config.contentType,
  mediaType: 'HLS',
  fastForwardRule: 'TRICK_FW_PLAY_LAST',
  rewindRule: 'TRICK_RW_SKIP_ALL',
  // add the remaining required policies
  dataCollectionConfig: {
    accountId: config.accountId,
    videoId: config.videoId,
  },
};

const player = await createPlayer(playerConfig);
await player.play(); // Explicitly call play for Android.

For player lifecycle management (stop, dispose, event listeners), see Core Player Features.

Related Documentation

• ADVERTISING.md — General ad integration
• PLAYER_FEATURES.md — Core player features
• PLAYER_ERRORS.md — Error handling