NAV Navbar
  • Verifai Web SDK Setup (v2.3.x)
  • Registration on the Verifai Dashboard
  • Setup the Verifai Frontend
  • Verifai Web SDK Setup (v2.3.x)

    Welcome to the Verifai Web SDK implementation documentation. A ready-to-use flow for the web for the best user experience in your application. If you have any unanswered questions you can always contact our support.

    This documentation will continue to expand as extra services will be added.

    Older versions:

    Documentation for older versions can be found below:

    Registration on the Verifai Dashboard

    Here we will describe how you can subscribe to our Web SDK SaaS.

    We assume you already have an account at our dashboard. To subscribe to our SaaS solution you will need to follow the next steps:

    1. Click on "Your solutions" in the top bar.
    2. Manage the solution you want to group the Web SDK in or create a new solution.
    3. Click the "Add implementation" button and select the Web SDK.
    4. Now you can reveal your API key.

    Please handle your API key responsibly, as that is what will allow you to start new Verifai processes for your customers.

    Setup the Verifai Frontend

    Prerequisites

    There are a few things you need:

    Authorization Overview

    A One Time Password (OTP) can be used to start a single session.

    After it is used it cannot be used again.

    The following steps are needed to Authorize a WebSDK session:

    The process of obtaining and supplying the OTP is shown in the figure below:

    Global overview

    Obtaining the One Time Password (OTP)

    import json
    import requests
    
    api_token = '<YOUR API KEY>'
    endpoint = 'https://websdk.verifai.com/v1/auth/token'
    handover_base_url = '<YOUR HANDOVER URL>'
    
    data = {
      'document_type_whitelist': ["P", "I"],
      'handover_base_url': f'{handover_base_url}?s=',
      'locale': "en_US"
    }
    headers = {
      'Authorization': f'Bearer {api_token}'
    }
    
    response = requests.post(endpoint, json=data, headers=headers)
    

    To initialize your Verifai frontend you need an OTP endpoint in your backend. The OTP can only be retrieved with the API token obtained from the Verifai Dashboard.

    To the right, an example is shown on how you could retrieve the OTP from the Verifai backend. From your backend, you need to supply your frontend with the Verifai OTP.

    You can find more detailed information on the public endpoints here

    Endpoint body

    Key Type Required Example Default Api link
    document_type_whitelist array [ ] ["P"] All link
    country_choices_whitelist array [ ] ["NL"] All link
    country_choices_blacklist array [ ] ["BE"] None link
    handover_base_url str [ ] See link - link
    allow_edit_privacy_filters bool [ ] true true -
    locale str [ ] "en_US" "en_US" link
    enable_viz bool [ ] true true link
    enable_facematch bool [ ] false false link

    Implementing the Verifai Frontend

    <!DOCTYPE html>
    <html lang="en">
    <head>
    
      <!-- React is needed in the current version of the SDK -->
      <script crossorigin src="https://unpkg.com/react@17/umd/react.production.min.js"></script>
      <script crossorigin src="https://unpkg.com/react-dom@17/umd/react-dom.production.min.js"></script>
    
      <!-- For mobile devices -->
      <meta name="viewport" content="width=device-width, initial-scale=1">
    
    </head>
    <body>
      <!-- Inject Verifai js -->
      <script src="dist/bundle.js"></script>
    
      ...
    
      <div id="verifai-mount"></div>
    
      ...
    
    </body>
    </html>
    

    With the OTP we can start implementing the frontend.

    As mentioned here The Verifai frontend consists of two flows:

    1. The main flow (implemented on your main web page)
    2. Handover flow (implemented on a separate web page)

    The main flow should be implemented in your main "Know your customer flow". To the right, we supplied the necessary HTML to include the Web SDK into your frontend.

    In general there are four things you need to do:

    1. Inject React 17.x.x.
    2. Inject the Verifai bundle.js in the body (bundle.css is removed starting from version 2.0.0).
    3. Create a mount point (div) for the Verifai app to mount to.

    Start the Verifai Main Flow

    const config  = {
      token: "<OTP_TOKEN>",
      assetsUrl: 'dist/assets',
    
      onSuccess: (sessionID) => {
        make_your_own_callback(sessionId)
        // Here you can get the Verifai Result
        // And clear the temperal storage
      },
      onCanceled: (sessionID) => {
        make_your_own_callback()
        // Here your customer canceled the Verifai flow
        // And clear the session
      }
    }
    // Get the element Verifai should be mounted on
    const verifaiElement = document.getElementById('verifai-mount')
    
    // Create a WebSDK object
    const webSDK = new Verifai.WebSDK(config, verifaiElement)
    
    // Start the SDK
    webSDK.start()
    
    

    Or if you are using React, in your package.json:

    
    {
      "dependencies": {
        "react": "^17.0.2",
        "react-dom": "^17.0.2",
    
        // path to the Verifai websdk package
        "verifai-websdk": "file:./dist"
        // on Linux and Mac add the "file:" prefix -> "file:./dist"
        // on Wndows it should not be added -> "./dist"
      }
    }
    
    

    Then use as:

    
    import {WebSDKReact} from "verifai-websdk"
    
    <WebSDKReact
        token="<OTP_TOKEN>"
        assetsUrl="dist/assets"
    
        show={true} // you can manipulate the show prop to show and hide the modal.
    
        onSuccess={sessionID => {
          // set show prop to false, to close the modal
    
          // Here you can get the Verifai Result
          // And clear the temperal storage
        }}
       onCanceled={sessionID => {
          // set show prop to false, to close the modal
          // Here your customer canceled the Verifai flow
          // And clear the session
    
        }}
    />
    
    

    With the HTML in place and scripts loaded we can start the Verifai flow. To the right a Javascript example is given of how you can initialize the Verifai flow.

    Config

    Key Type Required Description Default
    token str [x] The OTP token -
    assetsUrl str [x] Url to the assets -
    onSuccess fn [ ] Callback for when the flow finishes link
    onCanceled fn [ ] Callback for when the flow is canceled link
    closable bool [ ] Flow can always be closed false
    showGreeting bool [ ] Will show a greeting at beginning of flow true
    showSMS bool [ ] Will show a SMS option for using the handover true
    uploadTypes array [ ] Restrict upload types ["phone", "file"]
    backendUrl str [ ] The url to the Verifai backend SaaS
    theme object [ ] Theme of the sdk link
    faceMatchMobileOnly bool [ ] Allow the Face Match feature only on Mobile Flow false

    uploadTypes

    The format for uploadTypes has changed to an array instead of a single value starting from version 2.1.0. It has also been renamed from uploadType to uploadTypes.

    Accepted types are:

    Type Description
    "phone" Enables the handover flow
    "file" Enables the file upload flow
    "scanner" Enables the scanner flow, Only in Electron on Windows

    The upload types can carry extra configuration, for now this is only supported for the scanner (see here for options).

    An upload type can therefore be formated as one of the following:

    An example is given to the right.

    Upload Types

    {
      uploadTypes: [
        "phone",
        ["file"],
        ["scanner", {rotation: 180, color: true}]
      ]
    }
    

    onSuccess callback

    The onSuccess callback is triggered when the user successfully ends the Verifai flow. At this point, the Verifai flow is closed and the callback is called with a sessionId.

    You need this session ID to do two things:

    1. Get the Verifai Result.
    2. Clear the session data from the Verifai backend.

    You can achieve these by calling the Verifai backend from your backend with the following endpoints:

    Action Endpoint Method API Link
    Get Result v1/session/<session_id>/verifai-result GET link
    Delete Session Data v1/session/<session_id> DELETE link

    Follow this link for the latest documentation on the Verifai result:

    Verifai Result Documentation

    onCanceled Callback

    The onCanceled callback is called when the user has canceled the Verifai flow. At this point, the Verifai flow is closed and the callback is called with a sessionId. You need to remove this session from the Verifai backend equivalent to the onSuccess callback. However, there is no Verifai result to handle in this case.

    You can achieve this removal with the same call in the onSuccess callback to the Verifai backend:

    Action Endpoint Method API Link
    Delete Session Data v1/session/<session_id> DELETE link

    Theme

    Theming

    const theme = {
    
      corners: {
        modalRadius: "15",
        buttonRadius: "25"
      }
    
      colors: {
        modalBackground: "#0084c8",
        ...
        imageBackground: "#f3f3f3"
      }
    }
    

    Radius is given in px

    Key Description Default
    modalRadius Modal outer corners 15 px
    buttonRadius All buttons 25 px

    For theming the following colors are supported. Add them to a colors object in your theme object.

    Key Description Default Color
    modalBackground Background color of the modal #ffffff
    buttonBack Back button #757575
    buttonBackHover Back button if clickable and hovered #636363
    buttonMain Main button in the footer #0084c8
    buttonMainHover Main button if clickable and hovered #0070aa
    buttonMainText Main button text #ffffff
    bodyText Text in the body #757575
    bodyErrorText Error message in the #e90000
    bodyButton Buttons in the body #0084c8
    bodyButtonHover Buttons in the body if clickable and hovered #0070aa
    textHeader Title text in the header #212529
    textDescription Description text in the body #757575
    imageForeground Primary image color (Foreground) #212529
    imageBackground Secondary image color (Background #f3f3f3

    Implement the Verifai Handover Flow

    Use the HTML from the main flow example

    const config  = {
      assetsUrl: 'dist/assets',
    }
    // Get the element Verifai should be mounted on
    const verifaiElement = document.getElementById('verifai-mount')
    
    // Create a Handover object
    const handover = new Verifai.Handover(config, verifaiElement)
    
    // Start the Handover
    handover.start()
    
    

    Or if you are using React:

    
    import {HandoverReact} from "verifai-websdk"
    
    <HandoverReact assetsUrl="dist/assets" />
    
    

    As mentioned here you need a separate web page for the handover flow. If you already implemented the Verifai main flow the handover is more of the same. You can use the html from the main flow example. The only difference is that the handover flow does not need an OTP because authorization is handled through the URL.

    To the right is shown how you can implement the handover flow on a separate web page.

    With the handover in place, you have reached the end of the setup. If everything went well you should have a functioning Web SDK. If you have any questions you can always contact our support.

    You can also take an look at the following links: