mDocs Holder SDK/global.mattr.mobilecredential.holder/MobileCredentialHolder/initialise

initialise

suspend fun initialise(activity: Activity, instanceId: String = DEFAULT_INSTANCE_ID, userAuthRequiredOnInitialise: Boolean = true, loggerConfiguration: Logger.LoggerConfiguration? = null)

Initialise the MobileCredentialHolder SDK. The MobileCredentialHolder class is a singleton which can only be initialised with one instanceId at a time. After this initialise method has been called, all subsequent method calls in this class, such as [getTrustedIssuerCertificates], will return a result unique to the specified instanceId.

This function requires user authentication to execute successfully. If a suitable user authentication mechanism is not setup on the device OR authentication fails for some reason, suitable errors will be thrown.

An important behaviour to note is that after initialising the SDK for the first time, if the user disables user authentication on their device entirely and then re-enables it, they will no longer be able to initialise the SDK. A HolderException.UserAuthenticationUnrecoverableKeyException will be thrown as the decryption key stored in the android key store used to decrypt the storage will no longer be accessible. The instance must be deleted using the destroy API and re-initialised.

Parameters

activity

Android activity used to perform user authentication

instanceId

OPTIONAL Used to identify the instance to configure for the SDK initialisation This will load all certificates and credentials unique to this instance. If instance is empty, the default instance will be used.

userAuthRequiredOnInitialise

OPTIONAL parameter to configure whether user authentication (biometric or passcode) is required to unlock the storage. Default value is true. The SDK cannot accept further changes to this option with a particular instance id. HolderException.UserAuthenticationOnInitChangedException will be thrown if this option is changed.

loggerConfiguration

: Optional settings related to SDK logger

Throws

If the SDK was initialized with a different instanceId.

If the user cancels the authentication process.

If biometric authentication is locked out.

If the user has not set up authentication.

for general authentication failures.

If storage initialization fails.

If the provided instanceId is invalid.

If user key has been compromised.

If authentication changes during initialization.