(Legacy) Android 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(resources)

  Triggered by checkPreauthorizedResources().
  The authorizedResources parameter presents the resources that the user is authorized to view.

Start the upper-level application.

Initiate Adobe Pass Authentication

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

• Dependency: Adobe Pass Authentication Native
  Android Library (AccessEnabler)

b. Call setRequestor() to establish the identify of the Programmer; pass in the Programmer’s requestorID and (optionally) an array of Adobe Pass Authentication endpoints.

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

• Triggers: setRequestorComplete() callback

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() callback. Open a WebView and direct that WebView control to the URL.

Through the WebView 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 WebView.

Note: At this point, the user has the opportunity to cancel the authentication flow. If this occurs, your UI layer is responsible for informing the AccessEnabler about this event by calling setSelectedProvider() with null as a parameter. This allows the AccessEnabler to clean up it’s internal state and reset the Authentication Flow.

Upon a succesful login by the user, your application layer detects the loading of a “custom redirect URL” (i.e.: http://adobepass.android.app). This custom URL is actually an invalid URL that is not intended for the WebView to load. It is a signal that the Authentication Flow has completed, and that the WebView needs to be closed.

Close the WebView control and call getAuthenticationToken(), 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.
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).

Note: ResourceIDs should be the same as those used on any other devices or platforms, and will be the same across MVPDs.

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 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.

Call logout() to log the user out.
The AccessEnabler clears out all cached values and tokens for the current MVPD for current requestor and also for requestors with Single Sign On. 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 WebView control.

a. Following the same pattern as the authentication workflow, the AccessEnabler domain makes a request to the UI application layer (via thenavigateToUrl() callback) to create a WebView control and instruct that control to load the URL of the logout endpoint on the backend server.

b. Again, the UI must monitor the activity of the WebView control and detect the moment when the control, as it goes through several redirects, loads the application’s custom URL (i.e.: http://adobepass.android.app/). Once this event takes place, the UI application layer closes the WebView and the logout process is complete.

Note: The logout flow differs from the authentication flow in that the user is not required to interact with the WebView in any way. The UI application layer uses a WebView to make sure that all the redirects are being followed. Thus it is possible (and recommended) to make the WebView control invisible (i.e. hidden) during the logout process.