Skip to main content

Media analytics

What you learn​

You're instantiating DIVA Player in your Roku app and relying on DIVA Back Office as the video streaming source.

The goal of this article is to build the simplest Roku app to stream a video from the DIVA Back Office with active Conviva and Youbora media analytics.

Before starting​

  • Ensure Conviva plugin lib and Youbora plugin lib downloaded (Setup > Step 13).
  • Ask your video engineers team the <video id> and the related <settings URL>.
  • Ensure the settings file contains the mediaAnalytics section: 
    "mediaAnalytics": {
      "conviva": {
        "enabled": true,
        "customerKey": "<yourCustomerKey>",
        "playerName": "Diva",
        "viewerId": "<yourViewerIdentifier>",
        "cdnName": "Akamai",
        "touchstoneUrl": "https://<yourSubdomain>.conviva.com"
      },
      "youbora": {
        "enabled": true,
        "playerName": "Diva",
        "cdnName": "<yourCDNName>",
        "userName": "<yourViewerIdentifier>",
        "accountCode": "<yourAccountCode>"
      }
    }
    Based on your project requirements, the settings file only contains either the Conviva or Youbora configuration.

Setup​

  1. Authorize to the AWS CodeArtifact (Setup > Steps 1-6).

  2. Download the Conviva plugin lib or Youbora plugin lib (based on your project requirements) from the AWS CodeArtifact:

    • Conviva plugin lib: The Package name is roku-diva-conviva-plugin.

    • Youbora plugin lib: The Package name is roku-diva-youbora-plugin.

    Note: The approach for downloading Conviva plugin lib and Youbora plugin lib are identical. The next steps 3-8 describe how to download the Conviva plugin lib and these steps are similar to downloading the Youbora plugin lib

  3. Find the package in AWS CodeArtifact. Navigate to the Diva repository. Add package filter by name: roku-diva-conviva-plugin / roku-diva-youbora-plugin.

    Note: roku-diva-conviva-plugin is the Conviva plugin lib's package, while roku-diva-youbora-plugin is the Youbora plugin lib's package.

    Diva Package search

  4. Select the roku-diva-conviva-plugin / roku-diva-youbora-plugin package in the search result.

    Diva Package search

  5. On the Packages page, select the required Package version.

    Diva Package version

  6. In the Asset tab, find the package name(1), version(2) and package lib name(3).

    Diva Package search

  7. Download package (roku-diva-conviva-plugin / roku-diva-youbora-plugin) by running the following command in the cmd line:

    Note: This command for cmd line on Windows, for other platform use AWS instruction here

    Replace values in command before sending:

    aws codeartifact get-package-version-asset --domain deltatre-diva --repository Diva ^
    --format generic --namespace com.deltatre.diva --package PACKAGE_NAME  ^
    --package-version PACKAGE_VERSION --asset PACKAGE_LIB_NAME PACKAGE_LIB_NAME

    • PACKAGE_NAME: It is the package name(1) from the Step 11. Can be: roku-diva-conviva-plugin / roku-diva-youbora-plugin

    • PACKAGE_VERSION: It is the version(2) from the Step 11. For example: 1.0.2

    • PACKAGE_LIB_NAME: It is the package lib name(3) from the Step 11. For example: roku-diva-conviva-plugin-1.0.2.zip

    Example of command for downloading the Conviva plugin lib and Youbora plugin lib:

    aws codeartifact get-package-version-asset --domain deltatre-diva --repository Diva ^
    --format generic --namespace com.deltatre.diva --package roku-diva-conviva-plugin  ^
    --package-version 1.0.2 --asset roku-diva-conviva-plugin-1.0.2.zip roku-diva-conviva-plugin-1.0.2.zip

  8. Store the Conviva plugin lib and Youbora plugin lib in your Roku project, in the pkg:/resources/plugins/ folder.

  9. After downloading the Conviva plugin lib and Youbora plugin lib you are ready to create the Roku app with Conviva plugin lib and Youbora plugin lib.

Instantiation​

Media analytics code​

Enrich the Basic instantiation code with the media analytics configuration.

Set up configuration object for initialization Conviva plugin lib and Youbora plugin lib instance.

  • divaVersion: Player version passed down to media analytics platforms.
  • playerName: Player name parameter passed down to media analytics platforms. Can be mapped on the BO Adapter settings response mediaAnalytics.conviva.playerName key
  • customerKey: Customer Key parameter passed down to media analytics platforms. Can be mapped on the BO Adapter settings response mediaAnalytics.conviva.customerKey key
  • viewerId: Viewer id passed down to media analytics platforms. Can be mapped on the BO Adapter settings response mediaAnalytics.conviva.viewerId key
  • cdnName: CDN name parameter passed down to media analytics platforms. Can be mapped on the BO Adapter settings response mediaAnalytics.conviva.cdnName key
  • gatewayUrl: Gateway url parameter passed down to media analytics platforms. Can be mapped on the BO Adapter settings response mediaAnalytics.conviva.touchstoneUrl key

Code sample​

Write the initialization of the Conviva plugin lib and Youbora plugin lib:

sub init()
    ...
    loadLibs()
    ...
end sub

sub loadLibs()
    ...
    loadConviva()
    ...
end sub

sub loadConviva()
    m.convivaLibrary = CreateObject("roSGNode", "ComponentLibrary")
    m.convivaLibrary.id = "DivaConvivaPlugin"
    m.convivaLibrary.uri = "pkg:/resources/plugins/diva-conviva-plugin-cl-1.0.2.zip"

    ' Adding the ComponentLibrary node to the scene will start the download of the library
    m.top.appendChild(m.convivaLibrary)
    m.convivaLibrary.observeField("loadStatus", "onConvivaPluginLoadStatusChanged")
end sub

sub onConvivaPluginLoadStatusChanged()
    if m.convivaLibrary.loadStatus = "ready"
        m.convivaAnalytics = CreateObject("roSGNode", "DivaConvivaPlugin:ConvivaAnalytics")
    end if
end sub

Write the media analytics configuration for Conviva plugin lib and Youbora plugin lib:

sub launchBOAdapter(divaLaunchParams as object)
    ...
    ' Observe BO Adapter Settings
    m.boAdapterNode.observeField("settingsNode", "onSettingsHandler")
    ...
end sub

sub onSettingsHandler(evt as dynamic)
    data = evt.getData()
    ...
    launchConviva(data)
end sub

sub launchConviva(settingsData as dynamic)
    if m.convivaAnalytics <> invalid
        m.convivaAnalytics.callFunc("initConviva", getConvivaConfig(settingsData))
    end if
end sub

function getConvivaConfig(settingsData = invalid as dynamic) as dynamic
    convivaInitData = invalid
    if settingsData <> invalid and settingsData.mediaAnalytics <> invalid and settingsData.mediaAnalytics.conviva <> invalid
        convivaInitData = settingsData.mediaAnalytics.conviva
    end if

    config = {}

    if convivaInitData <> invalid and convivaInitData.enabled <> invalid and convivaInitData.enabled
        config.divaVersion = "5.8.0"
        config.playerName = "Diva"
        config.customerKey = convivaInitData.customerKey
        config.playerName = convivaInitData.playerName
        config.viewerId = convivaInitData.viewerId
        config.cdnName = convivaInitData.cdnName
        config.gatewayUrl = convivaInitData.touchstoneUrl
    end if

    return config
end function

Finally, add the observer on the mediaAnalyticsEvent field to the DIVA Player instantiation:

sub launchBOAdapter(divaLaunchParams as object)
    ...
    m.dpUtilsNode.observeField("mediaAnalyticsEvent", "onMediaAnalyticsEventHandler")
    ...
end sub

sub onMediaAnalyticsEventHandler(evt)
    'Media analytics event handler callback
    data = evt.getData()

    if m.youboraAnalytics <> invalid
        m.youboraAnalytics.callFunc("handleMediaEvent", data)
    end if

    if m.convivaAnalytics <> invalid
        m.convivaAnalytics.callFunc("handleEvent", data)
    end if
end sub

Working sample code (.tsx)​

sub init()
    ...
    loadLibs()
    ...
end sub

sub loadLibs()
    ...
    loadYoubora()
    loadConviva()
    ...
end sub

sub launchBOAdapter(divaLaunchParams as object)
    ...
    m.boAdapterNode = CreateObject("roSGNode", "DivaBOAdapter:DivaBOAdapter")
    ...
    ' Observe BO Adapter Settings
    m.boAdapterNode.observeField("settingsNode", "onSettingsHandler")
    ...
    'Diva Player Utils Node
    m.dpUtilsNode = CreateObject("roSGNode", "DivaPlayerSDK:DPUtilsNode")
    ...
    ' Observe DivaPlayer media analytics event call
    m.dpUtilsNode.observeField("mediaAnalyticsEvent", "onMediaAnalyticsEventHandler")
    ...
    ' Observe Diva Player exit call
    m.dpUtilsNode.observeField("divaPlayerExit", "onDivaPlayerExitHandler")
end sub

sub onSettingsHandler(evt as dynamic)
    data = evt.getData()
    ...
    launchYoubora(data)
    launchConviva(data)
end sub

function getYouboraConfig(settingsData = invalid as dynamic) as dynamic
    youboraInitData = invalid
    if settingsData <> invalid and settingsData.mediaAnalytics <> invalid and settingsData.mediaAnalytics.youbora <> invalid
        youboraInitData = settingsData.mediaAnalytics.youbora
    end if

    config = {}

    if youboraInitData <> invalid and youboraInitData.enabled <> invalid and youboraInitData.enabled
        config.divaVersion = "5.8.0"
        config.playerName = "Diva"
        config.accountCode = youboraInitData.accountCode
        config.playerName = youboraInitData.playerName
        config.viewerId = youboraInitData.userName
        config.cdnName = youboraInitData.cdnName
    end if

    return config
end function

function getConvivaConfig(settingsData = invalid as dynamic) as dynamic
    convivaInitData = invalid
    if settingsData <> invalid and settingsData.mediaAnalytics <> invalid and settingsData.mediaAnalytics.conviva <> invalid
        convivaInitData = settingsData.mediaAnalytics.conviva
    end if

    config = {}

    if convivaInitData <> invalid and convivaInitData.enabled <> invalid and convivaInitData.enabled
        config.divaVersion = "5.8.0"
        config.playerName = "Diva"
        config.customerKey = convivaInitData.customerKey
        config.playerName = convivaInitData.playerName
        config.viewerId = convivaInitData.viewerId
        config.cdnName = convivaInitData.cdnName
        config.gatewayUrl = convivaInitData.touchstoneUrl
    end if

    return config
end function

sub onMediaAnalyticsEventHandler(evt)
    ' Media analytics event handler callback
    data = evt.getData()

    if m.youboraAnalytics <> invalid
        m.youboraAnalytics.callFunc("handleMediaEvent", data)
    end if

    if m.convivaAnalytics <> invalid
        m.convivaAnalytics.callFunc("handleEvent", data)
    end if
end sub

sub onDivaPlayerExitHandler()
    ...
    startPlayerCleanupTimer()
end sub

sub startPlayerCleanupTimer()
    m.cleanupTimer = CreateObject("roSGNode", "Timer")
    m.cleanupTimer.repeat = false
    m.cleanupTimer.duration = 0.5
    m.cleanupTimer.observeField("fire", "onCleanupTimerHandler")
    m.cleanupTimer.control = "START"
end sub

sub onCleanupTimerHandler()
    closeYoubora()
    closeConviva()
end sub

' Youbora plugin setup
sub loadYoubora()
    m.youboraLibrary = CreateObject("roSGNode", "ComponentLibrary")
    m.youboraLibrary.id = "DivaYouboraPlugin"
    m.youboraLibrary.uri = "pkg:/resources/plugins/diva-youbora-plugin-cl-1.0.1.zip"

    ' Adding the ComponentLibrary node to the scene will start the download of the library
    m.top.appendChild(m.youboraLibrary)
    m.youboraLibrary.observeField("loadStatus", "onPluginLoadStatusChanged")
end sub

sub onPluginLoadStatusChanged()
    if m.youboraLibrary.loadStatus = "ready"
        m.youboraAnalytics = CreateObject("roSGNode", "DivaYouboraPlugin:YouboraAnalytics")
    end if
end sub

sub launchYoubora(settingsData as dynamic)
    if m.youboraAnalytics <> invalid
        m.youboraAnalytics.callFunc("initYoubora", getYouboraConfig(settingsData))
    end if
end sub

sub closeYoubora()
    if m.youboraAnalytics <> invalid
        m.youboraAnalytics.callFunc("closeYoubora")
    end if
end sub

' Conviva plugin setup
sub loadConviva()
    m.convivaLibrary = CreateObject("roSGNode", "ComponentLibrary")
    m.convivaLibrary.id = "DivaConvivaPlugin"
    m.convivaLibrary.uri = "pkg:/resources/plugins/diva-conviva-plugin-cl-1.0.2.zip"

    ' Adding the ComponentLibrary node to the scene will start the download of the library
    m.top.appendChild(m.convivaLibrary)
    m.convivaLibrary.observeField("loadStatus", "onConvivaPluginLoadStatusChanged")
end sub

sub onConvivaPluginLoadStatusChanged()
    if m.convivaLibrary.loadStatus = "ready"
        m.convivaAnalytics = CreateObject("roSGNode", "DivaConvivaPlugin:ConvivaAnalytics")
    end if
end sub

sub launchConviva(settingsData as dynamic)
    if m.convivaAnalytics <> invalid
        m.convivaAnalytics.callFunc("initConviva", getConvivaConfig(settingsData))
    end if
end sub

sub closeConviva()
    if (m.convivaAnalytics <> invalid)
        m.convivaAnalytics.callFunc("closeConviva")
        m.convivaAnalytics = invalid
    end if
end sub