Onboarding service - Web SDK Integration documentation
===
> **Product Name:** SDK Web ShareID - onboarding
> **Version:** 2.0.5
> **Date:** 2024-04-26
#

# Overview 👀

ShareID's web SDK is a set of screens and tools that runs on the web browser of your customers laptop and phone. They allow the capture of identity document and user videos for the purpose of identity verification. They are designed to help you create the best experience for your users:

* An enhanced UI to guide your customers through the entire video-capturing process.
* Modular design to help you seamlessly integrate the video-capturing process into your application flow.
* Advanced image quality detection technology to ensure the quality of the captured videos meets the requirement of ShareID's identity verification process, guaranteeing the best success rate.
* Auto-capture of the videos from the document and the user to limit the necessay user interactions
* Direct video upload to the ShareId service, to simplify integration.


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 t scan a **QR code** or use the generated **link** :


Once the user is on his phone, he is informed about his progress in the acquisition phase:

<!--## Minimum required configuration

| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Text | Text | Text |

----->

#
# Quick Start 🎯

In order to perform an identity verification, you should follow the integration steps:

1. Get your business credentials.
2. Install the npm package **onboarding_desktop**.
3. Get an authentication Token.
4. Trigger an identity verification request.
5. Get the identity verifcation result.

# Integration 🧩

### 1. Get your business credentials

ShareID's SDKs use API keys to securely communicate with ShareID's backend.
Upon your registration with ShareID, you will receive an email to generate your **business_Identifier** and a **Business_secret**.

:::warning
:warning: Your crediantials are your responsability. You must never expose them in your frontend.
:::

### 2. Install the npm package onboarding_desktop
You need to provide us with a **username npm** so that we give you an access permission.
When you have recieved the invitation email you can Login and Install the private **npm** package :

npm login
npm install --save @shareid/onboarding_desktop

or install the **yarn** package:

yarn add @shareid/onboarding_desktop

### 3. Get an authentication Token

For security purposes, ShareID service requires an *access token* per identity verification. This means that each identity verification demand requires a new token.

A token request is a **POST** request to ShareID's authorization service with your *business identifier*, *business secret* and:
- *callback url* : You should set up a **callback url** and implement a **listner** if you want to receive the result with this method. Otherwise, do not use this parameter.
- *with_capture* : This parameter allows you to specify if you need to receive a capture of the ID document in the response. Set it to 'False' if you do not want to recieve the captures.

POST  https://sandbox.shareid.net/authorization/v1/auth_business/login
{
  "business_identifier": "my_business_identifier",
  "business_secret": "my_business_secret",
  "callback_url": "my_callback_url", //optional
  "with_capture": True //optional
}

You can try this request here: [/login](https://shareid.readme.io/reference/post_v1-business-login?redirect=%2Fv1.0%2Freference)
Access tokens are valid for **10** minutes.

### 4. Trigger an identity verification request

Once you have your token, you can trigger an identity verification by setting your web SDK as described below:

import React from "react";
import ShareID from "@shareid/onboarding_desktop";

type SuccessDataType = {
    uuid: string, 
    message: string,
    external_id: string
};

type FailDataType = {
    message: string,
    external_id: string,
    code: number,
    description: string[]
};

const App = () => (
    <ShareID
        accessToken="YOUR AUTHENTICATION TOKEN HERE"
        metadata={
            external_id: "The identifier of the user you set up in your system",
            [key: string]: "Other metadata you want to receive with the final result" 
        }
        language="en"
        environment='sandbox'
        onFail={ (data: FailDataType) => { /*any side effect here*/ }}
        onSuccess={ (data: SuccessDataType) => { /*any side effect here*/ }        
        }
    />
);
export default App; 

The user will be guided to scan a QR code and follow the steps to provide his data : videos of his document and/or his face are recorded and sent to ShareID's backend for processing.
When the user finishes those steps, the OnSuccess Callback function is triggered and you will recieve the **uuid** to identify the user, along with other data.
Exemple:

type SuccessDataType = {
    uuid: string, 
    message: string,
    external_id: string
};
    onSuccess={ (data: SuccessDataType) => {
    console.log("verification" & data.external_id & "or" & data.uuid & "completed")
     }}

Other **Props** can also be specified:
* *accessToken*: the token you get through the authentication process.
* *language*: the language used in the sdk.
* *environment*: You can use our 'sandbox' environment to test your integration, 'production' for production.
* *debug*: display more detailed error messages in the browser console if **True**
* *dark*: handle dark mode if **True**
* *theme*: this propriety allows you to customize the SDK to yours colors and text style (see examples in the FAQs).

* *callback functions*: these functions are used to manage the interactions ShareID's service. Examples of the use of *callbacks (OnFail, OnExit, OnSuccess)* are presented in the FAQs section.
* *OnSuccess* is triggered when the videos of the user has been succesfully uploaded (sent to backend for verification).
* *OnFail* is triggered when something goes wrong during the acquisition process of the user or his identity document videos (an error occured, example: token expired and user didn't start the process). The list of errors (code + message are detailed in the FAQs section).
* *OnExit* is triggered when the user exist the verification process without finishing all the steps. It is only triggered if the token has expired.
* *redirectUrl* redirects the user at the end of the onboarding process

### 5. Get the identity verification result
Once the verification process is finished, you can get the result in two ways:
1. You will recieve it on the callback url that you specified in your Token request, see **5.1**.
2. Or use the **GET** request (You will need the **token** and the **UUID** of the request), see **5.2**.
### 5.1. Receive the response on a callback url
When creating your identity verification request, you have set a callback url and communicate it to us in the next step (Get an authentication Token).
The identity verification **result** will be sent to you on this url as soon as it is available.

Once the verification process is finished, ShareID will send you a response on the callback url you have set up. and the **uuid** received in OnSuccess callback function (step 4).
### 5.2. Get an report result by API request

You can get the same result by calling an endpoint as follows:

GET  https://sandbox.shareid.net/v1/data/sdk/onboarding_demand/get_report/UUID/true

You will need to specify the UUID of your request.
If your request includes an ID document, you can setup the value 'true'. If you don't need to receive the captures of front and back of the document in the response you can setup to 'False'.
<!---

Get {sandbox}.shareid.net/data/sdk/document_authenticity_demand/{uuid}
Authorization: Token token=<YOUR_ACCESS_TOKEN>{}

### 5.3. Response exemple:

 type OnboardingDemandResult = {
        id: string, // UUID
        result: 'validated' | 'rejected',
        reason: string | null, // rejection reason if 'rejected'
        reason_id: string | null, // rejection reason id (see FAQs)
        metadata: {
            external_id: string, 
            [key: string]: string // other metadata that you have sent
        }
        document: {
            type: {
                document_type: "id_card" | "passport" | "driver_permit" | "residency_permit",
                document_year: string //ex: "1994"
                country: string //country code ISO 3166-1. ex: "fr"
            },
            ocr: {
                doc_num: string | null,
                surname: string | null,
                alternate_name: string | null,
                widow_of: string | null,
                mariage_name: string | null,
                name: string | null,
                sex: string | null,
                date_of_birth: string | null,
                place_of_birth: string | null,
                size: string | null,
                address: string | null,
                expiration_date: string | null,
                issuance_date: string | null,
                authority_issuer_fr: string | null
            }
        } | null
        document_front: string | null, //base64 of the photo of document front page 
        document_back: string | null  //base64 of the photo of document back page 
        
    }

If your business configuration is not set up to verify ID document authenticity (Only face verification), the result you will receive is :

 type OnboardingDemandResult = {
       id: string, // UUID
       result: 'validated' | 'rejected',
       reason: string | null, // rejection reason if 'rejected'
       reason_id: string | null, // rejection reason id (see FAQs)
       metadata: {
           external_id: string,
           [key: string]: string // other metadata that you have sent
       }
       document: null
       document_front: null,  
       document_back: null 
    }

The dates are in ISO 8601 format and the details about these response can be found in the FAQs section.

***
<!---The chart below summarize the workflow of an identity verification using ShareID's SDK.
-->

## FAQs 🙋🏽‍♂️

### What are the answers I can get from token request?

The possible response to this request can be found here: [/login](https://shareid.readme.io/reference/post_v1-business-login?redirect=%2Fv1.0%2Freference)

### How to manage the Callback functions ?

The callback functions are used to manage the interactions ShareID's service.

##### onFail {function} optional

This the callback function that triggers when something goes wrong during the acquisition process of the user or his identity document videos. You can call your backend to react to this event.

Exemple:

onFail={ (data: FailDataType) => {
    console.log("verification of : " & data.external_id & "failed")
 }

##### onExit {function} optional
This the callback function that triggers when the user exist the verification process without finishing all the steps.

##### onSuccess {function} optional

This callback function triggers when the videos of the identity document and the user has been succesfully uploaded. You can call your backend to react to this event.

Exemple:

    onSuccess={ (data: SuccessDataType) => {
    console.log("verification" & data.external_id & "completed")
     }}

### **What are the errors from OnFail callback function?**
| Status code| Message | Description (exemple) |
| -------- | -------- | -------- |
| 400 |BadRequest | Authorization Token can not be empty or null |
|401|unauthorized| Authorization Token has expired|
403| forbidden |quota Exceeded
404 |notFound| There is no demand with this id
405|MethodNotAllowed| Method Not Allowed
415 |UnsupportedMediaType |The media format of the requested data is not supported by the server
422 |ValidationError| Unprocessable Content response|

SDK Error Handling
| Status code| Message | Description (exemple) |
| -------- | -------- | -------- |
500 |internalError| Request failed for a server side internal error
503| backendError |Request failed for a connection error
600|AcessTokenRequired|The 'accessToken' has to be provided
604 |UploadVideosError|Something went wrong during the upload of the videos
607|CustomUrlRequired |The "customUrl" has to be provided
608 |WrongDevice |This process should be executed on a mobile device
610 |SessionExpired|User session has expired
666 |UnknownError|Request failed because of an unknown error
700 |CameraAccessError|User has denied camera access
701 |CameraSettingError|Something went wrong during the setting of camera or record buffer.

### **How to use the Prop *theme* to customize the SDK to my colors ?**
You can set the following values to customize the SDK's colors and text style:

type SdkThemeType = {
  colors?: {
    primary?: SdkCssColorType, // Light mode colors
    secondary?: SdkCssColorType, // Dark mode colors
  },
  text?: {
    title?: SdkCssTextType,
    subtitle?: SdkCssTextType,
    paragraph?: SdkCssTextType,
  }
}

Example of *SdkCssColorType*:

type SdkCssColorType = {
  active?: string,
  hover?: string,
  disabled?: string,
  bg?: string,
}

Example of *SdkCssTextType*:

type SdkCssTextType = {
  size?: string,
  lineHeight?: string,
  weight?: FontWeight,
  primaryColor?: string, // Light mode text color
  secondaryColor?: string, // Dark mode text color
}

The accepted values for *colors* are:

HEX : example => '#92a8d1'
RGB : example => 'rgb(201, 76, 76)'
RGBA : example => 'rgba(201, 76, 76, 0.6)'
HSL : example => 'hsl(89, 43%, 51%)'
HSLA : example => 'hsla(89, 43%, 51%, 0.6)'
Named : example => 'red'

The accepted values for *font size* are:

PX : example => '16px'
EM : example => '2em'
REM : example => '2rem'

The accepted values for *FontWeight* are:

type FontWeight =
  | 100 
  | '100'

### **What are the possible reasons for rejecting an onbording of a user?**
The possible rejection reasons are presented below by reason_id :
| **reason_id** | **reason** |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
1|document expired|
2|document unusable (old, wrong capture)|
3 |hidden elements in the document|
4 |low resolution|
5 |printed or scanned document|
6 |fraud suspicion on document|
7 |fraud suspicion on liveness |
8 |fraud on facial recognition|
9 |fraud suspicion on both document and liveness
#

### **What are the possible fields in the OCR output of the identity verification response ?**

The OCR output in the response above displays all the information available in the document provided by the user.
The list of fields can differ from a document to another and from a country to another.
In case you need to integrate these fields per documents, ShareID can provide you with a mapping per country
:::warning
:warning: Toutes les variables ne sont pas forcément présentes dans la réponse du service, seules celles détectées sur le document sont ajoutées à la réponse.
:::
The maping table below provides all the possible variables that can be extracted from a user document.

| **variable_name** | **Type** | **Description** |
| ----------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| doc_num | text | document number |
| surname | text | surname |
| alternate_name | text | alternate name |
| widow_of | text | widow of |
| mariage_name | text | mariage name |
| name | text | name |
| sex | text | sex |
| date_of_birth | date (ISO 8601) | date of birth |
| place_of_birth | text | place of birth |
| size | text | size |
| address | text | address |
| expiration_date | date (ISO 8601) | document expiration date |
| issuance_date | date (ISO 8601) | document issuance date |
| type | text | document type (diplomatic, driver licence type A, B) |
| country_code | text | country code |
| nationality | text | nationality |
| height | text | height |
| eye_color | text | eye color |
| issuance_date_place | text | document issuance place |
| remark | text | issuer remarks |
| date_place_of_birth | text | date and place of birth when aggregated in the same field within the document |
| category | text | category (mainly for driver licence) |
| issuance_date_by_category | text | issuance date per category |
| expiration_date_by_category | text | expiration date per category |
| complementary_info | text | complementary information provided by the document issuer |
| surname_name | text | surname and name |
| personal_number | text | personal number |
| particularities | text | particularities provided by the document issuer |
| start_date | date (ISO 8601) | document start date ( mainly for driver licence) |
| city | text | city |
| codes | text | codes provided by the issuer authority |
| signature | text | signature |
| issuance_place | text | document issuance place |
| parent_name | text | parent name |
| fiscal_code | text | fiscal code |
| birth_certificate_details | text | birth certificate details |
| notes | text | notes provided by the issuer authority |
| authority_date_issuer | text | authority issuing the document |
| foreigner_authority | text | foreigner authority |
| management_number | text | management number |
| ukf | text | registration number as british citizen |
| passport_number | text | passport number when available on another ID document. This is different from the doc_num which is the document number for all type of documents |
| record_number | text | record number |
| id_card_number | text | id card number when available on another ID document. This is different from the doc_num which is the document number for all type of documents |
| pin | text | pin |
| state_of_birth | text | state of birth |
| family_attitude | text | family attitude |
| can | text | commun account number |
| place_of_origin | text | place of origin |
| issuance_date_place_authority | date (ISO 8601) | issuance date, place and authority when aggregated in the same field within the document |
| entry_date | text | entry date to the country |
| reference | text | reference |
| surname_at_birth | text | surname at birth |
| issuance_date_authority | text | issuance date and authority when aggregated in the same field within the document |
| occupation | text | occupation |
| company | text | company |
| national_name | text | national name |
| birth_name | text | birth name |
| blood_type | text | blood type |
| father_surname | text | father surname |
| father_name | text | father name |
| mother_name | text | mother name |
| mother_surname | text | mother surname |
| control | text | control |
| profession | text | occupation |
| marital_status | text | marital status |
| children | text | children |
| authority_issuer | text | authority who issued the document
### Technical support and contact 💬

[[e-mail]](mailto:[e-mail])

* * *