Installing Iterable's Roku SDK

Before you can send messages from Iterable to your users' Roku devices, you'll need to install Iterable's Roku SDK in your channel's source code.

# In this article

# Step 1: Clone the SDK repository and zip up the SDK

To download the SDK:

1. Clone the iterable-roku-sdk repository: https://github.com/Iterable/iterable-roku-sdk/.

2. In your local clone of the repository, navigate to the source/itbl-sdk directory.

3. Zip up the contents of this directory (not the directory itself, but everything it contains).

4. Rename the zip file itbl-sdk.zip.

# Step 2: Add the SDK to your channel

Now, add the SDK to your channel:

1. Copy itbl-sdk.zip into your channel's source folder.

2. Copy itblHelper.brs from the source folder of your local clone of the SDK's repository into your channel's source folder. This file contains four helper methods that make it easy to work with the SDK.

# Step 3: Set ui_resolution

In your channel's manifest file, set ui_resolution to fhd:

ui_resolutions=fhd

# Step 4: Add custom fonts

For a font, Iterable's Roku SDK by default uses Source Sans Pro. To use custom. fonts, include .ttf files in the source/fonts directory of your channel.

When creating Roku messages in Iterable, you can specify custom fonts for the title, body, and buttons. When specifying fonts, you'll need to reference the same font files included in your channel's source code.

# Step 5: Configure your scene XML

Now, configure the XML file associated with your channel's scene.

• In the <component> node, add a reference to itbleHelper.brs.

• In the <interface> node, add:

  • A field with id set to ItblClickEvent, of type assocArray.
  • A field with id set to ItblCloseEvent, of type assocArray.
  • A function with name set to ItblOnApplicationLoaded.

For example, a scene called MainScene might look like this:

<component name="MainScene" extends="Scene">
   <script type="text/brightscript" uri="pkg:/components/scene/MainScene.brs"/>
   <script type="text/brightscript" uri="pkg:/source/itblHelper.brs"/>
   <interface>
      <!-- This event is triggered when a user clicks on any button on an in-app message. -->
       <field id="ItblClickEvent" type="assocArray" alwaysNotify="true" OnChange="OnItblClickEvent"/>
       <!-- This event triggered when the user closes an in-app message.-->
       <field id="ItblCloseEvent" type="assocArray" alwaysNotify="true" OnChange="OnItblCloseEvent"/>
       <!-- To show an in-app message, this function can be called from any component or page. -->
       <function name="ItblOnApplicationLoaded" />
   </interface>
   ...

# Step 6: Get a Web API key from Iterable

In Iterable, create a Web API key. The SDK uses this API key to fetch messages from Iterable.

# Step 7: Initialize the SDK

To initialize the SDK, call the SDK's ItblInitializeSDK method as you initialize your channel's scene. For example:

ItblInitializeSDK("...", "https://api.iterable.com", "com.example.my-roku-app")

Pass in three values:

• A web API key (preferably JWT-enabled)
• https://api.iterable.com (the root URL for Iterable's API)
• The package name of your Roku channel (the same value you used when adding your channel to Iterable)

# Step 8: Fetch a JWT token

If you're using a JWT-enabled API key, you'll need to fetch, from your server, a JWT token for the current user. To make sure you're using a valid token, fetch a new one each time your channel opens.

For more information about JWT-enabled API keys and JWT tokens, see JWT-Enabled API Keys.

# Step 9: Identify the user

Next, tell the SDK the identity of the user for whom you'd like to fetch and display an in-app message. To do this, call ItblSetEmailOrUserId and pass in either a valid email address or user ID (not both).

When using a JWT-enabled API key, you'll also need to include the JWT token you fetched in the previous step.

For example:

status = ItblSetEmailOrUserId({"email":"user@example.com", "token": jwtToken})

or

status = ItblSetEmailOrUserId({"userId":"testUser1234567"})

To learn more about ItblSetEmailOrUserId, see Iterable's Roku SDK: Reference.

# Step 10: Display a message when your channel loads

After you've initialized the SDK and identified a user, and the SDK has fetched an in-app message, tell the SDK to display the message by calling ItblOnApplicationLoaded:

applicationLoadStatus = ItblOnApplicationLoaded()

To learn more about ItblOnApplicationLoaded, see Iterable's Roku SDK: Reference.

# Step 11: Handle click events and deep linking

To handle button click events, add the following method to the script file associated with your scene:

function OnItblClickEvent(event as dynamic)
    clickEventData = event.getData()
    print "OnItblClickEvent deeplink: "clickEventData.buttonDeepLink
end function

Adjust the implementation of this method as needed. The above implementation just logs a click event:

OnItblClickEvent : <Component: roAssociativeArray> =
{
    action: "link"
    buttonDeeplink: "https://www.example.com/item-a"
    buttonText: "Button #1: Show A"
    isClick: true
    message: "https://www.example.com/item-a"
}

To follow a deep link, use the value of buttonDeepLink to determine where to navigate. For example (only a sample, your code will differ):

if Instr(0, clickEventData.buttonDeeplink, "item-a")
   ...
else if Instr(0, clickEventData.buttonDeeplink, "item-b")
   ...
end if

# Step 12: Handle close events

To handle close events, which fire when the in-app message closes, add the following method to the script file associated with your scene:

function OnItblCloseEvent(event as dynamic)
    closeDialogData = event.getData()
    print "OnItblDialogClose: "closeDialogData
end function

Adjust the implementation of this method as needed. The above implementation logs a close event. For example:

OnItblDialogClose : <Component: roAssociativeArray> =
{
    BackClick: false
    ButtonClick: true
}

# Step 13: Track custom events

Iterable's Roku SDK automatically tracks system events. To learn how to track custom events with Iterable's Roku SDK, read Tracking Events with Iterable's Roku SDK.