OpenPass SDK for tv OS quickstart guide

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

The tvOS SDK helps you create an OpenPass client, which can be integrated with your website to implement single sign-on (SSO) for the open internet. With the help of this SDK, you can also integrate OpenPass directly with your tvOS application.

After you have configured the SDK, you can handle the authentication response that is optimized for TV-based interfaces to sign in a user.

For details on integrating your OpenPass implementation with UID2, contact your Technical Account Manager at The Trade Desk.

Follow these steps to install the SDK:

  1. Install the SDK.
  2. Implement the SDK using the device authorization flow.

The following sections detail each step.

Install the SDK

To install the SDK, use the Swift Package Manager tool and choose one of these distribution options:

NOTE: You can modify the Swift Package Manager configuration in the Package.swift file directly, but using the Xcode option may be easier because it provides a user interface for configuring this file.

The following is an example URL for an OpenPass Swift package.

dependencies [
    .package(url: "https://github.com/openpass-sso/openpass-ios-sdk.git", .upToNextMajor(from: "1.0.0"))
]

Implement the SDK

To configure the SDK, you must do the following:

  1. Configure your app
  2. Follow Apple privacy requirements
  3. Initialize the OpenPass manager
  4. Implement the device authorization sign-in flow
  5. Handle an expired device code
  6. Sign out of the flow

Configure your app

To get up and running with OpenPass using the tvOS SDK, follow these steps:

  1. Sign up for an OpenPass account to get a client ID.
  2. To configure the Info.plist information property list for your app, add the OpenPassClientId key with the client ID from step 1 and the OpenPassRedirectHost file with the redirect host.

Here's a screenshot showing the OpenPassClientId key and OpenPassRedirectHost file in Xcode.

Follow Apple privacy requirements

Implement any requirements from Apple regarding in-app privacy and app-store publishing. For details, see the following:

Initialize the OpenPass Manager

The OpenPass manager is a singleton that automatically initializes the first time it is used.

TIP: Though not necessary, you can initialize the manager before your app uses it, such as during an app launch in the AppDelegate class. When the manager is initialized, it will perform a small amount of processing, such as reading or parsing the file from disk or storage. Some apps may want to control when this overhead happens rather than when it's actually being used. The following is a code example.


    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Initializes the OpenPass Manager.
        _ = OpenPassManager.shared

    }

Implement device authorization flow

The OpenPass login can be standalone, or you can add it to a list if you support other SSO providers such as Google, Facebook, and Apple. Choose from two options for authentication flows:

The sign-in flow for tvOS uses the Apple ASWebAuthenticationSession service to launch the sign-in experience. After the user starts the sign-in process in your tvOS app (usually through a button press), Apple TV will search for an iPhone or iPad nearby to continue to process through the web component. When completed, the iPhone or iPad redirects to the Apple TV with the authenticated data.

This integration provides the developer the raw information they need to build a custom user experience around device authorization. It provides the user code and its associated URI, but it's up to the consuming application to display them.

To launch the flow, follow these steps:

  1. Request a new device code from the flow.
  2. When a new device code is returned, display the user code and URI to the user and ask them to sign in through a mobile or computer device.
  3. Request an access token and wait for a successful sign-in or failure message.

The following code example requests a new device code and retrieves access tokens. If successful, tokens are automatically set on the shared OpenPassManager instance.

Task {
    // Retrieves a flow instance for device authorization.
    let flow = OpenPassManager.shared.deviceAuthorizationFlow
    do {
        // Request a device code containing the user code and verification URI.
        let deviceCode = try await flow.fetchDeviceCode()
        // Polls for authorization until access tokens are retrieved.
        let tokens = try await flow.fetchAccessToken(deviceCode: deviceCode)
        // Success! Use the access tokens for further actions...
    } catch OpenPassError.tokenExpired {
        // Timeout during device authorization. Inform the user to restart the device authentication flow.
    } catch {
        // Handle the error and provide an error message with possible solutions...
    }
}

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 that was fetched has an expiration time. When that time is reached, the code will no longer be invalid. When this case is detected during the polling fetchAccessToken(deviceCode: ) call, the SDK throws an error. Be sure to provide a UI that enables the user to fetch a new device code to restart the flow.

Sign out of the flow

To sign the user out from OpenPass on the device, use the OpenPassManager.shared.signOut() method. It removes previously saved OpenPass tokens from the key chain and the OpenPassManager.shared.openPassTokens manager, and resets OpenPass to its original post-initialized state.

For more information, see the following pages: