iOS/tvOS SDK Cookbook iostvos-sdk-cookbook

Create your callback functions:

• setRequestorComplete()

• Triggered by setRequestor(), returns success or failure.

• Success indicates you can proceed with entitlement calls.

• displayProviderDialog(mvpds)

  • Triggered by getAuthentication() only if the user has not selected a provider (MVPD) and is not yet authenticated.
  • The mvpds parameter is an array of providers available to the user.

• setAuthenticationStatus(status, errorcode)

  • Triggered by checkAuthentication() every time.
  • Triggered by getAuthentication() only if the user is already authenticated and has selected a provider.
  • Status returned is success or failure, the errorcode describes the type of the failure.

• navigateToUrl(url)

  • Triggered by getAuthentication() after the user selects an MVPD. The url parameter provides the location of the MVPD’s login page.

• sendTrackingData(event, data)

  • Triggered by checkAuthentication(), getAuthentication(), checkAuthorization(), getAuthorization(), setSelectedProvider().
  • The event parameter indicates which entitlement event occurred; the data parameter is a list of values relating to the event.

• setToken(token, resource)

  • Triggered by checkAuthorization() and getAuthorization() after a successful authorization to view a resource.
  • The token parameter is the short-lived media token; the resource parameter is the content that the user is authorized to view.

• tokenRequestFailed(resource, code, description)

  • Triggered by checkAuthorization() and getAuthorization() after an unsuccessful authorization.
  • The resource parameter is the content that the user was attempting to view; the code parameter is the error code indicating what type of failure occurred; the description parameter describes the error associated with the error code.

• selectedProvider(mvpd)

  • Triggered by getSelectedProvider().
  • The mvpd parameter provides information about the provider selected by the user.

• setMetadataStatus(metadata, key, arguments)

  • Triggered by getMetadata().
  • The metadata parameter provides the specific data you requested; the key parameter is the key used in the getMetadata() request; and the arguments parameter is the same dictionary that was passed to getMetadata().

• preauthorizedResources(authorizedResources)

  • Triggered by checkPreauthorizedResources().

  • The authorizedResources parameter presents the resources that the user
    is authorized to view.

• presentTvProviderDialog(viewController)

  • Triggered by getAuthentication() when the current requestor supports at least on MVPD that has SSO support.
  • The viewController parameter is the Apple SSO Dialog and needs to be presented on the main view controller.

• dismissTvProviderDialog(viewController)

  • Triggered by a user action (by selecting “Cancel” or “Other TV Providers” from the Apple SSO Dialog).
  • The viewController parameter is the Apple SSO Dialog and needs to be dismissed from the main view controller.

Start the upper-level application.

Initiate Adobe Pass Authentication

a. Call init to create a single instance of the Adobe Pass Authentication AccessEnabler.

• Dependency: Adobe Pass Authentication Native iOS/tvOS Library (AccessEnabler)

b. Call setRequestor() to establish the identity of the Programmer; pass in the Programmer’s requestorID and(optionally) an array of Adobe Pass Authentication endpoints. For tvOS you will also need to provide the public key and the secret. See Clientless documentation for details.

• Dependency: Valid Adobe Pass Authentication RequestorID (Work with your Adobe Pass Authentication Account
  Manager to arrange this).

• Triggers:
  setRequestorComplete() callback.

You have two implementation options: Once the requestor identification information is sent to the backend server, the UI application layer may choose one of the two following approaches:

1. Wait for the triggering of the setRequestorComplete() callback (part of the AccessEnabler delegate). This option provides the most certainty that setRequestor() completed, so it is recommended for most implementations.

2. Continue without waiting for the triggering of the setRequestorComplete() callback, and start issuing entitlement requests. These calls (checkAuthentication, checkAuthorization, getAuthentication, getAuthorization, checkPreauthorizedResource, getMetadata, logout) are queued by the AccessEnabler library, which will make the actual network calls after the setRequestor(). This option can occasionally be disrupted if, for example, the network connection is unstable.

Call checkAuthentication() to check for an existing authentication without initiating the full Authentication flow. If this call succeeds, you can proceed directly to the Authorization flow. If not, proceed to the Authentication flow.

• Dependency: A successful call to setRequestor() (this dependency applies to all subsequent calls as well).

• Triggers: setAuthenticationStatus() callback.

Call getAuthentication() to initiate the authentication flow, or to get confirmation that the user is already
authenticated.

Triggers:

• The setAuthenticationStatus() callback, if the user is already authenticated. In this case, proceed directly to the Authorization Flow.

• The displayProviderDialog() callback, if the user is not yet authenticated.

Present the user with the list of providers sent to
displayProviderDialog().

After the user selects a provider, obtain the URL of the user’s MVPD from the navigateToUrl: or navigateToUrl:useSVC: callback and open a UIWebView/WKWebView or SFSafariViewController controller and direct that controller to the URL.

Through the UIWebView/WKWebView or SFSafariViewController instantiated in the previous step, the user lands on the MVPD’s login page and inputs login credentials. Several redirect operations take place within the controller.

Upon a successful login by the user, your application layer detects the loading of a specific custom URL. Note that this specific custom URL is actually invalid, and it is not intended for the controller to actually load it. It must be only interpreted by your application as a signal that the authentication flow has completed and that it is safe to close the UIWebView/WKWebView or SFSafariViewController controller. In case a SFSafariViewControllercontroller is required to be used the specifc custom URL is defined by the application's custom scheme (e.g.adbe.u-XFXJeTSDuJiIQs0HVRAg://adobe.com), otherwise this specific custom URL is defined by the ADOBEPASS_REDIRECT_URL constant (that is, adobepass://ios.app).

Close the UIWebView/WKWebView or SFSafariViewController controller and call AccessEnabler’s handleExternalURL:url API method, which instructs the AccessEnabler to retrieve the authentication token from the backend server.

(Optional) Call checkPreauthorizedResources(resources) to check which resources the user is authorized to view. The resources parameter is an array of protected resources that is associated with the user’s authentication token. One use for the authorization information obtained from the user’s MVPD is to decorate your UI(for example, locked / unlocked symbols next to protected content).

• Triggers: preauthorizedResources() callback
• Execution point: After the completed Authentication Flow

If authentication was successful, proceed to the Authorization Flow.

Call getAuthentication() to initiate the authentication flow, or to get confirmation that the user is already authenticated.
Triggers:

• The presentTvProviderDialog() callback, if the user is not authenticated and the current requestor has at least on MVPD that supports SSO. If no MVPDs support SSO, the classic authentication flow will be used.

After the user selects a provider the AccessEnabler library will obtain an authentication token with the information provided by Apple’s VSA framework.

The setAuthenticatiosStatus() callback will be triggered. At this point the user should be authenticated with Apple SSO.

[Optional] Call checkPreauthorizedResources(resources) to check which resources the user is authorized to view. The resources parameter is an array of protected resources that is associated with the user’s authentication token. One use for the authorization information obtained from the user’s MVPD is to decorate your UI (for example, locked / unlocked symbols next to protected content).

• Triggers: preauthorizedResources() callback
• Execution point: After the completed Authentication Flow

If authentication was successful, proceed to the Authorization Flow.

Call getAuthentication() to initiate the
authentication flow, or to get confirmation that the user is already
authenticated.
Triggers:

• The presentTvProviderDialog() callback, if the user is not authenticated and the current requestor has at least on MVPD that supports SSO. If no MVPDs support SSO, the classic authentication flow will be used.

After the user selects a provider the status() callback will be called. A registration code will be provided and the AccessEnabler library will start polling the server for a successfull second screen authentication.

If the registration code provided was used to successfully authenticate on the second screen, the setAuthenticatiosStatus() callback will be triggered. At this point the user should be authenticated with Apple SSO.

[Optional] Call checkPreauthorizedResources(resources) to check which resources the user is authorized to view. The resources parameter is an array of protected resources that is associated with the user’s authentication token. One use for the authorization information obtained from the user’s MVPD is to decorate your UI (for example, locked / unlocked symbols next to protected content).

• Triggers: preauthorizedResources() callback

• Execution point: After the completed Authentication Flow

If authentication was successful, proceed to the Authorization Flow.

Call getAuthorization() to initiate the authorization flow.

• Dependency: Valid ResourceID(s) agreed upon with the MVPD(s).
• Resource IDs should be the same as those used on any other devices or platforms, and will be the same across MVPDs. For information on Resource IDs, see Identifying Protected Resources

Validate authentication and authorization.

• If the getAuthorization() call succeeds: The user has valid AuthN and AuthZ tokens (the user is authenticated and authorized to watch the requested media).

• If getAuthorization() fails: Examine the exception thrown to determine its type (AuthN, AuthZ, or something else):

  • If it was an authentication (AuthN) error then re-start the authentication flow.
  • If it was an authorization (AuthZ) error then the user is not authorized to watch the requested media and some kind of error message should be displayed to the user.
  • If there was some other type of error (connection error, network error, etc.) then display an appropriate error message to the user.

Validate the Short Media Token.
Use the Adobe Pass Authentication Media Token Verifier library to verify the short-lived media token returned from the getAuthorization() call above:

• If the validation succeeds: Play the requested media for the user.
• If the validation fails: The AuthZ token was invalid, the media request should be refused, and an error message should be displayed to the user.

Return to your normal application flow.

User selects the media to view.

Is the media protected? Your application checks if the selected media is protected:

• If the selected media is protected, your application starts the Authorization Flow above.

• If the selected media is not protected, then play the media for
  the user.

Call logout() to log the user out. The AccessEnabler clears out all cached values and tokens. After clearing out the cache, the AccessEnabler makes a server call to clean the server-side sessions. Note that since the server call could result in a SAML redirect to the IdP (this allows for the session clean-up on the IdP side), this call must follow all redirects. For this reason, this call must be handled inside a UIWebView/WKWebView or SFSafariViewController controller.

a. Following the same pattern as the authentication workflow, the AccessEnabler domain makes a request to the UI application layer, via the navigateToUrl: or navigateToUrl:useSVC: callback, to create a UIWebView/WKWebView or SFSafariViewController controller and instruct that to load the URL provided in the callback’s url parameter. This is the URL of the logout endpoint on the backend server.

b. Your application must monitor the activity of the UIWebView/WKWebView or SFSafariViewController controller and detect the moment when it loads a specific custom URL, as it goes through several redirects. Note that this specific custom URL is actually invalid, and it is not intended for the controller to actually load it. It must be only interpreted by your application as a signal that the logout flow has completed and that it is safe to close the UIWebView/WKWebView or SFSafariViewController controller. When the controller loads this specific custom URL your application must close the UIWebView/WKWebView or SFSafariViewController controller and call AccessEnabler’s handleExternalURL:urlAPI method. In case a SFSafariViewControllercontroller is required to be used the specifc custom URL is defined by the application's custom scheme (for example, adbe.u-XFXJeTSDuJiIQs0HVRAg://adobe.com), otherwise this specific custom URL is defined by the ADOBEPASS_REDIRECT_URL constant (that is, adobepass://ios.app).