ShareID Technical Documentation

# Overview

The web SDK is a React component that enables you to trigger an identity verification on your web application. It is responsive and works on both desktop and mobile browsers.

🖋️   Note:

The acquisition of the videos for the identity verification will happen on the browser of your user's phone.

The web SDK of ShareID is a drop-in set of screens and tools that runs on the web browser of your customers 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 customers:

  • 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 the ShareId 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 acquisition screens are very similar to those of the mobile SDKs:

mobile sdk screens

# 1. SDK languages

The web SDK is available in the languages below:

  • French Flag French
  • GB Flag English
  • Spanish Flag Spanish
  • German Flag German
  • Italian Flag Italian
  • Romanian Flag Romanian
  • Russian Flag Russian

The default language is english but you can set another opening language upon the component launch.
The languages stay at the user hand on the Web SDK screen.

# 2. Web component on desktop

The desktop screens inform your user about how it works and enable him to scan a QR code with his phone camera so he can start the acquisition process on his phone web browser.

desktop screens QR Code

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

desktop screens steps

# 3. Web component on mobile

The mobile screens are the responsive version of the desktop screens. Of course they don't have a QR code but a link the user can use to start his acquisition process:

web mobile sdk

When the user clicks on the link, a new tab will open to take him through the acquisition process.
He is asked to keep the initial tab open so he can come back to your workflow once he is done with his identity verification.

🖋️   Note:

The SDK is only responsible for guiding the user and launching the acquisition phase to capture and upload videos. You will still need to access the ShareID API to create identity verification requests.

# Quick Start

# 1. Obtain API Key

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 Key.
Please make sure you store them in a safe and secure place as they are your credentials to access ShareID.

Request API KEY

⚠️   Important:

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

# 2. Onboarding demand

Step 1: Use your API Key to request one time tokens so that you can securely communicate with ShareID's backend.
Step 2: Using the one time token generated, initiate an onboarding demand using and external id and a callback url.
Step 3: Record the videos on the front-end. Step 4: Send all the onboarding demand props and metadata to ShareID Step 5: Retrieve the results and your metadata from the callback url.

Request Onbaording demand

🖋️   Note:

Remember that you can use the metadata to pass elements from your backend to your front-end.

# 3. Authentication demand

Step 1: Use your API Key to request one time tokens so that you can securely communicate with ShareID's backend.
Step 2: Using the one time token generated and the user's UUID, initiate an authentication demand.
Step 3: Stream the user video to ShareID's backend through the SDK. Step 4: Receive authentication results in realtime.

Request Onbaording demand

🖋️   Note:

Remember to set callbacks for success and fail attempts.

# Getting started

# 1. Obtain API Key

You will need an API Key to communicate with ShareID's backend to get your tokens, send identity verification requests and receive your results.

To get your API Key, please carefully read the API Key documentation

# 2. Obtain authentication token

For security purposes, the ShareID authorization service requires a token per API call. This means that each demand requires a new token.
Access tokens must be included in the header of all requests made to the API.

Carefully read the Authentication token documentation to understand how to get a token.

# 3. Request an identity verification

Identity verification is used both for a one time identity verification and for the onboarding of users for authentcation with the official identity.

# 3.1. Install your npm package

Install the package : npm install @shareid/onboarding_desktop.

# 3.2. Get your authentication Token

Get your one time token from the authorization service to be able to launch your identity verification request.
If you don't know how to get your token yet, please read the Authentication token documentation to understand how to get a token.

# 3.3. Trigger the identity verification request

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

    type Metadata = {
        [key: string]: string,
        external_id: string,
        callback_url: string
    }

    type ShareIDProps = {
        accessToken: string,
        metadata: Metadata,
        multipleOnboarding?: boolean,
        language: 'en' | 'fr',
        onFail?: () => void,
        onSuccess?: () => void,
        environment?: 'prod' | 'sandbox' | 'staging'
    }

The web SDK will handle all the rest for you.

The configuration of the web SDK component is very simple and uses Metadataand props:

Parameter Format Comment
accessToken string required
The token you get through the authentication process
external_id string required
your id for this verification request
callback_url string required
the url where ShareID will send you the identity verification results
multipleOnboarding boolean required
unlock view to add applicants
language string required
default en
onFail void optional
callback function when the verification fails
onSuccess void optional
callback function when the verification suceeds
environment string required
default production

The language is at the hand of the user on the SDK screen.

🖋️   Note:

You can add additional metadata to your request. ShareID will always return your metadata within the results file. The externalId is a metadata used by ShareID to provide you with statistics regarding user retry, drop-off or failure.

In the component example below, my_key is a metadata example and can take any name.

# 3.4. Example Component

import { ShareID } from '@shareid/onboarding_desktop';
    < ShareID 
        accessToken="YOUR TOKEN HERE"
        metadata={
            external_id: "YOUR ID HERE",
            my_key: "MY VALUE", 
            callback_url: "MY CALLBACK URL HERE"
        }
        multipleOnboarding={false}
        language="en"
        onFail={ () => { any side effect here }}
        onSuccess={ () => { any side effect here }}
        environment='staging'
    />

# 4. Authentication with official identity

This feature is usable on users onboarded through the identity verification request.
If you haven't onboarded your user yet, refer to the documentation Identity Verification Request.

# 4.1. Install your npm package

Install the package using : 

npm install --save @shareid/authenticate_desktop

or 

yarn add @shareid/authenticate_desktop

# 4.2. Get your authentication Token

To launch the authentication with official identity process, get a one time token from the authorization service. This token can not be reused for another request. The process for getting tokens is described in the API Reference documentation in the Access Token section

# 4.3. Trigger the authentication request

Once you have your token, you can trigger an authentication with official identity request by setting your web SDK as described below:

    import React from "react";
    import { Authenticate } from "@shareid/authenticate_desktop";

    const App = () => (
    <View>
        <Authenticate
            accessToken="YOUR TOKEN HERE"
            uuid="USER UUID HERE"
            language="fr"
            onFail={ (data: object) => { /*any side effect here*/ }}
            onSuccess={ (data: object) => { /*any side effect here*/ }}
            environment='staging'
        />
    </View>
    );


    export default App;

The web SDK will handle all the rest for you.

The configuration of the web SDK component is very simple and uses props:

Name Description Type Required Default Value
accessToken The token you get through the authentication process string ✓
uuid your client/user id for this verification request string ✓
language default en string en
onFail callback function when the verification fails func
onSuccess callback function when the verification suceeds func false
environment default production string production

# Handling callbacks

# 1. Identity verification or onboarding

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

# Example onFailcallback
    < ShareID 
        accessToken="YOUR TOKEN HERE"
        onFail={ () => { 
            console.log("verification" & external_id & "failed")
         }},
         ...
    />

Callback that fires when both the document and face have been successfully captured and uploaded. You can then trigger your backend to create a check, using the associated applicant ID.

# onSuccess {function} optional

This the callback function that 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.

# Example onSuccesscallback
    < ShareID 
        accessToken="YOUR TOKEN HERE"
        onSuccess={ () => { 
            console.log("verification" & external_id & "completed")
         }},
         ...
    />

# 2. Authentication with official identity

# onFail

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.

type data = {
  error_code: number, // 0 | 1 | 2 | 3
  message: string // eg: "User not authenticated"
}

# onSuccess

This the callback function that 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.

type data = {
  success: true,
  message: string // eg: "User authenticated successfully"
}

# Customization

We are currently working to make the web SDK customizable at your hand. Meanwhile, you can request your tailor-made web SDK from the ShareID team before you go to production.

The web SDK can be fully customized on demand. You can change:

  • Colors
  • Style (font, size)
  • Text content
  • Add your logo

←