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.

Tip

Check our GitHub repo to be aware of our latest releases.

1. Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. To integrate AliceOnboarding into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'AliceOnboarding'

Install it with:

pod repo update
pod install

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.

Adding AliceOnboarding as a dependency is very easy just press in Xcode File/Add Package Dependencies and add this repository as a dependency to your project.

Or adding it to the dependencies value of your Package.swift

dependencies: [
    .package(url: "https://github.com/alice-biometrics/onboarding-ios.git", .upToNextMajor(from: "2.0.0"))
]

Note

SPM version availabe above AliceOnboaring v2.0.0

2. Getting started

2.1 Import the library

import AliceOnboarding

2.2 Permissions

Camera Permission is required

For more info, please check the Apple Documentation

2.3 Config your Alice Onboarding

You can configure the onboarding flow with the OnboardingConfig builder. The following snippet configures:

1. A Selfie capture (.withAddSelfieStage()).
2. Two different document stages for a Spanish ID Card and Driver License (.withAddDocumentStage()).
3. A final stage to capture another trusted document (e.g. proof of address, bill...) (.withAddOtherTrustedDocumentStage()).
4. To see the configuration details of each stage go to section 4.Stages configuration.

let userToken = "<ADD-YOUR-USER-TOKEN-HERE>"

let config = try! 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:

let config = try! OnboardingConfig.builder()
    .withUserToken(userToken)
    .withAddSelfieStage()
    .withAddDocumentStage(ofType: .idcard, issuingCountry: "ESP")
    .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 Authentication)

2.4 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")
    case .dismissButton:
        print("Dismiss pressed")
    @unknown default:
        print("Uncontrolled exception")        
    }

}

Tip

Please, check detailed doc about Onboarding class here

3. Authentication

For production environments is mandatory to use your backend to obtain the required USER_TOKEN. You should obtain it from your backend (see Authentication)

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 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 Selfie stage configuration parameters

There are two different types of selfies available in this SDK

• Selfie: standard selfie with passive liveness.
• Selfie with Challenge: the SDK will ask the user to put the document inside a random position after capturing the selfie.

    config = try! config.withAddSelfieStage()

    config = try! config.withAddSelfieWithChallengeStage()

4.2 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 enum DocumentType 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:
    • 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.3 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. Customization

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 Customization

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 customization

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 customization

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 Localization

The Alice Onboarding SDK provides several default translations for the following locales:

Locale	Code
Arabic	ar
Catalan	ca
German	de
English	en
Spanish	es
Basque	eu
French	fra
Italian	it
Galician	gl
Dutch	nl
Japanese	ja
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.

```swift
config = try! OnboardingConfig.builder()
                .withUserToken(userToken)
                .withCustomLocalization(inBundle: Bundle.main)
```

On the contrary, if you want to force the language used by the SDK, add the language parameter after the bundle.

```swift
config = try! OnboardingConfig.builder()
                .withUserToken(userToken)
                .withCustomLocalization(inBundle: Bundle.main, language: "en")
```