OpenPass SDK for Roku TV quickstart guide

This quickstart guide helps you integrate OpenPass directly with your Roku channel.

IMPORTANT: Before installation, be sure to sign up for an OpenPass account to get a client ID.

Follow these steps to integrate OpenPass with Roku:

  1. Install the SDK.
  2. Set up the Roku development environment.
  3. Configure the device authorization flow client.
  4. Create task nodes.
  5. Launch the device authorization flow.
  6. Handle an expired device code.
  7. Clean up the device authorization flow.

The following sections detail each step.

1. Install the SDK

Install the Roku SDK package using ROPM:

 ropm install @openpass/openpass-roku-sdk

2. Set up the Roku development environment

To set up the development environment, you need to use a Roku device and follow the instructions in the following Roku guides:

  1. Have your Roku device at hand. You will use it to enter a secret code for testing channel applications in the developer application installer.
  2. Sign up for a Roku account.
  3. Enroll in the Roku developer program.
  4. Follow the instructions in the developer setup guide.

3. Configure the device authorization flow client

To customize the user experience for OpenPass device authorization, configure the device authorization flow client.

NOTE: This client provides the user code and URL, but you will handle the authentication response through the Roku channel to sign in the user.

To configure the client, provide your OpenPass client ID and initialized OpenPass manager, as shown in the following code example.

  sub AuthorizeDevice()
    ' Your client Id
    clientId = "YOUR_CLIENT_ID"

    ' Init client
    m.op = openpass_openpassrokusdk_OpenPass()

    ' optionalParams = { polling_timeout: 200}

    optionalParams = { enable_logging: true }
    m.op.Init(clientId, AuthCallback, optionalParams)

    ' Start sign in process
    m.op.SignIn()
  end sub

4. Create task nodes

To run the device authorization flow, follow the instructions in Roku Developers Task to create two SceneGraph control nodes for handling tasks simultaneously. For an example, see the following XML template file and script for authorize-device tasks.

tasks/AuthorizeDeviceTask.xml

This XML template file defines how OpenPass device authorization is handled in a Roku channel.

<?xml version="1.0" encoding="utf-8"?>

<?xml version="1.0" encoding="utf-8"?>

<component name="AuthorizeDeviceTask" extends="Task">
  <interface>
    <field id="authDevice" type="node" />
    <field id="authorizedDevice" type="node" />
    <field id="signedOut" type="node" />
  </interface>

  <!-- Import the library -->
  <script type="text/brightscript"
    uri="pkg:/source/roku_modules/openpass_openpassrokusdk/dist/OpenPass.brs" />

  <script type="text/brightscript" uri="AuthorizeDeviceTask.brs" />
</component>

tasks/AuthorizeDeviceTask.brs

This script manages the device authorization process in OpenPass.

  sub Init()
    m.top.functionName = "AuthorizeDevice"
  end sub

  sub AuthorizeDevice()
    ' Your client ID
    clientId = "YOUR_CLIENT_ID"

    ' Init client
    m.op = openpass_openpassrokusdk_OpenPass()
    optionalParams = { enable_logging: true }
    m.op.Init(clientId, AuthCallback, optionalParams)

    ' Start sign in process
    m.op.SignIn()

    ' m.op.SignOut()
  end sub

  sub AuthCallback(state, data)

    print state
    _states = {
      "SignedIn": 0,
      "SignedOut": 1,
      "Error": 2,
      "Loading": 3,
      "Polling": 4,
      "Refreshable": 5 ' Signed in but needs to refresh
    }

    if state = _states.SignedIn
      HandleSignedIn(data)
    else if state = _states.Polling
      HandlePolling(data)
    ' else if state = _states.Error
    '   HandleSignOut()
    end if

  end sub

  sub HandleSignedIn(data)
    authorizedDevice = CreateObject("roSGNode", "ContentNode")
    authorizedDevice.addFields(data["device_token_success"])
    m.top.authorizedDevice = authorizedDevice
  end sub

  sub HandlePolling(data)
    authDevice = CreateObject("roSGNode", "ContentNode")
    authDevice.addFields(data["authorize_device_success"])
    m.top.authDevice =authDevice
  end sub

5. Launch the device authorization flow

To launch the device authorization flow, follow these steps:

  1. Request a new device code from the flow. The code status is provided by the flow or through a configured listener.
  2. When a new device code is available, display it to the user with instructions to sign in through a mobile device or computer. A successful sign-in will share the device code and access tokens with your Roku channel.
  3. If you receive an error message, use Error code reference to troubleshoot the problem.

TIP: When displaying the user code and verification URI, we recommend generating a QR code for the user. This makes it easier for them to navigate to the linked website through their computer or smartphone.

The following code example requests a new device code.

sub DeviceAuthorization()
  m.authTask = CreateObject("roSGNode", "AuthorizeDeviceTask")
  m.authTask.ObserveField("authDevice", "OnAuthDeviceCompleted")
  m.authTask.ObserveField("authorizedDevice", "OnAuthenticateTaskCompleted")
  m.authTask.ObserveField("signedOut", "OnSignedOutComplete")

  m.authTask.control = "run"
end sub

' Get device token
sub OnAuthDeviceCompleted()
  print "authorize device"
  print m.authTask.authDevice
  m.SigningScreen.authDevice = m.authTask.authDevice
end sub

' Get Authorized information
sub OnAuthenticateTaskCompleted()
  print "authorized"
  print m.authTask.authorizedDevice
  m.SigningScreen.authorizedDevice = m.authTask.authorizedDevice
  ' Do what you need with the response
end sub

sub OnSignedOutComplete()
  print "signedOut"
end sub

6. Handle an expired device code

The device code has an expiration time when it is fetched. When that time limit is reached, the code becomes invalid. If this happens, the application notifies the user with the option to refresh the code and create a new device authorization flow client before launching again.

7. Clean up the device authorization flow

When you are finished with the device authorization flow client, even if it was successful, call signOut() on it to ensure resources are cleaned up.

Additional resources

For more information, see the following pages: