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.

React App
No React
No package manager

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.3.7/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}
    />
)

// bo adapter sdk
import { createDivaWebBoAdapter } 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.3.7/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 el = document.getElementById("video-player-container");

(async () => {
    try{
        const divaBo = await createDivaWebBoAdapter({
            el,
            settingsUrl: SETTINGS_URL,
            config
        });

        // to be run when it is required to cleanup diva after its usage
        const onUnmount = () => {
            divaBo.unmount();
        }
    } catch (e) {
        // here it is possible to react to BoAdapterIssues
    }
})();

note

{targetEnv}: .min (production), (empty string) development

<html>
  <head>
    <!-- ... -->
    <script src="path/to/diva/webBOAdapter.reactBundled .js"></script>
    <link rel="path/to/diva.bundle.min.css" />
  </head>
  <body>
    <!-- ... -->
    <div id="diva-container"></div>
    <!-- ... -->

    <script>
        // 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.3.7/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 el = document.getElementById("diva-container");

        (async () => {
            try{
                const divaBo = await divaWebBoAdapter.createDivaWebBoAdapter({
                    el,
                    settingsUrl: SETTINGS_URL,
                    config,
                });

                // to be run when it is required to cleanup diva after its usage
                const onUnmount = () => {
                    divaBo.unmount();
                }
            } catch (e) {
                // here it is possible to react to BoAdapterIssues
            }
        })();
    </script>
  </body>
</html>

Properties

Property	Type	Default	Description
Mandatory
Property: settingsUrl	type: string	Default: NA	url to reach diva bo adapter settings for the specific project
Property: config	type: BoAdapterWebComponentConfig	Default: NA	initialization data for DIVA BO adapter
Property: el (vanilla js/react embedded)	type: HTML div element reference	Default: NA	HTML div element where diva should be started into
Optional
Property: mediaAnalyticsParam	type: MediaAnalyticsProps	Default: undefined	properties useful to implement media analytics
Property: entitlementConfiguration	type: BoEntitlementConfiguration	Default: undefined	properties useful to implement entitlement
Middleware
Property: videoMetadataMap	type: (videoMetadata: VideoMetadata) => Promise<VideoMetadata>	Default: undefined	asynchronous middleware for the app to interact and modify the videoData as soon as videoData is returned from the request (passthrough if not defined)
Callbacks
Property: onDivaBoAdapterError	type: (e: unknown) => void	Default: undefined	notify 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 videoData as soon as videoData 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

Property	Type	Default	Description
Optional
Property: entitlementPlatform	type: string	Default: ""	platform parameter used to request entitlement token
Property: otherParameters	type: Record<string, string>	Default: ""	other parameters used to request entitlement token
Property: entitlementPlayerType	type: string	Default: ""	player type parameter used to request entitlement token
Property: version	type: string	Default: undefined	Entitlement service version. If the version is set, `Data` will be included in the request body
Middlewares
Property: entitlementUser	type: () => string	Default: undefined	a middleware to provide user token when requested
Property: entitlementPayloadMap	type: (type: 'token' \| 'heartbeat', payload: any) => Promise<any>	Default: undefined	a 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

Property	Type	Default	Description
Optional
Property: viewerId	type: string	Default: ""	viewer id passed down to media analytics platforms
Property: userName	type: string	Default: ""	user name passed down to media analytics platforms
Property: playerVersion	type: string	Default: ""	player version parameter passed down to media analytics platforms
Property: playerType	type: string	Default: ""	player type parameter passed down to media analytics platforms
Property: cdnName	type: string	Default: ""	cdn name parameter passed down to media analytics platforms
Property: omLibs	type: object	Default: undefined	It'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: mediaAnalyticsEventHandler	type: (event: MediaEvent) => void	Default: undefined	additional callback for notifying media analytics events
Middlewares
Property: customTag	type: (videoMetadata: VideoMetadataClean) => Record<string, string>	Default: undefined	custom tag generator
Property: customDimensions	type: (videoMetadata: VideoMetadataClean) => string[]	Default: undefined	custom dimensions generator
Property: customDeviceMetadata	type: () => ConvivaDeviceMetadata	Default: undefined	custom device metadata generator for Conviva
Property: setPALNonce	type: (nonceRequest: NonceRequest) => Promise<NonceRequest>	Default: undefined	a 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://ajax.googleapis.com/ajax/libs/shaka-player/4.7.11/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',
}

Requirements​

Initialization​

Properties​

Typescript interfaces for Properties​

Config​

Entitlement​

Typescript interfaces for Entitlement configuration​

Media Analytics​

Typescript interfaces for Media Analytics Configuration​

DivaAPI​

Typescript interfaces for DIVA API​

Libs​

Disable Lazy Loading​