Web
Latest version: 3.0.8
Overview
The web SDK is a React component that enables you to trigger an identity verification.
It is responsive and works on both desktop and mobile browsers.
The user is asked to scan a QR code or use the generated link:
Once the user is on his phone, he is informed about his progress in the onboarding process
Browser limitations
The Web SDK supports modern mobile browsers with the following minimum versions:
| Device | OS min version | Chrome | Firefox | Safari | Edge |
|---|---|---|---|---|---|
| iOS | ≥ iOS 15.0 | ≥ 65 | ≥ 63 | ≥ 13 | ≥ 100 |
| Android | ≥ Android 5.0 | ≥ 65 | ≥ 63 | - | ≥ 100 |
!!! Compatibility Warning
Ensure your users have compatible browsers to avoid issues during the identity verification process.
Getting started
In order to perform an Onboarding or an Authenticate, you should follow those steps:
- Set up the SDK: install and import the SDK.
- Get a token: request a token using your business credentials.
- Start an onboarding or authenticate flow: launch a user workflow.
- Get the user workflow result from SDK
- Get the Analysis result: use your callback or the endpoint to get the analysis result.
1. Set up the SDK
Install the npm packages
The Web SDK is hosted on a private repository.
You'll need to configure your npm client to authenticate with this private registry before installing the SDK.
Step 1 — Receive your access credentials
You will receive your username and password from the ShareID team.
These credentials will allow you to authenticate and install the private SDK packages.
Step 2 — Authenticate with the private registry
You can authenticate with this following method:
You will be prompted for your credentials:
Username: <username provided by ShareID>
Password: <password provided by ShareID>
Email: (this IS public) <email>
After logging in, npm will store your authentication token automatically.
Step 3 — Install the package
Once authentication is configured, you can install the SDK package:
Info
The SDK package includes both Onboarding and Authenticate workflows. You can switch between them using the mode prop.
Step 4 — Troubleshooting
If you encounter an authentication or 404 error:
- Verify that your
.npmrcfile is at the root of your project. - Ensure the registry URL matches exactly:
- Make sure your token has not expired.
- Contact your ShareID technical contact if the issue persists.
2. Get a token
Use the credentials you received from ShareID's team to get an authentication token and launch an onboarding or authenticate workflow.
Depending on the SDK you are integrating (Onboarding/Authenticate), you may use an API here Get a Token
3. Start an onboarding or authenticate flow
Once you have your token, you can start the process by setting your web SDK. The same component can be used for both onboarding and authentication by setting the mode prop.
import React from "react";
import ShareID from "@shareid/onboarding_desktop";
enum OnboardingError {
SUCCESS_ONBOARDING = "success_onboarding",
SUCCESS_AUTHENTICATE = "success_authenticate",
EXIT = "exit",
ACCESS_TOKEN_REQUIRED = "access_token_required",
SDK_CONFIGURATION_FAILED = "sdk_configuration_failed",
CONTEXT_FAILED = "context_failed",
AI_FAILED = "ai_failed",
ASSETS_FAILED = "assets_failed",
ERROR_FAILED = "error_failed",
RESET_FAILED = "reset_failed",
NO_CAMERA = "no_camera",
SET_FRAME_RATE_FAILED = "set_frame_rate_failed",
PROCESS_IMAGE_FAILED = "process_image_failed",
PROCESS_VIDEO_FAILED = "process_video_failed",
NO_HTTP_RESPONSE = "no_http_response",
INVALID_STATUS_CODE = "invalid_status_code",
SERIALIZATION_FAILED = "serialization_failed",
TOO_MANY_ERRORS = "too_many_errors",
CAMERA_ACCESS_REFUSED = "camera_access_refused",
SESSION_EXPIRED = "session_expired",
HTTP_TIMEOUT = "http_timeout",
LOST_INTERNET_CONNECTION = "lost_internet_connection",
}
enum ClientStep {
PRE_PROCESS = "pre_process", // Initialization phase
DOC_CHOICE = "doc_choice", // User is selecting document type
DOC_SCAN = "doc_scan", // Document capture in progress
FACE_SCAN = "face_scan", // Face liveness verification in progress
POST_PROCESS = "post_process", // Final processing phase
}
type CallbackDataType = {
code: OnboardingError;
step?: ClientStep;
};
// For Onboarding mode
const OnboardingApp = () => {
const handleSuccess = (data: CallbackDataType) => {
console.log("Onboarding completed successfully:", data);
};
const handleFail = (data: CallbackDataType) => {
console.error("Onboarding failed:", data);
};
const handleExit = (data: CallbackDataType) => {
console.error("User has exited the onboarding:", data);
};
return (
<ShareID
mode="onboarding"
token="YOUR AUTHENTICATION TOKEN HERE"
language="en"
onFail={handleFail}
onExit={handleExit}
onSuccess={handleSuccess}
dark={false}
redirectUrl="https://www.exemple.com"
theme={{
colors: {
main: "#007bff",
mainText: "#ffffff",
},
}}
/>
);
};
// For Authenticate mode
const AuthenticateApp = () => {
const handleSuccess = (data: CallbackDataType) => {
console.log("Authentication completed successfully:", data);
};
const handleFail = (data: CallbackDataType) => {
console.error("Authentication failed:", data);
};
return (
<ShareID
mode="authenticate"
token="YOUR AUTHENTICATION TOKEN HERE"
language="en"
onFail={handleFail}
onSuccess={handleSuccess}
dark={false}
redirectUrl="https://www.exemple.com"
theme={{
colors: {
main: "#007bff",
mainText: "#ffffff",
},
}}
/>
);
};
4. Get the user workflow result from SDK
The SDK provides callbacks (onSuccess, onFail, onExit) that allow you to receive real-time feedback about the user's progress through the workflow.
These callbacks are triggered at various stages of the process and provide you with:
- The code - indicates what happened (success, failure, or exit)
- The step - indicates at which step the event occurred
The callback data contains important information about the user's journey:
type CallbackDataType = {
code: OnboardingError; // See error codes table below
step?: ClientStep; // Optional: current step in the process
};
Info
For a complete list of all possible codes and steps, refer to the Message Handler documentation.
Props
| Name | Description | Type | Required | Default Value |
|---|---|---|---|---|
mode |
Set to "onboarding" or "authenticate" to choose the workflow type |
string | "onboarding" |
|
token |
The token you get through the authentication process | string | ✓ | |
language |
Possible values: fr, en, es, de, it, ar, pl, pt, ro, ru |
string | en |
|
onFail |
Triggered when something goes wrong during the acquisition process of the user or his identity document videos | function | ||
onExit |
Triggered when the user exist the verification process without finishing all the steps | function | ||
onSuccess |
Triggered when the videos of the user has been successfully uploaded | function | ||
dark |
Handle dark mode if True | boolean | false | |
theme |
Customize the SDK to your colors | object | {} | |
redirectUrl |
Redirects the user at the end of the onboarding process | string |
Callback Data Explanation
| Code | Message |
|---|---|
| success_onboarding | The user has successfully completed the onboarding process. |
| success_authenticate | The user has successfully completed the authentication process. |
| exit | The user exited the SDK flow without completing the process. |
| access_token_required | The access token must be provided. |
| sdk_configuration_failed | A problem occurred when retrieving the SDK configuration. |
| context_failed | A problem occurred during context initialisation. |
| ai_failed | A problem occurred in the AI processing. |
| assets_failed | A problem occurred when loading assets. |
| error_failed | A problem occurred when sending the error to the server. |
| reset_failed | A problem occurred during reset. |
| no_camera | No cameras can be used. |
| set_frame_rate_failed | A problem has occurred when setting the frame rate. |
| process_image_failed | A problem has occurred during image processing. |
| process_video_failed | A problem has occurred during video processing. |
| no_http_response | No HTTP response was received. |
| invalid_status_code | The status code received by server is invalid. |
| serialization_failed | A problem occurred during data serialization. |
| too_many_errors | Too many errors occurred during the operation. |
| camera_access_refused | Access to the camera has been denied by the user. |
| session_expired | The session has expired. |
| http_timeout | The HTTP request timed out. |
| lost_internet_connection | The internet connection was lost. |
Note
Web SDK steps are specific to the web implementation. For a complete list of all possible steps and their meanings, see the Message Handler documentation.
| Step | Description |
|---|---|
| pre_process | The initialization phase before document capture begins. |
| doc_choice | The user is selecting which document type to scan. |
| doc_scan | The user is capturing the document using the mobile camera. |
| face_scan | The user is performing face liveness verification using the front camera. |
| post_process | The final processing phase after all captures are complete. |
How it works
- QR Code/Link Display: The user sees a QR code on the desktop that they can scan with their mobile device, or they can use the generated link
- Mobile Device: The user completes the verification on their mobile phone:
- Document capture (front and back)
- Face liveness verification
- Progress Tracking: The SDK callbacks (
onSuccess,onFail,onExit) provide real-time feedback on the user's progress - Processing: Videos are uploaded to ShareID's backend for AI analysis
- Completion: The appropriate callback is triggered when the process completes
Note
The entire verification process happens on the user's mobile device, not on the desktop browser. Except for the Liveness IDV, which can be done on a desktop computer.
5. Get the Analysis result
When the processing of an onboarding request is finished, you may receive the result through the callback if you provided it. You may also, fetch yourself the result by calling our API.
See Get the analysis result for more details.
Customisation
The ShareID Web SDK allows you to fully customise its main color.
You can do so by passing a theme prop to the ShareID component.
The accepted values for colors are:
HEX: exemple => '#92a8d1'RGB: exemple => 'rgb(201, 76, 76)'RGBA: exemple => 'rgba(201, 76, 76, 0.6)'HSL: exemple => 'hsl(89, 43%, 51%)'HSLA: exemple => 'hsla(89, 43%, 51%, 0.6)'Named: exemple => 'red'