Exposed APIs of the Orchestration SDK

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

The Customer Mobile Application can initialize a notification registration process by calling the startNotificationRegistration method of the Orchestrator object.

A NotificationRegistrationParams object must be provided as an input parameter of the startNotificationRegistration method; this NotificationRegistrationParams object must be initiated with the following parameters:

• User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.

• Notification identifier. Uniquely identifies an app on a given device in the context of push-notification-based authentication. Defined by the notification service (i.e. Apple or Google).
• An object implementing the NotificationRegistrationCallback interface.

The NotificationRegistrationCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the notification registration process. It exposes the following methods:

• onNotificationRegistrationStepComplete: Called when a step of the notification registration process is complete. The provided orchestration command must be sent to the server.
• onNotificationRegistrationSuccess: Called upon successful notification registration.

For more information about this feature, see Notification registration.

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

The Customer Mobile Application must call the setRemoteAuthenticationCallback method and provide an implementation of the RemoteAuthenticationCallback interface to process a remote authentication flow.

The RemoteAuthenticationCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the remote authentication process. It exposes the following methods:

• onRemoteAuthenticationDisplayData. Called when the Orchestration SDK needs the RemoteAuthenticationCallback interface implementation to display data for approval by the user.
  • The Customer Mobile Application must call the onDataApproved method of the DisplayDataCaller object if the user approves the authentication request.
  • The Customer Mobile Application must call the onDataRejected method of the DisplayDataCaller object if the user rejects the authentication request.
• onRemoteAuthenticationStepComplete. Called when a step of the remote authentication process is complete. The provided orchestration command must be sent to the server.
• onRemoteAuthenticationSuccess. Called upon remote authentication success. It can also be called to notify the Customer Mobile Application that the rejected request has been taken into account by the Customer Application Server.
• onRemoteAuthenticationSessionOutdated. Called when the remote authentication session is outdated (expired, already approved, or already rejected).
• onRemoteAuthenticationAborted. Called when remote authentication is canceled.
• onRemoteAuthenticationPasswordError. Called upon remote authentication process error due to incorrect user input. The possible errors are listed in the OrchestrationErrorCodes class.

For more information about this feature, see Remote authentication.

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

The Customer Mobile Application must call the setRemoteTransactionCallback method and provide an implementation of the RemoteTransactionCallback interface to process a remote transaction flow.

The RemoteTransactionCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the remote transaction process. It exposes the following methods:

• onRemoteTransactionDisplayData. Called when the Orchestration SDK needs the RemoteTransactionCallback interface implementation to display data for approval by the user.
  • The Customer Mobile Application must call the onDataApproved method of the DisplayDataCaller object if the user approves the transaction request.
  • The Customer Mobile Application must call the onDataRejected method of the DisplayDataCaller object if the user rejects the transaction request.
• onRemoteTransactionStepComplete. Called when a step of the remote transaction process is complete. The provided orchestration command must be sent to the server.
• onRemoteTransactionSuccess. Called upon remote transaction success. It can also be called to notify the Customer Mobile Application that the rejected request has been taken into account by the Customer Application Server.
• onRemoteTransactionSessionOutdated. Called when the remote transaction session is outdated (expired, already approved, or already rejected).
• onRemoteTransactionAborted. Called when remote transaction is canceled.
• onRemoteTransactionPasswordError. Called upon remote transaction process error due to incorrect user input. The possible errors are listed in the OrchestrationErrorCodes class.

For more information about this feature, see Remote transaction.

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

The Customer Mobile Application can initialize a local authentication process by calling the startLocalAuthentication method of the Orchestrator object.

A LocalAuthenticationParams object must be provided as an input parameter of the startLocalAuthentication method; this LocalAuthenticationParams object must be initiated with the following parameters:

• User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.

• Cryptographic Application Index. The index of the cryptographic application which must be used to generate the OTP.
• (OPTIONAL) Challenge. A string which can be used to diversify the OTP generation. If the crypto-app index is related to a Challenge/Response application, a challenge parameter must be provided.
• Protection Type. The authentication method which must be used to authenticate the user before the OTP is generated (see Authentication methods for more information).
• An object implementing the LocalAuthenticationCallback interface.

The LocalAuthenticationCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the local authentication process. It exposes the following methods:

• onLocalAuthenticationSuccess: Called upon local authentication success. It returns the generated OTP and, depending on the Digipass configuration, a host code (used to authenticate the authentication server on which the OTP has been submitted).
• onLocalAuthenticationAborted: Called when local authentication is canceled.
• onLocalAuthenticationPasswordError: Called upon a local authentication process error due to incorrect user input. The possible errors are listed in the OrchestrationErrorCodes class.

For more information about this feature, see Local authentication.

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

The Customer Mobile Application can initialize a local transaction process by calling the startLocalTransaction method of the Orchestrator object.

A LocalTransactionParams object must be provided as an input parameter of the startLocalTransaction method; this LocalTransactionParams object must be initiated with the following parameters:

• User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.

• Cryptographic Application Index. The index of the cryptographic application which must be used to generate the signature.
• Data Fields. The transaction data to sign. A list of max. 8 data fields; the length of the data fields is limited to 16 characters.
• Protection Type. The authentication method which must be used to authenticate the user before signing the transaction (see Authentication methods for more information).

The LocalTransactionCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the local transaction process. It exposes the following methods:

• onLocalTransactionSuccess. Called upon local transaction success. It returns the generated signature and, depending on the Digipass configuration, a host code (used to authenticate the authentication server on which the signature has been submitted).
• onLocalTransactionAborted. Called when local transaction is cancelled.
• onLocalTransactionPasswordError. Called upon a local transaction process error due to incorrect user input. The possible errors are listed in the OrchestrationErrorCodes class.

For more information about this feature, see Local transaction.

Customization of integrated authentication

The texts related to the authentication methods can be customized using the keys listed in Virtual keypad - Text customization keys in the configuration files of the Customer Mobile Application (i.e. string.xml for Android and Localizable.strings for iOS).

Virtual keypad - Text customization keys

Key	Default value	Description
orch_pinpad_text_registration	Choose a password	Registration text
orch_pinpad_text_registration_confirm	Confirm your password	Confirmation text during registration
orch_pinpad_text_authentication	Enter your password	Text for authentication
orch_pinpad_text_update	Choose a new password	Text for updating the password
orch_pinpad_text_update_confirmation	Confirm new password	Text for confirming the updated password
orch_pinpad_error_weak	The password is too simple. Choose a more complex password.	Weak password error
orch_pinpad_error_confirmation	The password confirmation has failed. Make sure you entered the same password twice.	Password confirmation error

Biometric recognition

Key	Default value
orch_biometric_title	Biometric Authentication
orch_biometric_description	Please, use your Biometric scanner to authenticate
orch_biometric_failed	Authentication failed
orch_biometric_btn_cancel	Cancel

The color can be customized using the keys listed in Virtual keypad - Color customization keys in the configuration files of the Customer Mobile Application (i.e. color.xml for Android and Localizable.strings for iOS).

u

Virtual keypad - Color customization keys

Key	Default value	Description
orch_pinpad_background_color	#ffffffff	Background color
orch_pinpad_arrow_color	#ffffc107	Delete arrow color
orch_pinpad_input_color	#ffffc107	Secure input color
orch_pinpad_text_color	#ff000000	Title color
orch_pinpad_text_error_color	#ffff0000	Text error color
orch_pinpad_digit_color	#ff000000	Color of the Virtual keypad digits

The font size can be customized using the keys listed in Virtual keypad - Font size customization keys in the configuration files of the Customer Mobile Application (i.e. dimens.xml for Android and Localizable.strings for iOS).

Virtual keypad - Font size customization keys

Key	Android Default value	iOS Default value	Description
orch_pinpad_input_empty_size	N/A	15	Secure input inactive font size, only on iOS
orch_pinpad_input_full_size	N/A	20	Secure input active font size, only on iOS
orch_pinpad_title_text_size	20sp	25	Title font size
orch_pinpad_text_error_size	18sp	16	Text error font size
orch_pinpad_digit_text_size	40sp	50	Font size of the Virtual keypad digits

The other graphical elements are defined differently on iOS and Android.
For iOS, you can define these by customizing the keys listed in Virtual keypad - Graphical elements customization keys for iOS in the configuration files of the Customer Mobile Application (i.e. Localizable.strings).

Virtual keypad - Graphical elements customization keys for iOS

Key	Default value	Description
orch_pinpad_background_image		Background image (can be empty)
orch_pinpad_background_mode	fit	Background image display mode. Possible values: center fit stretch
orch_pinpad_arrow_image	backspace	Delete arrow image
orch_pinpad_input_font_name		Secure input font (System if empty)
orch_pinpad_input_empty_character	□	Secure input empty character
orch_pinpad_input_full_character	■	Secure input full character
orch_pinpad_text_font_name	HelveticaNeue-Light	Title font name
orch_pinpad_text_error_font_name	HelveticaNeue	Text error font name
orch_pinpad_digit_font_name	HelveticaNeue-UltraLight	Font name of the Virtual keypad digits

For Android, the font can be customized by overriding the styles listed in Virtual keypad - Font customization for Android in the configuration files of the Customer Mobile Application (i.e. styles.xml).

Virtual keypad - Font customization for Android

Style	Default font family name	Description
PinpadTitleFont	sans-serif-thin	Title font style
PinpadErrorFont	sans-serif-thin	Text error font style
PinpadDigitFont	sans-serif-thin	Font style of the Virtual keypad digits

For Android, the secure input and the backspace arrow can be customized by overriding the drawable elements listed in Virtual keypad - Drawable element customization for Android in the configuration files of the Customer Mobile Application (i.e. in the drawable folder).

Virtual keypad - Drawable element customization for Android

Drawable	Description
orch_pinpad_backspace.xml	Delete arrow drawable
orch_pinpad_clue_activated.xml	Secure input full drawable
orch_pinpad_clue_deactivated.xml	Secure input empty drawable
orch_pinpad_clue_highlighted.xml	Secure input highlighted drawable
orch_pinpad_background_image.xml	Virtual keypad background drawable, can be overridden by an image.

For Android, the Virtual keypad background can be customized in multiple ways:

• by changing its background color, as indicated in the Virtual keypad color table
• by overriding its background image, as indicated in the Virtual keypad drawable table
• by overriding its layout in the configuration files of the Customer Mobile Application (i.e. in the layout folder)

Virtual keypad - Background customization for Android

Layout	Description
orch_pinpad_background_layout.xml	Layout of the Virtual keypad background; the background image can be changed by using the android:src key.

Dark mode support for iOS

In the iOS sample, a file named PinPad.storyboard is available.

This file makes it possible to customize fonts, icon and colors. The Dark mode is managed by declaring named colors in the assets catalog (Assets.xcassets) or by using system colors.

The storyboard will take over the string customization as soon as it is added to the integrating project.

This storyboard contains a lot of links to outlets defined inside the OrchestrationSDK. These links can't be restored if they are removed.

The error you see in the storyboard is perfectly normal and doesn't make the compilation fail.

External user authentication

We also provide an option to override the user authentication. For example instead of displaying the integrated Virtual keypad, you can display your own password authentication.

The Customer Mobile Application must call the setUserAuthenticationCallback method and provide:

• an implementation of the UserAuthenticationCallback interface that will be called when an overridden user authentication is required.
• a list of UserAuthenticationType containing all the user authentication you want to override. For now only the UserAuthenticationType.PASSWORD can be overridden.

The UserAuthenticationCallback interface is used by the Orchestration SDK Client to interact with the Customer Mobile Application during the process of overridding the user authentication. It exposes the following methods:

• onUserAuthenticationRequired. Called when the Orchestration SDK Client needs the UserAuthenticationCallback object to authenticate the end user.

  • The Customer Mobile Application must call the onUserAuthenticationInputSuccess method of the UserAuthenticationInputCallback object if the user is authenticated. An input from the user is expected, it may be used to derive the secret store in the device.
  • The Customer Mobile Application must call the onUserAuthenticationInputAborted method of the UserAuthenticationInputCallback object if the user aborts the user authentification.
• onUserAuthenticationInputError. This is called when the Orchestration SDK Client needs to inform the UserAuthenticationCallback method that there is an issue with the input.

  For iOS, different names are used: UserAuthenticationCallback is called UserAuthenticationDelegate, and UserAuthenticationInputCallback is called UserAuthenticationInputDelegate.

For more information about this feature, see Authentication methods.

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

The Customer Mobile Application can initialize a change password process by calling the startChangePassword method of the Orchestrator object.

A ChangePasswordParams object must be provided as an input parameter of the startChangePassword method.

The ChangePasswordParams object must be initiated with the following parameters:

• User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.

• Cryptographic Application Index: The index of the cryptographic application which must be used to generate the OTP.
• An object implementing the ChangePasswordCallback interface.

The ChangePasswordCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the change password process. It exposes the following methods:

• onChangePasswordStepComplete. Called when a step of the change password process is complete. The provided orchestration command must be sent to the server.
• onChangePasswordSuccess. Called upon successful change of the password.
• onChangePasswordAborted. Called when changing the password is cancelled.
• onChangePasswordInputError. Called upon an error in the change password process due to incorrect user input. The possible errors are listed in the OrchestrationErrorCodes class.

For more information about this feature, see Change password.

The Customer Mobile Application can initialize user enrollment for authentication via face recognition by calling the enrollFace method of the UserAuthenticationMethodManager object.

The UserAuthenticationMethodManager object must be retrieved using the getUserAuthenticationMethodManager method of the Orchestrator object.

A FaceEnrollmentParams object must be provided as an input parameter of the enrollFace method.

The FaceEnrollmentParams object must be initiated with the following parameters:

• User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.

• An object implementing the FaceEnrollmentCallback interface.

The FaceEnrollmentCallback interface is used by the Orchestration SDK to interact with the Customer Mobile Application during the biometric enrollment process. It exposes the following methods:

• onFaceEnrollmentSucceed. Called upon a successful enrollment process.
• onFaceEnrollmentCanceled. Called when the enrollment process is canceled.
• onFaceEnrollmentError. Called upon an enrollment process error. The possible errors are listed in the OrchestrationErrorCodes class.

For more information about this feature, see Features of the Orchestration SDK.

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

Device data collection can be optionally configured with a CDDCParams object. The following parameters can be configured:

• Refresh interval. The interval (in seconds) at which device data is refreshed. Default: 60 seconds.
• Optional device data. The collection of certain device data types (i.e. geolocation, Bluetooth, and Wi-Fi) requires specific permissions. By default, these data types are not collected. For more information about required permissions on Android, see Integrating the Orchestration SDK.

Most of the device data is collected automatically by the Orchestration SDK. Device data which cannot be collected automatically can be provided by the Customer Mobile Application, by using the CDDCDataFeeder object.

The CDDCDataFeeder object must be retrieved using the getCDDCDataFeeder method of the Orchestrator object.

The Orchestrator object provides the getCDDCMessage method to transmit the collected device data to the OneSpan Trusted Identity platform without using an orchestration command.

A CDDCMessageParams object must be provided as an input parameter of the getCDDCMessage method.

The CDDCMessageParams object must be initiated with the following parameters:

• User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.

• Encrypted. Indicates whether the data must be encrypted.
• Event Name. A string representing an event related to the collected data. For more information, refer to the Client Device Data Collector SDK Integration Guide.
• Application Data. A JSON string representing additional data to add in the CDDC message. For more information, refer to the Client Device Data Collector SDK Integration Guide.

For more information about this feature, see Device data collection.

The UserManager object provides the following methods:

• getUsers. Lists the activated users.
• isUserActivated. Checks whether the provided user identifier corresponds to an activated user.
• getUserInformation. Retrieves the information related to a specific user.
• deleteUser. Deactivates a specified user.

The UserManager object must be retrieved using the getUserManager method of the Orchestrator object.

For more information about this feature, see Multi-user management.