DocumentationAdobe PassAdobe Pass Authentication

iOS/tvOS SDK API Reference iostvos-sdk-api-reference

Last update: Mon Oct 02 2023 00:00:00 GMT+0000 (Coordinated Universal Time)
NOTE
The content on this page is provided for information purposes only. Usage of this API requires a current license from Adobe. No unauthorized use is permitted.

Introduction intro

This page describes the methods and callback functions exposed by the iOS/tvOS native client for Adobe Pass Authentication. The methods and callback functions described here are defined in the AccessEnabler.h and EntitlementDelegate.h header files; you can find them in the iOS AccessEnabler SDK here: [SDK directory]/AccessEnabler/headers/api/

Associated documentation:

NOTE
Adobe encourages you to use only the Adobe Pass Authentication public APIs:
  • Public APIs are available and fully tested on all supported client types. For any public feature, we make sure that each client type has a corresponding version of the associated method(s).
  • Public APIs are required to be as stable as possible, to support backwards compatibility and ensure that partner integrations do not break. However, for non-public APIs, we reserve the right to change their signature at any future point. If you encounter a particular flow that cannot be supported through a combination of the current public Adobe Pass Authentication API calls, the best approach is to let us know. Taking into account your needs, we can modify the public APIs and provide a stable solution moving forward.

API Reference apis

init:softwareStatement initWithSoftwareStatement

File: AccessEnabler/headers/AccessEnabler.h

Description: Instantiates the AccessEnabler object. There should be a single AccessEnabler instance per application instance.

API call: iOS AccessEnabler constructor
- (id) init:
(NSString *)softwareStatement;

Availability: v3.0+

Parameters:

  • softwareStatement: A string that identifies the application in Adobe’s system. Check out how to obtain a Software Statement.

Back to top…

init - [DEPRECATED] init

File: AccessEnabler/headers/AccessEnabler.h

Description: Instantiates the AccessEnabler object. There should be a single AccessEnabler instance per application instance.

API call: iOS AccessEnabler constructor
- (id) init;

Availability: v1.0+ Until: v3.0

Parameters: None

Back to top…

setOptions:options setOptions

File: AccessEnabler/headers/AccessEnabler.h

Description: Configures global SDK options. It accepts an NSDictionary as an argument. The values from the dictionary will be passed to the server along with every network call that the SDK makes.

Note: The values will be passed to the server independent of the current flow (authentication/authorization). If you want to change the values you can call this method at any point in time.

API call: setOptions
- (void) setOptions:(NSDictionary *)options;

Availability: v2.3.0+

Parameters:

  • options: An NSDictionary containing global SDK options. Currently, the following options are available:

    • applicationProfile - It can be used to make server configurations based on this value.

    • visitorID - The Experience Cloud ID Service. This value can be later used for advanced analytics reports.

    • handleSVC - Boolean indicating if the programmer will handle the SFSafariViewControllers. Please see SFSafariViewController support on iOS SDK 3.2+ for more details.

      • If set to false, the SDK will automatically present the end user with an SFSafariViewController. The SDK will further navigate to the MVPDs login page URL.
      • If set to true, the SDK will NOT automatically present the end user with an SFSafariViewController. The SDK will further trigger navigate(toUrl:{url}, useSVC:YES).

  • device_info - Client information as described in Passing client information.

Back to top…

setRequestor:requestorID, setRequestorserviceProviders: setReqV3

File: AccessEnabler/headers/AccessEnabler.h

Description: Establishes the identity of the Programmer. Each Programmer is assigned a unique ID upon registering with Adobe for the Adobe Pass Authentication system. When dealing with SSO and remote tokens, the authentication state can change when the application is in the background, setRequestor can be called again when the application is brought into the foreground in order to synchronize with the system state (fetch a remote token if SSO is enabled or delete the local token if a logout happened in the meantime).

The server response contains a list of MVPDs together with some configuration information that is attached to the identity of the Programmer. The server response is used internally by the AccessEnabler code. Only the status of the operation (i.e., SUCCESS/FAIL) is presented to your application via the setRequestorComplete: callback.

If the urls parameter is not used, the resulting network call targets the default service provider URL: the Adobe RELEASE/production environment.

If a value is provided for the urls parameter, the resulting network call targets all of the URLs provided in the urls parameter. All configuration requests are triggered simultaneously in separate threads. The first responder takes precedence when compiling the list of MVPDs. For each MVPD in the list, the AccessEnabler remembers the URL of the associated service provider. All subsequent entitlement requests are directed to the URL associated with the service provider that was paired with the target MVPD during the configuration phase.

API call: requestor configuration
- (void) setRequestor:(NSString *)requestorID

Availability: v3.0+

API call: requestor configuration
- (void) setRequestor:(NSString *)requestorID serviceProviders:(NSArray *)urls;

Availability: v3.0+

Parameters:

  • requestorID: The unique ID associated with the Programmer. Pass the unique ID assigned by Adobe to your site when you first register with the Adobe Pass Authentication service.
  • urls: Optional parameter; by default, the Adobe service provider is used (http://sp.auth.adobe.com/). This array allows you to specify endpoints for authentication and authorization services provided by Adobe (different instances might be used for debugging purposes). You can use this to specify multiple Adobe Pass Authentication service provider instances. When doing so, the MVPD list is composed of the endpoints from all the service providers. Each MVPD is associated with the fastest service provider; that is, the provider that responded first and that supports that MVPD.
NOTE
If called without the serviceProviders parameter, the library will retrieve the configuration from the default service provider (that is, https://sp.auth.adobe.com for the production profile or https://sp.auth-staging.adobe.com for the staging profile). If the serviceProviders parameter is provided, it must be an array of URL’s. The configuration information is retrieved from all specified endpoints and is merged. If duplicate information exists in different service provider responses, the conflict is resolved in favor of the fastest responding server (that is, the server with the shortest response time takes precedence).

Callbacks triggered: setRequestorComplete:

Back to top…

setRequestor, setRequestorserviceProviders: - [DEPRECATED] setReq

File: AccessEnabler/headers/AccessEnabler.h

Description: Establishes the identity of the Programmer. Each Programmer is assigned a unique ID upon registering with Adobe for the Adobe Pass Authentication system. When dealing with SSO and remote tokens the authentication state can change when the application is in the background, setRequestor can be called again when the application is brought into foreground in order to synchronize with the system state (fetch a remote token if SSO is enabled or delete the local token if a logout happened in the meantime).

The server response contains a list of MVPDs together with some configuration information that is attached to the identity of the Programmer. The server response is used internally by the AccessEnabler code. Only the status of the operation (i.e., SUCCESS/FAIL) is presented to your application via the setRequestorComplete: callback.

If the urls parameter is not used, the resulting network call targets the default service provider URL: the Adobe RELEASE/production environment.

If a value is provided for the urls parameter, the resulting network call targets all of the URLs provided in the urls parameter. All configuration requests are triggered simultaneously in separate threads. The first responder takes precedence when compiling the list of MVPDs. For each MVPD in the list, the AccessEnabler remembers the URL of the associated service provider. All subsequent entitlement requests are directed to the URL associated with the service provider that was paired with the target MVPD during the configuration phase.

API call: requestor configuration
- (void) setRequestor:(NSString *)requestorID
signedRequestorID:(NSString *)signedRequestorID;

Availability: v1.0+ Until: v3.0

API call: requestor configuration
- (void) setRequestor:(NSString *)requestorID
signedRequestorID:(NSString *)signedRequestorID
serviceProviders:(NSArray *)urls;

Availability: v1.0+ Until: v3.0

Parameters:

  • requestorID: The unique ID associated with the Programmer. Pass the unique ID assigned by Adobe to your site when you first registered with the Adobe Pass Authentication service.
  • signedRequestorID: This parameter exists in iOS AccessEnabler versions 1.2 and later. A copy of the requestor ID that is digitally signed with your private key. .
  • urls: Optional parameter; by default, the Adobe service provider is used (http://sp.auth.adobe.com/). This array allows you to specify endpoints for authentication and authorization services provided by Adobe (different instances might be used for debugging purposes). You can use this to specify multiple Adobe Pass Authentication service provider instances. When doing so, the MVPD list is composed of the endpoints from all the service providers. Each MVPD is associated with the fastest service provider; that is, the provider that responded first and that supports that MVPD.

Notes: If called without the serviceProviders parameter, the library will retrieve the configuration from the default service provider (that is,https://sp.auth.adobe.com for the production profile or https://sp.auth-staging.adobe.com for the staging profile). If the serviceProviders parameter is provided, it must be an array of URL’s. The configuration information is retrieved from all specified endpoints and is merged. If duplicate information exists in different service provider responses, the conflict is resolved in favor of the fastest responding server (i.e., the server with the shortest response time takes precedence).

Callbacks triggered: setRequestorComplete:

Back to top…

setRequestorsecret:publicKey, setRequestorserviceProviderspublicKey - [DEPRECATED] setReq_tvos

File: AccessEnabler/headers/AccessEnabler.h

Description: Establishes the identity of the Programmer. Each Programmer is assigned a unique ID upon registering with Adobe for the Adobe Pass Authentication system. This setting should be performed only once during the application’s life cycle.

The server response contains a list of MVPDs together with some configuration information that is attached to the identity of the Programmer. The server response is used internally by the AccessEnabler code. Only the status of the operation (i.e., SUCCESS/FAIL) is presented to your application via the setRequestorComplete: callback.

If the urls parameter is not used, the resulting network call targets the default service provider URL: the Adobe RELEASE/production environment.

If a value is provided for the urls parameter, the resulting network call targets all of the URLs provided in the urls parameter. All configuration requests are triggered simultaneously in separate threads. The first responder takes precedence when compiling the list of MVPDs. For each MVPD in the list, the AccessEnabler remembers the URL of the associated service provider. All subsequent entitlement requests are directed to the URL associated with the service provider that was paired with the target MVPD during the configuration phase.

API call: requestor configuration
code language-none 
- (void) setRequestor:(NSString *)requestorID
    signedRequestorID:(NSString *)signedRequestorID
               secret:(NSString *)secret
            publicKey:(NSString *)publicKey;

Availability: v2.0+ Until: v3.0

API call: requestor configuration
code language-none 
- (void) setRequestor:(NSString *)requestorID
    signedRequestorID:(NSString *)signedRequestorID
     serviceProviders:(NSArray *)urls

secret:(NSString *)secret

publicKey:(NSString *)publicKey;

Availability: v2.0+ Until: v3.0

Parameters:

  • requestorID: The unique ID associated with the Programmer. Pass the unique ID assigned by Adobe to your site when you first registered with the Adobe Pass Authentication service.
  • signedRequestorID: This parameter exists in iOS AccessEnabler versions 1.2 and later. A copy of the requestor ID that is digitally signed with your private key. .
  • urls: Optional parameter; by default, the Adobe service provider is used (http://sp.auth.adobe.com/). This array allows you to specify endpoints for authentication and authorization services provided by Adobe (different instances might be used for debugging purposes). You can use this to specify multiple Adobe Pass Authentication service provider instances. When doing so, the MVPD list is composed of the endpoints from all the service providers. Each MVPD is associated with the fastest service provider; that is, the provider that responded first and that supports that MVPD.
  • secret and publicKey: The secret and public key used to sign the second screen calls. For more information see the Clienteless documentation.

If called without the serviceProviders parameter, the library will retrieve the configuration from the default service provider (i.e., https://sp.auth.adobe.com for the production profile or https://sp.auth-staging.adobe.com for the staging profile). If the serviceProviders parameter is provided, it must be an array of URL’s. The configuration information is retrieved from all specified endpoints and is merged. If duplicate information exists in different service provider responses, the conflict is resolved in favor of the fastest responding server (i.e., the server with the shortest response time takes precedence).

Callbacks triggered: setRequestorComplete:

Back to top…

setRequestorComplete: setReqComplete

File: AccessEnabler/headers/EntitlementDelegate.h

Description Callback triggered by the AccessEnabler that informs your application that the configuration phase is complete. This is a signal that the app can start issuing entitlement requests. No entitlement requests can be issued by the application until the configuration phase is complete.

Callback: requestor configuration complete
code language-none 
- (void) setRequestorComplete:(int)status;

Availability: v1.0+

Parameters:

  • status: can take one of the following values:

    • ACCESS_ENABLER_STATUS_SUCCESS - configuration phase was successfully completed
    • ACCESS_ENABLER_STATUS_ERROR - configuration phase failed

Triggered by:
setRequestor:setSignedRequestorId:, setRequestor:setSignedRequestorId:serviceProviders:

Back to top…

checkAuthentication checkAuthN

File: AccessEnabler/headers/AccessEnabler.h

Description: Checks the authentication status of the current user.
It does this by searching for a valid authentication token in the local
token storage space. This method performs no network calls and we recommend calling it on the main thread.
It is used by the application to query the user’s authentication status and
update the UI accordingly (i.e., update the login/logout UI). The
authentication status is communicated to the application via
the setAuthenticationStatus:errorCode: callback.

API call: check authentication status
code language-none 
- (void) checkAuthentication;

Availability: v1.0+

Parameters: None

Callbacks triggered:
setAuthenticationStatus:errorCode:

Back to top…

getAuthentication, getAuthentication getAuthN

File: AccessEnabler/headers/AccessEnabler.h

Description: Starts the full authentication workflow. It starts by checking the authentication status. If not already authenticated, the authentication flow state-machine is started:

  • if the last authentication attempt was successful, the MVPD selection phase is skipped and the navigateToUrl: callback is triggered. The application uses this callback to instantiate the WebView control that presents the user with the MVPD’s login page. [NOTE: As of Acccess Enabler 1.5, this functionality is unavailable because of a limitation in the SDK].
  • if the last authentication attempt was unsuccessful or if the user explicitly logged out, the displayProviderDialog: callback is triggered. Your application uses this callback to display the MVPD selection UI. Also your app is required to resume the authentication flow by informing the AccessEnabler library about the user’s MVPD selection via the setSelectedProvider: method.

As the user’s credentials are verified on the MVPD login page, your application is required to monitor the multiple redirection operations that take place while the user authenticates at the MVPD’s login page. When the correct credentials are entered, the WebView control is redirected to a custom URL defined by the ADOBEPASS_REDIRECT_URL constant. This URL is not intended to be loaded by the WebView. The application must intercept this URL and interpret this event as a signal that the login phase is complete. It should then hand over control to the AccessEnabler in order to complete the authentication flow (by calling the handleExternalURL method).

Finally, the authentication status is communicated to the application via the setAuthenticationStatus callback.

API call: initiates the authentication flow
code language-none 
- (void) getAuthentication;

Availability: v1.0+

API call: initiates the authentication flow
code language-none 
- (void) getAuthentication:(BOOL)forceAuthn:
                  withData:(NSDictionary* )data;

Availability: v1.9+

Parameters:

  • forceAuthn: A flag that specifies if the authentication flow should be started, regardless if the user is already authenticated or not.
  • data: A dictionary consisting of key-value pairs to be sent to the Pay-TV pass service. Adobe can use this data to enable future functionality without changing the SDK.

Callbacks triggered: setAuthenticationStatus:errorCode:,displayProviderDialog:,`` sendTrackingData:forEventType:

Back to top…

getAuthentication:filter, getAuthenticationandFilter getAuthN_filter

File: AccessEnabler/headers/AccessEnabler.h

Description: Starts the full authentication workflow. It starts by checking the authentication status. If not already authenticated, the authentication flow state-machine is started:

  • presentTvProviderDialog() will be called if the current requestor has at least one MVPD that supports SSO. If no MVPD supports SSO, the classic authentication flow will begin and the filter parameter is ignored.
  • After the user completes the Apple SSO flow dismissTvProviderDialog() will be triggered and the authentication process will finish.

Finally, the authentication status is communicated to the application via the setAuthenticationStatus callback.

Availability: v2.4+

API call: initiates the authentication flow
code language-none 
- (void) getAuthentication:(NSDictionary *)filter;
API call: initiates the authentication flow
code language-none 
- (void) getAuthentication:(BOOL)forceAuthn:
                  withData:(NSDictionary* )data
                 andFilter:(NSDictionary *)filter;

Parameters:

  • forceAuthn: A flag that specifies if the authentication flow should be started, regardless if the user is already authenticated or not.

  • data: A dictionary consisting of key-value pairs to be sent to the Pay-TV pass service. Adobe can use this data to enable future functionality without changing the SDK.

  • filter: A dictionary with two lists of MVPD ids that should appear in the Apple SSO Dialog. Any MVPD that does not support SSO will be ignored but the order will be respected. The dictionary needs to have two keys:

    • TV_PROVIDERS: A list with all MVPDs that should appear in the picker
    • FEATURED_TV_PROVIDERS: A list with all MVPDs that should be marked as featured in the picker. MVPDs in this list must also be specified in the TV_PROVIDERS list.

Availability: v2.0 - v2.3.1

API call: initiates the authentication flow
code language-none 
- (void) getAuthentication:(NSArray *)filter;
API call: initiates the authentication flow
code language-none 
- (void) getAuthentication:(BOOL)forceAuthn:
                  withData:(NSDictionary* )data
                 andFilter:(NSArray *)filter;

Parameters:

  • forceAuthn: A flag that specifies if the authentication flow should be started, regardless if the user is already authenticated or not.
  • data: A dictionary consisting of key-value pairs to be sent to the Pay-TV pass service. Adobe can use this data to enable future functionality without changing the SDK.
  • filter: A list of MVPD ids that should appear in the Apple SSO Dialog. Any MVPD that does not support SSO will be ignored but the order will be respected.

Callbacks triggered: setAuthenticationStatus:errorCode:, presentTvProviderDialog, dismissTvProviderDialog

Back to top…

displayProviderDialog: dispProvDialog

File: AccessEnabler/headers/EntitlementDelegate.h

Description Callback triggered triggered by the AccessEnabler to inform the application that the appropriate UI elements need to be instantiated to allow the user to select the desired MVPD. The callback provides a list of MVPD objects with additional information that can help to correctly build the selection UI panel (such as the URL pointing to the MVPD’s logo, friendly display name, etc.)

Once the user has selected the desired MVPD, the upper-layer application is required to resume the authentication flow by calling setSelectedProvider: and passing it the ID of the MVPD corresponding to the user’s selection.

Aborting the authentication flow - This is a point where the user has the ability to press the “Back” button, which is equivalent to aborting the authentication flow. In that scenario, your application is required to call the setSelectedProvider: method, passing null as the parameter, to give the AccessEnabler the opportunity to reset its authentication state-machine.

Callback: display the MVPD selection UI
code language-none 
- (void) displayProviderDialog:(NSArray *)mvpds;

Availability: v1.0+

Parameters:

  • mvpds: list of MVPD objects holding MVPD-related information that the application can use to build the MVPD selection UI elements.

Triggered by: getAuthentication,getAuthentication,getAuthorization:,getAuthorization

Back to top…

setSelectedProvider: setSelProv

File: AccessEnabler/headers/AccessEnabler.h

Description: This method is called by your application to inform the Access Enabler of the user’s MVPD selection. The application can use this method to select or change the service provider used for authentication.

If the MVPD selected is a TempPass MVPD it will automatically authenticate with that MVPD without needing to call getAuthentication() afterwards.

Please note that this is not possible for Promotional Temp Pass where extra parameters are given on getAuthentication() method.

When passing null as a parameter, the Access Enabler assumes that the user has canceled the authentication flow (i.e. pressed the “Back” button), and responds by resetting the authentication state-machine and by calling the setAuthenticationStatus callback with the AccessEnabler.PROVIDER_NOT_SELECTED_ERROR error code.

API call: set the currently selected provider
code language-none 
- (void) setSelectedProvider:(NSString *)mvpdId;

Availability: v1.0+

Parameters: None

Callbacks triggered: setAuthenticationStatus:errorCode:,sendTrackingData:forEventType:, navigateToUrl:

Back to top…

File: AccessEnabler/headers/EntitlementDelegate.h

Description: Callback triggered by the AccessEnabler to request your application to instantiate a UIWebView/WKWebView controller and to load the URL provided in the callback’s url parameter. The callback passes the url parameter which represents the URL of the authentication endpoint or the URL of the logout endpoint.

As the UIWebView/WKWebView controller goes through several redirects, your application must monitor the activity of the controller and detect the moment when it loads a specific custom URL defined by the ADOBEPASS_REDIRECT_URL constant (i.e. adobepass://ios.app). 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 or logout flow has completed and that it is safe to close the controller. When the controller loads this specific custom URL your application must close the UIWebView/WKWebView and call AccessEnabler’s handleExternalURL:url API method.

Note: Please note that in case of the authetication flow this is a point where the user has the ability to press the “Back” button, which is equivalent to the aborting of the authentication flow. In such a scenario, your application is required to call the setSelectedProvider: method passing nil as the parameter and giving a chance to the AccessEnabler to reset its authentication state-machine.

Callback: display MVPD login page
code language-none 
- (void) navigateToUrl:(NSString *)url;

Availability: v1.0+

Parameters:

  • url: the URL pointing to the MVPD’s login page

Triggered by: setSelectedProvider:

Back to top…

File: AccessEnabler/headers/EntitlementDelegate.h

Description: Callback triggered by the AccessEnabler instead of the navigateToUrl: callback in case your application previously enabled manual Safari View Controller (SVC) handling via the setOptions([“handleSVC”:true"]) call, and only in case of MVPDs requiring Safari View Controller (SVC). For all other MVPDs the navigateToUrl: callback will be called. Please seeSFSafariViewController support on iOS SDK 3.2+ for details on how Safari View Controller (SVC) should be managed.

Similar to the navigateToUrl: callback the navigateToUrl:useSVC: is triggered by the AccessEnabler to request your application to instantiate a SFSafariViewController controller and to load the URL provided in the callback’s url parameter. The callback passes the url parameter which represents the URL of the authentication endpoint or the URL of the logout endpoint, and the useSVC parameter which specifies that the application must use a SFSafariViewController.

As the SFSafariViewController controller goes through several redirects, your application must monitor the activity of the controller and detect the moment when it loads a specific custom URL defined by your application's custom scheme (e.g.** **adbe.u-XFXJeTSDuJiIQs0HVRAg://adobe.com). 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 or logout flow has completed and that it is safe to close the controller. When the controller loads this specific custom URL your application must close the SFSafariViewController and call AccessEnabler’s handleExternalURL:url API method.

Note: Please note that in case of the authetication flow this is a point where the user has the ability to press the “Back” button, which is equivalent to the aborting of the authentication flow. In such a scenario, your application is required to call the setSelectedProvider: method passing nil as the parameter and giving a chance to the AccessEnabler to reset its authentication state-machine.

Callback: display MVPD login page in SFSafariViewController
code language-none 
@optional
- (void) navigateToUrl:(NSString *)url useSVC:(BOOL)useSVC;

**Availability:**v 3.2+

Parameters:

  • url: the URL pointing to the MVPD’s login page
  • useSVC: whether the url should be loaded in SFSafariViewController.

Triggered by:setOptions: before setSelectedProvider:

Back to top…

handleExternalURL:url handleExternalURL

File: AccessEnabler/headers/AccessEnabler.h

Description: This method is called by your application to complete the authentication or logout flow. This method should be called right after your application detects the moment when the UIWebView/WKWebView or SFSafariViewController controller is redirected to a specific custom URL. In case your application is required to use a SFSafariViewController controller the specifc custom URL is defined by your application's custom scheme (e.g.adbe.u-XFXJeTSDuJiIQs0HVRAg://adobe.com), otherwise this specific custom URL is defined by the ADOBEPASS_REDIRECT_URL constant (i.e. adobepass://ios.app).

In case of the authentication flow the AccessEnabler completes the flow by retrieving the authentication token from the back-end server and storing it locally in the token storage. The AccessEnabler will inform your application that the authentication flow is complete by calling the setAuthenticationStatus() callback with a status code of 1, indicating success. If there is an error during the execution of these steps, the setAuthenticationStatus() callback is triggered with a status code of 0, indicating authentication failure, as well as a corresponding error code.

API call: complete the authentication or logout flow
code language-none 
 (void) handleExternalURL:(NSString *)url;

Availability: v3.0+

Parameters:

  • url: The intercepted URL from the UIWebView/WKWebView or SFSafariViewController control as string.

Callbacks triggered: setAuthenticationStatus:errorCode, sendTrackingData:forEventType:

Back to top…

getAuthenticationToken - [DEPRECATED] getAuthNToken

File: AccessEnabler/headers/AccessEnabler.h

Description: Completes the authentication flow by requesting the authentication token from the back-end server. This method should be called by your application only in response to event where the WebView control hosting the MVPD login page is redirected to the custom URL defined by the ADOBEPASS_REDIRECT_URL constant.

API call: retrieve the authentication token
code language-none 
- (void) getAuthenticationToken;

Availability: v1.0+ Until: v3.0

Parameters: None

Callbacks triggered: setAuthenticationStatus:errorCode,sendTrackingData:forEventType:

Back to top…

</br

setAuthenticationStatus setAuthNStatus

File: AccessEnabler/headers/EntitlementDelegate.h

Description Callback triggered by the AccessEnabler which informs the application of the status of the authentication flow. There are many places where this flow can fail, either as a result of user’s interaction or due to other unforeseen scenarios (i.e., network connectivity problems, etc.). This callback informs the application of the success/failure status of the authentication flow, while also providing additional information about the failure reason, when needed.

Callback: report the status of the authentication flow
code language-none 
- (void) setAuthenticationStatus:(int)status
                       errorCode:(NSString *)code;

Availability: v1.0+

Parameters:

  • status: can take one of the following values:

    • ACCESS_ENABLER_STATUS_SUCCESS - authentication flow was successfully completed
    • ACCESS_ENABLER_STATUS_ERROR - authentication flow failed

  • code: failure reason. If status is ACCESS_ENABLER_STATUS_SUCCESS, then code is an empty string (i.e., defined by the USER_AUTHENTICATED constant). In case of failure, this parameter can take one of the following values:

    • USER_NOT_AUTHENTICATED_ERROR - The user is not authenticated. In response to the checkAuthentication: method call when there is no valid authentication token in the local token cache.
    • PROVIDER_NOT_SELECTED_ERROR - The AccessEnabler has reset the authentication state-machine after the upper-layer application passed null to setSelectedProvider: to abort the authentication flow. Presumably the user has canceled the authentication flow (i.e., pressed the “Back” button).
    • GENERIC_AUTHENTICATION_ERROR - The authentication flow failed due to reasons such as network unavailability or the user canceled the authentication flow explicitly.

Triggered by: checkAuthentication, getAuthentication,getAuthentication,checkAuthorization:,checkAuthorization

Back to top…

checkPreauthorizedResources: checkPreauth

File: AccessEnabler/headers/AccessEnabler.h

Description: This method is used by the application to determine if the user is already authorized to view specific protected resources. The primary purpose of this method is to retrieve information for use in decorating the UI (for example, indicating access status with lock and unlock icons).

API call: set the currently selected provider
code language-none 
- (void) checkPreauthorizedResources:(NSArray *)resources;

Availability: v1.3+

Parameters:

  • resources: array of resources for which authorization should be checked. Each element in the list should be a string representing the resource ID. The resource ID is subject to the same limitations as the resource ID in the call, that is, it should be an agreed upon value established between the Programmer and the MVPD or a media RSS fragment.

Callback triggered: preauthorizedResources:

Back to top…

checkPreauthorizedResources checkPreauthCache

File: AccessEnabler/headers/AccessEnabler.h

Description: This method is used by the application to determine if the user is already authorized to view specific protected resources. The primary purpose of this method is to retrieve information for use in decorating the UI (for example, indicating access status with lock and unlock icons). The cache parameter controls wether the internal cache is used for resolving resources.

API call: set the currently selected provider
code language-none 
- (void) checkPreauthorizedResources:(NSArray *)resources cache:(BOOL)cache;

Availability: v3.1+

Parameters:

  • resources: array of resources for which authorization should be checked. Each element in the list should be a string representing the resource ID. The resource ID is subject to the same limitations as the resource ID in the getAuthorization: call, that is, it should be an agreed upon value established between the Programmer and the MVPD or a media RSS fragment.
  • cache: Boolean specifying wether to use the internal cache for resolving resources. If false the cache will be bypassed, resulting in server calls each time this API is called.

Callback triggered: preauthorizedResources:

Back to top…

preauthorizedResources: preauthResources

File: AccessEnabler/headers/EntitlementDelegate.h

Description: Callback triggered by checkPreauthorizedResources:. Provides a list of resources the user is already authorized to view.

API call: set the currently selected provider
code language-none 
- (void) checkPreauthorizedResources:(NSArray *)resources;

Availability: v1.3+

Parameters:

  • resources: array of resources for which the user is already authorized to view.

Triggered by: checkPreauthorizedResources:

Back to top…

checkAuthorization:, checkAuthorization checkAuthZ

File: AccessEnabler/headers/AccessEnabler.h

Description: This method is used by the application to check the authorization status. It starts by checking the authentication status first. If not authenticated, the tokenRequestFailederrorDescription: callback is triggered, and the method exits. If the user is authenticated, it also triggers the authorization flow. See details on the getAuthorization: method.

API call: check authorization status
code language-none 
- (void) checkAuthorization:(NSString *)resource;

Availability: v1.0+

API call: check authorization status
code language-none 
- (void) checkAuthorization:(NSString *)resource:
                   withData:(NSDictionary *)data;

Availability: v1.9+

Parameters:

  • resource: the ID of the resource for which the user requests authorization.
  • data: A dictionary consisting of key-value pairs to be sent to the Pay-TV pass service. Adobe can use this data to enable future functionality without changing the SDK.

Callbacks triggered:
tokenRequestFailederrorDescription:,setToken:forResource:, sendTrackingData:forEventType:, setAuthenticationStatus:errorCode:

Back to top…

getAuthorization:, getAuthorization getAuthZ

File: AccessEnabler/headers/AccessEnabler.h

Description: This method is used by the application to initiate the authorization flow. If the user is not already authenticated, it also initiates the authentication flow. If the user gets authenticated, the AccessEnabler proceeds to issue requests for the authorization token (if no valid authorization token is present in the local token cache) and for the short-lived media token. Once the short media token is obtained, the authorization flow is considered complete. The setToken callback gets triggered and the short media token is delivered as a parameter to the application. If for any reason, the authorization fails, the tokenRequestFailed callback is triggered and the error code/details are provided.

API call: initiate the authorization flow
code language-none 
- (void) getAuthorization:(NSString *)resource;

Availability: v1.0+

API call: initiate the authorization flow
code language-none 
- (void) getAuthorization:(NSString *)resource:
                 withData:(NSDictionary *)data;

Availability: v1.9+

Parameters:

  • resource: the ID of the resource for which the user requests authorization.
  • data: A dictionary consisting of key-value pairs to be sent to the Pay-TV pass service. Adobe can use this data to enable future functionality without changing the SDK.

Callbacks triggered: tokenRequestFailed:errorCode:errorDescription:, setToken:forResource:,sendTrackingData:forEventType:

Additional callbacks triggered:
This method can also trigger the following callbacks (if the authentication flow is also initiated): setAuthenticationStatus:errorCode:, displayProviderDialog:

NOTE: Please use checkAuthorization: / checkAuthorization instead of getAuthorization: / getAuthorization whenever possible. The getAuthorization: / getAuthorization method will start a full authentication flow (if the user is not authenticated) and this could lead to a complicated implementation on the Programmer’s side.

Back to top…

setToken setToken

File: AccessEnabler/headers/EntitlementDelegate.h

Description Callback triggered by the AccessEnabler that informs your application that the authorization flow was completed successfully. The short-lived media token is also delivered as a parameter.

Callback: authorization flow completed successfully
code language-none 
- (void) setToken:(NSString *)token
      forResource:(NSString *)resource;

Availability: v1.0+

Parameters:

  • token: the short-lived media token
  • resource: the resource for which the authorization was obtained

Triggered by: checkAuthorization:,checkAuthorization, getAuthorization:, getAuthorization

Back to top…

tokenRequestFailederrorDescription: tokenReqFailed

File: AccessEnabler/headers/EntitlementDelegate.h

Description Callback triggered by the AccessEnabler that informs the upper-layer application that the authorization flow failed.

Callback: authorization flow failed
code language-none 
- (void) tokenRequestFailed:(NSString *)resource
                  errorCode:(NSString *)code
           errorDescription:(NSString *)description;

Availability: v1.0+

Parameters:

  • resource: The resource for which the authorization was obtained.
  • code: The error code associated with the failure scenario. Possible values:
    • USER_NOT_AUTHORIZED_ERROR - the user was not able to authorize
      for the given resource
  • description: Additional details about the failure scenario. If this descriptive string is not available for any reason, Adobe Pass Authentication sends an empty string (“”).
    This string can be used by an MVPD to pass custom error messages or sales-related messages. For example, if a subscriber is denied authorization for a resource, the MVPD could send a message such as: “You currently do not have access to this channel in your package. If you would like to upgrade your package click here.” The message is passed by Adobe Pass Authentication through this callback to the Programmer, who has the option to display or ignore it. Adobe Pass Authentication can also use this parameter to provide notification of the condition that might have led to an error. For example, “A network error occurred when communicating with the provider’s authorization service”.

Triggered by: checkAuthorization:,checkAuthorization, getAuthorization:, getAuthorization

Back to top…

logout logout

File: AccessEnabler/headers/AccessEnabler.h

Description: This method is called by your application to initiate the logout flow. The logout is the result of a series of HTTP redirect operations due to the fact that the user needs to be logged out from both Adobe Pass Authentication servers and also from the MVPD’s servers. Because this flow cannot be completed with a simple HTTP request issued by the AccessEnabler library, a UIWebView/WKWebView or SFSafariViewController controller needs to be instantiated in order to be able to follow the HTTP redirect operations.

The logout flow differs from the authentication flow in that the user is not required to interact with the UIWebView/WKWebView or SFSafariViewController controller in any way. Therefore, Adobe recommends that you make the control invisible (i.e. hidden) during the logout process.

A pattern similar with the authentication flow is employed. The iOS AccessEnabler triggers the navigateToUrl: callback or the navigateToUrl:useSVC: to create a UIWebView/WKWebView or SFSafariViewController controller and to load the URL provided in the callback’s url parameter. This is the URL of the logout endpoint on the backend server. For the tvOS AccessEnabler neither the navigateToUrl: callback or the navigateToUrl:useSVC: callback is called.

As it goes through several redirects, your application must monitor the activity of the UIWebView/WKWebView or SFSafariViewController controller and detect the moment when it loads 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 logout flow has completed and that it is safe to close the controller. When the controller loads this specific custom URL your application must close the controller and call AccessEnabler’s handleExternalURL:url API method. In case your application is required to use a SFSafariViewController controller the specifc custom URL is defined by your application's custom scheme (e.g.adbe.u-XFXJeTSDuJiIQs0HVRAg://adobe.com), otherwise this specific custom URL is defined by the ADOBEPASS_REDIRECT_URL constant (i.e. adobepass://ios.app).

In the end the AccessEnabler will call the setAuthenticationStatus() callback with a status code of 0, indicating success of the logout flow.

Note: If the user is logged in using Apple SSO the VSA203 status will be triggered. If this is the case, the user should be instructed to also logout from the system settings. Failure to do so will result in a re-authentication when the application is re-launched.

API call: initiate the logout flow
code language-none 
- (void) logout;

Availability: v1.0+

Parameters: None

Callbacks triggered: navigateToUrl:, setAuthenticationStatus:errorCode:

Back to top…

getSelectedProvider getSelProv

File: AccessEnabler/headers/AccessEnabler.h

Description: Use this method to determine the currently selected provider.

API call: determine the currently selected MVPD
code language-none 
- (void) getSelectedProvider;

Availability: v1.0+

Parameters: None

Callbacks triggered: selectedProvider:

Back to top…

selectedProvider selProv

File: AccessEnabler/headers/EntitlementDelegate.h

Description Callback triggered by the AccessEnabler that delivers information about the currently selected MVPD to the application.

Callback: information about the currently selected MVPD
code language-none 
- (void) selectedProvider:(MVPD *)mvpd;

Availability: v1.0+

Parameters:

  • mvpd: object containing information about the currently selected MVPD

Triggered by: getSelectedProvider

Back to top…

getMetadata: getMeta

File: AccessEnabler/headers/AccessEnabler.h

Description: Use this method to retrieve information exposed as metadata by the AccessEnabler library. The application can access this data by providing a dictionary-based key input parameter.

There are two types of metadata available to Programmers:

  • Static metadata (Authentication token TTL, Authorization token TTL and Device ID)
  • User metadata (User-specific information, such as User ID, zip code; can be passed from an MVPD to a user’s device during the Authentication and Authorization flows)
API call: query the AccessEnabler for metadata
code language-none 
- (void) getMetadata:(NSDictionary *)keyDictionary;

Availability: v1.0+

Parameters:

  • keyDictionary: a dictionary data structure, with the following
    format:

    • If key is METADATA_OPCODE_KEY and value is METADATA_AUTHENTICATION, then the query is made to obtain the authentication token expiration time.

    • If key is METADATA_OPCODE_KEY and value is METADATA_AUTHORIZATION and
      key is METADATA_RESOURCE_ID_KEY and value is a particular resource ID, then the query is made to obtain the expiration time of the authorization token associated to the specified resource.

    • If key is METADATA_OPCODE_KEY and value is METADATA_DEVICE_ID, then the query is made to obtain the current device id. Note that this feature is disabled by default and Programmers should contact Adobe for information regarding enablement and fees.

    • If key is METADATA_OPCODE_KEY and value is METADATA_USER_META and key is METADATA_USER_META_KEY and value is the name of the metadata, then the query is made for user metadata. The list of available user metadata types:

      • zip - List of Zip Codes
      • householdID - Household identifier. In the case when an MVPD does not support subaccounts this will be identical to userID.
      • maxRating - A collection of maximum parental ratings for the user
      • userID - The user identifier. If an MVPD supports subaccounts, and the user is not the main account, userID will be different than householdID.
      • channelID - A list of channels a user is entitled to view.
    note note
    NOTE
    The actual User Metadata available to a Programmer depends on what an MVPD makes available. This list will be expanded as new metadata is made available and added into the Adobe Pass Authentication system.

Callbacks triggered: setMetadataStatus:encrypted:forKey:andArguments:

More Information: User Metadata

Back to top…

presentTVProviderDialog presentTvDialog

File: AccessEnabler/headers/EntitlementDelegate.h

Description Callback triggered by the AccessEnabler after callinggetAuthentication() if the current requestor supports at least one MVPD with SSO support.

Callback: result of SSO flows
code language-none 
- (void) presentTvProviderDialog: (UIViewController *) viewController;

Availability: v2.0+

Parameters:

  • viewController: represents the Apple SSO Dialog. This viewController needs to be displayed on the screen.

Triggered by: getAuthentication

More Information: iOS/tvOS Single Sign On

Back to top…

dismissTVProviderDialog dismissTvDialog

File: AccessEnabler/headers/EntitlementDelegate.h

Description Callback triggered by the AccessEnabler after the user closes the Apple SSO Dialog.

Callback: result of SSO flows
code language-none 
- (void) dismissTvProviderDialog: (UIViewController *) viewController;

Availability: v2.0+

Parameters:

  • viewController: represents the Apple SSO Dialog. This viewController needs to be removed from the screen.

Triggered by: User action

More Information: iOS/tvOS Single Sign On

Back to top…

setMetadataStatusforKey setMetaStatus

File: AccessEnabler/headers/EntitlementDelegate.h

Description Callback triggered by the AccessEnabler that delivers the metadata requested via a getMetadata: call.

Callback: result of metadata retrieval request
code language-none 
- (void) setMetadataStatus:(id)metadata
                 encrypted:(bool)encrypted
                    forKey:(int)key
              andArguments:(NSDictionary *)arguments;

Availability: v1.0+

Parameters:

  • metadata: The requested metadata. This value is an NSString in the case of static metadata (Authentication TTL, Authorization TTL, Device ID). It is a complex object when requesting user specific metadata. This complex object is usually the Objective-C representation of a JSON payload (e.g. ‘{“street”: “Main Avenue”, “buildings”: [“150”, “320”]}’ is translated in Objective-C as NSDictionary(“street” -> “Main Avenue”, “buildings” -> NSArray(“150”, “320”))). Sample metadata JSON object:
        {
            updated: 1334243471,
            encrypted: ["encryptedProp"],
            data: {
                zip: ["12345", "34567"],
                maxRating: {
                    "MPAA": "PG-13",
                    "VCHIP": "TV-Y",
                    "URL": "http://exam.pl/e/manage/ratings"
                },
                householdID: "3456",
                userID: "BgSdasfsdk23/dsaf3+saASesadgfsShggssd=",
                channelID: ["channel-1", "channel-2"]
            }

  • encrypted: Boolean value that specifies if the retrieved metadata is encrypted or not. This parameter is significant only for User Metadata requests, it has no meaning for Static Metadata (e.g., Authentication TTL) that is always received unencrypted. If this parameter is set to true, then it’s up to the Programmer to obtain the unencrypted User Metadata value by performing an RSA decryption using the whitelisting private key (the same private key that is used for the signing of the Requestor ID in the setRequestor:setSignedRequestorId: and setRequestor:setSignedRequestorId:serviceProviders: calls).

  • key: The key used to formulate the metadata retrieval request.

  • arguments: The same dictionary that was passed to the getMetadata: call. This is provided to allow the application to match the requests with the responses.

Triggered by: getMetadata:

More Information: User Metadata

Back to top…

MVPD mvpd

File: AccessEnabler/headers/model/MVPD.h

Description Describes the MVPD object. Can be used to obtain information about the MVPD’s properties.

Availability: v1.0+ [boardingStatus property is available from v2.2]

Properties:

  • (NSString) ID - The MVPD Id.

  • (NSString) displayName - The MVPD name. [This should be used to display in the picker]

  • (NSString) logoURL - The MVPD logo address.

  • (BOOL) enablePlatformServices - If true, the MVPD supports SSO services like Apple SSO.

  • (NSString) boardingStatus - Can have 3 values:

    • nil - The MVPD does not support Apple SSO.
    • PICKER - The MVPD can appear in Apple picker but the authentication flow is done by Adobe.
    • SUPPORTED - The MVPD is fully supported by Apple and will use Apple’s SSO token.

Back to top…

Tracking Events tracking

The AccessEnabler triggers an additional callback that is not necessarily related to the entitlement flows. Implementing the sendTrackingData() callback function is optional, but it enables the application to track specific events and compile statistics such as number of successful/failed authentication/authorization attempts.

sendTrackingData sendTracking

File: AccessEnabler/headers/EntitlementDelegate.h

Description Callback triggered by the AccessEnabler signaling to the application the occurrence of various events such as the completion/failure of authentication/authorization flows. With Adobe Pass Authentication 1.6, the device type, AccessEnabler client type, and operating system are reported by sendTrackingData(). The sendTrackingData() callback remains backwards compatible.

Callback: tracking events

(void) sendTrackingData:(NSArray *)data
             forEventType:(int)event;

Availability: v1.0+

Note: The device type and operating system are derived through the use of a public Java library (http://java.net/projects/user-agent-utils) and the user agent string. Be advised that this information is provided only as a coarse way to break down operational metrics into device categories, but that Adobe can take no responsibility for incorrect results. Please use the new functionality accordingly.

  • Possible values for device type:

    • computer
    • tablet
    • mobile
    • gameconsole
    • unknown

  • Possible values for AccessEnabler client type:

    • flash
    • html5
    • ios
    • android

Parameters:

  • event: the code of the event that is being tracked. There are three possible tracking events types:

    • authorizationDetection: any time an authorization token request returns (event is TRACKING_AUTHORIZATION)
    • authenticationDetection: any time an authentication check occurs (event is TRACKING_AUTHENTICATION)
    • mvpdSelection: when the user selects an MVPD in the MVPD selection form (event is TRACKING_GET_SELECTED_PROVIDER)

  • data: additional data that is associated to the reported event. This data is presented in the form of an list of values.

Triggered by: checkAuthentication, getAuthentication, getAuthentication, checkAuthorization:, checkAuthorization, getAuthorization:, getAuthorization, setSelectedProvider:

Instructions for interpreting the values in the data array:

  • For trackingEventType TRACKING_AUTHENTICATION:

    • 0 - Whether the token request was successful (true/false) and if successful:
    • 1 - MVPD ID string
    • 2 - GUID (md5 hashed)
    • 3 - Token already in cache (true/false)
    • 4 - Device type
    • 5 - AccessEnabler client type
    • 6 - Operating system type

  • For trackingEventType TRACKING_AUTHORIZATION:

    • 0 - Whether the token request was successful (true/false) and if successful:
    • 1 - MVPD ID
    • 2 - GUID (md5 hashed)
    • 3 - Token already in cache (true/false)
    • 4 - Error
    • 5 - Details
    • 6 - Device type
    • 7 - AccessEnabler client type
    • 8 - Operating system type

  • For trackingEventType TRACKING_GET_SELECTED_PROVIDER:

    • 0 - ID of the currently selected MVPD
    • 1 - Device type
    • 2 - AccessEnabler client type
    • 3 - Operating system type
recommendation-more-help
3f5e655c-af63-48cc-9769-2b6803cc5f4b