# WebSDK

# Introduction

The easiest way to start with our solution is to use our WebSDK. We put lots of efforts to improve conversion of your users and we thought about little details that make a difference. You will love WebSDK because:

• It is highly customizable (choose any steps you want, change styles or copy)
• Feature a face liveness module that improves conversion and minimizes fraud
• Adaptive design and mobile friendly
• Gives hints to users about how to better pass the flow
• Ability to continue on mobile
• Automatically refreshes when status is changed

# Integration

# Steps overview

Here are 3 simple steps that you should do:

• Step 1: [Dashboard] Set up your applicant flow or pick a predefined one (e.g. basic-kyc)
• Step 2: [Backend] Generate an Access token to pass it later on to the WebSDK
• Step 3: [Frontend] Install an NPM package or use CDN version of the script and launch it with the flow you picked on the first step

# Generating an access token

To initialize a WebSDK you must generate a temporary access token, which is also passed to the WebSDK initialization. This action must be performed on the server side. You also have to provide a userId query parameter, that is unique and meaningful. It can be an external user ID in your system, or an email address. Do not randomly generate these IDs, unless you do testing.

# Frontend integration

# 1a) Install the package - NPM

npm i @sumsub/websdk --save
# OR
yarn add @sumsub/websdk

Import the module

import snsWebSdk from '@sumsub/websdk';

# 1b) Install the package - Standalone

<script src = "https://static.sumsub.com/idensic/static/sns-websdk-builder.js"></script>

# 2) Create a container for the WebSDK on your page

<!-- iframe will be inserted as a child element -->
<div id="sumsub-websdk-container"></div>

# 3) Initialize a WebSDK

/**
 * @param apiUrl - 'https://test-api.sumsub.com' (sandbox)
                    or 'https://api.sumsub.com' (production)
 * @param flowName - the flow name chosen at Step 1 (e.g. 'basic-kyc')
 * @param accessToken - access token that you generated on the backend in Step 2
 * @param applicantEmail - applicant email (not required)
 * @param applicantPhone - applicant phone, if available (not required)
 * @param customI18nMessages - customized locale messages for current session (not required)
 */
function launchWebSdk(apiUrl, flowName, accessToken, applicantEmail, applicantPhone, customI18nMessages) {
    let snsWebSdkInstance = snsWebSdk.Builder(apiUrl, flowName)
        .withAccessToken(
            accessToken,
            (newAccessTokenCallback) => {
                // Access token expired
                // get a new one and pass it to the callback to re-initiate the WebSDK
                let newAccessToken = this.newAccessToken(); // get a new token from your backend
                newAccessTokenCallback(newAccessToken)
            }
        )
        .withConf({
            lang: 'en',
            email: applicantEmail,
            phone: applicantPhone,
            i18n: customI18nMessages,
            onMessage: (type, payload) => {
                // see below what kind of messages the WebSDK generates
                console.log('WebSDK onMessage', type, payload)
            },
            uiConf: {
                customCss: "https://url.com/styles.css"
                // URL to css file in case you need change it dynamically from the code
                // the similar setting at Applicant flow will rewrite customCss
                // you may also use to pass string with plain styles `customCssStr:`
            },
            onError: (error) => {
                console.error('WebSDK onError', error)
            },
        })
        .build();

    // you are ready to go:
    // just launch the WebSDK by providing the container element for it
    snsWebSdkInstance.launch('#sumsub-websdk-container')
}

# Standalone working example

Below is a fully working example. Just substitute $FLOW_NAME and $ACCESS_TOKEN with the appropriate values (see steps above), save it to an HTML file and open it in your browser.

<html>
 <head>
  <title>WebSDK CDN Example</title>
 </head>
 <body>
	<script src="https://static.sumsub.com/idensic/static/sns-websdk-builder.js"></script>
	<div id="sumsub-websdk-container"></div>
</body>
</html>
<script>

function launchWebSdk(apiUrl, flowName, accessToken, applicantEmail, applicantPhone) {
    let snsWebSdkInstance = snsWebSdk.Builder(apiUrl, flowName)
        .withAccessToken(
            accessToken,
            (newAccessTokenCallback) => {
                newAccessTokenCallback(accessToken)
            }
        )
        .withConf({
            lang: 'en',
            email: applicantEmail,
            phone: applicantPhone,
            onMessage: (type, payload) => {
                console.log('WebSDK onMessage', type, payload)
            },
            onError: (error) => {
                console.error('WebSDK onError', error)
            },
        })
        .build();
    snsWebSdkInstance.launch('#sumsub-websdk-container')
}

    launchWebSdk('https://test-api.sumsub.com', $FLOW_NAME, $ACCESS_TOKEN)
</script>

# WebSDK messages

When providing the onMessage handler you will receive messages from the WebSDK (all of them are prefixed with idCheck.):

// id of the iframe in the current context 
{}

{}

{
  "idDocSetType": "$idDocSetType",
  "types": ["$idDocType1", "$idDocType2"] 
  }

{"step": "$idDocSetType"}

{"applicantId": "$id"}

{}

{
 "reprocessing": false,
 "levelName": "$levelName",
 "createDate": "$createDate",
 "expireDate": "$expireDate",
 "reviewStatus": "$reviewStatus",
 "notificationFailureCnt": 0,
 "autoChecked": false
 } 

{}

{}

{
  "applicantActionId": "$id"
}

{
  "answer": "GREEN" 
}

{
  "height": 159 
}

{}

{}

{}

# Receiving verification results

Your backend receives results via a web-hook mechanism. You can get the results via email, Slack or Telegram. But for production use we recommend setting up a web-hook endpoint that we would call when necessary:

• We need a webhook URL from you to send your results to. You can set up webhooks in developer's space at test and production environments.
• We may send several types of webhooks, but the one that is of interest to you is the one described in the "Getting verification results" section. We encourage you to carefully get accustomed to this section, since there are quite a few options for what the results may look like.
• If you want to manually check the applicant status you can always do it by this method. However, we don't recommend using polling as base method for getting verification results and rather strongly encourage the webhook mechanism. If for some reason you missed the webhooks, don't worry: we make a note of everything that was attempted to be sent, and can resend failed webhooks at any point in time. If webhook request fails we attempt to resend it four times: after 5 minutes, 1 hour, 5 and 18 hours until request succeeds. Check createdAt field of webhook payload to make sure that you're getting relevant applicant status.
• Also you can monitor webhook statuses and resend them manually on the API Health page of dashboard on test and production.

# Getting the production key

# How can we get the production key?

In order to ensure the best experience for you and your users, before giving you access to the production environment, we would like to test the flow and pass the verification as your end-user. To do so, we would kindly ask you to provide us with a link to your server.

Ensure that:

• Integration on the test environment is completed, works and meets your requirements
• There are no dev console errors or warnings
• You saved our applicantIds to your database and matched your users
• You received and successfully processed test webhooks from our side
• You know how to correlate results received in the webhook payload with your users

# What information should be provided to obtain a production key?

Please provide us with:

• An email where we can send the production credentials
• A webhook URL for the production environment (you can set them up by yourself here)
• Set up a list of countries to be excluded (Example: USA, RUS, IRL) and the age threshold for your users here

# Customization

All the customization is done from our dashboard. You can customize texts, styles, navigation, etc. See hints and guides in the dashboard for more details.

# Twilio integration

If you want to allow your users to send verification links via SMS to their mobile devices, you have to set it up at dashboard on production and test and make sure that target regions are enabled in your twilio account here.

# FAQ

# How can we get the applicantId?

Two ways:

• When a user completes a first page an applicant is created. At this moment we send webhook to your endpoint with type applicantCreated. Its payload will contain the applicantId
• GET /resources/applicants/-;externalUserId=${externalUserId}/one