NAV Navbar
  • Verifai Web SDK Setup (v2.5.x)
  • Registration on the Verifai Dashboard
  • Setup the Verifai Frontend
  • Verifai Web SDK Setup (v2.5.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

    An 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

    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.

    Generic JS project

    HTML

    <div id="verifai-mount"></div>
    

    ES Module

    import WebSDK from "@verifai/websdk"
    
    const config  = {
    
      token: "<OTP_TOKEN>",
    
      onSuccess: (sessionID) => {
        // Here you can get the Verifai Result
        // And clear the temperal storage
      },
      onCanceled: (sessionID) => {
        // 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 WebSDK(config, verifaiElement)
    
    // Start the SDK
    webSDK.start()
    
    

    Install the verifai websdk:

    With npm npm install @verifai/websdk --save

    Or with yarn yarn add @verifai/websdk

    Public methods:

    Constructor

    WebSDK(config: Object, elem: DOMElement)

    Creates an instance of the webSDK

    setConfig

    setConfig(config: Object)

    Shallow merges the given config with the already set config on the SDK instance.

    start

    start()

    Starts the SDK flow (opens modal)

    React project

    React:

    import React, {useState} from "react"
    import WebSDK from "@verifai/websdk-react"
    
    
    export default function MyComponent() {
    
      const [show, setShow] = useState(true)
    
      return <WebSDK
        // For the token look at: https://docs.verifai.com/web-sdk
        token="<OTP_TOKEN>"
    
        // you can manipulate the show prop to show and hide the modal.
        show={show}
    
        onSuccess={sessionID => {
          // set show prop to false, to close the modal
          setShow(false)
    
          // Here you can get the Verifai Result
          // And clear the temporal storage
        }}
        onCanceled={sessionID => {
          // set show prop to false, to close the modal
          setShow(false)
    
          // Here your customer canceled the Verifai flow
          // And clear the temporal storage
    
        }}
      />
    
    }
    

    Install the verifai websdk:

    With npm npm install @verifai/websdk-react --save

    Or with yarn yarn add @verifai/websdk-react

    Config / props

    Key Type Required Description Default
    token str [x] The OTP token -
    assetsUrl str [ ] Url to the assets CDN
    onSuccess fn [ ] Callback for when the flow finishes link
    onCanceled fn [ ] Callback for when the flow is canceled link
    show bool [ ] Bool that shows and closes the flow false
    closable bool [ ] Flow can always be closed false
    showGreeting bool [ ] Will show a greeting at beginning of flow true
    showSMS - [ ] DEPRECATED, can be used through uploadTypes -
    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
    nonce str [ ] Nonce for inline styles CSP undefined

    Assets

    The assets are side-loaded from our CDN, if you want to side-load them from your own server, you can download them from our dashboard and set the assetsUrl accordingly.

    uploadTypes

    Upload Types

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

    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 Default
    "phone" Enables the handover flow [x]
    "file" Enables the file upload flow [x]
    "scanner" Enables the scanner flow, Only in Electron on Windows [ ]

    The upload types can carry extra configuration. An upload type can be formated as one of the following:

    Unset config items will use defaults. An example is given to the right.

    Phone config:

    ["phone", {showSms: false}]

    Enables the handover flow for uploading photos with a user's phone, default with a QR code, optionally with an sms.

    Key Type Default Description
    showSms bool false Enables handover through sms

    File config:

    ["file"]

    There is no extra file config.

    Scanner config:

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

    The scanner option is only supported for Windows with Electron. Will be ignored in any other case. (See here for more info.)

    Key Type Default Description
    width int 3000 Width of the scan
    height int 2900 Height of the scan
    resolution int 600 Scan resolution
    format str jpeg Image format: jpeg, bmp, png
    rotation int 0 Image rotation: 0, 90, 180, 270
    color bool true Use color

    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. Important is to set the show value to false to close the flow correctly.

    With the returned sessionId you need 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?image_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

    HTML

    <div id="verifai-mount"></div>
    

    ES Module

    import {Handover} from "@verifai/websdk"
    
    const config  = {...}
    
    // Get the element Verifai should be mounted on
    const verifaiElement = document.getElementById('verifai-mount')
    
    // Create a Handover object
    const handover = new Handover(config, verifaiElement)
    
    // Start the Handover
    handover.start()
    

    React:

    import {Handover} from "@verifai/websdk-react"
    
    export default function MyComponent() {
        return <Handover/>
    }
    

    The handover flow is only available when you set phone as the uploadType in the SDK.

    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.

    The only difference is that the handover flow does not need an OTP because authorization is handled through the URL. Other than that the config/props are the same for the Handover as for the WebSDK.

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

    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 a look at the following links: