HTML + JS

Alice Onboarding Web 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. Import the library

Warning

As this SDK uses getUserMedia for accessing the webcam a secure context is required when using it.

Alice Onboarding can be used as a NPM module (1.1) or with a regular script tag on your page (1.2). In production environment we strongly recommend use the last stable version. For development environment we recommend use the "latest" version.

1.1 NPM installation & import

The NPM module can be installed as follows:

Stable VersionLatest Version

npm install aliceonboarding@6.5.1

npm install aliceonboarding

Import the NPM package

import { Onboarding, OnboardingConfig, DocumentType } from "aliceonboarding";
import "aliceonboarding/dist/aliceonboarding.css";

1.2 HTML Script Tag Include

The HTML tag can be integrated as follows:

Stable VersionLatest Version

<script src='https://unpkg.com/aliceonboarding@6.5.1/dist/aliceonboarding.min.js'></script>
<link rel="stylesheet" href="https://unpkg.com/aliceonboarding@6.1.0/dist/aliceonboarding.css" />

<script src='https://unpkg.com/aliceonboarding/dist/aliceonboarding.min.js'></script>
<link rel="stylesheet" href="https://unpkg.com/aliceonboarding/dist/aliceonboarding.css" />

Warning

When using the HTML script you will need to use the aliceonboarding namespace (like the examples below).
The NPM module requires ES9.

1.3 HTML INTEGRATION

Add a div element with onboarding tag inside in your page to load the Alice Onboarding component. An identifier must be set for this div, for example alice-onboarding-mount:

<div id="alice-onboarding-mount"/>

2. 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): 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 to do critical operations.
- Cons: Needs some integration in your backend.

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

Note

Use the TrialAuthenticator class to ease the integration.

Version < 7.0.0Version >= 7.0.0

let trialToken = "<ADD-YOUR-TRIAL-TOKEN-HERE>";
let userInfo = new aliceonboarding.UserInfo(email: email, // required
                    firstName: firstName, // optional 
                    lastName: lastName);  // optional 

let authenticator = new aliceonboarding.TrialAuthenticator( trialToken, userInfo);

authenticator.execute()
.then( userToken => {  
    // Configure Alice Onboarding with the OnboardingConfig
    // Then, Run the Alice Onboarding Flow
})
.catch(err => {
    // Inform the user about Authentication Errors
});

let trialToken = "<ADD-YOUR-TRIAL-TOKEN-HERE>";
let userInfo = new aliceonboarding.UserInfo(email: email, // required
                    firstName: firstName, // optional 
                    lastName: lastName);  // optional 

let authenticator = new aliceonboarding.TrialAuthenticator({
    sandboxToken: trialToken, 
    userInfo: userInfo
});

authenticator.execute()
.then( userToken => {  
    // Configure Alice Onboarding with the OnboardingConfig
    // Then, Run the Alice Onboarding Flow
})
.catch(err => {
    // Inform the user about Authentication Errors
});

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

2.2. Production

On the other hand, for a production environments we strongly recommend to use your backend to obtain required USER_TOKEN.

You can implement the Authenticator protocol available in the AliceOnboarding framework.

class MyBackendAuthenticator extends aliceonboarding.Authenticator {
    constructor() {
        super();
    }
    execute() {
        return new Promise((resolve, reject) => {

        // Add here your code to retrieve the user token from your backend

        let userToken = "fakeUserToken";
        resolve(userToken);
        });
    }
}

In a very similar way to the authentication available with the sandbox:

let authenticator = MyBackendAuthenticator()

authenticator.execute()
.then( userToken => {  
   // Configure Alice Onboarding with the OnboardingConfig
   // Then, Run the Alice Onboarding Flow
})
.catch( error => {
  // Inform the user about Authentication Errors
});

3. Onboarding Flow

You can configure the onboarding flow with the following code:

Version < 7.0.0Version >= 7.0.0

let userToken = "<ADD-YOUR-USER-TOKEN-HERE>"
let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddSelfieStage()
    .withAddDocumentStage(aliceonboarding.DocumentType.IDCARD)
    .withAddDocumentStage(aliceonboarding.DocumentType.DRIVERLICENSE)
    .withAddOtherTrustedDocumentStage(aliceonboarding.otd.title)

let userToken = "<ADD-YOUR-USER-TOKEN-HERE>"
let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddSelfieStage({})
    .withAddDocumentStage({documentType: aliceonboarding.DocumentType.IDCARD})
    .withAddDocumentStage({documentType: aliceonboarding.DocumentType.DRIVERLICENSE})
    .withAddOtherTrustedDocumentStage({title: "OTD title"})

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.

3.1 Selfie stage configuration parameters

withAddSelfieStage can be configured the optional parameter SelfieStageConfig.

SelfieStageConfig constructor has the following parameters names in version equal to or greater than 7.0.0 (in versions less than 7.0.0 parameters must be passed in order):

capturerType: type of capturer to use. The enum aliceonboarding.SelfieCapturerType can be used to indicate the capturer. Default value is SelfieCapturerType.CAMERA meaning that the selfie will be recorded using the camera. You can set it to SelfieCapturerType.FILE to use the file upload or set it to SelfieCapturerType.ALL to allow both options to the user.

Warning

The parameter capturerType and the enum aliceonboarding.SelfieCapturerType will disappear from version 6.0.0.

automaticCapture: a boolean parameter to indicate if the selfie capture should be triggered manually by clicking a button or automatically when a face is detected. Its default value is true.
cameraType: type of camera to use. The enum aliceonboarding.CameraType can be used to indicate the camera. Default value is CameraType.FACE meaning that the camera facing the user will be used. You can set it to CameraType.BACK to use rear camera. This argument is only used when there are available different cameras on the device.

3.2 Document stage configuration parameters

withAddDocumentStage constructor has the following parameters names in version equal to or greater than 7.0.0 (in versions less than 7.0.0 parameters must be passed in order):

documentType: type of document to capture. The enum aliceonboarding.DocumentType can be used to indicate the type (id card, driver license, residence permit, passport).
issuingCountry: country ISO 3166-1 alpha-3 code. Don't set it to allow the user to choose the country.
documentStageConfig: (optional) capture configuration parameters.

DocumentStageConfig encapsulates different capture configuration parameters. Its constructor has the following parameters names in version equal to or greater than 7.0.0 (in versions less than 7.0.0 parameters must be passed in order):

capturerType: type of capturer to use. The enum aliceonboarding.DocumentCapturerType can be used to indicate the capturer. Default value is DocumentCapturerType.CAMERA meaning that the document capture will be recorded with the camera. You can set it to DocumentCapturerType.FILE to allow just the file upload or set it to DocumentCapturerType.ALL to allow both options to the user.
automaticCapture: boolean parameter to indicate if the document capture should be triggered manually by clicking a button or automatically when a document is detected. Default value is false.
cameraType: type of camera to use. The enum aliceonboarding.CameraType can be used to indicate the camera. Default value is CameraType.BACK meaning that the rear camera will be used. You can set it to CameraType.FACE to use the frontal camera. This argument is only used when there are available different cameras on the device.
manualCaptureTimeout: timeout for showing an alert giving the user the option to start a manual capture when the automatic capture fails to start. Default value is 11000 (ms).
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.

The following example initializes a document capture of Spanish driving licenses only with file upload

Version < 7.0.0Version >= 7.0.0

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

//initialise the documentStageConfig classs with your custom config

let documentStageConfig = new DocumentStageConfig(DocumentCapturerType.FILE,true, CameraType.BACK);

let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddDocumentStage(aliceonboarding.DocumentType.DRIVERLICENSE, issuing_country, aliceonboarding.documentStageConfig)

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

//initialise the documentStageConfig classs with your custom config

let documentStageConfig = new DocumentStageConfig({
        capturerType: DocumentCapturerType.FILE,
        automaticCapture: true,
        cameraType: CameraType.BACK
    });

let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddDocumentStage({
        documentType: aliceonboarding.DocumentType.DRIVERLICENSE,
        issuingCountry: issuing_country, 
        documentStageConfig: aliceonboarding.documentStageConfig
    })

The following example initializes a document capture allowing the user to update the document as a file or capture them with the camera. The example also allows the user to select the country for that document

Version < 7.0.0Version >= 7.0.0

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

//initialise the documentStageConfig classs with your custom config

let documentStageConfig = new DocumentStageConfig({
        capturerTỳpe: DocumentCapturerType.ALL
    });

let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddDocumentStage(aliceonboarding.DocumentType.DRIVERLICENSE, "SELECT", aliceonboarding.documentStageConfig)

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

//initialise the documentStageConfig classs with your custom config

let documentStageConfig = new DocumentStageConfig({
        capturerTỳpe: DocumentCapturerType.ALL
    });

let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddDocumentStage({
        documentType: aliceonboarding.DocumentType.DRIVERLICENSE,
        issuingCountry: "SELECT", 
        documentStageConfig: aliceonboarding.documentStageConfig
    })

3.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 three 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. Note: this argument is case-insensitive.
description: optional argument. Allows you to display a description of the document (e.g. given extra information about how the document should be captured) during the onboarding process.
capturerType: type of capture to use. The enum aliceonboarding.DocumentCapturerType can be used to indicate the capturer. Default value is DocumentCapturerType.CAMERA meaning that the other trusted document capturer will be recorded with the camera. You can set it to DocumentCapturerType.FILE to allow just the file upload or set it to DocumentCapturerType.ALLto allow both options to the user.

An example of several Other Trusted Documents could be this:

Version < 7.0.0Version >= 7.0.0

let userToken = "<ADD-YOUR-USER-TOKEN-HERE>"
let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddOtherTrustedDocumentStage( 
        title, // required 
        category // optional
    )
    .withAddOtherTrustedDocumentStage({ç
        title2, // required
        category2 // optional
    })

let userToken = "<ADD-YOUR-USER-TOKEN-HERE>"
let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddOtherTrustedDocumentStage({
        title: title, // required
        category: category // optional
    })
    .withAddOtherTrustedDocumentStage({
        title: title2, // required
        category: category2 // optional
    })

3.4 Complete Timeout

This functionality allows you to set a timeout on the last part of the process. Once the user has completed all the steps you can complete the process without clicking the "Continue" button.

Completed Process

Version < 7.0.0>Version >= 7.0.0

let completeTimeout = 1; //in ms and always completeTimeout > 0
let userToken = "<ADD-YOUR-USER-TOKEN-HERE>"
let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddSelfieStage()
    .withAddDocumentStage(aliceonboarding.DocumentType.IDCARD)
    .withCustomParameters(completeTimeout)

let completeTimeout = 1; //in ms and always completeTimeout > 0
let userToken = "<ADD-YOUR-USER-TOKEN-HERE>"
let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddSelfieStage({})
    .withAddDocumentStage({documentType: aliceonboarding.DocumentType.IDCARD})
    .withCustomParameters(completeTimeout)

3.5 Run Alice Onboarding

Once you have configured the Alice Onboarding Flow, you can run the process with:

function onSuccess(userInfo) {console.log("onSuccess: " + userInfo)}
function onFailure(error) {console.log("onFailure: " + error)}
function onCancel() { console.log("onCancel")}

new aliceonboarding.Onboarding("alice-onboarding-mount", config).run(onSuccess, onFailure, onCancel);

3.6 Removing Alice Onboarding

If you are running the onboarding process inside a SPA, you can call the unmount method to remove the SDK from the current web page. This will reset its state, so you can restart the onboarding process later on:

const onboarding = new aliceonboarding.Onboarding("alice-onboarding-mount", config);
onboarding.run(onSuccess, onFailure, onCancel);
...
onboarding.unmount();

4. Customization

The SDK is provided with themes for:

Typography ("corporate", "modern", "classic")
Icons ("classic", "modern", "minimal")
Icons variant ("circle", "square", "shape")

Note

Default values are in bold.

You can choose the themes with the OnboardingConfig method withTheme. That has the following parameters:

theme: Typography theme
iconTheme: Icon theme (Optional. Default value is "minimal")
iconVariant: Icon variant (Optional. Default value is "circle")
style: Custom theme parameters

You can customize your Onboarding process with the following parameters

{ 
    alice_color_primary: "#000e8f",
    alice_color_accent: "black",
    alice_color_secondary: "#4d525f",
    alice_color_background: "white",
    alice_color_check: "#28a745"
    alice_font_family: '"Arial",sans-serif',
    alice_title_font_family: '"Arial",sans-serif',
    alice_title_font_size: "1.2rem",
    alice_title_font_size_desktop: "2.2em",
    alice_subtitle_font_size: "1rem",
    alice_subtitle_font_size_desktop: "1.3rem",
    alice_modal_title_font_size: "1.2rem",
    alice_modal_title_font_size_desktop: "1.5rem",
    alice_input_font_size: "1rem",
    alice_input_font_size_desktop: "1.3rem",
    alice_button_font_size: "1rem",
    alice_button_font_size_desktop: "1.3rem",
    alice_button_font_color: "white",
    alice_button_border_radius: "0.4rem",
    alice_button_height: "2.8rem",
    alice_font_bold_weight: "500",
    alice_letter_spacing: "0.25px",
    alice_title_letter_spacing: "0.25px",
    alice_font_extra_bold_weight: "700"
}

Example:

Version < 7.0.0Version >= 7.0.0>

let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddSelfieStage()
    .withAddDocumentStage(onboarding.DocumentType.IDCARD)
    .withTheme("corporate", "minimal", "square", { "alice-color-primary":"blue", etc })

let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddSelfieStage({})
    .withAddDocumentStage({documentType: onboarding.DocumentType.IDCARD})
    .withTheme({
        theme: "corporate",
        iconTheme: "minimal",
        iconVariant: "square", 
        style: { "alice-color-primary":"blue", etc }
    })

Warning

Only supported with Onboarding Flow.

4.2 Localization

Supported languages are:

Catalan
Chinese (simplified)
English (default)
French
Galician
German
Italian
Japanese
Spanish
Polish
Portuguese
Russian
Turkish

By default, the SDK uses English, but the language used can be set through withCustomLocalization (using ISO 639-1 codes):

Version < 7.0.0Version >= 7.0.0

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

let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddSelfieStage()
    .withAddDocumentStage(onboarding.DocumentType.IDCARD)
    .withAddDocumentStageonboarding.DocumentType.DRIVERLICENSE)
    .withCustomLocalization(language);

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

let config = new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddSelfieStage({})
    .withAddDocumentStage({documentType: onboarding.DocumentType.IDCARD})
    .withAddDocumentStage({documentType: onboarding.DocumentType.DRIVERLICENSE})
    .withCustomLocalization({language: language});

Additionally, messages can be overridden with the second argument of withCustomLocalization. This argument must is an object that maps languages and strings to override:

Version < 7.0.0Version >= 7.0.0

let userToken = "<ADD-YOUR-USER-TOKEN-HERE>";
let language = "es";
const customMessages = {"en": {"onboarding_stages_title" : "Hello" }, "es": {"onboarding_stages_title" : "Hola" }};
let  new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddSelfieStage()
    .withCustomLocalization(language, customMessages);

let userToken = "<ADD-YOUR-USER-TOKEN-HERE>";
let language = "es";
const customMessages = {"en": {"onboarding_stages_title" : "Hello" }, "es": {"onboarding_stages_title" : "Hola" }};
let  new aliceonboarding.OnboardingConfig()
    .withUserToken(userToken)
    .withAddSelfieStage({})
    .withCustomLocalization({language: language, customMessages: customMessages});

The default messages can be found here.

5. Extra

5.1. Welcome

We provide an additional component for retrieving the user information (email, first name and/or last name). You can use this component before the onboarding process to retrieve this info in case you don't already have it.

let config = {
    language: "en",
    requiredInfo: ["email"] // Possible options are "email", "firstName" and/or "lastName"
};

  function onUserInfo(userInfo) {} // Callback that will receive the user information
  function onCancel() {} // Callback to handle cancellation

new aliceonboarding.OnboardingWelcome("alice-onboarding-mount", config).run(
    onUserInfo, onCancel
);

6. Demo

Check our JSFiddle demo here. Remember you must add your TRIAL_TOKEN credentials. If you have already integrated Alice Onboarding in your backend, remove the aliceonboarding.logInWithSandbox function and use your retrieved USER_TOKEN.