Iterable's Roku SDK: Reference

When installing Iterable's Roku SDK, you'll add the SDK's itblHelpers.brs file to your channel's source code. This file contains various methods, four of which represent the SDK's public interface. This article describes these methods.

Methods that exist in itblHelpers.brs but aren't described below should be treated as internal SDK methods (you shouldn't usually have a need to call them manually).

# In this article

# ItblInitializeSDK

ItblInitializeSDK initializes Iterable's Roku SDK with:

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

Example call:

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

# ItblSetEmailOrUserId

ItblSetEmailOrUserId sets the email or userId to use when fetching in-app messages and tracking events.

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"})

ItblSetEmailOrUserId returns an object with two fields:

• status - A string set to one of the following values:

  • waiting - The method was called before the SDK was fully initialized. No need to call the method again, though, since execution continues after the SDK completes its initialization.

  • failed - The specified email or userId is invalid, or you provided both values.

  • started - Success. The email or userId has been set, and the SDK can attempt to fetch an in-app message from the server. However, it does not display the message until you call ItblOnApplicationLoaded.

• message - A string that describes the status.

To fetch an in-app message, this method calls GET /api/inApp/getPriorityMessage, which returns a single in-app message. To determine which message to return, Iterable sorts the user's waiting messages by priority, then by send time.

# ItblOnApplicationLoaded

ItblOnApplicationLoaded loads the SDK, and then checks for and displays an in-app message.

applicationLoadStatus = ItblOnApplicationLoaded()

ItblOnApplicationLoaded returns an object with three fields:

• status - A string set to one of the following values:

  • NOT_LOADED - The SDK is still loading. Assuming you've already set an email or userId by calling ItblSetEmailOrUserId, wait a short delay and call ItblOnApplicationLoaded again.

  • initializing - The SDK is still initializing. After a short delay, call `ItblOnApplicationLoaded again.

  • loading - The SDK is waiting for messages to come back from the server. After a short delay, call ItblOnApplicationLoaded again.

  • waiting - The SDK still needs an email or userId. To set one, call ItblSetEmailOrUserId. Then, call ItblOnApplicationLoaded again.

  • loaded - The SDK attempted to fetch a message. If there's a message to display, success is true. Otherwise, success is false.

  • closed - An in-app message has already been shown this session. You cannot display another.

  • failed - There was an error loading the SDK, there was a problem with your JWT token, or an API call failed.

• success - A boolean value:

  • true - The SDK has a message for the user and will display it.
  • false - The SDK cannot display a message. For more detail, inspect status. If success is false and status is loaded, there are no messages to display for the specified user.

• message - A description of the status.

scene = m.top.getScene()
applicationLoadStatus = scene.CallFunc("ItblOnApplicationLoaded")

# ItblCustomEventTrack

ItblCustomEventTrack saves a custom event to the user profile of the user currently signed in to the channel. Accepts the name of an event and a JSON object of contextual metadata to store with it.

ItblCustomEventTrack("customEventName", {"field":"value"})