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:
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:
<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.
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:
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 enumaliceonboarding.SelfieCapturerType
can be used to indicate the capturer. Default value isSelfieCapturerType.CAMERA
meaning that the selfie will be recorded using the camera. You can set it toSelfieCapturerType.FILE
to use the file upload or set it toSelfieCapturerType.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 istrue
.cameraType
: type of camera to use. The enumaliceonboarding.CameraType
can be used to indicate the camera. Default value isCameraType.FACE
meaning that the camera facing the user will be used. You can set it toCameraType.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 enumaliceonboarding.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 enumaliceonboarding.DocumentCapturerType
can be used to indicate the capturer. Default value isDocumentCapturerType.CAMERA
meaning that the document capture will be recorded with the camera. You can set it toDocumentCapturerType.FILE
to allow just the file upload or set it toDocumentCapturerType.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 enumaliceonboarding.CameraType
can be used to indicate the camera. Default value isCameraType.BACK
meaning that the rear camera will be used. You can set it toCameraType.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
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
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 enumaliceonboarding.DocumentCapturerType
can be used to indicate the capturer. Default value isDocumentCapturerType.CAMERA
meaning that the other trusted document capturer will be recorded with the camera. You can set it toDocumentCapturerType.FILE
to allow just the file upload or set it toDocumentCapturerType.ALL
to allow both options to the user.
An example of several Other Trusted Documents could be this:
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.
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:
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):
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:
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
.