OpenPass SDK for Android TV/Fire TV quickstart guide

This quickstart guide helps you integrate OpenPass directly with your Android-based TV application, such as Fire TV.

To improve the user experience, we've included options for smart TVs where the user can go to a link on their computer or smartphone to enter a code for authorizing the device.

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.

Follow these steps to install the SDK:

1. Initialize the OpenPass manager.
2. Add the Sign In with OpenPass button by following the instructions for the device authorization flow for the Android-based TV platform.

The following sections detail each step.

Initialize the OpenPass Manager

Initialize the OpenPass manager before using it in your application. You can do this using one of these options:

• Provide access to an Android Context. You should use this option because it uses its own default network session.
• Use a custom network session.

Provide access to Android context

When initializing your main application instance, provide access to an Android Context. When you initialize the OpenPassManager class using this option, there's no need to provide a custom implementation because it uses its own default network session. See the following code example.

class DevApplication : Application() {
   override fun onCreate() {
      super.onCreate()

      OpenPassManager.init(this)
   }
}

Use a custom network session

Configure the OpenPass manager with a custom network-session implementation to control network access. When you initialize the OpenPassManager class with a custom network session, you can wrap HTTP clients like OkHttp.

class DevApplication : Application() {
   override fun onCreate() {
      super.onCreate()

      OpenPassManager.init(this, OkNetworkSession())
   }
}

After initialization, you can access the OpenPass manager instance through the getInstance method, as shown in the following example:

OpenPassManager.getInstance()

Add sign-in button click handler

The sign-in process uses a device authorization flow for TV. It provides the user a code that allows them to use another device, like a smartphone, to complete the steps for authentication before returning to the application. To improve the user experience, smart TVs and similar input-constrained devices ask the user to go to a link on their computer or smartphone to enter a code for authorizing the device.

There are two options for the device authorization flow. Choose from the following table the one that best fits your situation.

Each option has two different paths:

• The device requesting authorization
• The browser. The browser flow path, where a device authorization code is bound to the session in the browser, occurs in parallel to the device flow path.

For more information, see Device Authorization Flow in Auth0 Docs.

TV sign-in flow client

This simple integration delegates the sign-in responsibility to the OpenPass SDK. It does the following:

1. Launch its own Android activity.
2. Present its own user experience.
3. Return the results of the interaction to the calling application.

Set up this flow by providing your OpenPass client identifier and initialized OpenPass manager.

IMPORTANT: To obtain the results in step 3, the calling application must create the flow before the activity is created. For details, see Get a result from an activity in Android for Developers.

The following code example shows how a single instance of the TV sign-in flow client is created. Because the activity-result registry must be used before the lifecycle owner is created, it is reused for all sign-in attempts.

tvClient = TvSignInFlowClient(clientId, manager, registry, owner)
tvClient?.launchSignIn(context)

If the flow is successful, you can obtain OpenPass tokens through the OpenPass manager.

Device authorization flow client

This integration provides the developer the raw information to build a custom user experience around device authorization. It provides the user code and URL the user needs to navigate to but leaves the responsibility of displaying them to the consuming application.

To configure this client, provide your OpenPass client identifier and initialized OpenPass manager, as shown in this code example.

client = DeviceAuthorizationFlowClient(clientId, manager)
client?.let { client ->
   // ...
}

When the client is configured, do the following:

1. Launch the device authorization flow.
2. Handle an expired device code.
3. Clean up the flow.

The following sections detail each step.

Launch the Device Authorization Flow

To launch the flow, follow these steps:

1. Request a new device code from the flow.
2. Observe the state provided by the flow or configured through the supported listener.
3. When a new device code is provided, display the relevant information to the user and ask them to sign in through a mobile or computer device.
4. Wait for a successful sign-in or failure message.

The following code example requests a new device code. A successful result will share the device code and access tokens.

client = DeviceAuthorizationFlowClient(clientId, manager)
client?.let { client ->
   // Request a new device code.
   client.fetchDeviceCode()

   // Observe the results of the flow.
   client.state.collect { state ->
      when (state) {
         is DeviceCodeAvailable -> _viewState.emit(AuthCodeAvailableState(state.deviceCode))
         is DeviceCodeExpired -> _viewState.emit(AuthCodeExpiredState)
         is Error -> _viewState.emit(ErrorState(state.error))
         is Complete -> {
            val tokens = manager.currentTokens
            if (tokens != null) {
                // Tokens are available
                _viewState.emit(SignedInState(tokens))
            } else {
                // Tokens are not available
                _viewState.emit(SignedOutState)
            }
         }
      }
   } 
}

TIP:When displaying the user code and verification URI, The Trade Desk recommends generating a QR code for the user. This makes it easier for them to navigate to the linked website through their mobile device or computer.

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.

Clean Up the Device Authorization Flow

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

Additional resources

For more information, see the following pages:

Developer Documentation:

• Android API reference
• Integration best practices
• Co-branding guidelines

External Resources:

• UID2
• Latest release on Maven
• OpenPass Android changelog
• Android custom tabs
• Auth0's guide on the device authorization flow