Digipass S3 is now DigipassONE. This section is currently being updated to reflect our new name.

Customizing the biometric UI

  • Updated on Apr 3, 2026
  • Published on Nov 25, 2025
  • 3 minute(s) read
Prev Next

Authentication fallback option

If the user is unable to successfully scan their face or chooses not to use Face ID, your app can provide the user with a different method of authentication. This is called "fallback."

The image above shows the dialog box that the Face ID authenticator displays to the user in a fallback situation. The end user can tap Use alternate authentication to sign in with a different method.

To provide the user with a fallback option, create an extension that the App SDK passes to the Face ID authenticator. The extension contains information that tells the authenticator to change its appearance and behavior when the user's Face ID doesn't match or if they cancel the Face ID scan.

var extensions : [Any]? = nil
SampleExtensions.useFallbackFunctionality(ext: &extensions, fallbackTitle: "Use alternate authentication")

The fallbackTitle contains the display text for the button. After you create the extension, add it to extras and then pass extras to the SDK when your app calls any authentication method.

TAUtils.addExtensionsToExtras(extras: &extras, ext: extensions!)

If the user taps Use alternate authentication, the App SDK's authentication method (either NNLAdaptiveUI.getAuthenticationView() or NNLAdaptiveUI.authenticate()) returns FidoStatusEnum.FALLBACK.rawValue. Your code checks for this result and has the user perform the alternate authentication of your choice.

Working Example in Tutorial App

  • Refer to file SampleExtensions.swift for more details on how to create an extension.

  • Refer to file TAUtils.swift for more details on how to add extensions to extras.

Customizing biometric authentication behavior

You can customize the biometric authenticator to better suit your needs. For example, when you need to migrate existing end users of your company's apps from non-FIDO fingerprint authentication to FIDO fingerprint authentication. Your end users would need to enter their fingerprint twice: once to login to your app and a second time to complete FIDO registration.

For a better user experience, you can disable the biometric scan to get the following user interaction:

  • A customer signs in to your app using their fingerprint with the existing non-FIDO fingerprint authentication.

  • Your app initiates a FIDO registration.

  • The App SDK processes that registration request without requiring the customer to rescan their fingerprint.

By default, biometric authentication requires a biometric scan. If the user has already gone through this process, it is inconvenient to repeat it. If there is an LAContext available, you can reuse the biometric scan for registration, authentication, and transaction confirmation.

The App SDK provides a delegate, called BiometricContextDelegate, for getting LAContext.

In your application you need to implement the BiometricContextDelegate delegate:

// Implementation of BiometricContextDelegate.
func getLAContext() -> LAContext! {
     //reset the delegate so it is not used multiple times
     return self.laContext;
}

If you have the authenticated context you need to set the delegate before starting a registration, authentication, or transaction confirmation operation:

self.mLAContext = context;
BiometricContext.setDelegate(self)

Once the FIDO operation completes you can reset the delegate to avoid using context during other operations:

BiometricContext.setDelegate(nil)

Working example in Tutorial App

  • SampleSignUpViewController.swift and MiscellaneousOptionsViewController.swift show how to implement and set the delegate.

Managing changes to enrolled fingerprints

On Touch ID equipped iOS devices, all the fingerprints enrolled on the device can be used to unlock a key stored within the Secure Enclave. For security-sensitive applications, it is important to take action when a new fingerprint is added to the device, such as asking the user to authorize the new fingerprint.

The App SDK has the following behavior when the maximum number of incorrect retries is exhausted:

  • The App SDK returns the error
    Authentication failed with Client error:fidoStatus=1
    after three failed attempts. If the user continues to present the wrong finger, they are asked to use an alternate registration. If the user continues to present the wrong finger, App SDK returns the error
    Fido Auth method failed with Client error: fidoStatus=23

Selecting Touch ID behavior

The different Touch ID behaviors on iOS are implemented as different authenticators. By specifying policies on the Digipass S3 Server to select a particular authenticator, you can select the appropriate behavior for your application.

For Touch ID authenticators: if the user exceeds the maximum number of failed retries, iOS prompts the user to enter the device passcode before allowing the user to authenticate using Touch ID again. The Passcode or Touch ID authenticator can be used in situations where you want to allow authentication using either passcode or fingerprint. Face ID-compatible devices use the Touch ID authenticators.