Android¶
Alice Onboarding iOS SDK allows the automatic capture of documents and video selfie of the user in real time from the camera of your device. It also simplifies the communication with the onboarding API to facilitate rapid integration and development.
See also
Check the our GitHub repo to be aware of our latest releases.
1. Installation¶
Requirements¶
All versions of Android are supported since Android 5.0 (sdk 21).
Our configuration¶
minSdkVersion = 21
targetSdkVersion = 30
compileSdkVersion = 30
gradleVersion = 4.1.2
kotlinVersion = 1.6.21
Adding the SDK dependency¶
repositories {
mavenCentral()
maven {
url "https://alicebiometrics.jfrog.io/artifactory/alicebiometrics-maven-pro-local/"
}
}
dependencies {
implementation 'com.alicebiometrics.onboarding:AliceOnboarding:+'
}
2. Getting started¶
2.1 Permissions¶
Alice Onboarding needs to have the following permissions granted.
<uses-permission android:name="android.permission.CAMERA" />
2.2 Onboarding modes¶
You can integrate the onboarding process in two different ways: using a pre-configured flow, through the Onboarding
class,
or creating a manual flow, through the OnboardingCommands
class.
In the first case, you simply need to indicate to the SDK the flow you want: number and type of documents, order, etc. From this configuration, the SDK takes control and allows you to perform the entire onboarding process autonomously without having to worry about managing Alice Onboarding API calls. This is the fastest and easiest way to integrate AliceOnboarding in your application.
In the second case, no flow is specified. The onboarding process is completely free, allowing your application to manage the beginning and end of it, as well as the capture and upload of the different documents to the API. This case is indicated for an expert level of configuration, allowing you to split the onboarding process into different stages and add other tasks related to your customer flow (e.g. a form to be filled in by the user). If your interested in this mode, skip the following 2.3 and 2.4 sections and go to Onboarding Commands.
2.3 Config your Alice Onboarding¶
You can configure the onboarding flow with the OnboardingConfig
builder.
The following snippet configures:
A Selfie capture (
.withAddSelfieStage()
)Two different document stages for an Spanish ID Card and Driver License (
.withAddDocumentStage()
).A final stage to capture another trusted document (e.g. proof of address, bill…) (
.withAddOtherTrustedDocumentStage()
)
to see the configuration details of each stage go to section 4. Stages configuration
val userToken = "<ADD-YOUR-USER-TOKEN-HERE>"
val config = OnboardingConfig.builder()
.withUserToken(userToken)
.withAddSelfieStage()
.withAddDocumentStage(type = DocumentType.IDCARD, issuingCountry = "ESP")
.withAddDocumentStage(type = DocumentType.DRIVERLICENSE, issuingCountry = "ESP")
.withAddOtherTrustedDocumentStage(title = "Proof of address")
If you want the sdk to ask for the permissions internally, attach the following line:
config.askForPermission = true
Where userToken is used to secure requests made by the users on their mobile devices or web clients. You should obtain it from your Backend. Check it in authentication section.
2.5 Run Alice Onboarding¶
Once you configured the Alice Onboarding Flow, you can run the process with:
val onboarding = Onboarding(this, config = config)
onboarding.run(ONBOARDING_REQUEST_CODE)
}
}
...
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == ONBOARDING_REQUEST_CODE) {
if (resultCode == Activity.RESULT_OK) {
val userInfo = data!!.getStringExtra("userStatus")
} else if (resultCode == Activity.RESULT_CANCELED) {
}
}
}
3. Authentication¶
How can we get the userToken to start testing Alice Onboarding technology?
AliceOnboarding can be used with two different authentication modes:
- Trial test (Using Alice Onboarding Sandbox): ONLY to be used on demonstrators.
Pros: This mode does not need backend integration.
Cons: Security compromises. It must be used only for demonstrators.
- Production (Using your Backend): In a production deployment you must use your backend to obtain the required TOKENS.
Pros: Full security level. Only your backend is able todo critical operations.
Cons: Needs some integration in your backend.
3.1 Trial test¶
If you want to test the technology without integrate it with your backend, you can use our Sandbox Service. This service associates a user mail with the Alice Onboarding user_id. You can create a user and obtain his USER_TOKEN already linked with the email.
Use the TrialAuthenticator class to ease the integration.
val trialToken = "<ADD-YOUR-TRIAL-TOKEN-HERE>"
val userInfo = UserInfo(email = email, // required
firstName = firstName, // optional
lastName = lastName) // optional
val authenticator = TrialAuthenticator(trialToken = trialToken, userInfo = userInfo)
authenticator.execute { response ->
when (response) {
is Response.Success -> {
// Configure Alice Onboarding with the OnboardingConfig
// Then Run the Alice Onboarding Flow
// The userToken is contained on the response.message
}
is Response.Failure -> {
// Inform the user about Authentication Errors
}
}
}
Where trialToken is a temporary token for testing the technology in a development/testing environment.
An email parameter in UserInfo is required to associate it to an Alice Onboarding user_id. You can also add some additional information from your user as firstName and lastName.
3.2 Production¶
On the other hand, for production environments we strongly recommend to use your backend to obtain the required USER_TOKEN.
You can implement the Authenticator interface available in the AliceOnboarding library.
class MyBackendAuthenticator : Authenticator {
override fun execute(callback: (Response) -> Unit) {
// Add here your code to retrieve the user token from your backend
val userToken = "fakeUserToken"
callback(Response.Success(userToken))
}
}
In a very similar way to the authentication available with the sandbox:
val authenticator = MyBackendAuthenticator()
authenticator.execute { response ->
when (response) {
is Response.Success -> {
// Configure Alice Onboarding with the OnboardingConfig
// Then Run the Alice Onboarding Flow
}
is Response.Failure -> {
// Inform the user about Authentication Errors
}
}
}
4. Stages configuration¶
4.1 Document stage configuration parameters¶
- config = config.withAddDocumentStage(type = DocumentType.IDCARD,
issuingCountry = “ESP”, documentStageConfig = documentStageConfig)
withAddDocumentStage
has the following parameters (in order):
type
: type of document to capture. The enumDocumentType
can be used to indicate the type (id card, driver license, residence permit, passport, health insurance card).issuingCountry
: (Optional) country ISO 3166-1 alpha-3 code. If you don’t set it, a menu will be shown where the user can choose the country.documentStageConfig
: (optional) capture configuration parameters.
DocumentStageConfig
encapsulates different capture configuration parameters. Its constructor has the following parameters:
attemptsToShowManualAlert
: number of attempts of automatic capture before showing an alert giving the user the option to start a manual capture. Default value is 2.withTorchFlash
: boolean parameter to give the possibility to turn on the flash in the capture.
4.2 Other Trusted Document stage configuration parameters¶
This functionality is an easy way to have a document that is not necessarily identification (e. g. proof of address, bill…).
There are two ways to use this feature:
Uploading a file: It must be a pdf file and less than 10 MB in size.
Capturing your document: You can add the sheets that are needed from your document. After each capture you can check if the image is correct and to finish you will press the send button that joins all the captures made and will generate a pdf.
withAddOtherTrustedDocumentStage
has two arguments:
title
: a title for this section during the onboarding process.category
: this argument is required if your flow requires multiple documents. You must use this argument to tag each document, for example if your flow requires an invoice and a payslip you could use “invoice” and “payslip” as categories.
5. Customisation¶
To improve the onboarding experience into your look and feel, Alice onboarding allows you to customise onboarding stages using your own style.
5.1. General & Fast Customisation¶
Colors¶
You can define certain colors inside your own colors.xml file.
onboardingPrimary: Defines button colors and main text.
onboardingSecondary: Defines secondary text (Helping info).
onboardingBackgroundColor: Defines the background color.
Font¶
You can define your regular and bold font inside your own styles.xml file.
<style name="onboardingClassicFontBold">
<item name="android:fontFamily">sans-serif-medium</item>
</style>
<style name="onboardingClassicFontRegular">
<item name="android:fontFamily">sans-serif</item>
</style>
and then select the classic font theme:
<style name="onboardingFontTheme">
<item name="fontTheme">Classic</item>
</style>
5.2. Theme customisation¶
We provide you up to 3 different themes to customize fonts and icons.
Font theme¶
You can change the default font between three different options. Just define onboardingFontTheme inside your own styles.xml file.
<style name="onboardingFontTheme">
<item name="fontTheme">Classic</item>
</style>
Available values:
<attr name="fontTheme">
<enum name="Corporative" value="0" />
<enum name="Classic" value="1" />
<enum name="Modern" value="2" />
</attr>



Icons Theme¶
You can change the default icons theme between three different options. Just define onboardingIconsTheme inside your own styles.xml file.
<style name="onboardingIconsTheme">
<item name="iconsTheme">Classic</item>
</style>
Available values:
<attr name="iconsTheme">
<enum name="Classic" value="0" />
<enum name="Minimal" value="1" />
<enum name="Modern" value="2" />
</attr>



Icons Style¶
You can change the default icons style between three different options. Just define onboardingIconsStyle inside your own styles.xml file.
<style name="onboardingIconsStyle">
<item name="iconsStyle">Circle</item>
</style>
Available values:
<attr name="iconsStyle">
<enum name="Circle" value="0" />
<enum name="Shape" value="1" />
<enum name="Square" value="2" />
</attr>



5.3 Fine customisation¶
If you want a more specific customisation without using the default themes this is your section.
There are 4 views and 1 alert dialog with configurable values:

Define certain colors inside your own colors.xml
<color name="statusViewBackgroundColor">@color/onboardingColorWhite</color>
<color name="statusViewCardBackgroundColor">@color/onboardingColorWhite</color>
<color name="statusIconBackgroundColor">@color/onboardingColorWhite</color>
<color name="statusViewContinueButtonColor">@color/onboardingPrimary</color>
To change text appearance, define inside your own styles.xml
<style name="statusViewTitleTextAppearance">
<item name="android:textSize">24dp</item>
<item name="android:textColor">@color/onboardingPrimary</item>
</style>
<style name="statusViewSubtitleTextAppearance"> . . . </style>
<style name="statusViewButtonTextAppearance"> . . . </style>
<style name="statusViewCardTextAppearance"> . . . </style>
To change icons, first set the onboardingIconsTheme to Custom inside your own styles.xml
<style name="onboardingIconsTheme">
<item name="iconsTheme">Custom</item>
</style>
and then define inside your own drawable folder the following resources (at least 50x50 dp):
onboarding_arrow.xml
onboarding_face.xml
onboarding_id_card.xml
onboarding_driver_license.xml
onboarding_passport.xml
onboarding_resident_permit.xml
SelfieCaptureView¶

Define certain colors inside your own colors.xml
<color name="captureViewBackgroundColor">@color/onboardingColorWhite</color>
<color name="captureViewGradientStartColor">#0CFFFFFF</color>
<color name="captureViewGradientEndColor">#FFFFFFFF</color>
<color name="selfieCaptureViewEdgeRightMaskColor">@color/onboardingColorGreen</color>
<color name="selfieCaptureViewWrongMaskColor">@color/onboardingColorWhite</color>
To change text appearance, define inside your own styles.xml
<style name="selfieCaptureViewTitleTextAppearance">
<item name="android:textSize">24dp</item>
<item name="android:textColor">@color/onboardingPrimary</item>
</style>
<style name="selfieCaptureViewSubtitleTextAppearance"> . . . </style>
DocumentIntermediateView¶

Define certain colors inside your own colors.xml
<color name="documentIntermediateViewBackgroundColor">@color/onboardingColorWhite</color>
<color name="documentIntermediateCardBackgroundColor">@color/onboardingColorWhite</color>
To change text appearance, define inside your own styles.xml
<style name="documentIntermediateViewTitleTextAppearance">
<item name="android:textSize">24dp</item>
<item name="android:textColor">@color/onboardingPrimary</item>
</style>
<style name="documentIntermediateViewSubtitleTextAppearance"> . . . </style>
<style name="documentIntermediateViewCardTextAppearance"> . . . </style>
To change icons, define inside your own drawable folder the following resources:
onboarding_doc_mask_front.xml
onboarding_doc_mask_back.xml
DocumentCaptureView¶

Define certain colors inside your own colors.xml
<color name="captureViewBackgroundColor">@color/onboardingColorWhite</color>
<color name="captureViewGradientStartColor">#0CFFFFFF</color>
<color name="captureViewGradientEndColor">#FFFFFFFF</color>
<color name="documentCaptureViewRetryButtonBackgroundColor">@color/onboardingColorTransparent</color>
<color name="documentCaptureViewSendButtonBackgroundColor">@color/onboardingPrimary</color>
<color name="documentCaptureViewTriggerCameraButtonColorStroke">@color/onboardingColorGray</color>
<color name="documentCaptureViewTriggerCameraButtonColorBackground">@color/onboardingSecondary</color>
To change text appearance, define inside your own styles.xml
<style name="documentCaptureViewTitleTextAppearance">
<item name="android:textSize">24dp</item>
<item name="android:textColor">@color/onboardingPrimary</item>
</style>
<style name="documentCaptureViewSubtitleTextAppearance"> . . . </style>
<style name="documentCaptureViewInfoTextAppearance"> . . . </style>
<style name="documentCaptureViewSendButtonTextAppearance"> . . . </style>
<style name="documentCaptureViewRetryButtonTextAppearance"> . . . </style>
To change icons, define inside your own drawable folder the following resources:
onboarding_back_id_template_no_frame.xml
onboarding_front_id_template_no_frame.xml
onboarding_passport_template_no_frame.xml
onboarding_front_driver_license_no_frame.xml
onboarding_back_driver_license_no_frame.xml
onboarding_front_resident_permit_template_no_frame.xml
onboarding_back_resident_permit_template_no_frame.xml
Alert dialog¶
Define certain colors inside your own colors.xml
<color name="customAlertDialogTitleColor">@color/onboardingPrimary</color>
<color name="customAlertDialogSubtitleColor">@color/onboardingSecondary</color>
<color name="customAlertDialogButtonColor">@color/onboardingPrimary</color>
5.4 Localisation¶
Alice Onboarding SDK provides several default translations for the following locales:
Locale |
Code |
---|---|
Catalan |
ca |
German |
de |
English |
|
English in United Kingdom |
en-rGB |
English in Ireland |
en-rIE |
English in United States |
en-rUS |
Spanish |
es |
Spanish in Spain |
es-rES |
Basque |
eu |
French |
fra |
Italian |
it |
Galician |
gl |
Polish |
pl |
Portuguese |
pt |
Portuguese in Brazil |
pt-rBR |
Russian |
ru |
Turkish |
tr |
Simplified chinese |
zh |
By default, the SDK infers what is the default language to use. If locale does not exist, it uses English.
In addition, you can also provide custom translations (or different texts) to clarify whatever you want in your app.
To do this, you just need to add an additional XML string file inside your app resources folder for the desired locale (e.g res/values-{<LOCALISATION-CODE>}/alice_onboarding_strings.xml
). In this way, you can overwrite the text keys that you want to change.
In order to know which text keys you can modify, please check the following examples:
English string-en.xml
Spanish string-es.xml
6. Troubleshooting¶
java.lang.ExceptionInInitializerError on launch (versions >= 1.5.1)
If you are using versions greather than or equal to 1.5.1 and the application crashes on launch and the trace it’s like this:
Caused by java.lang.ExceptionInInitializerError
at kotlin.reflect.jvm.internal.impl.builtins.DefaultBuiltIns.getInstance(DefaultBuiltIns.java)
at kotlin.reflect.jvm.internal.impl.types.ErrorUtils$1.getBuiltIns(ErrorUtils.java:139)
at kotlin.reflect.jvm.internal.impl.resolve.descriptorUtil.DescriptorUtilsKt.getBuiltIns(Descriptor
....
Caused by: java.lang.IllegalStateException: No BuiltInsLoader implementation was found. Please ensure that the META-INF/services/ is not stripped from your application and that the Java virtual machine is not running under a security manager
The error is caused by proguard. You can fix this by adding these new rules:
-keep interface kotlin.reflect.jvm.internal.impl.builtins.BuiltInsLoader
-keep class kotlin.reflect.jvm.internal.impl.serialization.deserialization.builtins.BuiltInsLoaderImpl
Note
This will be fixed on future versions of the library since it’s already fixed on the upstream of the faulty dependency