IDnGO Documentation

# WebSDK

# WebSDK Integration

To start integrating WebSDK, you need to:

  1. Generate a temporary access token accessToken, as described in the Getting Started section.
  2. Install the NPM package or use the CDN version of the script, and then initialize it with the access token, as explained below.
  3. If you reuse access tokens, make sure you have set up a handler for token expiration.

# Integration setup

  1. Install the NPM package:
npm yarn
  1. Import the cyberitySdk module:
import  cyberitySdk  from  '@idngo/websdk';
  1. Create a container for WebSDK on your page.
<!-- The iframe will be inserted as a child element -->
<div  id="cyberity-websdk-container"></div>
  1. Initialize WebSDK:
/**
    * @param accessToken - the access token generated on your backend
    * @param applicantEmail - user email (optional)
    * @param applicantPhone - user phone number, if available (optional)
    */
function  launchWebSdk(accessToken, applicantEmail, applicantPhone) {
    let  sdkInstance  =  cyberitySdk.init(
        accessToken,
        // callback for refreshing the token, must return a Promise
        // access token has expired
        // obtain a new one and pass it to the callback to relaunch WebSDK
        () =>  this.getNewAccessToken()
    )

        .withConf({
            lang: 'ru', // language of WebSDK text and comments (ISO 639-1 format)
            email: applicantEmail,
            phone: applicantPhone,
        })

        .on('idCheck.stepCompleted', (payload) => {
            console.log('stepCompleted', payload)
        })

        .on('idCheck.onError', (error) => {
            console.log('onError', error)
        })

        .build();

    // launch WebSDK in the specified container element
    sdkInstance.launch('#websdk-container');
}

function  getNewAccessToken() {
    return  Promise.resolve(newAccessToken) // obtain a new token from your backend
}

Make sure that the token provided during SDK initialization is an accessToken, not any other type of token.

# WebSDK configuration

Here you will find information about WebSDK configuration parameters, message types, and their payloads.

Fields of the withConf element

Name Type Required Description
lang String No Language for WebSDK texts and comments in ISO 639-1 format (default: en).
country String No Three-letter country code Alpha-3 (for example, RUS) for pre-filling on the document upload screen.
email String No User's email address.
phone String No User's phone number.
i18n JSON No Your custom SDK translations that will dynamically change during initialization. The default format and texts can be found in the «SDK Translations» section.
uiConf Object No Your custom SDK UI settings.
documentDefinitions Object No Definitions for the doCapture screen.

Fields of the uiConf element

Name Type Required Description
customCss String No URL of your external CSS file to be applied by the SDK during initialization.
customCssStr String No A string containing CSS modifications.
scrollIntoView Boolean No Enables or disables automatic scrolling of the SDK when switching screens (default is true).

Structure of the documentDefinitions element

documentDefinitions is a key-value object {idDocSetType: documentDefinition}, where the keys are idDocSetType and the values are documentDefinition.

# Example

documentDefinitions: {
    IDENTITY: {idDocType: 'PASSPORT', country: 'GBR'}
}

Fields of the documentDefinition element

Name Type Required Description
country String Yes Three-letter country code Alpha-3 (for example, RUS).
idDocType String Yes Type of the document.

Available values for idDocSetType

Name Description
IDENTITY Identity verification step.
IDENTITY2 Second identity verification step.
IDENTITY3 Third identity verification step.
IDENTITY4 Fourth identity verification step.

See the list of verification steps.

Fields of the withOptions element

Name Type Required Description
addViewportTag Boolean No Adds an iFrame viewport meta tag to adapt the SDK for mobile devices (default is true).
adaptIframeHeight Boolean No Allows the SDK to adjust its height based on the page/screen size (default is true).

# WebSDK example

Below is a fully working example. Simply replace $ACCESS_TOKEN with the appropriate value.

html main.js

# WebSDK messages

The on handler allows you to receive messages from WebSDK about various important events, such as changes in applicant status, actions, etc. All messages are prefixed with idCheck.

You can view all these messages in your browser's developer console (DevTools) if you launch WebSDK from our Dashboard.

Message Type Payload Description
onReady 
// id of the iframe in the current context 
{}
 WebSDK resources have been loaded.
onError 
{
  "code":  "invalid-origin" |
 "initialization-error" | "invalid-token" |
 "invalid-config" | "bad-request",
  "error": "Error message" 
}
 Verification error occurred. Detailed reason is in "error" field.
onInitialized 
{}
 The first page has been rendered.
onStepInitiated 
{ 
 "idDocSetType": "$idDocSetType", 
 "types": ["$idDocType1", "$idDocType2"] 
 }
 The screen corresponding to $idDocSetType is displayed.
onStepCompleted
or
stepCompleted		 
{ 
 "step": "$idDocSetType" 
 }
 The verification step $idDocSetType has been completed.
onApplicantLoaded 
{ 
 "applicantId": "$id" 
 }
 Applicant with ID $id has been loaded.
onApplicantSubmitted 
{}
 Documents have been submitted for verification.
applicantStatus 
{ 
 "reprocessing": false, 
 "levelName": "$levelName", 
 "createDate": "$createDate", 
 "expireDate": "$expireDate", 
 "reviewStatus": "$reviewStatus", 
 "autoChecked": false 
 }
 Applicant verification status has changed.
onApplicantResubmitted 
{}
 Documents have been resubmitted for verification.
onUploadError 
{
 "code": "$error",
 "msg": "Error message" 
}
 Uploaded document was rejected. See the available values here.
onUploadWarning 
{
  "code": "$warning",
  "msg": "Warning message"
}
 Warnings about the uploaded document. The msg field contains a warning — see here.
onActionSubmitted 
{}
 Applicant action has been submitted for verification.
onActionCompleted 
{ 
 "action": "$actionType", 
 "applicantActionId": "$id", 
 "answer": "$answer" 
 }
 Verification of applicant action $id has been completed.
onModuleResultPresented 
{ 
 "answer": "GREEN" 
 }
 The verification result has been presented to the user. (GREEN/YELLOW/RED)

# Webhooks

Your backend receives results via webhooks. For use in the Production environment, we recommend setting up your own webhook endpoint, which we will call as needed.

The URL where you will receive results can be set in the «Webhook manager» section.

# Receiving verification results

You can always check an applicant's status manually using this endpoint, but we do not recommend using API requests as the primary method for receiving verification results. We strongly recommend using webhooks instead.

In case a webhook is not received for any reason, we log everything we attempt to send you and can resend the webhook at any time. If a webhook fails to be delivered, we retry four times: after 5 minutes, 1 hour, 5 hours, and 18 hours, until the request is successful. Therefore, check the createdAt field in the webhook payload to ensure you receive the applicant's current status. We recommend waiting no more than 24 hours for the webhook, after which you can query our server for the applicant's status.

You can track webhook statuses and resend them manually in the «Dev space» section.

Warning:

Please note that we may send multiple final webhooks, so be prepared for the applicant's status to change on your side as well. A typical example is when an applicant was initially approved but later identified as a fraudster, resulting in a second final webhook with status RED.

In the Sandbox environment, verifications do not run automatically, and therefore webhooks are also not sent automatically. You can either request us to trigger them manually or send the webhook yourself using this API request.

Once the integration is complete and you move to the Production environment, webhooks will be sent automatically after the verification process is finished.

# WebSDK personalization

We provide the ability to use your own branding in WebSDK and email notifications: you can customize logos, texts, CSS, and external links to your domain.

The main settings can be found in the «Branding» and «WebSDK Settings» tabs in the Dashboard. You can change SDK texts in different languages in the «SDK Translations» section.

More detailed information is available in the Dashboard tips.

By default, if you configure email sending on our side, the user will receive a link to our WebSDK hosted on the api.idngo.kz domain. The same applies to the «Continue on phone» WebSDK links and QR codes.

Through «WebSDK Settings» in the Dashboard, you can set the «External WebSDK Link» parameter, which changes the domain of the link and adds a JWT key for link authentication. To use this, you must initialize WebSDK on your side using the dynamic link with JWT and its verified value. The JWT contains externalUserId (applicant identifier) and clientId (your identifier in our system). This allows you to make requests and use the correct accessToken. The token is generated using the HMACSHA256 algorithm, and the secret key is used without encoding to create the JWT signature.

  • Your URL: https://your-project.io/kyc
  • Secret key for signing the user link: 1
  • externalUserId: userId_8
  • clientId: your-project

Example of the final link:

https://your-project.io/kyc?jwt=eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2MjAwNTI1MjcsImV4cCI6MTYyMDY1NzMyNywic3ViIjoidXNlcklkXzgiLCJhdWQiOiJzdW1zdWIifQ.qCR-4VMfC_zOAN1hCtbjj9DJxmB6c0sEg7XD5Y8ZvvM

Example of JWT payload:

{
  "iat": 1620052527, // Issued at (seconds since Unix epoch)
  "exp": 1620657327, // Expires at (seconds since Unix epoch)
  "sub": "userId_8", // External ID of the applicant (externalUserId)
  "aud": "your-project"  // Your identifier (clientId)
}

# Email notifications for users

You can configure email notifications for users by selecting the desired options under «Email notifications» in the level settings.

To use branded email notifications, you need to add the following in the «Branding» section:

  • Icon,
  • Logo,
  • Sender email address in the «Send customer emails from» field.

All email text can be customized for each language in the «SDK Translations» section.

If you want to allow us to send emails on behalf of your domain, you need to configure SPF and DKIM records on your DNS server.

# SPF

  • Create or edit an SPF record to include IDnGO.
  • Add a .TXT record in your domain's DNS settings.

We recommend using the following SPF record:

v=spf1 include:_spf.cyberity.ru ~all

If you already have an SPF record for another purpose, you can simply add the IDnGO include:

include:_spf.cyberity.ru

Warning:

Not having an SPF record configured will result in our emails being blocked for users. In this case, email sending will be automatically disabled on our side.

# DKIM

Edit your domain's DNS settings to add CNAME records.

The CNAME records should have the following format:

cyberity1._domainkey CNAME cyberity1._domainkey.cyberity.ru.
cyberity2._domainkey CNAME cyberity2._domainkey.cyberity.ru.

You can verify the correctness of the record using the following tools:

# Recommendations

# Using WebView

To initialize WebSDK in a mobile application via WebView, make sure that:

  • The WebView can access the device's local storage and initialize the camera (for older iOS versions, camera access is only possible via the Safari browser or a WebView using SFSafariViewController);

  • HTML5 video playback is allowed (we use some instructions within <video> tags). If video instructions do not play, try using WebChromeClient to enable video playback;

  • Autoplay in fullscreen mode is disabled, and allowsInlineMediaPlayback is set to true for the WebView running the SDK.

# Camera access

If you encounter issues with accessing the camera for liveness checks, make sure that:

  • The Feature-Policy header for your webpage/frame does not impose any restrictions on camera initialization (for example, value camera 'none');

  • The Permissions-Policy header does not restrict access to the camera and microphone; if the allow parameter is set, verify that it includes camera; microphone;

  • Your site operates over a secure HTTPS connection.

# Placement

For optimal conversion, try to initialize the SDK at the center of the screen so that users can more easily follow the instructions during the verification process.

The SDK iframe resizes relative to its container and the SDK screen content, so the container itself should not have a fixed size but should adapt to the screen size. Try using the following meta tag: <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">.