Server Side Ad Insertion using Broadpeak

fl-ads-broadpeak implements server-side ad insertion (SSAI) using Broadpeak SmartLib.

• Wraps the underlying Player
• Resolves stream URLs via Broadpeak
• Emits ad lifecycle events
• Optionally integrates with Google PAL for programmatic ad monetization

Usage

1. Create a Broadpeak Session instance to initialize the SmartLib session.
2. Create a Broadpeak Ad Player that wraps the content Player.
3. The Ad Player resolves the stream URL through Broadpeak and manages ad lifecycle events.

Session Configuration

const broadpeakSessionInitializationData: BroadpeakSessionInitializationData = {
  broadpeakDomainNames: 'broadpeakDomainNames',
  analyticsAddress: 'https://analytics.broadpeak.io',
  uuid: 'unique-user-id',
  deviceType: 'browser',
  customParams: {
    customParam1: 'value1',
    customParam2: 'value2',
  },
  adParams: playbackAsset.custom.adParams, // from playback Authorization
  loggerLevel: BroadpeakLoggerLevel.VERBOSE,
};

BroadpeakSessionInitializationData

Name	Type	Optional	Description
broadpeakDomainNames	string	Yes	Broadpeak CDN domain names for stream resolution
analyticsAddress	string	Yes	Broadpeak analytics endpoint URL
uuid	string	Yes	Unique user identifier for session tracking
deviceType	string	Yes	Device type identifier (e.g. browser, tv)
customParams	Record<string, any>	Yes	Custom key-value parameters for the session
adParams	Record<string, any>	Yes	Ad-specific parameters passed to PAL and the ad server
loggerLevel	BroadpeakLoggerLevel	Yes	Logging verbosity: BASIC (0), VERBOSE (1), OFF (-1)
nanoCDNHost	string	Yes	NanoCDN host address
gdprPreference	any	Yes	GDPR consent data
sessionKeepAliveFrequency	number	Yes	Keep-alive interval in milliseconds
nanoCDNResolvingRetryDelay	number	Yes	Retry delay for NanoCDN resolution
timeoutNanoCDNRequestRouter	number	Yes	Timeout for NanoCDN request router
multicastOnlySession	boolean	Yes	Enable multicast-only session
pipSession	boolean	Yes	Enable picture-in-picture session
ultraLowLatencySupport	boolean	Yes	Enable ultra-low latency support
requestDiversityDynamicFailover	boolean	Yes	Enable diversity dynamic failover
userAgent	string	Yes	Custom user agent string

BroadpeakLoggerLevel

Value	Description
BASIC (0)	Basic logging
VERBOSE (1)	Verbose logging with detailed output
OFF (-1)	Logging disabled

Session creation

const broadpeakSession: BroadpeakAdsSessionData = createBroadpeakSession(
  broadpeakSessionInitializationData,
  initializationUrl,     // Broadpeak initialization URL
  fallbackUrl,           // Content URL used for fallback playback
  videoElement,
  allowStorage,          // Optional. Set to true to allow storage usage. Defaults to false.
  palConfiguration,
  logger,
);

BroadpeakAdsSessionData

createBroadpeakSession() returns a BroadpeakAdsSessionData object that provides access to the Broadpeak playback session and helper methods.

Properties

Property	Type	Description
initializationData	BroadpeakSessionInitializationData	Configuration used to initialize the Broadpeak session.
session	any	Underlying Broadpeak SmartLib streaming session instance.
shakaPlayer	any	Shaka Player instance managed by the Broadpeak session.
broadpeakAdUrl	string	Broadpeak-resolved playback URL containing CDN routing and ad parameters. Available after preparePlaybackSession() completes.
isFallback	boolean	Indicates whether the session switched to fallback playback.
fallbackReason	Error	Error that triggered fallback playback.

Create Ad Composed Player

AdComposedPlayer handles both content and ad playback by extending the base Player implementation with integrated ad rendering capabilities.

const contentPlayer: Player = createPlayerBuilder()
  .mediaElement(mediaElement)
  .mediaUrl(broadpeakSession.broadpeakAdUrl) // Broadpeak resolved URL
  .mediaType(MediaType.DASH)
  .shakaPlayer(broadpeakSession.shakaInstance) // Mandatory: required Shaka Player instance
  .build();

const adsPlayer: BroadpeakAdsPlayer = createBroadpeakPlayer(
  contentPlayer,
  broadpeakSession,
  adPlaybackPolicy,   // Optional
  logger,             // Optional
);

createBroadpeakPlayer Parameters

Name	Type	Optional	Description
player	Player	No	The underlying platform player instance (must expose rawPlayer and rawLibrary for Shaka integration)
broadpeakSession	BroadpeakAdsSession	No	Session created via createBroadpeakSession
adPlaybackPolicy	AdPlaybackPolicy	Yes	Policy for ad playback behavior (fast-forward, rewind, repeat, etc.)
logger	Logger	Yes	Custom logger instance

Google PAL & OM SDK Integration

When Google PAL and OM SDK are enabled, the SDK automatically handles the following operations:

• Playback start notifications
• Playback end notifications
• Ad impression notifications
• PAL nonce generation
• OM SDK session lifecycle management

The application is responsible for notifying the SDK of:

• Ad user interactions (for example, ad clicks or invitation accepts)
• Ad view state changes

Required APIs

The following APIs must be integrated by the application when Google PAL and OM SDK are enabled.

sendAdTouch

Forwards user touch and mouse interactions on the video element to Google PAL. This helps PAL accurately measure and validate user engagement with ads.

Call this API whenever the user interacts with the video element through touch or mouse events.

videoElement.addEventListener('mousedown', (event) => {
  adsPlayer.sendAdTouch(event);
});

videoElement.addEventListener('touchstart', (event) => {
  adsPlayer.sendAdTouch(event);
});

---

sendAdClick

Notifies the SDK when a user interacts with an ad.

Call this API when the user clicks an ad or accepts an ad invitation/engagement prompt.

adsPlayer.sendAdClick(interactionType: 'click' | 'invitationAccept' );

Supported interaction types:

Value	When to use
click	The user clicks or taps the ad.
invitationAccept	Call when the user accepts an invitation presented by the ad, such as tapping a Learn More, Expand, Participate, or similar engagement button that initiates an interactive ad experience

---

setAdViewState

Notifies the SDK when the visibility or presentation state of the ad changes. This information is used by OM SDK for ad viewability measurement.

Call this API whenever the player transitions between view states such as normal, minimized, expanded, or fullscreen.

adsPlayer.setAdViewState(AdViewState.NORMAL);

Supported states:

export enum AdViewState {
  /** Default player state. */
  NORMAL = 'normal',

  /** Player is minimized or not visible. */
  MINIMIZED = 'minimized',

  /** Player view is reduced. */
  COLLAPSED = 'collapsed',

  /** Player view is expanded. */
  EXPANDED = 'expanded',

  /** Player is displayed in fullscreen mode. */
  FULLSCREEN = 'fullscreen',
}

Example:

document.addEventListener('fullscreenchange', () => {
  player.setAdViewState(document.fullscreenElement ? 'fullscreen' : 'normal');
});

Listening to Ad Events

Subscribe to ad lifecycle events to monitor ad playback state, ad breaks, progress, errors, and context changes.

adsPlayer.subscribe(AdEvent.ADVERT_BREAK_START, (adBreakInfo: AdBreakInfo) => {
  console.log('Ad break started', adBreakInfo);
});

adsPlayer.subscribe(AdEvent.ADVERT_START, (adInfo: AdInfo) => {
  console.log('Ad started', adInfo);
});

adsPlayer.subscribe(AdEvent.ADVERT_PROGRESS_UPDATE, (adInfo: AdInfo, progressSec: number) => {
  console.log('Ad progress', progressSec, 'seconds');
});

adsPlayer.subscribe(AdEvent.ADVERT_END, (adInfo: AdInfo) => {
  console.log('Ad ended', adInfo);
});

adsPlayer.subscribe(AdEvent.ADVERT_BREAK_END, (adBreakInfo: AdBreakInfo) => {
  console.log('Ad break ended', adBreakInfo);
});

adsPlayer.subscribe(AdEvent.ADVERT_ERROR, (error: Error) => {
  console.log('Ad error', error);
});

adsPlayer.subscribe('playercontextchanged', (context: PlayerContext) => {
  // PlayerContext.AD during ad playback, PlayerContext.MAIN during content
  console.log('Player context changed', context);
});