Exposed APIs of the Orchestration SDK: Core

The Orchestration SDK contains a native interface for Swift. This interface provides native Swift methods and objects. It offers the same logical flow as the Objective-C interface but provides better signatures and more data on orchestrator instances. The Swift sample app delivered with the Orchestration SDK package uses the relevant Swift APIs, and the README.md file delivered with the sample app contains examples and code snippets.

Entry point

The Orchestrator class is the entry point of the Orchestration SDK. It manages the flows related to the features of the SDK by providing methods to start these flows (e.g. startActivation) and to interpret the orchestration commands received from the OneSpan Trusted Identity platform (via the execute method).

An Orchestrator object must be created by using the dedicated Orchestrator.Builder class.

The following parameters must be defined when building an Orchestrator object:

• Hardcoded salts, which will be used for weak diversification with certain security features (e.g. device binding, secure storage). These salts will be derived by the Orchestration SDK to complicate reverse-engineering attacks.

• Default domain, as configured in the OneSpan Trusted Identity platform. If the Customer Mobile Application must manage multiple domains, the default domain can be dynamically overwritten for each action (e.g. startActivation).

• Android only: A Context object is required for using the native features of the mobile device (e.g. data storage).

• Android only: An ActivityProvider object is required to properly display and handle the Biometric and PinPad dialog.

• A CDDCParams object, which will define the parameters for device data collection. These parameters are optional; default parameters are hardcoded in the Orchestration SDK. For more information, see Device data collection.

• An OrchestrationErrorCallback object, which will be used to throw errors from the Orchestration SDK to the Customer Mobile Application. For more information, see Error and warning management.

• An OrchestrationWarningCallback object, which will be used to throw warnings from the Orchestration SDK to the Customer Mobile Application. For more information, see Error and warning management.

New APIs are created for Swift users of the iOS SDK. For more information, refer to the Xcode API documentation on CDDCParameters, OrchestrationErrorDelegate and OrchestrationWarningDelegate.

Error and warning management

Error

Errors are thrown via the onOrchestrationError method of the OrchestrationErrorCallback object. The OrchestrationError object provides error codes and the cause of the error. The possible errors are listed in the OrchestrationErrorCodes class.

Warning

Warnings are thrown via the onOrchestrationWarning method of the OrchestrationWarningCallback object. The OrchestrationWarning object provides warning codes and the cause of the warning, as well as a list of all possible warning codes. The possible errors are listed in the OrchestrationWarningCodes class.

New APIs are created for  Swift users of iOS SDK. Please consult Xcode API documentation provided on OrchestrationErrorDelegate and OrchestrationWarningDelegate. All possible errors are listed under OrchestrationError enum and all possible warnings are listed under OrchestrationWarning enum.

Callback mechanism

The Orchestration SDK uses asynchronous mechanisms to execute the flows related to the features of the SDK.

Callback methods are used to notify the Customer Mobile Application when an action related to a specific flow is finished (e.g. the activation has succeeded) or requires action of the Customer Mobile Application (e.g. perform a network request with the given orchestration command).

The callback methods are called from the UI thread on Android, and from the main thread on iOS.

The Customer Mobile Application must provide an implementation of the dedicated callback methods to receive these notifications.

Callback registration is required for the following features:

• Activation

• Remote authentication

• Remote transaction

• Local authentication

• Local transaction

• Change password

• Notification registration

Application life cycle

On Android, to properly display UI components such as the virtual keypad, the Orchestrator object is life-cycle-aware.

For the Orchestrator object to work properly, an instance of the ActivityProvidor is required. This returns weak references to the current Activity object.

This requirement does not apply to applications on iOS.