Get started with WebSDK integration
Integrate with the Sumsub WebSDK.
To get started with the WebSDK integration:
- Generate an access token to be passed to the WebSDK during initialization.
- Install an NPM package or use the CDN version of the script. We also have a package for React.
- Launch the WebSDK initialization function with the
accessTokenparameter you have generated at the first step, as shown in the standalone example. - Conduct verification and handle results.
Note
To initialize the WebSDK within the mobile app using
WebView, make sure that:
WebViewis able to access device local storage and initialize the camera. For older iOS versions, the camera can be accessed only from the Safari browser or WebViewSFSafariViewController.- HTML5 video playback is allowed (we are using some instructions within
<video>tags). If the video instructions are not played, try usingWebChromeClientto enable video playback.- Autoplay in fullscreen mode is disabled and
allowsInlineMediaPlaybackis set totrueforWebViewwith running SDK.- Callbacks for file selection and camera invocations are correctly configured on the host application side (required for file uploads).
Generate SDK access token
To generate an access token, use this API method as the following example demonstrates:
curl --request POST \
--url https://api.sumsub.com/resources/accessTokens/sdk \
--header 'content-type: application/json' \
--data '
{
"applicantIdentifiers": {
"email": "[email protected]",
"phone": "555-1111"
},
"ttlInSecs": 600,
"userId": "johndoeID",
"levelName": "basic-kyc-level"
}
'
{
"token": "eyJhbGciOiJub25lIn0.eyJqdGkiOiJfYWN0LTZmODI2ZTU0LTE2MzctNDViMS05NzMyLWY1MjZiN2YxNWE3YyIsInVybCI6Imh0dHBzOi8vYXBpLnN1bXN1Yi5jb20ifQ.",
"userId": "johndoeID"
}
Note
- Provide a unique and meaningful
userIdparameter, which can be an external user ID in your system or an email address. If youruserIdorlevelNamecontains reserved characters (e.g.,@,+, white spaces as%20), they should be URL-encoded, otherwise you may get a signature mismatch or just an invalid parameter value.- When generating an access token for Local Data Processing, use the regional domain. For example,
api.uae.sumsub.com. Further processing will be carried out in the region, which is guaranteed by our SDKs.- Authenticate all API requests as described in this article.
- For testing purposes, use an app token and secret key pair created in Sandbox mode to request authorization headers.
- Make sure your integration code does not validate or analyze the access token content, as the format is not fixed and may undergo changes. The token must be treated as an arbitrary string with the maximum length of 1KB.
- An access token for the applicant has limited access to the API, e.g., it is only valid for 1 applicant and cannot access other applicants. If you reuse access tokens, set up an access token expiration handler.
Set up frontend integration
To integrate the WebSDK:
- Install the NPM package.
npm i @sumsub/websdk --save
yarn add @sumsub/websdk
- Import the
snsWebSdkmodule.
import snsWebSdk from '@sumsub/websdk';
Alternatively, use the standalone package.
<script src = "https://static.sumsub.com/idensic/static/sns-websdk-builder.js"></script>
- Create a container for the WebSDK on your page.
<!-- iframe will be inserted as a child element -->
<div id="sumsub-websdk-container"></div>
- Initialize the WebSDK.
/**
* @param accessToken - access token that you generated on the backend
*/
function launchWebSdk(accessToken) {
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)
theme: "dark" | "light",
})
.withOptions({ addViewportTag: false, adaptIframeHeight: true })
// see below what kind of messages WebSDK generates
.on("idCheck.onStepCompleted", (payload) => {
console.log("onStepCompleted", 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
}
/**
* @param accessToken - access token that you generated on the backend
* @param customI18nMessages - customized locale messages for current session (not required)
*/
function launchWebSdk(accessToken, 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)
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
}
Note
- Make sure that
accessTokenwas provided to the SDK initialization function.- SDK's iframe resizes itself according to its container and SDK screen content, so the container itself shouldn't have a static size, but should adjust to the screen size. Try to use the
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">tags.
React integration
To integrate with React:
- Install
websdk-react.
import SumsubWebSdk from '@sumsub/websdk-react'
- Initialize the WebSDK.
<SumsubWebSdk
accessToken={accessToken}
expirationHandler={accessTokenExpirationHandler}
config={config}
options={options}
onMessage={messageHandler}
onError={errorHandler}
/>
Note
Use a newly generated
accessTokenfor initialization and prepare an expiration handler.
Standalone example of WebSDK initialization
The following is a fully working example; — change the $ACCESS_TOKEN variable with the appropriate value, save it to an HTML file, and open 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,
})
.withOptions({ addViewportTag: false, adaptIframeHeight: true })
.on("idCheck.onStepCompleted", (payload) => {
console.log("onStepCompleted", payload);
})
.on("idCheck.onError", (error) => {
console.log("onError", error);
})
.onMessage((type, payload) => {
console.log("onMessage", type, payload);
})
.build();
snsWebSdkInstance.launch("#sumsub-websdk-container");
}
// Requests a new access token from the backend side.
function getNewAccessToken() {
return Promise.resolve($NEW_ACCESS_TOKEN);
}
launchWebSdk($ACCESS_TOKEN);
</script>
<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", error);
})
.onMessage((type, payload) => {
console.log("onMessage", type, payload);
})
.build();
snsWebSdkInstance.launch("#sumsub-websdk-container");
}
// Requests a new access token from the backend side.
function getNewAccessToken() {
return Promise.resolve($NEW_ACCESS_TOKEN);
}
launchWebSdk($ACCESS_TOKEN);
</script>
Updated 5 days ago