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.2 Permissions

Camera Permission is required

For more info, please check the Apple Documentation

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:

1. A Selfie capture (.withAddSelfieStage())

2. Two different document stages for an Spanish ID Card and Driver License (.withAddDocumentStage()).

3. 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 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.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

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 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. For that, you need to add an additional .string file inside your resource folder for required locale, the file name should be the ISO 639-1 language code.

For example, to added Spanish language (es), the file name should be es.string.

config = OnboardingConfig.builder()
                .withUserToken(userToken)
                .withCustomLocalization(inBundle: Bundle.main)

To select a pre-defined language you can set it using the following code:

Using Onboarding mode

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

Using Onboarding commands

onboardingCommands = OnboardingCommands(self,
    userToken: userToken!,
    bundle: Bundle.main, language: "en") { error in
            showAlert(viewController: self,
                        title: "OnboardingCommand",
                        message: "Error with language config (\(error))")
})

Please, check the following examples, in order to know which text keys you can modify:

• English

• Spanish

6. Demo

Check our iOS demo in Github.

6.1 Setting up

Install cocoapods dependencies with:

cd AppOnboardingSample
pod install

Open the Xcode workspace

open AppOnboardingSample.xcworkspace

6.2 Add Testing Credentials

Add your TRIAL_TOKEN credentials in Settings -> CREDENTIALS -> Sandbox Token