In order to use the XignSys SDK an instance of the XignSdk must be retrieved. Since the SDK is designed as a singleton
it is reasonable to retrieve the instance in the beginning of the application lifecycle, for example the AppDelegate,
SceneDelegate, SwiftUI-@main-struct on iOS and the Application's onCreate function on Android. The XignSdk class
can be initialized by invoking XignSdk.initialize(application:config:).
The first parameter expects the instance of the apps Application class (a Context on Android). The second parameter
is an optional configuration object. The configuration object XignSdkConfig can be used to change the behavior of the
XignSys SDK slightly and/or to supply additional resources that are not provided by default. For example, a
configuration can be used to provide key material for XignIn-Manager instances that are not the official XignSys
Server (https://xign.me) and/or service configurations for the InApp-Authentication feature.
Note: The initialization of the XignSdk could take some time depending on how much optional parameters are passed.
Depending on the given configuration and state of the device, the initialization of the XignSys SDK may raise an error
XignSdkError (XignSdkException). This error contains a property named errorCode of the type
XignSdkErrorCodes which represents all possible errors that could occur within the SDK. To filter these codes the
function XignSdkInitializationErrorCodes.from can be used. The resulting enum of the
type XignSdkInitializationErrorCodes represents only errors that are relevant during the initialization of the XignSys
SDK. The following example shows how the SDK can be initialized simply (without an additional configuration):
private func initializationWithErrorHandling() {
do {
try XignSdk.initialize(application: .shared)
} catch let xe as XignSdkError {
// map the general error to a specific error targeting the invoked function
let specificErrorCode = XignSdkInitializationErrorCodes.from(xe.errorCode)
// Handle the error cases according to their documentation. A default case should be avoided so
// new cases added in future SDK updates are not accidentally handled incorrectly.
switch specificErrorCode {
case .alreadyInitialized:
// Signalizes that the SDK has already been initialized.
break
case .deviceLockNotSet:
// Indicates that no device lock is set.
break
case .keyRemovedBySystem:
// Indicates that a key has been removed by the system, because it was protected by
// a device lock and that lock has been removed.
break
case .unexpectedError:
// Marks an unexpected exception. If available, the `cause` could be checked during
// development.
break
}
} catch {
// other errors that should not happen normally, because the SDK only throws errors of
// the type `XignSdkError`. But to be safe, this block should be handled in the same
// manner as the "unexpectedError" case.
}
}
private fun initializationWithErrorHandling(context: Context) {
try {
XignSdk.initialize(context = context)
} catch (xe: XignSdkException) {
// map the general error to a specific error targeting the invoked function
val specificErrorCode = XignSdkInitializationErrorCodes.from(xe.errorCode)
// Handle the error cases according to their documentation. A default case should be avoided so
// new cases added in future SDK updates are not accidentally handled incorrectly.
when (specificErrorCode) {
XignSdkInitializationErrorCodes.ALREADY_INITIALIZED -> {
// Signalizes that the SDK has already been initialized.
}
XignSdkInitializationErrorCodes.DEVICE_LOCK_NOT_SET -> {
// Indicates that no device lock is set.
}
XignSdkInitializationErrorCodes.KEY_REMOVED_BY_SYSTEM -> {
// Indicates that a key has been removed by the system, because it was protected by
// a device lock and that lock has been removed.
}
XignSdkInitializationErrorCodes.DEVICE_LOCKED -> {
// Indicates that keys could not be created/accessed because the device is currently locked.
}
XignSdkInitializationErrorCodes.UNEXPECTED_ERROR -> {
// Marks an unexpected exception. If available, the `cause` could be checked during
// development.
}
}
} catch (t: Throwable) {
// other errors that should not happen normally, because the SDK only throws errors of
// the type `XignSdkException`. But to be safe, this block should be handled in the same
// manner as the "UNEXPECTED_ERROR" case.
}
}
The error code alreadyInitialized signalizes that the XignSys SDK has already been initialized. If the configuration
of the SDK should be changed during runtime the SDK must be deinitialized beforehand. For that purpose please take a
look at the chapter Reset the SDK.
Whether the error codes keyRemovedBySystem, deviceLockNotSet and DEVICE_LOCKED (Android only) can occur depends on
the current state of the device and the configured "device lock required" policy within the XignSys SDK. These errors
are further discussed in the chapter Device lock required. Note that the XignSys SDK requires a
device lock by default, therefore these errors could occur and must be handled accordingly.
The unexpectedError summarizes all other errors that can not be simply handled. During development the cause of the
error can be checked and the code base optimized so that the error does not occur again. However, during runtime the
handling of this error is not that simple. First off, this error should not happen normally. But if it does the cause is
most likely relatively obscure. If the XignSys SDK is initialized at a later point in the application's life cycle as
recommended (not within AppDelegate / Application's onCreate) or "re-initialized", the first attempt to resolve
the issue could be to achieve a clean memory state, meaning to close/crash the app. If the problem still persists the
next step could be to wipe all persistent data of the SDK by invoking XignSdk.deinitialize(wipePersistentData: true).
Note that by doing so all previous setups are lost, e.g. personalized XignIn-Managers. Finally, if that still does not
resolve the error please contact us with a description of the situation so that we can examine it and supply an update
as soon as possible.