Skip to main content

Web BO Adapter 5.8

Legacy documentation

This page contains deprecated documentation and is no longer actively maintained. A new version of this documentation is now available here.

This guide explains how to integrate DIVA RW with DIVA BO using DIVA BoAdapter into your web application. application.

AWS Codeartifact
Setup the development environment

Requirements​

Refer to DIVA Web SDK documentation.

Initialization​

Diva BO Adapter gives programmatic access to the standard providers and to common plugins used by the DIVA player SDK when connected to DIVA BO.

import React, { useEffect, useState } from "react";

// bo adapter sdk
import { DivaWebBoAdapter } from "@deltatre-vxp/diva-sdk/diva-web-bo-adapter";
// Import SDK style
import "@deltatre-vxp/diva-sdk/diva-web-sdk/index.min.css";

// bo settings link
const SETTINGS_URL = "https://example.com/settings.json";

// id of the video to be runned
const VIDEO_ID = "123456789890";

const config = {
    videoId:VIDEO_ID,
    libs: {
        mux: 'https://cdnjs.cloudflare.com/ajax/libs/mux.js/6.2.0/mux.min.js',
        shaka: 'https://cdnjs.cloudflare.com/ajax/libs/shaka-player/4.11.2/shaka-player.compiled.js',
        hlsJs: 'https://cdn.jsdelivr.net/npm/hls.js@1.5.7',
        googleIMA: 'https://imasdk.googleapis.com/js/sdkloader/ima3.js',
        googleDAI: 'https://imasdk.googleapis.com/js/sdkloader/ima3_dai.js',
        googleCast: 'https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1',
        threeJs: 'https://cdnjs.cloudflare.com/ajax/libs/three.js/0.148.0/three.min.js',
    }
};

const entitlementConfiguration = {
    entitlementUser: () => 'token',
    entitlementPayloadMap: (type, payload) => {
        // Modify the payload
        return payload;
    },
    version: "1",
};

const mediaAnalyticsParam = {
    viewerId: 'DivaWebUser',
    userName: 'DivaWebUser',
    playerVersion: '5.8.0',
    cdnName: 'AKAMAI',
    playerType: 'HTML5',
    omLibs: {
        omWeb: 'omweb-v1.js',
        omSessionClient: 'omid-session-client-v1.js',
    },
    setPALNonce: (nonceRequest: NonceRequest) => {
        nonceRequest.sessionId = 'xyz'
		return Promise.resolve(nonceRequest);
    },
};

export const App = () => (
    <DivaWebBoAdapter
        settingsUrl={SETTINGS_URL}
        languageCode={"en-US"}
        entitlementConfiguration={entitlementConfiguration}
        mediaAnalyticsParam={mediaAnalyticsParam}
        config={config}
    />
)

Properties​

PropertyTypeDefaultDescription
Mandatory
Property: settingsUrltype:
string
Default: NAurl to reach diva bo adapter settings for the specific project
Property: configtype:
BoAdapterWebComponentConfig
Default: NAinitialization data for DIVA BO adapter
Property: el (vanilla js/react embedded)type:
HTML div element reference
Default: NAHTML div element where diva should be started into
Optional
Property: mediaAnalyticsParamtype:
MediaAnalyticsProps
Default: undefinedproperties useful to implement media analytics
Property: entitlementConfigurationtype:
BoEntitlementConfiguration
Default: undefinedproperties useful to implement entitlement
Middleware
Property: videoMetadataMaptype:
(videoMetadata: VideoMetadata) => Promise<VideoMetadata>
Default: undefinedasynchronous middleware for the app to interact and modify the videoMetadata as soon as videoMetadata is returned from the request (passthrough if not defined)
Callbacks
Property: onDivaBoAdapterErrortype:
(e: unknown) => void
Default: undefinednotify errors on bo adapter start (React)

Typescript interfaces for Properties​

BoAdapterWebComponentProps and BoAdapterWebVanillaProps

Refer to DivaConfiguration in Diva Web SDK, taking in account the omits.

type BoAdapterWebComponentConfig = Omit<
	DivaConfiguration,
	'videoMetadataProvider' | 'dictionary' | 'entitlementProvider' | 'setting' | 'fairplayCertificatePath'
>;

interface BoAdapterWebComponentProps {
	/**
	 * url to reach diva bo adapter settings for the specific project
	 */
	settingsUrl: string;
	/**
	 * pushengine language
	 */
	languageCode: string;
	/**
	 * dictionary language
	 */
	languageDictionary?: string;
	/**
	 *
	 */
	onDivaBoAdapterError?: OnDivaBoAdapterError;

	/**
	 * 	a middleware for the app to interact and modify the videoMetadata as soon as videoMetadata is returned from the request (passthrough if not defined)
	 */
	videoMetadataMap?: VideoMetadataMap;

	mediaAnalyticsParam?: MediaAnalyticsProps;

	entitlementConfiguration?: EntitlementConfiguration;

	config: BoAdapterWebComponentConfig;
}

interface BoAdapterWebVanillaProps extends BoAdapterWebComponentProps {
	el: HTMLElement;
}

Config​

BO Adapter config are the same as those in the DIVA Web SDK, excluding for videoMetadataProvider, dictionary, entitlementProvider, setting, fairplayCertificatePath properties, because they are provided by BO adapter.

Refer to DivaConfiguration in Diva Web SDK, taking in account the omits.

Entitlement​

PropertyTypeDefaultDescription
Optional
Property: entitlementPlatformtype:
string
Default: ""platform parameter used to request entitlement token
Property: otherParameterstype:
Record<string, string>
Default: ""other parameters used to request entitlement token
Property: entitlementPlayerTypetype:
string
Default: ""player type parameter used to request entitlement token
Property: versiontype:
string
Default: undefinedEntitlement service version. If the version is set, `Data` will be included in the request body
Middlewares
Property: entitlementUsertype:
() => string
Default: undefineda middleware to provide user token when requested
Property: entitlementPayloadMaptype:
(type: 'token' | 'heartbeat', payload: any) => Promise<any>
Default: undefineda middleware to modify the payload before sending it to the entitlement service

Typescript interfaces for Entitlement configuration​

BoEntitlementConfiguration
interface BoEntitlementConfiguration {
  /**
   * platform parameter used to request entitlement token
   */

  entitlementPlatform?: string;
  /**
   *
   */
  otherParameters?: Record<string, string>;

  /**
   * function that returns the user token
   */
  entitlementUser?: () => string;

  /**
   * default to "HTML5", used in the entitlement "PlayerType" request parameter
   */
  entitlementPlayerType?: string;

  /**
   * Entitlement service version. If the version is set, `Data` will be included in the request body
   */
  version?: string;

  /**
   * Function type definition that can be used to modify the payload of an entitlement at runtime.
   *
   * @param {('token' | 'heartbeat')} entitlementType - The type of the entitlement.
   * @param {any} payload - The original payload of the entitlement.
   *
   * @returns {Promise<any>} The Promise object represents the modified payload of the entitlement.
   */
  entitlementPayloadMap: (
    entitlementType: "token" | "heartbeat",
    payload: any
  ) => Promise<any>;
}

Media Analytics​

PropertyTypeDefaultDescription
Optional
Property: viewerIdtype:
string
Default: ""viewer id passed down to media analytics platforms
Property: userNametype:
string
Default: ""user name passed down to media analytics platforms
Property: playerVersiontype:
string
Default: ""player version parameter passed down to media analytics platforms
Property: playerTypetype:
string
Default: ""player type parameter passed down to media analytics platforms
Property: cdnNametype:
string
Default: ""cdn name parameter passed down to media analytics platforms
Property: omLibstype:
object
Default: undefinedIt's an object of type:
{omWeb: string; omSessionClient: string;}.
It contains the libs urls for OpenMeasurement hosted by project.
It's mandatory to make OM work.
Download libs files
Callbacks
Property: mediaAnalyticsEventHandlertype:
(event: MediaEvent)  =>  void
Default: undefinedadditional callback for notifying media analytics events
Middlewares
Property: customTagtype:
(videoMetadata: VideoMetadataClean)  => Record<string, string>
Default: undefinedcustom tag generator
Property: customDimensionstype:
(videoMetadata: VideoMetadataClean) => string[]
Default: undefinedcustom dimensions generator
Property: customDeviceMetadatatype:
()  =>  ConvivaDeviceMetadata
Default: undefinedcustom device metadata generator for Conviva
Property: setPALNoncetype:
(nonceRequest: NonceRequest) => Promise<NonceRequest>
Default: undefineda middleware to modify the NonceRequest before requesting it to PAL.

Typescript interfaces for Media Analytics Configuration​

MediaAnalyticsProps
export interface MediaAnalyticsProps {
	/**
	 * custom tag generator
	 */
	customTag?: CustomTagGenerator;

	/**
	 * custom dimensions
	 */
	customDimensions?: CustomDimensionsGenerator;

	/**
	 * custom device metadata generator for Conviva
	 */
	customDeviceMetadata?: CustomDeviceMetadataGenerator;

	/**
	 * additional callback for media analytics events.
	 */
	mediaAnalyticsEventHandler?: OnMediaAnalyticsEventHandler;

	/**
	 * viewer id passed down to media analytics platforms
	 */
	viewerId?: string;

	/**
	 * user name passed down to media analytics platforms
	 */
	userName?: string;

	/**
	 * player version passed down to media analytics platforms
	 */
	playerVersion?: string;

	/**
	 * player type parameter passed down to media analytics platforms
	 */
	playerType?: string;

	/**
	 * cdn name parameter passed down to media analytics platforms
	 */
	cdnName?: string;

	/**
	 * urls for OpenMeasurement libs hosted by project
	 */
	omLibs?: {
		omWeb: string;
		omSessionClient: string;
	};

	/**
	 * Function add properties to the PAL NonceRequest object
	 */
	setPALNonce?: (nonceRequest: NonceRequest) => Promise<NonceRequest>;
}

DivaAPI​

Imperative API to interact with the player.

Typescript interfaces for DIVA API​

DIVA API

The property setAPI inside DIVA Configuration is intended to be a function that returns an object containing all the APIs for the current DIVA instance.

DIVA API reference list:

tip

For all the commands, in case of missing videoId parameter, action will be applied to Main video


/**
 * It will force DIVA to request a new VideoMetadata through videoMetadataProvider
 */
requestVideoMetadataUpdate: (videoId?: string) => void;

// Getters

/**
 * It returns the player position (both relative to the video logical start and unix timeCode as Date) of the video.
 */
getPlayerPosition: (videoId?: string) => { relative: number; absolute: Date };

/**
 * It returns the player duration (both relative to the video logical duration and absolute end point as a Date) of the video.
 */
getPlayerDuration: (videoId?: string) => { relative: number; absolute: Date };

/**
 * It returns the current video playback rate.
 */
getPlaybackRate: (videoId?: string) => number;

/**
 * It returns the current video state. Possible value: STOPPED, PLAYING, BUFFERING, PAUSED, UNKNOWN, NOT_MONITORED.
 */
getPlayerState: (videoId?: string) => PlayerState;

/**
 * It returns the current video volume. Values could be from 0 to 1.
 */
getVolume: (videoId?: string) => number;

/**
 * It returns the Diva version in this format: 'major.minor.patch'.
 */
getVersion: () => string;

// Actions

/**
 * It mute/unmute the video.
 * @param value boolean, true to mute, false to unmute.
 */
mute: (value: boolean, videoId?: string) => void;

/**
 * It pauses video playback.
 * @param interactive boolean, for analytics track, true if with user interaction.
 */
pause: (interactive?: boolean, videoId?: string) => void;

/**
 * It starts the video playback.
 * @param interactive boolean, for analytics track, true if with user interaction.
 * @returns the videoElement play promise.
 */
play: (interactive?: boolean, videoId?: string) => Promise<void>;

/**
 * It seeks the video playback.
 * @param value number, milliseconds value relative to the video start time.
 * @param interactive boolean, for analytics track, true if with user interaction.
 * @returns A promise usefull to check when the action is done.
 */
seek: (value: number, interactive?: boolean, videoId?: string) => Promise<void>;

/**
 * It seeks back the video playback by the value get from videoMetadata.behaviour.seekInterval. Default 10 seconds.
 * @param interactive boolean, for analytics track, true if with user interaction.
 * @returns A promise usefull to check when the action is done.
 */
skipBack: (interactive?: boolean, videoId?: string) => Promise<void>;

/**
 * It seeks forward the video playback by the value get from videoMetadata.behaviour.seekInterval. Default 10 seconds.
 * @param interactive boolean, for analytics track, true if with user interaction.
 * @returns A promise usefull to check when the action is done.
 */
skipForward: (interactive?: boolean, videoId?: string) => Promise<void>;

/**
 * It seeks the video playback by percentage.
 * @param value number, percentage from 0 to 100.
 * @param interactive boolean, for analytics track, true if with user interaction.
 * @returns A promise usefull to check when the action is done.
 */
seekPercentage: (value: number, interactive?: boolean, videoId?: string) => Promise<void>;

/**
 * It seeks the video playback by Date object.
 * @param value Date, in ISO 8601 format. (YYYY-MM-DDThh:mm:ssZ)
 * @param interactive boolean, for analytics track, true if with user interaction.
 * @returns A promise usefull to check when the action is done.
 */
seekAbsolute: (value: Date, interactive?: boolean, videoId?: string) => Promise<void>;

/**
 * It sets the rate at which the video is being played back.
 * @param value number, a value of 1 indicates normal speed.
 */
setPlaybackRate: (value: number, videoId?: string) => void;

/**
 * It sets the video volume.
 * @param value number, from 0 to 1, where 0 is effectively muted and 1 is the loudest possible value.
 */
setVolume: (value: number, videoId?: string) => void;

/**
 * It increases the video volume by 0.1 steps.
 */
raiseVolume: (videoId?: string) => void;

/**
 * It decreases the video volume by 0.1 steps.
 */
lowerVolume: (videoId?: string) => void;

/**
 * It sets the minimum distance between icons on timeline.
 * @param value number, in pixels. Default 20.
 */
setTimelineIconsMinDistance: (value: number) => void;

// Advanced UI actions

/**
 * It opens a data panel.
 * @param value string, data panel id.
 */
openDataPanel: (value: string, videoId?: string) => void;

/**
 * It closes the opened data panel.
 */
closeDataPanel: (videoId?: string) => void;

/**
 * It enters in native Picture in Picture.
 */
enterPiP: (videoId?: string) => void;

/**
 * It exits from native Picture in Picture.
 */
exitPiP: (videoId?: string) => void;

/**
 * It enters/exits in/from native Picture in Picture.
 */
togglePiP: (videoId?: string) => void;

/**
 * It enters in full screen mode.
 */
enterFullscreen: (videoId?: string) => void;

/**
 * It exits from full screen mode.
 */
exitFullscreen: (videoId?: string) => void;

/**
 * It enters/exits in/from full screen mode.
 */
toggleFullscreen: (videoId?: string) => void;

/**
 * Fires an event of the specified type with an optional payload.
 * Used for Ad beaconing.
 * @param type - The type of the event.
 * @param payload - The payload associated with the event.
*/
fireEvent: (type: AnalyticsMediaEventType, payload?: { ad: Ad }) => void;

// Exposed path resolver
resolve(
	value: string,
	options?: {
		videoId?: string; // if not provided it will fallback to main item
		data?: Record<string, string>;
		dontApplyDefault?: boolean;
	}
): string;

Single command entry point for: mute, pause, play, set playback rate, seek, seek absolute

sendPlayerCommand: (command: DivaCommand, interactive: boolean, videoId?: string) => void | Promise<void>;

// DIVA Commands interfaces 
export enum DivaCommandName {
	MUTE = 'mute',
	PAUSE = 'pause',
	PLAY = 'play',
	PLAYBACK_RATE = 'playback-rate',
	SEEK = 'seek',
	SEEK_ABSOLUTE = 'seek-absolute',
}

interface DivaCommandBase {
	videoId?: string;
	command: DivaCommandName;
}

export interface DivaCommandMute extends DivaCommandBase {
	command: DivaCommandName.MUTE;
	value: boolean;
}

export interface DivaCommandPause extends DivaCommandBase {
	command: DivaCommandName.PAUSE;
}

export interface DivaCommandPlay extends DivaCommandBase {
	command: DivaCommandName.PLAY;
}

export interface DivaCommandPlaybackRate extends DivaCommandBase {
	command: DivaCommandName.PLAYBACK_RATE;
	value: number;
}

export interface DivaCommandSeek extends DivaCommandBase {
	command: DivaCommandName.SEEK;
	value: number; // Milliseconds relative to trim in
}

export interface DivaCommandSeekAbsolute extends DivaCommandBase {
	command: DivaCommandName.SEEK_ABSOLUTE;
	value: Date;
}

export type DivaCommand =
	| DivaCommandMute
	| DivaCommandPause
	| DivaCommandPlay
	| DivaCommandPlaybackRate
	| DivaCommandSeek
	| DivaCommandSeekAbsolute;

Libs​

Object containing the external libraries' url lazy loaded only when needed by DIVA Web SDK.

The following block of code is an example of value pointing to public CDNs.

{
    // video libraries  
    hlsJs: 'https://cdn.jsdelivr.net/npm/hls.js@1.5.7',  
    shaka: 'https://cdnjs.cloudflare.com/ajax/libs/shaka-player/4.11.2/shaka-player.compiled.js',  
    mux: 'https://cdnjs.cloudflare.com/ajax/libs/mux.js/6.2.0/mux.min.js',  
    
    // Advertisement  
    googleIMA: 'https://imasdk.googleapis.com/js/sdkloader/ima3.js',  
    googleDAI: 'https://imasdk.googleapis.com/js/sdkloader/ima3_dai.js',  
    
    // Chromecast  
    googleCast: 'https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1',  
    
    // Used for 360 videos  
    threeJs: 'https://cdnjs.cloudflare.com/ajax/libs/three.js/0.148.0/three.min.js',
}

Disable Lazy Loading​

DIVA allows skipping the lazy loading of a third-party library by inserting the value 'false' (boolean) instead of the string containing the library's URL.
By doing so, the player assumes that the library has already been loaded and avoids loading it again.
This can improve startup performances.
Note: It is the integrator's responsibility to ensure the preloading of the necessary libraries.

Example disabling lazy loading for shaka and mux

{
    // video libraries  
    hlsJs: 'https://cdn.jsdelivr.net/npm/hls.js@1.0.4',  
    shaka: false,  
    mux: false,  
    
    // Advertisement  
    googleIMA: 'https://imasdk.googleapis.com/js/sdkloader/ima3.js',  
    googleDAI: 'https://imasdk.googleapis.com/js/sdkloader/ima3_dai.js',  
    
    // Chromecast  
    googleCast: 'https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1',  
    
    // Used for 360 videos  
    threeJs: 'https://cdnjs.cloudflare.com/ajax/libs/three.js/0.148.0/three.min.js',
}