API
Introduction​
This article lists API fields and functions of the libs that allow the DIVA Player to operate in sync with DIVA Back Office and customize the video consumption's experience:
DIVA Back Office Adapter libDIVA Player lib
DIVA Back Office Adapter lib API​
The DIVA Back Office Adapter lib acts as a bridge between the DIVA Player and the DIVA Back Office, enabling data exchange and integration of business logic, configuration, and metadata.
After initialization, the DIVA Back Office Adapter Node instance provides the API for the player to retrieve launch parameters, entitlement information, and other operational data from the back office.
To access the DIVA Back Office Adapter lib API, you need to get the DIVA Back Office Adapter Node instance:
sub loadBOAdapterLib()
' Creates the ComponentLibrary (the DIVA Back Office Adapter in this case)
m.divaBOAdapter = CreateObject("roSGNode", "ComponentLibrary")
m.divaBOAdapter.id = "DivaBOAdapter"
m.divaBOAdapter.uri = "pkg:/resources/diva-bo-adapter-cl-1.4.0.zip"
' Adding the ComponentLibrary node to the scene will start the download of the library
m.top.appendChild(m.divaBOAdapter)
m.divaBOAdapter.observeField("loadStatus", "onBOAdapterLoadStatusChanged")
end sub
sub onBOAdapterLoadStatusChanged(evt as dynamic)
loadStatus = evt.getData()
? "[DIVA Back Office Adapter lib.loadStatus]: " + loadStatus
if loadStatus = "ready"
m.boAdapterNode = CreateObject("roSGNode", "DivaBOAdapter:DivaBOAdapter")
' At this point you have access to the DIVA Back Office Adapter API
end if
end sub
Fields​
SET initData​
<field id="initData" type="assocarray"/>
This field is used for Basic instantiation code (BrightScript) implementation.
GET error​
<field id="error" type="assocarray"/>
If an error occurs in the DIVA Back Office Adapter, the error data is dispatched through this field. This field is used for Basic instantiation code (BrightScript) implementation.
GET divaLaunchParams​
<field id="divaLaunchParams" type="assocarray"/>
More information in the section Configuration.
GET dictionary​
<field id="dictionary" type="assocarray"/>
This field is used for Basic instantiation code (BrightScript) implementation.
More information in Configuration.
GET videoDataNode​
<field id="videoDataNode" type="node"/>
More information in the section VideoMetaDataMap.
GET settingsNode​
<field id="settingsNode" type="node"/>
This field is used for Basic instantiation code (BrightScript) implementation.
In Media analytics you will find tips on how to use this field within the analytics initialization flow.
GET boAdapterReady​
<field id="boAdapterReady" type="boolean"/>
When the DIVA Back Office Adapter gets all the necessary data for launching the DIVA Player, it triggers this event.
This field is used for Basic instantiation code (BrightScript) implementation.
SET entitlementRequest​
<field id="entitlementRequest" type="assocarray"/>
More information in the Entitlement and DRM section.
GET entitlementData​
<field id="entitlementData" type="assocarray"/>
More information in the Entitlement and DRM section.
SET activateEntitlementPayloadMapCallback​
<field id="activateEntitlementPayloadMapCallback" type="boolean" value="false"/>
More information in the Entitlement and DRM section.
GET entitlementPayloadMap​
More information in the Entitlement and DRM section.
<field id="entitlementPayloadMap" type="assocarray"/>
SET setEntitlementPayloadMap​
<field id="setEntitlementPayloadMap" type="assocarray"/>
More information in the Entitlement and DRM section.
SET requestMetaDataUpdate​
<field id="requestMetaDataUpdate" type="assocarray"/>
This field is used for Basic instantiation code (BrightScript) implementation.
DIVA Player makes a request to update the Meta Data then this request is forwarded to the DIVA Back Office Adapter.
GET ssaiSettingsNode​
<field id="ssaiSettingsNode" type="node"/>
This field is used for the transition of the SSAI Settings data from DIVA Back Office Adapter to the DIVA Ads Core.
Example:
m.boAdapterNode.observeField("ssaiSettingsNode", "onSSAISettingsHandler")
sub onSSAISettingsHandler(evt as dynamic)
m.divaAdsCoreNode.initData = evt.getData()
end sub
SET destroy​
<field id="destroy" type="boolean"/>
Inform the DIVA Back Office Adapter that it is planned to be removed from the child tree (scene).
An example of usage can be found in the Basic instantiation code (BrightScript) section.
Functions​
GET getVersion​
return string
Get version of the DIVA Back Office Adapter lib.
Example:
print m.boAdapterNode.callFunc("getVersion")
GET getEntitlementHeartBeatInterval​
return invalid
return integer
More information in the Entitlement and DRM section.
DIVA Player lib API​
The DIVA Player lib API exposes methods and fields for controlling playback, handling events, and interacting with player features. It's available after DIVA Player lib Node instance initialization.
To access the DIVA Player lib API, you need to get the DIVA Player Utils Node instance:
sub loadDivaPlayerLib()
' Creates the ComponentLibrary (the DivaPlayerSDK in this case)
m.divaPlayerSDK = CreateObject("roSGNode", "ComponentLibrary")
m.divaPlayerSDK.id = "DivaPlayerSDK"
m.divaPlayerSDK.uri = "pkg:/resources/diva-roku-cl-sdk-5.9.0.zip"
' Adding the ComponentLibrary node to the scene will start the download of the library
m.top.appendChild(m.divaPlayerSDK)
m.divaPlayerSDK.observeField("loadStatus", "onDivaPlayerLoadStatusChanged")
end sub
sub onDivaPlayerLoadStatusChanged(evt as dynamic)
loadStatus = evt.getData()
? "[Diva Player lib.loadStatus]: " + loadStatus
if loadStatus = "ready"
m.dpUtilsNode = CreateObject("roSGNode", "DivaPlayerSDK:DPUtilsNode")
' At this point you have access to the DIVA Player API
end if
end sub
Fields​
GET divaPlayerExit​
<field id="divaPlayerExit" type="boolean"/>
An example of usage can be found in the Basic instantiation code (BrightScript) section.
SET metaDataUpdate​
<field id="metaDataUpdate" type="assocarray" />
An example of usage can be found in the Basic instantiation code (BrightScript) section.
GET selectedTextTrack​
<field id="selectedTextTrack" type="string"/>
When the user selects a new closed caption track, a callback will be dispatched.
...
m.dpUtilsNode.observeField("selectedTextTrack", "onSelectedCCTrackHandler")
...
sub onSelectedCCTrackHandler(evt as dynamic)
print evt.getData()
end sub
GET CCMode​
<field id="CCMode" type="string" />
When the user changes the Closed Caption mode, a callback will be dispatched.
Available values: "Off", "On", "Instant replay", "When mute".
...
m.dpUtilsNode.observeField("CCMode", "onCCModeChangedHandler")
...
sub onCCModeChangedHandler(evt as dynamic)
print evt.getData()
end sub
GET selectedAudioTrack​
<field id="selectedAudioTrack" type="assocarray"/>
DIVA Player notifies when the user selects a new Audio Track in the Audio Panel.
m.dpUtilsNode.observeField("selectedAudioTrack", "onSelectedAudioTrackHandler")
sub onSelectedAudioTrackHandler(evt as dynamic)
print evt.getData()
end sub
GET analyticsEvent​
<field id="analyticsEvent" type="assocarray"/>
More information in the section Analytics.
GET mediaAnalyticsEvent​
<field id="mediaAnalyticsEvent" type="assocarray"/>
More information in the section Media analytics.
GET playerPositionEvent​
<field id="playerPositionEvent" type="assocarray" />
More information in the Resume Point API section.
GET playerStateEvent​
<field id="playerStateEvent" type="string"/>
More information in the Resume Point API section.
GET videoMetadataEvent​
<field id="videoMetadataEvent" type="node" />
More information in the Resume Point API section.
GET accessibilityUpdateEvent​
<field id="accessibilityUpdateEvent" type="assocarray" />
DIVA Player notifies when the user changes the accessibility option.
Data structure of the callback:
{
"darkerBackgroundCc": true/false 'dispatched when the user changes the dark background for closed caption
"enlargedCc": true/false 'dispatched when the user changes font size for closed captions
"opaqueBackground": true/false 'dispatched when the user changes the opacity of the background for all panels in DIVA Player
}
...
m.dpUtilsNode.observeField("accessibilityUpdateEvent", "onAccessibilityUpdateEventHandler")
...
sub onAccessibilityUpdateEventHandler(evt as dynamic)
data = evt.getData()
if data <> invalid
if data.darkerBackgroundCc <> invalid
setDarkerBackgroundCc(data.darkerBackgroundCc) 'save values to the Roku Box registry
end if
if data.enlargedCc <> invalid
setEnlargedCc(data.enlargedCc) 'save values to the Roku Box registry
end if
if data.opaqueBackground <> invalid
setOpaqueBackground(data.opaqueBackground) 'save values to the Roku Box registry
end if
end if
end sub
For the next DIVA Player playback session, the integrator can restore these settings for DIVA Player in the launch params:
...
m.dpUtilsNode.callFunc("setLaunchParams", prepareLaunchParams())
...
function prepareLaunchParams() as dynamic
params = {}
...
' accessibility options
params["darkerBackgroundCc"] = getDarkerBackgroundCc() 'true - turn on the darker Background, false - turn off the darker Background
params["enlargedCc"] = getEnlargedCc() 'true - enlarged Cc, false - standard CC size
params["opaqueBackground"] = getOpaqueBackground() 'Increase background opacity: true - transparent background, false - not transparent background, high contrast
params["ccEnhancementsOptionEnabled"] = getCcEnhancementsEnabled() 'Show/Hide the Caption style Btn in Subtitles menu: true - show, false - hide
params["transparencyOptionEnabled"] = getTransparencyEnabled() 'Show/Hide the Transparency Btn (Increase contrast) in Settings menu: true - show, false - hide
...
return params
end function
GET errorData​
<field id="errorData" type="assocarray"/>
DIVA Player error data is dispatched through this field.
GET entitlementRequest​
<field id="entitlementRequest" type="assocarray" />
More information in the Entitlement and DRM section.
GET entitlementConfigurationRequest​
<field id="entitlementConfigurationRequest" type="boolean"/>
More information in the Entitlement and DRM section.
GET onPlaybackSession​
<field id="onPlaybackSession" type="boolean"/>
Request from the DIVA Player when creating PlaybackSessionId.
Every time DIVA Player starts to play a new stream, it will call this observer. In this callback, you can update PlaybackSessionId.
The DIVA Player creates "PlaybackSessionId" by itself inside DIVA Player.
Then DIVA Player makes a request when creating PlaybackSessionId to the main application (calls this observer).
1.) If the main application reacts to this observer and calls setPlaybackSessionId with a new PlaybackSessionId, then DIVA Player uses this PlaybackSessionId.
2.) If the main application doesn't call setPlaybackSessionId, then DIVA Player will use its own PlaybackSessionId.
'Observe the DIVA Player on the request when creating Playback Session Id
m.dpUtilsNode.observeField("onPlaybackSession", "onPlaybackSessionIdEventHandler")
SET activateRecommendationRowCallback​
<field id="activateRecommendationRowCallback" type="boolean" />
More information in the Recommendations / Related section.
GET recommendationRowItemSelect​
<field id="recommendationRowItemSelect" type="assocarray"/>
More information in the Recommendations / Related section.
SET setRecommendationRowItemData​
<field id="setRecommendationRowItemData" type="assocarray" />
More information in the Recommendations / Related section.
SET castAndCrewData​
<field id="castAndCrewData" type="node"/>
Set data for Cast and Crew row.
...
m.dpUtilsNode.castAndCrewData = getCastAndCrewData()
...
function getCastAndCrewData() as dynamic
node = CreateObject("roSGNode", "ContentNode")
node.addFields({data:getCastAndCrewArrData()})
return node
end function
function getCastAndCrewArrData() as dynamic
return [
{
"id": "",
"name": "Actor Name",
"description": "sub title",
"image": "https:/demo.com/jack_mercer.jpg"
}
]
end function
GET onCrewItemSelection​
<field id="onCrewItemSelection" type="assocarray"/>
This callback is triggered when the user selects any Cast and Crew row item.
m.dpUtilsNode.observeField("onCrewItemSelection", "onCrewItemSelectionEventHandler")
GET contentDuration​
Returns video content duration in seconds.
<field id="contentDuration" type="integer" />
...
m.dpUtilsNode.observeField("contentDuration", "onContentDurationHandler")
...
sub onContentDurationHandler(evt as dynamic)
' get current content duration
print evt.getData()
end sub
SET adStatPanel​
<field id="adStatPanel" type="array"/>
Set ad banner for the DIVA Player Data Panel.
m.dpUtilsNode.adStatPanel = [
{
"panelType": "lineup" ' '"players_stats", "lineup", "teams_stats", "individual_ranking"
"ads":[{
"position": "above", '"below"
"uri": "pkg:/resources/images/testApp/ads/336x280.png",
"width": 336,
"height": 280
}]
}
]
SET debug​
<field id="debug" type="boolean"/>
Set debug to true to show the Debug Panel in the DivaPlayer.
'Set "debug" to "true" to show the Debug Panel in the `DivaPlayer`
m.dpUtilsNode.debug = true
Functions​
GET getPlayer​
return node
An example of use can be found in the Basic instantiation code (BrightScript) section.
GET getVersion​
return string
Get the version of the DIVA Player lib.
divaPlayerVersion = m.dpUtilsNode.callFunc("getVersion")
SET setLaunchParams​
An example of use can be found in the Basic instantiation code (BrightScript) section.
SET setDictionary​
An example of use can be found in the Basic instantiation code (BrightScript) section.
Example of the dictionaryData(Associative array)
SET setSettings​
An example of use can be found in the Basic instantiation code (BrightScript) section.
SET setMetaData​
More information in the section VideoMetaDataMap.
An example of use can be found in the Basic instantiation code (BrightScript) section.
SET command​
This function is used to control playback: 'play', 'pause', 'mute', 'unmute',
m.dpUtilsNode.callFunc("command", {commandName: "play"})
m.dpUtilsNode.callFunc("command", {commandName: "pause"})
m.dpUtilsNode.callFunc("command", {commandName: "mute"})
m.dpUtilsNode.callFunc("command", {commandName: "unmute"})
and toggle video - change the video player size from fullscreen to the specified width and height values.
m.dpUtilsNode = CreateObject("roSGNode", "DivaPlayerSDK:DPUtilsNode")
m.divaPlayer = m.dpUtilsNode.callFunc("getPlayer")
m.divaPlayer.width = 480
m.divaPlayer.height = 500
m.divaPlayer.translation = [1400, 180]
...
m.dpUtilsNode.callFunc("command", {commandName: "toggle video", value: true}) 'true-false
...
runPlayer​
An example of use can be found in the Basic instantiation code (BrightScript) section.
closePlayer​
Call this function if you need to remove DIVA Player from the node tree.
After calling this function, "DIVA Player" prepares to be removed, and then DIVA Player will call the callback divaPlayerExit
m.dpUtilsNode.callFunc("closePlayer")
SET setEntitlementConfiguration​
More information in the Entitlement and DRM section.
SET setEntitlementData​
More information in the Entitlement and DRM section.
SET setTimelineIconsMinDistance​
m.dpUtilsNode.callFunc("setTimelineIconsMinDistance", {"distance": timelineIconsMinDistance})
GET getSessionId​
return string
If the main application does not set data["sessionId"] in setLaunchParams params, then DivaPlayer will create sessionId by itself after calling setLaunchParams.
print "Session Id: " + m.dpUtilsNode.callFunc("getSessionId")
To set sessionId, the integrator should set it in the data for setLaunchParams.
...
m.dpUtilsNode.callFunc("setLaunchParams", prepareLaunchParams())
...
function prepareLaunchParams() as dynamic
params = {}
...
params.SessionId = CreateObject("roDeviceInfo").GetRandomUUID()
...
return params
end function
SET setPlaybackSessionId​
...
m.dpUtilsNode.observeField("onPlaybackSession", "onPlaybackSessionIdEventHandler")
...
sub onPlaybackSessionIdEventHandler() 'DivaPlayer
' Optional observer.
' Request from the DivaPlayer when creating "PlaybackSessionId"
' Every time DivaPlayer starts to play a new stream, it will call this observer. In this callback, you can update it.
' The DIVA Player creates "PlaybackSessionId" by itself inside DivaPlayer
' Then DIVA Player makes a request when creating PlaybackSessionId to the main application (calls this observer)
' 1.) If the main application reacts to this observer and calls "setPlaybackSessionId" with a new "PlaybackSessionId", then DIVA Player uses this "PlaybackSessionId"
' 2.) If the main application doesn't call "setPlaybackSessionId", then DivaPlayer will use its own "PlaybackSessionId"
print "PlaybackSessionId: " + m.dpUtilsNode.callFunc("getPlaybackSessionId") ' get "setPlaybackSessionId" that is created by default inside DivaPlayer
m.dpUtilsNode.callFunc("setPlaybackSessionId", {"playbackSessionId": CreateObject("roDeviceInfo").GetRandomUUID()})
print "PlaybackSessionId: " + m.dpUtilsNode.callFunc("getPlaybackSessionId") ' In this case, it returns the value that was set in the previous line of code
end sub
GET getPlaybackSessionId​
return string
print m.dpUtilsNode.callFunc("getPlaybackSessionId")
SET setAdsMetadata​
Set data for SSAI Ads.
m.divaAdsCoreNode.observeField("adMetadata", "handleAdMetadataChanges")
m.dpUtilsNode.callFunc("setAdsMetaData", evt.getData())
GET adsCoreMediaAnalyticsEvent​
m.divaAdsCoreNode.observeField("mediaAnalyticsEvent", "handleSSAIAdsCoreMediaAnalyticsEvent")
sub handleSSAIAdsCoreMediaAnalyticsEvent(evt as dynamic)
if m.dpUtilsNode <> invalid
m.dpUtilsNode.callFunc("adsCoreMediaAnalyticsEvent", evt.getData())
end if
end sub
GET getPlayerStateConst​
Get constants from the DIVA Player that are used for PlayerStateEvent. More information in the Resume Point API section.
divaPlayerStateConst = m.dpUtilsNode.callFunc("getPlayerStateConst")