iOS¶
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¶
The AliceOnboarding component is available on Cocoapods. You can add the component to your projects adding the following code to your Podfile:
pod 'AliceOnboarding'
Install it with:
pod repo update
pod install
Note
If your Podfile post_install does not set the BUILD_LIBRARY_FOR_DISTRIBUTION flag to YES, you need
to set it for both Alamofire and Yams pods at their Build Options settings.
or add the following lines in your Podfile:
post_install do |installer|
installer.pods_project.targets.each do |target|
if target.name == "Alamofire" || target.name == "Yams"
target.build_configurations.each do |config|
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
end
end
end
end
2. Getting started¶
2.1 Import the library¶
import AliceOnboarding
2.3 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.4 and 2.5 sections and go to Onboarding Commands.
2.4 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
let userToken = "<ADD-YOUR-USER-TOKEN-HERE>"
let config = OnboardingConfig.builder()
.withUserToken(userToken)
.withAddSelfieStage()
.withAddDocumentStage(ofType: .idcard, issuingCountry: "ESP")
.withAddDocumentStage(ofType: .driverlicense, issuingCountry: "ESP")
.withAddOtherTrustedDocumentStage(title: "Proof of address")
If you want the sdk to ask for the permissions internally, attach the following line:
config.askForPermissions(settingsUrl: UIApplication.openSettingsURLString)
Configured userToken is used to secure requests made by the users on their mobile devices or web clients. You should
obtain it from your Backend (see)
2.5 Run Alice Onboarding¶
Once you have configured the Alice Onboarding Flow, you can run the process with:
let onboarding = Onboarding(self, config: config)
onboarding.run { result in
switch result {
case let .success(userStatus):
print("userStatus: \(String(describing: userStatus))")
case let .failure(error):
print("failure: \(error.localizedDescription)")
case .cancel:
print("User has cancelled the onboarding")
}
}
See also
Please, check detailed doc about Onboarding class here
3. Authentication¶
How can we get the userToken to start testing Alice Onboarding technology?
AliceOnboarding can be used with two differnet authentication modes:
- Trial test (Using Alice Onboarding Sandbox): Recommended only in the early stages of integration.
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.
let trialToken = "<ADD-YOUR-TRIAL-TOKEN-HERE>"
let userInfo = UserInfo(email: email, // required
firstName: firstName, // optional
lastName: lastName) // optional
let authenticator = TrialAuthenticator(trialToken: trialToken, userInfo: userInfo)
authenticator.execute { result in
switch result {
case .success(let userToken):
// Configure Alice Onboarding with the OnboardingConfig
// Then Run the Alice Onboarding Flow
case .failure(let error):
// Inform the user about Authentication Errors
}
}
The trialToken is a temporal 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.
See also
See the authentication options
3.2. Production¶
On the other hand, for a production environments we strongly recommend to use your backend to obtain the required USER_TOKEN.
You can implement the Authenticator protocol available in the AliceOnboarding framework.
class MyBackendAuthenticator : Authenticator {
func execute(completion: @escaping Response<String, AuthenticationError>){
// Add here your code to retrieve the user token from your backend
let userToken = "fakeUserToken"
completion(.success(userToken))
}
}
In a very similar way to the authentication available with the sandbox:
let authenticator = MyBackendAuthenticator()
authenticator.execute { result in
switch result {
case .success(let userToken):
// Configure Alice Onboarding with the OnboardingConfig
// Then Run the Alice Onboarding Flow
case .failure(let error):
// Inform the user about Authentication Errors
}
}
4. Stages configuration¶
4.1 Document stage configuration parameters¶
config = try! config.withAddDocumentStage(ofType: .residencepermit, issuingCountry: “ESP”, documentStageConfig: documentStageConfig)
withAddDocumentStage has the following parameters (in order):
documentType: type of document to capture. The enumDocumentTypecan 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:
withTorchFlash: boolean parameter to give the possibility to turn on the flash in the capture.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.
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 customize Onboarding stages using your own style.
5.1. General & Fast Customisation¶
Colors¶
To define colors across all views in a fast way you can use the the static class DefaultAppearence
DefaultAppearence.primaryColor = UIColor.black
DefaultAppearence.secondaryColor = UIColor.gray
DefaultAppearence.backgroundColor = UIColor.white
Fonts¶
To define fonts also use the DefaultAppearence class and make sure the OnboardingAppearence.fontTheme value is set to FontTheme.custom.
DefaultAppearence.fontBold = "System-Bold"
DefaultAppearence.fontRegular = "System-Regular"
OnboardingAppearence.fontTheme = FontTheme.custom
5.2. Theme customisation¶
We provide you up to 3 different themes to customize fonts and icons, or a custom style.
Font theme¶
You can change the default font theme between three different options. Just overwrite fontTheme property using the static class OnboardingAppearence.
OnboardingAppearence.fontTheme = FontTheme.classic
Available values:
public enum FontTheme: String {
case classic
case corporative
case modern
case custom
}
Icons Theme¶
You can change the default icon theme between three different options. Just overwrite iconsTheme property using the static class OnboardingAppearence.
OnboardingAppearence.iconsTheme = IconsTheme.classic
Available values:
public enum IconsTheme: String {
case classic
case minimal
case modern
}
Icons Theme¶
You can change the default icons style between three different options. Just overwrite iconsStyle property using the static class OnboardingAppearence.
OnboardingAppearence.iconsStyle = IconsStyle.circle
Available values:
public enum IconsStyle: String {
case circle
case shape
case square
}
5.3 Fine-grained customisation¶
If you want a more specific customization without using the default themes this is your section. Alice Onboarding provides 4 views with configurable values:
Overwrite UI Properties using the static class OnboardingAppearence.
Example:
OnboardingAppearence.statusView.backgroundColor = UIColor.white
OnboardingAppearence.statusView.titleTextColor = UIColor.black
OnboardingAppearence.statusView.titleTextFont = "System-Bold"
OnboardingAppearence.statusView.titleTextSize = 15
You can also use your own icons:
OnboardingAppearence.statusView.selfieIcon = UIImage(named: "imagePath")
OnboardingAppearence.statusView.idCardIcon = UIImage(named: "imagePath")
OnboardingAppearence.statusView.driverLicenseIcon = UIImage(named: "imagePath")
OnboardingAppearence.statusView.residencePermitIcon = UIImage(named: "imagePath")
OnboardingAppearence.statusView.passportIcon = UIImage(named: "imagePath")
SelfieCaptureView¶
Overwrite UI Properties using the static class OnboardingAppearence.
Example:
OnboardingAppearence.selfieCaptureView.backgroundColor = UIColor.white. withAlphaComponent(0.7)
OnboardingAppearence.selfieCaptureView.titleTextColor = UIColor.black
OnboardingAppearence.selfieCaptureView.titleTextFont = "System-Bold"
OnboardingAppearence.selfieCaptureView.titleTextSize = 15
DocumentIntermediateView¶
Overwrite UI Properties using the static class OnboardingAppearence.
Example:
OnboardingAppearence.documentIntermediateView.backgroundColor = UIColor.white
OnboardingAppearence.documentIntermediateView.titleTextColor = UIColor.black
OnboardingAppearence.documentIntermediateView.titleTextFont = "System-Bold"
OnboardingAppearence.documentIntermediateView.titleTextSize = 15
DocumentCaptureView¶
Overwrite UI Properties using the static class OnboardingAppearence.
Example:
OnboardingAppearence.documentCaptureView.backgroundColor = UIColor.white. withAlphaComponent(0.7)
OnboardingAppearence.documentCaptureView.titleTextColor = UIColor.black
OnboardingAppearence.documentCaptureView.titleTextFont = "System-Bold"
OnboardingAppearence.documentCaptureView.titleTextSize = 15
5.4 Localisation¶
The Alice Onboarding SDK provides several default translations for the following locales:
Locale |
Code |
|---|---|
Catalan |
ca |
German |
de |
English |
en |
Spanish |
es |
Basque |
eu |
French |
fra |
Italian |
it |
Galician |
gl |
Polish |
pl |
Portuguese |
pt |
Russian |
ru |
Turkish |
tr |
Simplified chinese |
zh |
By default, the SDK infers what is the default language to use. If the 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 so, you need to add an additional .strings file inside your resource folder for the required locale. Please remember the naming should
follow the ISO 639-1 language codes. For example, in the case of Spanish (es), the file name should be es.strings.
The default messages can be found here.
Finally, you need to add the localization to the OnboardingConfig.
If you want our SDK to select the language depending on the user’s device configuration, follow the next example.
config = OnboardingConfig.builder()
.withUserToken(userToken)
.withCustomLocalization(inBundle: Bundle.main)
onboardingCommands = OnboardingCommands(self,
userToken: userToken!,
bundle: Bundle.main) { error in
showAlert(viewController: self,
title: "OnboardingCommand",
message: "Error with language config (\(error))")
})
On the contrary, if you want to force the language used by the SDK, add the language parameter after the bundle.
config = OnboardingConfig.builder()
.withUserToken(userToken)
.withCustomLocalization(inBundle: Bundle.main, language: "en")
onboardingCommands = OnboardingCommands(self,
userToken: userToken!,
bundle: Bundle.main, language: "en") { error in
showAlert(viewController: self,
title: "OnboardingCommand",
message: "Error with language config (\(error))")
})
