Roku — Tracking in SceneGraph

Last update: 2022-11-11
  • Created for:
  • User
    Admin
    Developer

Introduction

You can use the Roku SceneGraph XML programming framework to develop applications. This framework features two key concepts:

  • SceneGraph rendering of the application screens
  • XML configuration of the SceneGraph screens

The Adobe Mobile SDK for Roku is written in BrightScript. The SDK uses many components that are not available for an app running on SceneGraph (for example, threads). Therefore, a Roku app developer intending to use the SceneGraph framework cannot call Adobe Mobile SDK APIs (the latter are similar to those available in legacy BrightScript apps).

Architecture

To add SceneGraph support to the AdobeMobile SDK, Adobe has added a new API that creates a connector bridge between the AdobeMobile SDK and adbmobileTask. The latter is a SceneGraph node used for the SDK’s API execution. (Usage of adbmobileTask is explained in detail throughout the rest of this document.)

The connector bridge is designed to perform as follows:

  • The bridge returns a SceneGraph-compatible instance of the AdobeMobile SDK. The SceneGraph-compatible SDK has all of the APIs that the legacy SDK exposes.
  • You use the AdobeMobile SDK APIs in SceneGraph in a very similar way to how you used the legacy APIs.
  • The bridge also exposes a mechanism to listen for callbacks for APIs that return some data.

Components

SceneGraph Application:

  • Consumes AdobeMobileLibrary APIs via the SceneGraph connector bridge APIs.
  • Registers for response callbacks on adbmobileTask for expected output data variables.

AdobeMobileLibrary:

  • Exposes a set of public APIs (Legacy), including the connector bridge API.
  • Returns a SceneGraph connector instance that wraps all legacy public APIs.
  • Communicates with an adbmobileTask SceneGraph node for execution of APIs.

adbmobileTask Node:

  • A SceneGraph task node that executes AdobeMobileLibrary APIs on a background thread.
  • Serves as a delegate to return data back to application scenes.

Public SceneGraph APIs

ADBMobileConnector

Category Method Name Description
Constants
sceneGraphConstants Returns an object containing SceneGraphConstants. Refer to the table above for details.
Debug Logging
setDebugLogging SceneGraph API to set debug logging on the ADBMobile SDK.
getDebugLogging SceneGraph API to get debug logging from the ADBMobile SDK.
For more information refer to the Debug Logging section of the legacy SDK.
Privacy Status / Opt-Out
setPrivacyStatus SceneGraph API to set privacy status on the ADBMobile SDK.
getPrivacyStatus SceneGraph API to get privacy status from the ADBMobile SDK.
For more information, refer to the Opt-Out/Privacy Status section of the legacy SDK.
Analytics
trackState SceneGraph API to track state on the ADBMobile SDK.
trackAction SceneGraph API to track action on the ADBMobile SDK.
trackingIdentifier SceneGraph API to get a tracking identifier from the ADBMobile SDK.
userIdentifier SceneGraph API to get a user identifier from the ADBMobile SDK.
setUserIdentifier SceneGraph API to set the user identifier on the ADBMobile SDK.
getAllIdentifiers SceneGraph API retrieves all user identities known and persisted by the Roku SDK.
For more information refer to the Analytics section of the legacy SDK.
Experience Cloud
visitorSyncIdentifiers SceneGraph API to sync Experience Cloud identifiers on the ADBMobile SDK.
visitorMarketingCloudID SceneGraph API to get Visitor Experience Cloud ID from the ADBMobile SDK.
For more information refer to the Experience Cloud section of the legacy SDK.
Audience Manager
audienceSubmitSignal SceneGraph API to send an audience management signal with trait.
audienceVisitorProfile SceneGraph API to get an audience manager visitor profile from the ADBMobile SDK.
audienceDpid SceneGraph API to get an audience Dpid from the ADBMobile SDK.
audienceDpuuid SceneGraph API to get an audience Dpuuid from the ADBMobile SDK.
audienceSetDpidAndDpuuid SceneGraph API to set audience Dpid and Dpuuid on the ADBMobile SDK.
For more information refer to the Audience Manager section of the legacy SDK.
MediaHeartbeat
mediaTrackLoad SceneGraph API to load video content for MediaHeartbeat tracking.
mediaTrackStart SceneGraph API to start video tracking session using MediaHeartbeat.
mediaTrackUnload SceneGraph API to unload video content from MediaHeartbeat tracking.
mediaTrackPlay SceneGraph API to track playback of video content.
mediaTrackPause SceneGraph API to track paused video content.
mediaTrackComplete SceneGraph API to track playback complete for video content.
mediaTrackError SceneGraph API to track playback errors.
mediaTrackEvent SceneGraph API to track playback events during tracking. For example: Ads, Chapters.
mediaUpdatePlayhead SceneGraph API to send playhead updates to MediaHeartbeat during video tracking.
mediaUpdateQoS SceneGraph API to send QoS updates to MediaHeartbeat during video tracking.
For more information refer to the MediaHeartbeat section of the legacy SDK.

SceneGraphConstants

Constant Name Description
API_RESPONSE Used to retrieve the response object from adbmobileTask node’s adbmobileApiResponse field
DEBUG_LOGGING Used as apiName for getDebugLogging
PRIVACY_STATUS Used as apiName for getPrivacyStatus
TRACKING_IDENTIFIER Used as apiName for trackingIdentifier
USER_IDENTIFIER Used as apiName for userIdentifier
VISITOR_MARKETING_CLOUD_ID Used as apiName for visitorMarketingCloudID
AUDIENCE_VISITOR_PROFILE Used as apiName for audienceVisitorProfile
AUDIENCE_DPID Used as apiName for audienceDpid
AUDIENCE_DPUUID Used as apiName for audienceDpuuid

adbmobileTask Node

Field Type Default Usage
adbmobileApiCall assocarray Invalid Do NOT modify this field or let is be used by the Application. This field is used by the ADBMobile SceneGraphConnector to route API calls via SceneGraph nodes and to fetch responses. Therefore, this key/field is reserved for AdobeMobileSDK for SceneGraph compatibility. Important: Any modifications to this field may result in AdobeMobileSDK functioning incorrectly.
adbmobileApiResponse assocarray Invalid Read-Only All of the APIs executed on AdobeMobileSDK will return responses on this field. Register for a callback to listen for updates to this field in order to receive response objects. Following is the format for the response object:
response = {
  "apiName" : <SceneGraphConstants.
               API_NAME>
  "returnValue : <API_RESPONSE>
}
An instance of this response object will be sent for any API call on AdobeMobileSDK that is expected to return a value as per the API reference guide. For example, an API call for visitorMarketingCloudID() will return the following response object:
response = {
  "apiName" : m.
              adbmobileConstants.
              VISITOR_MARKETING_CLOUD_ID
  "returnValue : "07050x25671x33760x72644x14"
}
OR, response data can be invalid as well:
response = {
  "apiName" : m.
              adbmobileConstants.
              VISITOR_MARKETING_CLOUD_ID
  "returnValue : invalid
}

adbmobile.brs

getADBMobileConnectorInstance

API Signature: ADBMobile().getADBMobileConnectorInstance()
Input: adbmobileTask
Return Type: ADBMobileConnector

sgConstants

API Signature: ADBMobile().sgConstants()
Input: None
Return Type: SceneGraphConstants

NOTE

Refer to the ADBMobileConnector API reference for details.

ADBMobile Constants

 Feature  Constant Name Description  
Versioning version Constant for retreiving AdobeMobileLibrary verison info
Privacy/opt-out PRIVACY_STATUS_OPT_IN Constant for privacy status opted in
PRIVACY_STATUS_OPT_OUT Constant for privacy status opted out
MediaHeartbeat Constants Refer to the constants on this page:

Media Heartbeat Methods.
Use these constants with MediaHeartbeat APIs
Standard Metadata Refer to the constants on this page:

Standard Metadata Parameters.
Use these constants to attach Standard Video/Ad metadata in MediaHeartbeat APIs

Globally defined utility MediaHeartbeat APIs on the legacy AdobeMobileLibrary are accessible as is in the SceneGraph enviromnent because they do not use any Brightscript components that are unavailable in SceneGraph nodes. For more information on these methods, refer to the table below:

Global Methods for MediaHeartbeat

Method Description
adb_media_init_mediainfo This method returns an initialized Media Information object Function adb_media_init_mediainfo(name As String, id As String, length As Double, streamType As String) As Object
adb_media_init_adinfo This method returns initialized Ad Information object Function adb_media_init_adinfo(name As String, id As String, position As Double, length As Double) As Object
adb_media_init_chapterinfo This method returns initialized Chapter Information object. Function adb_media_init_adbreakinfo(name As String, startTime as Double, position as Double) As Object
adb_media_init_adbreakinfo This method returns initialized AdBreak Information object. Function adb_media_init_chapterinfo(name As String, position As Double, length As Double, startTime As Double) As Object
adb_media_init_qosinfo This method returns an initialized QoS Information object. Function adb_media_init_qosinfo(bitrate As Double, startupTime as Double, fps as Double, droppedFrames as Double) As Object

Implementation

  1. Download the Roku Library - Download the latest Roku library.

  2. Set Up Your Development Environment

    1. Copy adbmobile.brs (AdobeMobileLibrary) into your pkg:/source/ directory.

    2. For Scene Graph support, copy adbmobileTask.brs and adbMobileTask.xml into your pkg:/components/ directory.

  3. Initialize

    1. Import adbmobile.brs into your Scene.

      <script type="text/brightscript" uri="pkg:/source/adbmobile.brs" />
      
    2. Create an instance of adbmobileTask node into your Scene.

      m.adbmobileTask = createObject("roSGNode", "adbmobileTask")
      
    3. Get an instance of adbmobile connector for SceneGraph using the adbmobileTask instance.

      m.adbmobile = ADBMobile().getADBMobileConnectorInstance(m.adbmobileTask)
      
    4. Get adbmobile SG constants.

      m.adbmobileConstants = m.adbmobile.sceneGraphConstants()
      
    5. Register a callback for receiving response object for all AdbMobile API calls.

      m.adbmobileTask.ObserveField(m.adbmobileConstants.API_RESPONSE,
                                   "onAdbmobileApiResponse")
      
      ' Sample implementation of the callback
      ' Listen for all the constants for which API calls are made on the SDK
      function onAdbmobileApiResponse() as void
          responseObject = m.adbmobileTask[m.adbmobileConstants.API_RESPONSE]
      
          if responseObject <> invalid
              methodName = responseObject.apiName
              retVal = responseObject.returnValue
      
              if methodName = m.adbmobileConstants.DEBUG_LOGGING
                  if retVal
                      print "API Response: DEBUG LOGGING: " + "True"
                  else
                      print "API Response: DEBUG LOGGING: " + "False"
                  endif
              else if methodName = m.adbmobileConstants.PRIVACY_STATUS
                  print "API Response: PRIVACY STATUS: " + retVal
              else if methodName = m.adbmobileConstants.TRACKING_IDENTIFIER
                  if retVal <> invalid
                      print "API Response: TRACKING IDENTIFIER: " + retVal
                  else
                      print "API Response: TRACKING IDENTIFIER: " + "invalid"
                  endif
              else if methodName = m.adbmobileConstants.USER_IDENTIFIER
                  if retVal <> invalid
                      print "API Response: USER IDENTIFIER: " + retVal
                  else
                      print "API Response: USER IDENTIFIER: " + "invalid"
                  endif
              else if methodName = m.adbmobileConstants.VISITOR_MARKETING_CLOUD_ID
                  if retVal <> invalid
                      print "API Response: MCID: " + retVal
                  else
                      print "API Response: MCID: " + "invalid"
                  endif
              else if methodName = m.adbmobileConstants.AUDIENCE_DPID
                  if retVal <> invalid
                      print "API Response: AUDIENCE DPID: " + retVal
                  else
                      print "API Response: AUDIENCE DPID: " + "invalid"
                  endif
              else if methodName = m.adbmobileConstants.AUDIENCE_DPUUID
                  if retVal <> invalid
                      print "API Response: AUDIENCE DPUUID: " + retVal
                  else
                      print "API Response: AUDIENCE DPUUID: " + "invalid"
                  endif
              else if methodName = m.adbmobileConstants.AUDIENCE_VISITOR_PROFILE
                  if retVal <> invalid
                      print "API Response: AUDIENCE VISITOR PROFILE: Valid Object"
                  else
                      print "API Response: AUDIENCE VISITOR PROFILE: " + "invalid"
                  endif
              endif
          endif
      end function
      
      

Sample Implementation

Sample API calls on Legacy SDK

'get an instance of SDK
m.adbmobile = ADBMobile()

'execute setter APIs
m.adbmobile.setDebugLogging(true)

'execute getter APIs
debugLogging = m.adbmobile.getDebugLogging()

Sample API calls on SG SDK

'create adbmobileTask instance
m.adbmobileTask = createObject("roSGNode", "adbmobileTask")

'get an instance of SDK using task instance
m.adbmobile =
  ADBMobile().getADBMobileConnectorInstace(m.adbmobileTask)
m.adbmobileConstants = m.adbmobile.sceneGraphConstants()
'execute setter APIs
m.adbmobile.setDebugLogging(true)

'execute getter APIs
m.adbmobileTask.ObserverField(m.adbConstants.API_RESPONSE,
                              "onAdbmobileApiResponse")
m.adbmobile.getDebugLogging()

'listen for return data in registered callbacks
function onAdbmobileApiResponse() as void
    responseObject = m.adbmobileTask[m.adbmobileConstants.API_RESPONSE]

        if responseObject <> invalid
            methodName = responseObject.apiName
            retVal = responseObject.returnValue

        if methodName = m.adbmobileConstants.DEBUG_LOGGING
            if retVal
                print "API Response: DEBUG LOGGING: " + "True"
            else
                print "API Response: DEBUG LOGGING: " + "False"
         endif
    endif
end function

On this page