# 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 levels or pick a predefined one (e.g.
basic-kyc-level
) - 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. We also have a package for React. And launch SDK initialization function with an accessToken you generated on the second step
# Generating access token
All API requests must be authenticated as described in this section. For testing purposes make sure to use App token and Secret key pair that was created on Sandbox for request authorization headers.
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.
If you reuse access tokens make sure to set up an access token expiration handler (see the Frontend integration section)
# Frontend integration (general)
# 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 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(accessToken, applicantEmail, applicantPhone, customI18nMessages) {
let snsWebSdkInstance = snsWebSdk.init(
accessToken,
// token update callback, must return Promise
// Access token expired
// get a new one and pass it to the callback to re-initiate the WebSDK
() => this.getNewAccessToken()
)
.withConf({
lang: 'en', //language of WebSDK texts and comments (ISO 639-1 format)
email: applicantEmail,
phone: applicantPhone,
i18n: customI18nMessages, //JSON of custom SDK Translations
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 Customizations tab will rewrite customCss
// you may also use to pass string with plain styles `customCssStr:`
},
})
.withOptions({ addViewportTag: false, adaptIframeHeight: true})
// see below what kind of messages WebSDK generates
.on('idCheck.stepCompleted', (payload) => {
console.log('stepCompleted', payload)
})
.on('idCheck.onError', (error) => {
console.log('onError', error)
})
.build();
// you are ready to go:
// just launch the WebSDK by providing the container element for it
snsWebSdkInstance.launch('#sumsub-websdk-container')
}
function getNewAccessToken() {
return Promise.resolve(newAccessToken)// get a new token from your backend
}
Please make sure that an accessToken
was provided to SDK initialization function (it has a format like _act-b8ebfb63-5f24-4b89-9c08-5bbabeec986e
and can be obtained with API request) and not other kind of token.
# ATTRIBUTES OF withConf PARAMETER
Name | Type | Required | Description | Default |
---|---|---|---|---|
lang | String | No | Language of WebSDK texts and comments in ISO 639-1 format | 'en' |
country | String | No | Alpha-3 country code (Wikipedia) to prefill it on document upload screen | |
String | No | User's email to propagate it to the applicant | ||
phone | String | No | User's phone number to propagate it to the applicant | |
i18n | JSON | No | Custom SDK translations to change dynamically on SDK initialization. You can find format and default texts at the dashboard | |
uiConf | Object | No | SDK custom configuration. Check available attributes below | |
documentDefinitions | Object | No | Prefilled definitions on doCapture screen |
# ATTRIBUTES OF uiConf PARAMETER
Name | Type | Required | Description | Default |
---|---|---|---|---|
customCss | String | No | URL to your external css file for SDK to use it during initialization | |
customCssStr | String | No | Plain string with changes in css | |
scrollIntoView | Boolean | No | Disables/enables automatic scrolling to SDK view on SDK screen switches | true |
# STRUCTURE OF documentDefinitions PARAMETER
documentDefinitions is key value object, where keys are idDocSetType and values are documentDefinition
{ idDocSetType: documentDefinition }
# Example
documentDefinitions: {
IDENTITY: {idDocType: 'PASSPORT', country: 'GBR'}
}
# POSSIBLE idDocSetType VALUES
Value | Description |
---|---|
IDENTITY | Identity document step |
IDENTITY2 | Second identity document step |
IDENTITY3 | Third identity document step |
IDENTITY4 | Fourth identity document step |
# ATTRIBUTES OF documentDefinition PARAMETER
Name | Type | Required | Description |
---|---|---|---|
country | String | Yes | Alpha-3 country code (Wikipedia) |
idDocType | String | Yes | Document type |
# ATTRIBUTES OF withOptions PARAMETER
Name | Type | Required | Description | Default |
---|---|---|---|---|
addViewportTag | Boolean | No | Adds viewport meta tag for iFrame for mobile-optimized SDK adjustments | true |
adaptIframeHeight | Boolean | No | Allows our SDK to adapt its height depending on frame/container/page/screen size | true |
# Standalone working example
Below is a fully working example. Just substitute $ACCESS_TOKEN
with the appropriate value
(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(accessToken, applicantEmail, applicantPhone) {
let snsWebSdkInstance = snsWebSdk.init(
accessToken,
() => this.getNewAccessToken()
)
.withConf({
lang: 'en',
email: applicantEmail,
phone: applicantPhone,
i18n: {"document":{"subTitles":{"IDENTITY": "Upload a document that proves your identity"}}},
onMessage: (type, payload) => {
console.log('WebSDK onMessage', type, payload)
},
uiConf: {
customCssStr: ":root {\n --black: #000000;\n --grey: #F5F5F5;\n --grey-darker: #B2B2B2;\n --border-color: #DBDBDB;\n}\n\np {\n color: var(--black);\n font-size: 16px;\n line-height: 24px;\n}\n\nsection {\n margin: 40px auto;\n}\n\ninput {\n color: var(--black);\n font-weight: 600;\n outline: none;\n}\n\nsection.content {\n background-color: var(--grey);\n color: var(--black);\n padding: 40px 40px 16px;\n box-shadow: none;\n border-radius: 6px;\n}\n\nbutton.submit,\nbutton.back {\n text-transform: capitalize;\n border-radius: 6px;\n height: 48px;\n padding: 0 30px;\n font-size: 16px;\n background-image: none !important;\n transform: none !important;\n box-shadow: none !important;\n transition: all 0.2s linear;\n}\n\nbutton.submit {\n min-width: 132px;\n background: none;\n background-color: var(--black);\n}\n\n.round-icon {\n background-color: var(--black) !important;\n background-image: none !important;\n}"
},
onError: (error) => {
console.error('WebSDK onError', error)
},
})
.withOptions({ addViewportTag: false, adaptIframeHeight: true})
.on('idCheck.stepCompleted', (payload) => {
console.log('stepCompleted', payload)
})
.on('idCheck.onError', (error) => {
console.log('onError', payload)
})
.onMessage((type, payload) => {
console.log('onMessage', type, payload)
})
.build();
snsWebSdkInstance.launch('#sumsub-websdk-container')
}
function getNewAccessToken() {
return Promise.resolve($NEW_ACCESS_TOKEN)
}
launchWebSdk($ACCESS_TOKEN)
</script>
# React integration
# 1) Install websdk-react
import SumsubWebSdk from '@sumsub/websdk-react'
# 2) Initialize WebSDK
Make sure to use a newly generated accessToken for initialization and prepare accessToken expiration handler (usually it's just generating and using new accessToken)
<SumsubWebSdk
accessToken={accessToken}
expirationHandler={accessTokenExpirationHandler}
config={config}
options={options}
onMessage={messageHandler}
onError={errorHandler}
/>
# WebSDK messages
When providing the on
handler you will receive messages from the WebSDK for selected message type (all of them are prefixed with idCheck.
):
You can see all of those messages in your Browser dev console if you are launching the WebSDK from our dashboard.
messageType | Payload | Description |
---|---|---|
onReady | // id of the iframe in the current context | WebSDK resources have been loaded |
onInitialized | {} | The first screen is rendered |
onStepInitiated | { | A screen with that corresponds to '$idDocSetType' was shown |
stepCompleted | {"step": "$idDocSetType"} | Step '$idDocSetType' has been completed |
onApplicantLoaded | {"applicantId": "$id"} | Applicant with id $id has been loaded |
onApplicantSubmitted | {} | Documents were submitted for verification |
applicantStatus | { | Applicant status has been changed |
onApplicantResubmitted | {} | Documents were re-submitted for verification |
onActionSubmitted | {} | Applicant action was submitted |
actionCompleted | { | Applicant action $id was completed |
moduleResultPresented | { | Result of standalone module has been presented to the user. Valid only for "module" customization types. Happens either when the user has just completed the check or when user reopened the module for the previously completed check. Possible answers: GREEN - check was successful; YELLOW - user is allowed to proceed, final check result will be determined later; RED - user has been decisively rejected and is not allowed to proceed. Note, that if the rejection is not final, this even will not fire. |
onResize | { | WebSDK frame has been resized |
onVideoIdentCallStarted | {} | Video call was started by the user |
onVideoIdentModeratorJoined | {} | Video call was answered by operator |
onVideoIdentCompleted | {} | Video call was completed by operator |
onUploadError | { | Uploaded document was rejected. Available values of errors |
onUploadWarning | { | There are warnings about the uploaded document. Available values of warnings |
# Receiving verification results
On the sandbox checks will not be started automatically and therefore the webhooks will not be sent automatically either. Either ask us to do so manually, or trigger a webhook yourself by calling an API endpoint described here. Once integration is done, and you have moved to the production environment, the webhooks will be sent automatically once the verification procedure has been completed.
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.
- 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. - You can monitor webhook statuses and resend them manually on the
API Health
page of dashboard.
Please note that we may send several final webhooks, so be prepared to change the user's status on your side too. A typical example is when a user got approved, but later on he was detected as a fraudster, and therefore we block him with a second "RED" webhook.
# 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 from your end-user's point of view. To do so, we would kindly ask you to provide us with a link to your server.
Ensure that:
- Integration on the sandbox 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
# Moving to production
Please provide us info on expected amount of incoming users per hour/day/month if possible.
Note that settings won't be transferred from sandbox environment to production automatically. So don't forget to
- Set up webhooks at the Dev Space tab of production dashboard
- Tune regulation rules at Global settings tab of the dashboard
- Create and use production App Token and Secret Key for API authorization
# Customization
All the customization is done from our dashboard. You can customize styles (via custom CSS), navigation, etc. To change all SDK texts by locales you should use SDK Translations tab. 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 or use you own Twilio credentials for Phone verification
step,
you have to set it up at the dashboard and make sure that target regions are enabled in your twilio account here.
# Tips & Tricks
# WebView usage
The best way to use our services within mobile applications is by implementing our MobileSDK. But if you have to use WebView, please check tips below.
For initializing WebSDK within mobile app using WebView make sure that
- WebView is able to access device local storage and initialize camera (for older iOS versions camera can be accessed only from Safari browser or WebView with
SFSafariViewController
) - Make sure that HTML5 video playback is allowed (we're using some instructions within
<video>
tags): if video-instructions are not played, try usingWebChromeClient
to enable video playback - Autoplay in fullscreen mode is disabled and
allowsInlineMediaPlayback
is set astrue
for WebView with running SDK
# Camera access
If you're experiencing troubles with camera access for liveness, please make sure that
Feature-Policy
header for your webpage/frame or any other container with SDK doesn't have any restrictions for initializing camera like valuecamera 'none'
.Permissions-Policy
header doesn't restrict access to a camera and microphone (for some cases) and ifallow
is set check for"camera; microphone"
values.- Your website is being run on secure
https
connection.
# Placement
For the best conversion try to initialize SDK by the center of screen, so it would be easier for users to pay attention to instruction for during verification process.
SDK's iframe resizes itself regarding its container and SDK screen content - so container itself shouldn't have a static size but should adjust to screen size: try to use <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
tags.
# FAQ
# How can we get the applicantId
?
Two ways:
- When 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 theapplicantId
- GET
/resources/applicants/-;externalUserId=${externalUserId}/one
This endpoint will throw a 404
if no applicant exists with such a user id.
# Where can I find a list of supported locales?
Please check the list of supported languages by SDK here.