Documentation Analytics Streaming Media Collection Guide

Set up Mobile SDK v2.x for Roku set-up-roku

Last update: Wed Jul 31 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Topics:
Media Analytics

CREATED FOR:

User
Admin
Developer

Prerequisites roku-prerequisites

Obtain valid configuration parameters for the Streaming Media Collection Add-on

These parameters can be obtained from an Adobe representative after you set up your Adobe Streaming Media Collection Add-on account.
Include the following APIs in your media player
- An API to subscribe to player events - The Media SDK requires that you call a set of simple APIs when events occur in your player.
- An API that provides player information - This information includes details such as the media name and the play head position.

Roku SDK 2.x for Experience Cloud Solutions lets you measure Roku applications written in BrightScript, leverage and collect audience data through audience management, and measure video engagement through Video events.

Mobile Library / SDK Implementation

Add your downloaded Roku library to your project.

The AdobeMobileLibrary-2.*-Roku.zip download file consists of the following software components:
- adbmobile.brs: This library file will be included in your Roku app source folder.
- ADBMobileConfig.json: This SDK configuration file is customized for your app.

Add the library file and JSON config file to your project source.

The JSON that is used to configure Adobe Mobile has an exclusive key for media analytics called mediaHeartbeat. This is where the configuration parameters for media analytics belong.

note tip
TIP
A sample `ADBMobileConfig` JSON file is provided with the package. Contact your Adobe representatives for the settings.

For example:

code language-none

code language-none
{ "version":"1.0", "analytics":{ "rsids":"", "server":"", "charset":"UTF-8", "ssl":true, "offlineEnabled":false, "lifecycleTimeout":30, "batchLimit":50, "privacyDefault":"optedin", "poi":[ ] }, "marketingCloud":{ "org":"" }, "target":{ "clientCode":"", "timeout":5 }, "audienceManager":{ "server":"" }, "acquisition":{ "server":"example.com", "appid":"sample-app-id" }, "mediaHeartbeat":{ "server":"example.com", "publisher":"sample-publisher", "channel":"sample-channel", "ssl":true, "ovp":"sample-ovp", "sdkVersion":"sample-sdk", "playerName":"roku" } }

{
  "version":"1.0",
  "analytics":{
    "rsids":"",
    "server":"",
    "charset":"UTF-8",
    "ssl":true,
    "offlineEnabled":false,
    "lifecycleTimeout":30,
    "batchLimit":50,
    "privacyDefault":"optedin",
    "poi":[ ]
},
"marketingCloud":{
  "org":""
},
"target":{
  "clientCode":"",
  "timeout":5
},
"audienceManager":{
  "server":""
},
"acquisition":{
  "server":"example.com",
  "appid":"sample-app-id"
},

"mediaHeartbeat":{
   "server":"example.com",
   "publisher":"sample-publisher",
   "channel":"sample-channel",
   "ssl":true,
   "ovp":"sample-ovp",
   "sdkVersion":"sample-sdk",
   "playerName":"roku"
   }
}

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2
Config Parameter	Description
`server`	String that represents the URL of the tracking endpoint on the backend.
`publisher`	String that represents the content publisher unique identifier.
`channel`	String that represents the name of the content distribution channel.
`ssl`	Boolean that represents whether SSL should be used for tracking calls.
`ovp`	String that represents the name of the video player provider.
`sdkversion`	String that represents the current version of the app/SDK.
`playerName`	String that represents the name of the player.

note important
IMPORTANT
If `mediaHeartbeat` is incorrectly configured, the media module (VHL) enters an error state and will stop sending tracking calls.

Configure Experience Cloud Visitor ID.

The Experience Cloud Visitor ID service provides a universal Visitor ID across Experience Cloud solutions. The Visitor ID service is required by Video events and other Marketing Cloud integrations.

Verify that your ADBMobileConfig config contains your marketingCloud organization ID.

code language-none
`"marketingCloud": { "org": "YOUR-MCORG-ID" }`

Experience Cloud organization IDs uniquely identify each client company in the Adobe Marketing Cloud and appear similar to the following value: 016D5C175213CCA80A490D05@AdobeOrg.

note important
IMPORTANT
Ensure that you include `@AdobeOrg`.

After the configuration is complete, an Experience Cloud Visitor ID is generated and is included on all hits. Other Visitor IDs, such as custom and automatically-generated, continue to be sent with each hit.

Experience Cloud Visitor ID Service Methods

note tip
TIP
Experience Cloud Visitor ID methods are prefixed with `visitor`.

table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
Method	Description
`visitorMarketingCloudID`	Retrieves the Experience Cloud visitor ID from the visitor ID service. `ADBMobile().visitorMarketingCloudID()`
`visitorSyncIdentifiers`	With the Experience Cloud Visitor ID, you can set additional customer IDs that can be associated with each visitor. The Visitor API accepts multiple customer IDs for the same visitor and a customer type identifier to separate the scope of the different customer IDs. This method corresponds to `setCustomerIDs`. For example: `identifiers={}` `identifiers["idType"]="idValue"` `ADBMobile().visitorSyncIdentifiers(identifiers)`
`setAdvertisingIdentifier`	Used to set the Roku ID for Advertising (RIDA) on the SDK. For example: `ADBMobile().setAdvertisingIdentifier(` `"<sample_roku_identifier_for_advertising>")` Get the Roku ID for Advertising (RIDA) using the Roku SDK getRIDA() API.
`getAllIdentifiers`	Returns a list of all the identifiers stored by the SDK including Analytics, Visitor, Audience Manager and custom Identifiers. `identifiers = ADBMobile().getAllIdentifiers()`

Additional Public APIs

DebugLogging

table 0-row-2 1-row-2 2-row-2
Method	Description
`setDebugLogging`	Used to enable or disable debug logging for the SDK. `ADBMobile().setDebugLogging(true)`
`getDebugLogging`	Returns true if debug logging is enabled. `isDebugLoggingEnabled = ADBMobile().getDebugLogging()`

PrivacyStatus

table 0-row-2 1-row-2 2-row-2
Constant	Description
`PRIVACY_STATUS_OPT_IN`	Constant to be passed while calling setPrivacyStatus to opt in. `optInString = ADBMobile().PRIVACY_STATUS_OPT_IN`
`PRIVACY_STATUS_OPT_OUT`	Constant to be passed while calling setPrivacyStatus to opt out. `optOutString = ADBMobile().PRIVACY_STATUS_OPT_OUT`

table 0-row-2 1-row-2 2-row-2
Method	Description
`setPrivacyStatus`	Sets the privacy status on the SDK. `ADBMobile().setPrivacyStatus(ADBMobile().PRIVACY_STATUS_OPT_IN)`
`getPrivacyStatus`	Gets the current privacy status set on the SDK. `privacyStatus = ADBMobile().getPrivacyStatus()`

note important
IMPORTANT
Ensure that you call `processMessages` and `processMediaMessages` function in the main event loop every 250 ms to ensure that the SDK sends out the pings properly.

table 0-row-2 1-row-2 2-row-2
Method	Description
`processMessages`	Responsible to pass the Analytics events to the SDK to be handled. `ADBMobile().processMessages()`
`processMediaMessages`	Responsible to pass the Media events to the SDK to be handled. `ADBMobile().processMediaMessages()`

recommendation-more-help

c8eee520-cef5-4f8c-a38a-d4952cfae4eb