Roku Basic Integration

Prerequisites

In order to implement the Branch SDK into your Roku app, you need to have/complete the following:

Create a Branch Dashboard.
- Obtain your Branch Key.
Create a Roku Account.
- Purchase a Roku TV or Streaming Device
- Enroll in Roku's Developer Program

1. Set Up Development Environment

The first step you should take is to set up your development environment for Roku.

Enable Developer Mode on your Roku Device
Get your device's IP Address and set a pasword
Use the local IP address in your browser to access the developer workstation
- Log in using the credentials you set

For a detailed guide on this, visit Roku's Developer Docs here.

2. Install Branch

You must download the Branch Roku SDK and retrieve the following library files:

a. Create a new folder called tasks in the components folder of your application.
b. Copy both the BranchSdkTask.xml and BranchSdkTask.brs files into your project's new
tasks folder.
c. Create a new folder called libs in the source folder of your application.
d. Copy the BranchSdkLibrary.brs file from the Branch repo into your project's new libs folder

In the end, your application's folder structure should look like this:

 └──  components
 │   └── tasks
 │       └──  BranchSdkTask.brs
 │       └── BranchSdkTask.xml
 └── source
       └── libs
           └── BranchSdkLibrary.brs

3. Configure Branch

In the Main.brs file of your project (the entry point of the SceneGraph application). add ConfigureBranchSdk(screen) using your an roSGScreen object.

Be sure to use your Branch Key obtained from the prerequisites.

sub Main(args as dynamic)
    screen = CreateObject("roSGScreen")
    ' Set Branch SDK configurations'
    ConfigureBranchSdk(screen)

    ' Other screen configs below'
end sub
          
sub ConfigureBranchSdk(screen as dynamic)
    options = {}
    options.branchKey = "key_live_XXXX"
    options.logLevel = BranchSdkConstants().LOG_LEVEL.DEBUG
    options.environment = BranchSdkConstants().ENVIRONMENT.PRODUCTION

    ' Set Branch SDK configuration parameter as required'
    screen.getGlobalNode().addFields({branchSdkConfig: options})
end sub

You can view an example Main.brs here.

4. Initialize Branch

4.1 Add the Branch SDK Script

Open your main Scene file (ex. MainScene.xml) in your components folder, and add a new script file path for BranchSdkLibrary.brs

<?xml version="1.0" encoding="utf-8" ?>
<component name="MainScene" extends="Scene">
    <script type="text/brightscript" uri="pkg:/components/MainScene.brs"/>
    <!-- Replace with correct path if necessary -->
    <script type="text/brightscript" uri="pkg:/source/libs/BranchSdkLibrary.brs"/>
    <!-- Other Scripts Below -->
</component>

You can view an example MainScene.xml here.

4.2 Create & Initialize the Branch Instance

Next, open your main Scene's .brs file (ex. MainScene.brs), and create & initialize the Branch instance inside sub init() with a callback. This will initialise an app open event.

sub init()
  ' Other init Configs...'

  ' BRANCH SDK INTEGRATION - Create Instance'
  m.branchSdkObj = CreateBranchSdkForSceneGraphApp()

  if (m.branchSdkObj = invalid) then
    ShowMessageDialog("Failed to initialize Branch SDK!")
  else
    ' BRANCH SDK INTEGRATION - Initialize Branch'
    m.branchSdkObj.initSession(m.global.launchArgs, "OnInitSessionCallbackFunc")
  end if
    
  ' Other init Configs...'
end sub


function OnInitSessionCallbackFunc(event as object) as void
  data = event.GetData()
  print "OnInitSessionCallbackFunc: " data
    
  if (data <> invalid) then
    m.lSessionApiResultDetails.text = FormatJson(data)
  else
    m.lSessionApiResultDetails.text = "initSession API response received!"
  end if
    
  message = "API Succeeded!"
  if (data.error <> invalid)
    message = "API Error!"
  else
    print "Branch initSession details: " + message
  end if
end function

You can view an example MainScene.brs here.

5. Configure Deep Linking

When your Branch session is initialized, you'll want to configure your deep linking routing logic through a new sub method and handled through a callback function.

There are two primary ways in which links can trigger the Roku app to respond /launch/{channel} and /input. Here are curls that indicate the format of these links, which you can modify and use for testing:

curl -d '' 'http://ROKU_LOCAL_IP:8060/launch/dev?contentId=1234&mediaType=movie'

curl -d '' 'http://ROKU_LOCAL_IP:8060/input?contentId=1234&mediaType=movie'

In both cases, please send up the data (contentId, mediaType, and any other query parameters) to Branch through the handleInput(...) method.

📘
Deep Linking Format
For proper deep linking, please make sure that you are using a correct format, ex. contentId=1234&mediaType=movie

For a detailed guide on deep link routing please refer to Roku's dev docs on deep linking.
Roku also provides a useful deep link testing tool.

sub init()
  ' After Branch is initialized...'
  HandleInput_Clicked()
end sub

sub HandleInput_Clicked()
  if (m.branchSdkObj = invalid) then
    print "Branch SDK is not initialized!"
    return
  end if

  print "Calling Branch HandleInput API"
  print "m.global.launchArgs : " m.global.launchArgs
  if (m.global.launchArgs <> invalid) then
    ' BRANCH SDK INTEGRATION - Call API'
    m.branchSdkObj.handleInput(m.global.launchArgs, "OnHandleInputCallbackFunc")
  else
    print "Please provide deep linking arguments!"
  end if
end sub
    
function OnHandleInputCallbackFunc(event as object) as void
  data = event.GetData()
  print "OnHandleInputCallbackFunc: " data
    
  m.global.launchArgs = invalid
  message = "API Succeeded!"

  if (data.error <> invalid)
    message = "API Error!"
  end if
    print "handleInput: " + message
end function

6. Track Events

You will want to start tracking events in order for Branch to attribute conversions made on your application to campaigns.

function onKeyEvent(key as String, press as Boolean) as Boolean
  if press then
    if key = "play" then
      tmr = timer.start()
      m.branchSdkObj.logEvent("Video Stream", "Mandalorian-S2-EP5", "", "", 0, "OnLogEventVideoView")
      if key = "back" then
        timeSpentViewingMin = tmr.stop().toMin()
        m.branchSdkObj.logEvent("TSV(MIN)", "Mandalorian-S2-EP5", "", "", timeSpentViewingMin, "OnLogEventTSVMin")
      end if
    end if
  end if
end function

sub LogEventPurchase_Clicked()
    if (m.branchSdkObj = invalid) then
        ShowMessageDialog("Branch SDK is not initialized!")
        return
    end if

    print "Calling Branch LogEvent Standard API"
    ' BRANCH SDK INTEGRATION - Call API'
    m.branchSdkObj.logEvent(BranchSdkConstants().EVENT_TYPE.PURCHASE, "My First Purchase as customer_event_alias", "transaction_id", "INR", 99.99, "OnLogEventPurchaseCallbackFunc")
end sub

function OnLogEventPurchaseCallbackFunc(event as object) as void
    data = event.GetData()
    print "OnLogEventPurchaseCallbackFunc: " data
    message = "API Succeeded!"
    if (data.error <> invalid)
        message = "API Error!"
    end if
    ShowMessageDialog("logEvent Purchase" + " " + message)
end function

sub LogEventCustom_Clicked()
    if (m.branchSdkObj = invalid) then
        ShowMessageDialog("Branch SDK is not initialized!")
        return
    end if

    print "Calling Branch LogEvent Custom API"
    ' BRANCH SDK INTEGRATION - Call API'
    m.branchSdkObj.logEvent("Custom Event Name", "Custom Event Customer_event_alias", "transaction_id", "INR", 1199.99, "OnLogEventCustomCallbackFunc")
end sub

Be sure to follow the event tracking guide to determine which events you can track.

7. Verify Data in Branch

Once the above steps are complete, you are now ready to verify that conversions are being sent to Branch. To verify data is being sent to Branch Branch Dashboard's Liveview and apply the following filter:

Filter	Operator	Value
os	equals	ROKU

Additionally, you will see conversions within the Branch Dashboard reports.

Filters

Prerequisites

1. Set Up Development Environment

2. Install Branch

3. Configure Branch

4. Initialize Branch

4.1 Add the Branch SDK Script

4.2 Create & Initialize the Branch Instance

5. Configure Deep Linking

📘Deep Linking Format

6. Track Events

7. Verify Data in Branch

📘
Deep Linking Format