Set up frontend integration

To integrate the SDK:

  1. Install the NMP package.
npm i @sumsub/websdk --save
# OR
yarn add @sumsub/websdk
  1. Import the snsWebSdk module.
import snsWebSdk from '@sumsub/websdk';

Alternatively, use the standalone package.

<script src = "https://static.sumsub.com/idensic/static/sns-websdk-builder.js"></script>
  1. Create a container for the WebSDK on your page.
<!-- iframe will be inserted as a child element -->
<div id="sumsub-websdk-container"></div>
  1. Initialize the 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
}
/**
 * @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,
            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
}

📘

Note

  • Make sure that accessToken was provided to the SDK initialization function. For more information on how to obtain the token, see Generate access token.
  • For the best conversion, try to initialize the SDK by the center of the screen, so it would be easier for users to pay attention to instructions during verification process.
  • 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.

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 to prefill it on document upload screen.

N/A

email

String

No

User's email to propagate it to the applicant.

N/A

phone

String

No

User's phone number to propagate it to the applicant.

N/A

i18n

JSON

No

Custom SDK translations to change dynamically on SDK initialization.

N/A

uiConf

Object

No

SDK custom configuration.

N/A

documentDefinitions

Object

No

Pre-filled definitions on the doCapture screen.

N/A

ATTRIBUTES OF uiConf PARAMETER

Name Type Required Description Default

customCss

String

No

URL to your external CSS file for SDK to use during initialization.

N/A

customCssStr

String

No

Plain string with changes in CSS.

N/A

scrollIntoView

Boolean

No

Disables/enables automatic scrolling on SDK screen switches.

true

STRUCTURE OF documentDefinitions PARAMETER

The documentDefinitions parameter is a key-value object, where keys are idDocSetType and values are documentDefinition.

Possible values of idDocSetType are:

Value Description

IDENTITY

Identity document step.

IDENTITY2

Second identity document step.

IDENTITY3

Third identity document step.

IDENTITY4

Fourth identity document step.

Possible attributes of documentDefinition are:

Name Type Required Description

country

String

Yes

Alpha-3 country code.

idDocType

String

Yes

Document type.

ATTRIBUTES OF withOptions PARAMETER

Name Type Required Description Default

addViewportTag

Boolean

No

Adds the viewport metatag 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

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.

N/A

email

String

No

User's email to propagate it to the applicant.

N/A

phone

String

No

User's phone number to propagate it to the applicant.

N/A

theme

'dark' or 'light'

No

Sets a light or dark theme. Set 'dark'|'light' to match your website current theme. By default, with no theme attribute, the theme is automatically selected and follows the user device theme.

N/A

ATTRIBUTES OF withOptions PARAMETER

Name Type Required Description Default

addViewportTag

Boolean

No

Adds the viewport metatag 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

React integration

To integrate with React:

  1. Install websdk-react.
import SumsubWebSdk from '@sumsub/websdk-react'
  1. Initialize WebSDK.
<SumsubWebSdk
  accessToken={accessToken}
  expirationHandler={accessTokenExpirationHandler}
  config={config}
  options={options}
  onMessage={messageHandler}
  onError={errorHandler}
/>

📘

Note

Make sure to use a newly generated accessToken for initialization and prepare an expiration handler.