New APIs are created for Swift users of the iOS SDK. For more details, refer to the Xcode API documentation on OnlineActivationParameters and OnlineActivationDelegate.

The activation process must be initiated by calling the startActivation method of the Orchestrator object.

An OnlineActivationParams object must be provided as an input parameter of the startActivation method, and this OnlineActivationParams object must be initiated with the following parameters:

  • User identifier. A string which uniquely identifies the user on the OneSpan Trusted Identity platform.
  • Activation password. Secret data shared between the Customer Application Server and the user.
  • (OPTIONAL) Cryptographic Application Index. The index of the cryptographic application that must be used to sign the instance activation message. The default value is 1.
  • An object implementing the OnlineActivationCallback interface.

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

  • onActivationStepComplete. Called upon activation step success, the provided command must be sent to the server.
  • onActivationSuccess. Called upon activation process success.
  • onActivationInputError. Called upon activation process error due to incorrect user input. The possible errors are listed in the OrchestrationErrorCodes class.
  • onActivationAborted. Called when the activation process is canceled.

For more information about this feature, see Activation.

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
KeyDefault valueDescription
orch_pinpad_background_color#ffffffffBackground color
orch_pinpad_arrow_color#ffffc107Delete arrow color
orch_pinpad_input_color#ffffc107Secure input color
orch_pinpad_text_color#ff000000Title color
orch_pinpad_text_error_color#ffff0000Text error color
orch_pinpad_digit_color#ff000000Color 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.

PinPad.storyboard in XCode

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. Constraint not rendered in Interface builder

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.