Technical reference

Web SDK
  • Web SDK
  • Android SDK
  • iOS SDK
  • API Reference
6.15.0
  • SDK 6
  • - 6.15.0
  • - 6.14.0
  • - 6.13.0
  • - 6.12.0
  • - 6.11.1
  • - 6.3.0
  • - 6.2.1
  • - 6.2.0
  • - 6.1.0
  • - 6.0.1
  • - 6.0.0
  • SDK 5
  • - 5.13.0
  • - 5.11.3

Onfido SDK UI Layer

npm version

Overview

The Onfido Web SDK provides a set of components for JavaScript applications to capture identity documents and selfie photos and videos for the purpose of identity verification.

The SDK offers a number of benefits to help you create the best identity verification experience for your customers:

  • Carefully designed UI to guide your customers through the entire photo and video capture process
  • Modular design to help you seamlessly integrate the photo and video capture process into your application flow
  • Advanced image quality detection technology to ensure the quality of the captured images meets the requirement of the Onfido identity verification process, guaranteeing the best success rate
  • Direct image upload to the Onfido service, to simplify integration

Note: the SDK is only responsible for capturing photos and videos. You still need to access the Onfido API to manage applicants and perform checks.

Various views from the SDK

Getting started

The following content assumes you're using our API v3 versions for backend calls. If you are currently using API v2 please refer to this migration guide for more information.

1. Obtain an API token

In order to start integrating, you'll need an API token.

You can use our sandbox environment to test your integration. To use the sandbox, you'll need to generate a sandbox API token in your Onfido Dashboard.

1.1 Regions

Onfido offers region-specific environments. Refer to the Regions section in the API documentation for token format and API base URL information.

2. Create an applicant

To create an applicant from your backend server, make request to the 'create applicant' endpoint, using a valid API token.

Note: Different report types have different minimum requirements for applicant data. For a Document or Facial Similarity report, the minimum applicant details required are first_name and last_name.

shell
Copy
$ curl https://api.onfido.com/v3/applicants \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -d 'first_name=John' \
  -d 'last_name=Smith'

The JSON response will contain an id field containing an UUID that identifies the applicant. Once you pass the applicant ID to the SDK, documents and live photos and videos uploaded by that instance of the SDK will be associated with that applicant.

3. Generate an SDK token

The SDK is authenticated using SDK tokens. Each authenticated instance of the SDK will correspond to a single Onfido applicant. You’ll need to generate and include a new token each time you initialize the Web SDK.

Note: You must never use API tokens in the frontend of your application or malicious users could discover them in your source code. You should only use them on your server.

To generate an SDK token, make a request to the 'generate SDK token' endpoint, including the applicant ID and a valid referrer.

shell
Copy
$ curl https://api.onfido.com/v3/sdk_token \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -F 'applicant_id=<APPLICANT_ID>' \
  -F 'referrer=<REFERRER_PATTERN>'
ParameterNotes
applicant_idrequired
Specifies the applicant for the SDK instance
referrerrequired
The referrer URL pattern

Note: SDK tokens expire after 90 minutes.

3.1 The referrer argument

The referrer argument specifies the URL of the web page where the Web SDK will be used. The referrer sent by the browser must match the referrer URL pattern in the SDK token for the SDK to successfully authenticate.

The referrer pattern guarantees that other malicious websites cannot reuse the SDK token in case it is lost. You can read more about referrer policy in Mozilla's documentation.

Note: You must use a site referrer policy that lets the

`Referer` header be sent. If your policy does not allow this (e.g. `Referrer-Policy: no-referrer`), then you'll receive a `401 bad_referrer` error when trying to use the Web SDK.

Permitted referrer patterns are as follows:

SectionFormatExample
Referrerscheme://host/pathhttps://*.<DOMAIN>/<PATH>/*
Scheme* or http or httpshttps
Host* or *. then any char except / and **.<DOMAIN>
PathAny char or none<PATH>/*

An example of a valid referrer is https://*.example.com/example_page/*.

4. Import the library

You can either:

  • import directly into your HTML page
  • use npm

4.1 HTML Script Tag Include

You can include the library as a regular script tag on your page:

html
Copy
<script src="dist/onfido.min.js"></script>

Note: The above import does not include the Auth module. To include it, use:

html
Copy
<script src="dist/onfidoAuth.min.js"></script>

If you are importing the Auth module, you do not need to import the standard SDK module (dist/onfido.min.js) also.

The Authentication module is currently a BETA feature.

And the CSS styles:

html
Copy
<link rel="stylesheet" href="dist/style.css" />

You can see a simple example using script tags.

4.2 NPM style import

You can import the library as a module into your own JS build system (tested with Webpack):

shell
Copy
$ npm install --save onfido-sdk-ui
JavaScript
Copy
// ES6 module import
import { init } from 'onfido-sdk-ui'

// commonjs style require
var Onfido = require('onfido-sdk-ui')

Note: The above import does not include the Auth module. To include it, use:

JavaScript
Copy
// ES6 module import
import { init } from 'onfido-sdk-ui/dist/onfidoAuth.min.js'

// commonjs style require
var Onfido = require('onfido-sdk-ui/dist/onfidoAuth.min.js')

In addition to the alternative way of importing Auth, you need to have an auth-sdk/ folder in your public assets folder, and copy the contents of node_modules/onfido-sdk-ui/dist/auth-sdk into it.

If you are using Webpack on your application, you can automate this by adding:

JavaScript
Copy
new CopyPlugin({
  patterns: [
    {
      from: `../../node_modules/onfido-sdk-ui/dist/auth-sdk`,
      to: `${__dirname}/bin/src/auth-sdk`,
    },
  ],
})

This will fetch the core authentication technology from the SDK into your application. Using web workers for authentication enables the best performance achievable, without compromising on usability.

The CSS style will be included inline with the JS code when the library is imported.

Note: The library is Browser only, it does not support the Node Context.

You can see an example app using npm style import.

5. Add basic HTML markup

Add an empty HTML element at the bottom of your page for the modal interface to mount itself on.

html
Copy
<div id="onfido-mount"></div>

6. Initialize the SDK

You can now initialize the SDK, using the SDK token.

JavaScript
Copy
Onfido.init({
  token: '<YOUR_SDK_TOKEN>',
  containerId: 'onfido-mount',
  containerEl: <div id="root" />, //ALTERNATIVE to `containerId`
  onComplete: function (data) {
    console.log('everything is complete')
  },
  steps: ['welcome', 'document', 'face', 'complete'],
})
ParameterFormatNotes
tokenstringrequired
Your Web SDK token
containerIdstringoptional
A string containing the ID of the container element that the UI will mount to. This must be an empty element. The default is onfido-mount.
Alternatively, if your integration requires it, you can pass in the container element instead. Note that if containerEl is provided, then containerId will be ignored
onCompletefunctionoptional A callback function that executes after the applicant's document and face have both been captured and uploaded successfully
stepsstring or objectList of different steps corresponding to parts of the process the user will be presented with

Handling callbacks

onComplete {Function} optional

Callback that fires when both the document and face have been successfully captured and uploaded. You can then trigger your backend to create a check, using the associated applicant ID.

Example onComplete callback:

JavaScript
Copy
Onfido.init({
  token: '<YOUR_SDK_TOKEN>',
  containerId: 'onfido-mount',
  onComplete: function (data) {
    console.log('everything is complete')
  },
})

data is an object that contains properties of the document and face images captured during the SDK flow.

For two-sided documents like driving_licence and national_identity_card, the object will also contain a document_back property representing the reverse side.

For the face step an object is returned with the variant used for the face capture,'standard' | 'video'. This informs whether to specify a facial_similarity_photo or facial_similarity_video report during check creation.

JavaScript
Copy
    {
       "document_front": {
         "id": "<DOCUMENT_ID_FRONT>",
         "type": "passport",
         "side": "front"
       },
       "face": {
         "id": "<FACE_ID>",
         "variant": "standard"
       },
       "document_back": {
         "id": "<DOCUMENT_ID_BACK>",
         "type": "driving_licence",
         "side": "back"
       }
    }

For the Auth step a data object is returned with parameters success, token, type, and uuid. The success variable informs whether or not the user was authenticated successfuly, whereas token is a JWT that can be used to validate the user authentication.

Example of an auth onComplete data callback:

JavaScript
Copy
    {
      "success": true,
      "token": "eyJhbGciOiJSUz...",
      "type": "complete",
      "uuid": "b3b9142d-3071-401d-821b-17ab134d4798"
    }

onError {Function} optional

Callback that fires when an error occurs. The callback returns the following error types:

  • exception This will be returned for the following errors:

    • timeout and server errors
    • authorization
    • invalid token
    • missing data in onComplete callback
    • [Auth] exception handling API response

    This data can be used for debugging purposes.

JavaScript
Copy
{
  type: "exception",
  message: "The request could not be understood by the server, please check your request is correctly formatted"
}
  • expired_token This error will be returned when a token has expired. This error type can be used to provide a new token at runtime.
JavaScript
Copy
{
  type: "expired_token",
  message: "The token has expired, please request a new one"
}

onUserExit {Function} optional

Callback that fires when the user abandons the flow without completing it.

The callback returns a string with the reason for leaving. For example, 'USER_CONSENT_DENIED' is returned when a user exits the flow because they declined the consent prompt.

JavaScript
Copy
Onfido.init({
  token: '<YOUR_SDK_TOKEN>',
  containerId: 'onfido-mount',
  onUserExit: function (userExitCode) {
    console.log(userExitCode)
  },
})

onModalRequestClose {Function} optional

Callback that fires when the user attempts to close the modal.

You can then decide to close the modal or keep it open by changing the property isModalOpen.

Removing the SDK

If you have embedded the SDK inside a single page app, you can call the tearDown function to remove the SDK completely from the current webpage. It will reset the state and you can safely re-initialize the SDK inside the same webpage later on.

JavaScript
Copy
onfidoOut = Onfido.init({...})
...
onfidoOut.tearDown()

Initialization options

  • token {String} required

    A JWT is required in order to authorize with our WebSocket endpoint. If one isn’t present, an exception will be thrown.

  • useModal {Boolean} optional

    Turns the SDK into a modal, which fades the background and puts the SDK into a contained box.

    JavaScript
    Copy
    <script>
        var onfido = {}
    
        function triggerOnfido() {
          onfido = Onfido.init({
            useModal: true,
            isModalOpen: true,
            onModalRequestClose: function() {
              // Update options with the state of the modal
              onfido.setOptions({isModalOpen: false})
            },
            token: '<YOUR_SDK_TOKEN>',
            onComplete: function(data) {
              // callback for when everything is complete
              console.log("everything is complete")
            }
          });
        };
    </script>
    
    <body>
      <!-- Use a button to trigger the Onfido SDK  -->
      <button onClick="triggerOnfido()">Verify identity</button>
      <div id='onfido-mount'></div>
    </body>
    
  • isModalOpen {Boolean} optional

    Defines whether the modal is open or closed, if useModal is set to true. The default value is false.

    To change the state of the modal after calling init() you need to use setOptions().

  • shouldCloseOnOverlayClick {Boolean} optional

    If useModal is set to true, by default the user can close the SDK by clicking on the close button or on the background overlay. You can disable the user's ability to close the SDK by clicking the background overlay through setting shouldCloseOnOverlayClick to false.

  • containerId {String} optional

    A string of the ID of the container element that the UI will mount to. This needs to be an empty element. The default ID is onfido-mount. If your integration needs to pass the container element itself, use containerEl as described next.

  • containerEl {Element} optional

    The container element that the UI will mount to. This needs to be an empty element. This can be used as an alternative to passing in the container ID string previously described for containerId. Note that if containerEl is provided, then containerId will be ignored.

  • smsNumberCountryCode {String} optional

    You can change the default country for the SMS number input by passing the smsNumberCountryCode option when the SDK is initialized. The value should be a string containing a 2-character ISO Country code. If empty, the SMS number country code will default to GB.

    JavaScript
    Copy
    smsNumberCountryCode: 'US'
    
  • userDetails {Object} optional

    The following user details can be specified ahead of time, so that the user doesn't need to provide the information themselves:

    • smsNumber (optional) : The user's mobile number, which can be used for sending SMS messages to the user, for example, when a user requests to use their mobile devices to take photos. The value should be a string containing the mobile number with a country code.
    JavaScript
    Copy
    userDetails: {
      smsNumber: '+447500123456'
    }
    
  • steps {List} optional

    The list of different steps to be shown in the SDK flow and their custom options. Each step can either be specified as a string (when no customization is required) or an object (when customization is required).

    JavaScript
    Copy
    steps: [
      {
        type: 'welcome',
        options: {
          title: 'Open your new bank account',
        },
      },
      'document',
      'face',
    ]
    

    See flow customization for details of the custom options for each step.

Customizing the SDK

The Web SDK has multiple customizable features that provide flexibility, while also being easy to integrate. You can also read our SDK customization guide.

UI customization

Language Localization

  • language {String || Object} optional

    You can customize the language displayed on the SDK by passing a string or object. If language is not present the default copy will be in English.

    Supported languages

    The SDK supports and maintains 6 languages. These can be implemented directly inside the SDK by passing the language option as a string containing the supported language tag.

    LanguageLocale Tag
    English (default)en_US
    Germande_DE
    Spanishes_ES
    Frenchfr_FR
    Italianit_IT
    Portuguesept_PT

    Example:

    JavaScript
    Copy
    language: 'es_ES' | 'es'
    
    Custom lanugages

    The SDK can also be displayed in a custom language for locales that Onfido does not currently support. To implement this, pass an object containing the following keys:

    KeyDescriptionNotes
    localerequired
    A locale tag.
    This is required when providing phrases for an unsupported language. You can also use this to partially customize the strings of a supported language (e.g. Spanish), by passing a supported language locale tag (e.g. es_ES). For missing keys, the values will be displayed in the language specified within the locale tag if supported, otherwise they will be displayed in English. The locale tag is also used to override the language of the SMS body for the cross device feature. This feature is owned by Onfido and is currently only supports English, Spanish, French and German.
    phrasesrequired
    An object containing the keys you want to override and the new values.
    The keys can be found in src/locales/en_US/en_US.json. They can be passed as a nested object or as a string using the dot notation for nested values. See the examples below.
    mobilePhrasesoptional
    An object containing the keys you want to override and the new values.
    The values specified within this object are only visible on mobile devices. Please refer to the mobilePhrases property in src/locales/en_US/en_US.json. Note: support for standalone mobilePhrases key will be deprecated soon. Consider nesting it inside phrases if applicable.
    JavaScript
    Copy
    language: {
      locale: 'en_US',
      phrases: { welcome: { title: 'My custom title' } },
      mobilePhrases: {
        'capture.driving_licence.instructions': 'This string will only appear on mobile'
      }
    }
    

Flow customization

welcome

This step is the introduction screen of the SDK. It displays a summary of the capture steps the user will pass through. These steps can be specified to match the flow required. This is an optional screen.

The custom options are:

  • title (string)
  • descriptions ( [string])
  • nextButton (string)

userConsent

This step is a screen to collect US end users' privacy consent for Onfido. It contains the consent language required when you offer your service to US users as well as links to Onfido's policies and terms of use. This is an optional step in the SDK flow.

The user must click "Accept" to continue with the flow past this step. The content is available in English only, and is not translatable.

Note: this step does not automatically inform Onfido that the user has given their consent. At the end of the SDK flow, you still need to set the API parameter privacy_notices_read_consent_given outside of the SDK flow when creating a check.

If you choose to disable this step, you must incorporate the required consent language and links to Onfido's policies and terms of use into your own application's flow before your user starts interacting with the Onfido SDK.

For more information about this step, and how to collect user consent, please read Onfido Privacy Notices and Consent.

Note: The userConsent step must be used in conjunction with the onUserExit callback. See the Handling Callbacks for more information.

document

This is the identity document capture step. Users will be asked to select the document type and its issuing country before providing images of their selected document. They will also have a chance to check the quality of the image(s) before confirming.

Document selection and country selection are both optional screens. These screens will only show to the end user if specific options are not configured to the SDK.

The custom options are:

  • documentTypes (object)

    The list of document types visible to the user can be filtered by using the documentTypes option. The default value for each document type is true. If documentTypes only includes one document type, users will not see either the document selection screen or the country selection screen and instead will be taken directly to the capture screen.

  • country (string)

    Document country can be specified per document type. The country configuration for a document type allows you to specify the issuing country of the document as a string containing a 3-letter ISO 3166-1 alpha-3 country code.

    If a document country is specified for a document type, or is passed as null, the country selection screen is not displayed to the end user.

    ⚠️ Note: You can set the country for all document types except Passport. This is because passports have the same format worldwide so the SDK does not require this additional information.

    For example, if you would like to set the country as Spain (ESP) and skip the country selection screen for the driving licence document type only:

    JSON
    Copy
    {
      "steps":  [
        "welcome",
        {
          "type": "document",
          "options": {
            "documentTypes": {
              "driving_licence": {
                "country": "ESP"
              },
              "national_identity_card": true,
              "residence_permit": true
            }
          }
        },
        "complete"
      ]
    }
    

    For example, if you would like to skip the country selection screen for driving licence but do not want to set a country:

    JSON
    Copy
    {
      "steps": [
        "welcome",
        {
          "type": "document",
          "options": {
            "documentTypes": {
              "driving_licence": {
                "country": null
              },
              "passport": true,
              "national_identity_card": true
            }
          }
        },
        "complete"
      ]
    }
    
  • showCountrySelection (boolean - default: false)

    ⚠️ Note: Support for the showCountrySelection option will be deprecated soon in favour of the per document country configuration detailed above which offers integrators better control.

    The showCountrySelection option controls what happens when only a single document is preselected in documentTypes. It has no effect when the SDK has been set up with multiple documents preselected.

    The country selection screen is never displayed for a passport document.

    By default, if only one document type is preselected, and the document type is not passport, the country selection screen will not be displayed. If you would like to have this screen displayed still, set showCountrySelection to true.

    JavaScript
    Copy
    options: {
      documentTypes: {
        passport: boolean,
        driving_licence: boolean,
        national_identity_card: boolean,
        residence_permit: boolean
      },
      showCountrySelection: boolean (note that this will only apply for certain scenarios, see example configurations below)
    }
    

    Example of Document step without Country Selection screen for a preselected non-passport document (default behaviour):

    JSON
    Copy
    {
      "steps": [
        "welcome",
        {
          "type": "document",
          "options": {
            "documentTypes": {
              // Note that only 1 document type is selected here
              "passport": false,
              "driving_licence": false,
              "national_identity_card": true
            },
            "showCountrySelection": false
          }
        },
        "complete"
      ]
    }
    

    Examples of Document step configuration with more than one preselected documents where Country Selection will still be displayed:

    Example 1 All document type options enabled, "showCountrySelection": false has no effect

    JSON
    Copy
    {
      "steps": [
        "welcome",
        {
          "type": "document",
          "options": {
            "documentTypes": {
              "passport": true,
              "driving_licence": true,
              "national_identity_card": true
            },
            "showCountrySelection": false (NOTE: has no effect)
          }
        },
        "complete"
      ]
    }
    

    Example 2 2 document type options enabled, "showCountrySelection": false has no effect

    JSON
    Copy
    {
      "steps": [
        "welcome",
        {
          "type": "document",
          "options": {
            "documentTypes": {
              "passport": true,
              "national_identity_card": true,
              "driving_licence": false
            },
            "showCountrySelection": false (NOTE: has no effect)
          }
        },
        "complete"
      ]
    }
    
  • forceCrossDevice (boolean - default: false)

    The Web SDK offers a cross device flow where desktop users will be given the option to continue using their desktop browser or swap to using their mobile device browser to complete the capture process. If a user selects to use their mobile device they will be redirected via a secure link that they can receive by SMS or QR code to complete the flow. At the end of the capture process users will be redirected back to their desktop to complete the SDK flow.

    When forceCrossDevice is set to true, the cross device flow is mandatory for all users. Desktop users will be required to complete the capture process on a mobile device browser. Configuring this option minimises the risk of fraudulent upload by ensuring a higher likelihood of live capture.

    JavaScript
    Copy
    options: {
      forceCrossDevice: true
    }
    
  • useLiveDocumentCapture (boolean - default: false) This BETA feature is only available on mobile devices.

    When set to true, users on mobile browsers with camera support will be able to capture document images using an optimised camera UI, where the SDK directly controls the camera feed to ensure live capture. Configuring this option minimises the risk of fraudulent upload by bypassing the device's default camera application. For unsupported scenarios, see the uploadFallback section below.

    Tested on: Android Chrome 78.0.3904.108, iOS Safari 13

  • uploadFallback (boolean - default: true) Only available when useLiveDocumentCapture is enabled.

    When useLiveDocumentCapture is set to true, the SDK will attempt to open an optimised camera UI for the user to take a live photo of the selected document. When this is not possible (because of an unsupported browser or mobile devices with no camera), by default the user will be presented with an HTML5 File Input upload because of uploadFallback. In this scenario, they will be able to use their mobile device's default camera application to take a photo.

    This method does not guarantee live capture, because certain mobile device browsers and camera applications may also allow uploads from the user's gallery of photos.

    ⚠️ Warning: If the mobile device does not have a camera or lacks camera browser support the user will not be able to complete the flow if uploadFallback is set to false.

    JavaScript
    Copy
    options: {
      useLiveDocumentCapture: true,
      uploadFallback: false
    }
    

poa

This is the Proof of Address capture step. Users will be asked to select the document type and to provide images of their selected document. They will also have a chance to check the quality of the images before confirming. The custom options are:

  • country (default: GBR)
  • documentTypes
JavaScript
Copy
options: {
  country: string,
  documentTypes: {
    bank_building_society_statement: boolean,
    utility_bill: boolean,
    council_tax: boolean, // GBR only
    benefit_letters: boolean, // GBR only
    government_letter: boolean // non-GBR only
  }
}

The Proof of Address document capture is currently a BETA feature, and it cannot be used in conjunction with the document and face steps as part of a single SDK flow.

face

This is the face capture step. Users will be asked to capture their face in the form of a photo or a video. They will also have a chance to check the quality of the photo or video before confirming.

The custom options are:

  • requestedVariant (string)

    A preferred variant can be requested for this step, by passing the option requestedVariant: 'standard' | 'video'. If empty, it will default to standard and a photo will be captured. If the requestedVariant is video, the SDK will try to fulfil this request depending on camera availability and device and browser support on the user's device. If a video cannot be taken, the face step will fallback to the standard photo option.

    If the SDK is initialized with the requestedVariant option for the face step, make sure you use the data returned in the onComplete callback to request the correct report when creating a check.

  • uploadFallback (boolean - default: true)

    By default, the SDK will attempt to open an optimised camera UI for the user to take a live photo or video. When this is not possible (because of an unsupported browser or mobile devices with no camera), by default the user will be presented with an HTML5 File Input upload because of uploadFallback. In this scenario, they will be able to use their mobile device's default camera application to take a photo, but will not be presented with an optimised camera UI.

    This method does not guarantee live capture, because certain mobile device browsers and camera applications may also allow uploads from the user's gallery of photos.

    ⚠️ Warning: If the mobile device does not have a camera or lacks camera browser support the user will not be able to complete the flow if uploadFallback is set to false.

    JavaScript
    Copy
    options: {
      requestedVariant: 'standard' | 'video',
      uploadFallback: false
    }
    
  • useMultipleSelfieCapture (boolean - default: true)

    When enabled, this feature allows the SDK to take additional selfie snapshots to help improve face similarity check accuracy. When disabled, only one selfie photo will be taken.

  • photoCaptureFallback (boolean - default: true)

    When enabled, this feature allows end-users to upload selfies if the requested variant is video and their browser does not support MediaRecorder.

    When disabled, it will forward the user to the cross-device flow in order to attempt to capture a video in another device. If the user is already in a mobile device and it does not support MediaRecorder, the unsupported browser error will be shown.

auth

This is the authentication step. If you have followed the guidelines specific to including authentication, you'll have this step made available. In here, a loading screen is presented to the user to fetch all necessary resources to perform authentication.

After all resources are loaded, the session is initialized, and the authentication check begins. An oval frame of the camera will be present (if camera permissions are provided) and actionable elements will render, asking the user to place their face in the frame, followed up by a different set of instructions for them to follow to successfully authenticate the user.

If the user is not a match, or conditions are not good enough to successfully authenticate, the user will be asked to retry authentication. If authentication is not possible (i.e. user performing authentication is not a match, doesn't provide optimal light/environment conditions, or doesn't follow instructions on screen), the page will rollback to the previous step. Custom option is:

  • retries (number)

This option allows the integrator to set the maximum number of retries until authentication session is cancelled. Default maximum number of attempts is 3.

complete

This is the final completion step. The screen displays a completion message to signal the next steps to the user. This is an optional screen. The custom options are:

  • message (string)
  • submessage (string)

Cross device - mobile client introductory screen

When a user switches to the SDK's Cross Device flow, they will see an introductory screen when the SDK client loads on their mobile browser. ! Default Cross device mobile client introductory screen

  • crossDeviceClientIntroProductName {String} optional

    You can customize the text by adding your company or product name to the subtitle with this option. We recommend that you set this, alongside the corresponding crossDeviceClientIntroProductLogoSrc below, to notify the user that this is part of a flow initiated on a desktop or laptop browser when they open the Cross Device link on their mobile browser. This is also an opportunity to include your branding in the SDK flow.

    JavaScript
    Copy
    Onfido.init({
      token: '<YOUR_SDK_TOKEN>',
      crossDeviceClientIntroProductName: 'for a [COMPANY/PRODUCT NAME] loan',
    })
    

    Cross Device Client Intro screen with client product name and copy

  • crossDeviceClientIntroProductLogoSrc {String} optional

    You can customize the icon by adding your company or product logo to be displayed instead of the default SDK icon image with this option. We recommend that you set this, alongside the corresponding crossDeviceClientIntroProductName above, to notify the user that this is part of a flow initiated on a desktop browser when they open the Cross Device link on their mobile browser. This is also an opportunity to include your branding in the SDK flow. The image used should be no more than 144px in both height and width.

    JavaScript
    Copy
    Onfido.init({
      token: '<YOUR_SDK_TOKEN>',
      crossDeviceClientIntroProductLogoSrc: 'path://to/logo/image/file',
    })
    

    ! Cross Device Client Intro screen with client product logo

Changing options in runtime

It's possible to change the options initialized at runtime:

JavaScript
Copy
onfidoOut = Onfido.init({...})
...
//Change the title of the welcome screen
onfidoOut.setOptions({
  steps:  [
    {
      type:'welcome',
      options:{title:"New title!"}
    },
    'document',
    'face',
    'complete'
  ]
});
...
//replace the jwt token
onfidoOut.setOptions({ token: '<YOUR_NEW_SDK_TOKEN>' });
...
//Open the modal
onfidoOut.setOptions({ isModalOpen:true });

The new options will be shallowly merged with the previous one, so you can only pass the differences to a get a new flow.

Creating checks

The SDK is responsible for the capture of identity documents and selfie photos and videos. It doesn't perform any checks against the Onfido API. You need to access the Onfido API in order to manage applicants and perform checks.

1. Creating a check

For a walkthrough of how to create a document and facial similarity check using the Web SDK read our Web SDK Quick Start guide.

For further details on how to create a check with the Onfido API.

Note: If you are testing with a sandbox token, please be aware that the results are pre-determined. You can learn more about sandbox responses.

Note: If you are currently using API v2 please refer to this migration guide for more information.

2. Setting up webhooks

Reports may not always return actual results straightaway.

You can set up webhooks to be notified upon completion of a check or report, or both.

User Analytics

The SDK allows you to track a user's journey through the verification process via a dispatched event. This gives insight into how your users make use of the SDK screens.

Overriding the hook

In order to track a user's progress through the SDK an EventListener must be added that listens for UserAnalyticsEvent events. This can be done anywhere within your application.

For example:

JavaScript
Copy
addEventListener('userAnalyticsEvent', (event) => /*Your code here*/);

The code inside of the EventListener will now be called when a particular event is triggered. For a full list of events see tracked events.

The parameter being passed in is an Event object. The details related to the user analytics event can be found at the path event.detail and are as follows:

eventNamestring
Indicates the type of event. This will always be returned as "Screen" as each tracked event is a user visiting a screen.
propertiesmap object
Contains the specific details of an event. For example, the name of the screen visited.

Using the data

You can use the data to monitor how many users reach each screen in your flow. You can do this by storing the number of users that reach each screen and comparing that to the number of users who reached the Welcome screen.

Tracked events

Below is the list of potential events currently being tracked by the hook:

Copy
WELCOME - User reached the "Welcome" screen
USER_CONSENT - User reached the "User Consent" screen
DOCUMENT_TYPE_SELECT - User reached the "Choose document" screen where the type of document to upload can be selected
ID_DOCUMENT_COUNTRY_SELECT - User reached the "Select issuing country" screen where the the appropriate issuing country can be searched for and selected if supported
CROSS_DEVICE_INTRO - User reached the cross device "Continue on your phone" intro screen
CROSS_DEVICE_GET_LINK - User reached the cross device "Get your secure link" screen
CROSS_DEVICE_START - User reached the "document capture" screen on mobile after visiting the cross device link
DOCUMENT_CAPTURE_FRONT - User reached the "document capture" screen for the front side (for one-sided or two-sided document)
DOCUMENT_CAPTURE_BACK - User reached the "document capture" screen for the back side (for two-sided document)
DOCUMENT_CAPTURE_CONFIRMATION_FRONT - User reached the "document confirmation" screen for the front side (for one-sided or two-sided document)
DOCUMENT_CAPTURE_CONFIRMATION_BACK - User reached the "document confirmation" screen for the back side (for two-sided document)
FACIAL_INTRO - User reached the "selfie intro" screen
FACIAL_CAPTURE - User reached the "selfie capture" screen
FACIAL_CAPTURE_CONFIRMATION - User reached the "selfie confirmation" screen
VIDEO_FACIAL_INTRO - User reached the "face video intro" screen
VIDEO_FACIAL_CAPTURE_STEP_1 - User reached the 1st challenge during "face video capture", challenge_type can be found in eventProperties
VIDEO_FACIAL_CAPTURE_STEP_2 - User reached the 2nd challenge during "face video capture", challenge_type can be found in eventProperties
UPLOAD - User's file is uploading

Premium Enterprise Features

Please refer to the Premium Enterprise Features documentation for details of the following features offered to our Enterprise customers:

  • Customized API Requests
  • Callbacks Overview
  • Cross device URL

The above features must be enabled for your account before they can be used. For more information, please contact your Onfido Solution Engineer or Customer Success Manager.

Going live

Once you are happy with your integration and are ready to go live, please contact client-support@onfido.com to obtain a live API token. You will have to replace the sandbox token in your code with the live token.

Check the following before you go live:

Accessibility

The Onfido SDK has been optimised to provide the following accessibility support by default:

  • Screen reader support: accessible labels for textual and non-textual elements available to aid screen reader navigation, including dynamic alerts
  • Keyboard navigation: all interactive elements are reachable using a keyboard
  • Sufficient color contrast: default colors have been tested to meet the recommended level of contrast
  • Sufficient touch target size: all interactive elements have been designed to meet the recommended touch target size

Refer to our accessibility statement for more details.

Note: If you make your own UI customizations, you are responsible for ensuring that the UI changes will still adhere to accessibility standards. For example, accessible color contrast ratios and dyslexic friendly fonts.

TypeScript

From version 6.5.0, TypeScript is officially supported, providing typings for:

  • init() method
  • options argument (SdkOptions) and return object (SdkHandle) of init() method
  • Arguments (SdkResponse and SdkError) for onComplete() and onError() callbacks
  • steps option (StepTypes and StepConfig)
  • language option (SupportedLanguages and LocaleConfig)
  • region option (ServerRegions)

More information

Browser compatibility

ChromeFirefoxIEEdgeSafari
Latest ✔Latest *11 ✔Latest ✔Latest ✔

* Firefox on Android, iOS not supported

Troubleshooting

Content Security Policy issues

In order to mitigate potential cross-site scripting issues, most modern browsers use a Content Security Policy (CSP). These policies might prevent the SDK from correctly displaying the images captured during the flow or correctly load styles. If CSP is blocking some of the SDK functionalities, make sure you add the following snippet inside the <head> tag of your application.

html
Copy
<meta
  http-equiv="Content-Security-Policy"
  content="
  default-src 'self' https://assets.onfido.com;
  script-src 'self' https://www.woopra.com https://assets.onfido.com https://sentry.io;
  style-src 'self' https://assets.onfido.com;
  connect-src blob: *.onfido.com wss://*.onfido.com https://www.woopra.com https://sentry.io;
  img-src 'self' data: blob: https://lipis.github.io/flag-icon-css/;
  media-src blob:;
  object-src 'self' blob:;
  frame-src 'self' data: blob:;
"
/>

SDK navigation issues

In rare cases, the SDK back button might not work as expected within the application history. This is due to the interaction of history/createBrowserHistory with the browser history API. If you notice that by clicking on the SDK back button, you get redirected to the page that preceeded the SDK initialization, you might want to consider using the following configuration option when initialising the SDK: useMemoryHistory: true. This option allows the SDK to use the history/createMemoryHistory function, instead of the default history/createBrowserHistory. This option is intended as workaround, while a more permanent fix is implemented.

Example:

JavaScript
Copy
Onfido.init({
  useMemoryHistory: true,
})

Support

Please open an issue through GitHub. Please be as detailed as you can. Remember not to submit your token in the issue. Also check the closed issues to check whether it has been previously raised and answered.

If you have any issues that contain sensitive information please send us an email with the ISSUE: at the start of the subject to web-sdk@onfido.com.

Previous versions of the SDK will be supported for a month after a new major version release. Note that when the support period has expired for an SDK version, no bug fixes will be provided, but the SDK will keep functioning (until further notice).

How is the Onfido SDK licensed?

Please see LICENSE for licensing details.

Changelog

All notable changes to this project will be documented in this file.

This change log file is based on best practices from Keep a Changelog. This project adheres to Semantic Versioning. Breaking changes result in a different MAJOR version. UI changes that might break customizations on top of the SDK will be treated as breaking changes too. This project adheres to the Node default version scheme.

Added

  • Internal: Added configuration to support visual regression tests to run against multiple languages.
  • Internal: Send analytics events to v3/analytics. Analytics events are also sent to Woopra, until we are ready to discontinue the current Woopra integration.

Changed

  • UI: Accessibility - Return focus to Document capture image preview's "Enlarge image" toggle button when expanded image preview's "Close" toggle button is clicked.

Fixed

  • Public: Video element errors and validation errors returned by live_videos endpoint are handled by the Web SDK
  • Public: Fix grey oblong background appearing under the red cross icon on the Unsupported Browser error screen
  • Public: Remove grey circle background from SVG icon displayed on Generic Error screen so that custom circle background is visible
  • Internal: Upgraded some dev dependencies to fix some npm security vulnerabilities, also upgraded socket.io-client dependency to v4.2.0 to resolve npm security vulnerability in ws@7.4.4

6.14.0 - 2021-09-13

Added

  • UI: Added new Intro screen when user begins the Cross Device flow on their mobile device.
  • Public: Added SDK configuration options for integrators to customize product name, copy and/or logo image for the new Cross Device Mobile Client Intro screen.

Fixed

  • Public: Fixed custom SDK body text color set in customUI.colorContentBody option not getting applied to Country Selector text input if an element level text colour has been set in host app/site's stylesheet.
  • UI: Fixed Country Selector dropdown menu closing on clicking on scrollbar.
  • Internal: Auth - Fetch correct API URL from the Redux store

6.13.0 - 2021-08-23

Added

  • Internal: New data field in metadata to track number of takes for each submitted image.

Fixed

  • UI: Fixed the text placement to be below the primary button in the Document Upload screen.
  • Public: Fixed cross-device connection issue when cross-device link is accessed multiple times.
  • UI: Fix QR Code link section rendering issue in Safari 14 on desktops
  • UI: The Cross Device link options visible to end users can be configured by passing an array of the link method IDs (qr_code, sms, copy_link) in the order of preference to _crossDeviceLinkMethods in SDK initialization configuration.

6.12.0 - 2021-08-10

Fixed

  • UI: Fix camera view not lining up with Document Live Capture overlay and fix image distortion on some devices' live camera view by maintaining camera view aspect ratio.
  • Public: Fix file selector "capture" prop for WebSDK inside iOS WebView
  • Public: Fix CROSS_DEVICE_START user analytic event for integrators never being dispatched when user switches to the Cross Device flow
  • UI: Update copy in Face Liveness Video intro screen from 25s to 20s to reflect the correct time limit
  • Remove old locale key type definitions that are no longer used/exist in code base.

Changed

  • UI: Accessibility - Make "Tips" heading in Cross Device SMS Sent and Mobile Connected screens a level 3 heading.
  • UI: Accessibility - Change Cross Device Send Link alternate option text to be an ARIA heading level 2

6.11.1 - 2021-07-20

Added

  • UI: Accessibility - Add ARIA role img and an ARIA label for the generated cross device secure link QR code image
  • Internal: Resolved inaccurate reporting on test automation failures.
  • Internal: Added note about lockfileVersion and npm version requirement for SDK contributors in CONTRIBUTING.md documentation.
  • Public: Improvements in video capture steps.

Changed

  • UI: Accessibility - Add ARIA role button to "Resend link" and "Cancel" links on Cross Device flow SMS Sent, Mobile Connected screens.
  • Internal: Remove image_quality breakdowns from sdk_warnings response because the field will be soon deprecated.
  • Internal: Moved geckodriver from dependencies to devDependencies.
  • Internal: Added ability to run tests without the use of the mock server for the UI tests.

6.10.2 - 2021-07-08

Fixed

  • UI: Fixed Camera Permissions Primer screen rendering issue on Safari 14.1 (desktop) without changing existing SDK layout structure.

6.10.1 - 2021-07-05

Changed

  • Reduce resolution to VGA if browser does not support recording videos in WebM format (e.g. Safari 14.x that only supports MP4 format) to avoid large video files being created.
  • UI: Fixed Camera Permissions Primer screen rendering issue on Safari 14.1 (desktop) by using ScreenLayout wrapper component.

6.10.0 - 2021-06-22

Added

  • Internal: Added note about lockfileVersion and npm version requirement for SDK contributors in CONTRIBUTING.md documentation.
  • Public: Added support for Italian it_IT and Portuguese pt_PT.
  • Internal: Added support for visual regression testing using Percy.
  • Internal: Resolved inaccurate reporting on test automation failures.
  • Internal: Added ability to execute/ignore tests via the use of tags/regex.

Changed

  • UI: Update Face Liveness Video Challenge screen UI
  • UI: Updated default Welcome screen UI
  • Public: Move documentation for SDK UI Customizations and Premium Enterprise Features into separate Markdown files to reduce README size
  • Public: Updated SDK copy for English (en_US), Spanish (es_ES), French (fr_FR) and German (de_DE). For details on what keys/copy have changed please refer to the MIGRATION.md documentation.
  • Internal: Upgrade sass (Dart Sass) from 1.26.9 to 1.33.0
  • Internal: Upgrade stylelint from 13.6.1 to 13.13.1 as well as stylelint-config-sass-guidelines from 7.0.0 to 8.0.0 and stylelint-scss from 3.18.0 to 3.19.0

Fixed

  • Internal: Upgrade Preact from version 10.5.4 to 10.5.13 in order to resolve an unhandled exception on reinitialising the SDK after closing the SDK modal for some integrations when using Modal mode.
  • Public: Fix Country Selection screen not displaying when SDK is initialised with boolean documentTypes configuration.
  • Public: Fixed issue where onComplete callback was fired without the necessary data for the face step. Added exception to onError callback to inform that onComplete could not be fired due to missing data.

6.9.0 - 2021-05-24

Added

  • Public: Added Authentication module as a beta feature
  • Internal: Added support for testing across multiple browsers.
  • Internal: Added polyfills for Object.entries and Object.fromEntries for IE11.

Changed

  • Update to module on tsconfig.json from es6 to esnext, to allow conditional imports of specific modules (especially useful for Auth/IDV bundle separation).

Fixed

  • UI: Fix SVG icon on Cross Device Uploads Successful, Selfie Intro screens not displaying on some iOS devices, e.g. iPhone 12

6.8.0 - 2021-05-13

Added

  • Internal: Add type defition for borderRadiusSurfaceModal customisation option.
  • Public: Add information about Lokalise CLI v2 in CONTRIBUTING doc
  • Internal: Refactor useSdkOptions() hook to return a tuple: [options, { findStep }]
  • Internal: Added default filename for all document uploads if filename is not present.
  • Public: Added user consent content reload screen
  • Public: When photoCaptureFallback option is disabled in the face step, the requested variant is video and browser does not support MediaRecorder, attempt to redirect to the cross-device flow or display the unsupported browser error.
  • Internal: Refactor for better reusability of video capture components.

Changed

  • Internal: Migrate CI build from TravisCI to Github Actions
  • Internal: Upgraded socket.io-client to v4.0.1 to resolve npm security vulnerability 1665 (high severity)

Fixed

  • Public: Get latest copy from Lokalise with various grammar, punctuation fixes. Also reverts French, Spanish translations for some Proof of Address copy in these languages' locale files (Proof of Address is only supported for English)

6.7.2 - 2021-04-26

Fixed

  • Public: Fix Cross Device "Send Link" options link affecting host app/site's page routing on click
  • UI: Fixed flickering country list on SMS country dropdown. The fix involves updating deviceHasCameraSupport in the Redux store only when the value changes.
  • Internal: Fix Liveness Video upload payload to /live_videos API endpoint missing challenge_switch_at property and value
  • Internal: Fix incorrect format of language_code value in Liveness Video upload payload to /live_videos API endpoint

6.7.1 - 2021-03-26

Fixed

  • UI: Fix host app/site's own link styling getting overridden by SDK's default theme styling

6.7.0 - 2021-03-25

Added

  • Internal: Introduce SdkOptionsProvider component and useSdkOptions() hook for SDK options' single source of truth.
  • Public: Added cross-device support for useCustomizedApiRequests callbacks via customer hosting of SDK. Note - This is a premium enterprise feature.
  • Public: Added support for UI customizations in SDK configuration using customUI option. See README for details of supported customization options.
  • Internal: Add Woopra tracking for UI customization option usage.

Changed

  • UI: Replaced internal button component with button from @onfido/castor-react.
  • UI: Replaced some Sass variables with CSS variables to allow customization of colors and fonts.
  • Public: Added new enterprise feature logoCobrand. When purchased and enabled allows integrator to provide their own logo image to be displayed alongside the Onfido logo.
  • Internal: Use Node 14 LTS for Travis to be consistent with .nvmrc and Dockerfile.
  • Internal: Enable strict mode in tsconfig.json

Fixed

  • UI: Fix Camera Permission icon not displaying on iOS devices on Selfie/Liveness capture flow

6.6.0 - 2021-03-09

Added

  • Internal: Added ScreenLayout component. This is currently used in the Welcome and Complete screens.
  • Public: Added user consent screen
  • Public: Added callbacks that are triggered on user media submission if the feature is enabled. Note - This is a premium enterprise feature.
  • Internal: App component, Redux system, utils, HoCs & routers are now typed in TypeScript.
  • Internal: Use ScreenLayout component in Confirm screen.

Changed

  • Internal: Replace ts-loader with @babel/preset-typescript for better TypeScript transpilation.

Fixed

  • Public: Fix zoomed document capture view for Document Live Capture on some Huawei devices, e.g. Huawei P40, P30.
  • Public: Fix issue where documents are submitted to Onfido API without filename or file type.

6.5.0 - 2021-02-08

Added

  • Public: Added npm latest version badge.
  • Internal: Now the UI tests will hit API endpoints from a dockerised mock server.
  • Internal: Introduce TypeScript on non-critical components & deprecate FlowType.
  • Internal: Introduce integration tests for API endpoint integrations.

Changed

  • Internal: Switched to bundlewatch Github Action for bundle size diff reporting, checking.
  • UI: Updated text and background colours.
  • Public: Removed references to MIT license in README and updated copy in LICENSE to refer to Onfido Service Agreement and 3rd party licenses reports.
  • Public: Return error for image quality failures on the first two document upload attempts.

Fixed

  • Public: Fix "File type not supported" error on snapshot upload in selfie step.
  • Public: Fix typo in en_US.json file

6.4.0 - 2020-12-21

Added

  • Internal: Introduce Hooks on non-critical components.
  • Public: Added CROSS_DEVICE_INTRO, CROSS_DEVICE_GET_LINK user analytic events for integrators to listen for when tracking user journey when initiating Cross Device flow from desktop browser
  • Public: Added licenses.json file containing the list of dependencies licenses.

Changed

  • UI: User is no longer blocked from uploading an image file over 10MB in size. Instead image is resized to 1440px if file size is over 3MB.
  • Internal: Update SDK's Publish Release workflow to not use the now deprecated set-env command.

Fixed

  • Public: Fixed issue where the SDK could not be initialised with poa as a single step.
  • Public: Only return Missing keys warning for unsupported language locale tags

6.3.1 - 2020-11-30

Fixed

  • Public: Fix missing country selector screen when the SDK is imported as an NPM module.

6.3.0 - 2020-11-09

Added

  • Internal: Added unit tests for Demo and App components
  • Public: Updated supported documents data to include Peru, Colombia as an issuing country option in Country Selection screen when user selects Residence Permit document type and remove Saudi Arabia option for National Identity Card document type.
  • Public: Added CROSS_DEVICE_START to Tracked events list
  • Public: Country Selection screen can now be suppressed for a non-passport document type when configured with a 3-letter ISO code.

Changed

  • Internal: Upgrade Preact from version 8.5.2 to 10.5.4.
  • Internal: Replace react-modal-onfido with version 3.11.2 of react-modal.
  • Internal: Refactor cross device option logic.

Fixed

  • Public: Fixed Woopra module import errors
  • Internal: Include isCrossDevice property and value in Document, Face capture payload's sdk_metadata object for data tracking

6.2.1 - 2020-11-04

Fixed

  • Public: Non-Latin localised strings throw exception in Welcome screen.

6.2.0 - 2020-10-19

Changed

  • UI: Accessibility - Update passport quality guide copy to be more descriptive for visually impaired users using screen readers
  • Internal: Update the Web SDK to handle telephony back end service's new error response format which is now consistent with API's error response format
  • Public: Improve description of showCountrySelection option for Document step to be more explicit about when/how it works and include example configurations.
  • Internal: Store third-party licence comments for each bundle in separate files.
  • Internal: Re-enable skipped tests for image quality logic.

Fixed

  • UI: Accessibility - Loading screen is now announced on iOS
  • Internal: Release script didn't update BASE_32_VERSION correctly and didn't finish at publishing tag step

6.1.0 - 2020-10-16

Added

  • Public: Add migrate_locales script to enable integrator migrate to next versions of Web SDK locale system.
  • Internal: Add unwrap_lokalise script to sanitise locale files pulled from Lokalise.

Changed

  • Public: Introduced new system for locale keys. Keys are now more structured and easier to find within the code.
  • Internal: Replace all string values from JS SDK to Web SDK and js-sdk to web-sdk.

Fixed

  • UI: Accessibility - Error and warning alert heading is now ARIA heading level 1
  • UI: Camera inactivity timeout only starts from camera access granted instead of on initial render
  • UI: Fixed call to action buttons covering content and instructions on Passport Image Guide, Selfie Intro screens when viewed on a mobile device with a shorter viewport, e.g. iPhone SE (1st gen)

6.0.1 - 2020-10-09

Fixed

  • Public: Updated supported documents data. This update includes adding Turkey as an issuing country option in Country Selection screen when user selects National Identity Card type.
  • Public: Only send issuing_country to the documents endpoint if issuing_country is present. This fixes the issue that was preventing documents upload when showCountrySelection was disabled and issuing_country was undefined.

6.0.0 - 2020-09-17

Added

  • UI: Add country selection screen after document selection. This screen is skipped by default for a preselected document but can still be displayed by enabling the showCountrySelection option for the document step.
  • UI: New warnings for cut-off & blurry images detection.
  • UI: When the uploaded image is either cut-off, glary or blurry, the end-user must retry at most 2 times prior to proceeding further.
  • UI: Added Residence Permit option for document selection
  • Internal: The release script and the release/RELEASE_GUIDELINE.md file now include the information needed to update the MIGRATION.md file.
  • Internal: Send additional system data in sdk_metadata which contains os, os_version, browser & browser_version info of the current session.

Changed

  • Internal: Changed resolution constraints for live document captures from 720 to 1080.
  • Public: Remove SMS_BODY key from locale files as it's not a customisable key and does not belong to this codebase.
  • Internal: Update SDK to handle new error response format from cross device SMS service

Fixed

  • Public: Return a generic error for unmapped Onfido API validation keys.
  • Fix typo in PhoneNumberInput SASS styles producing invalid CSS
  • UI: Fixed inconsistent font family for non Primary, Secondary button elements.

5.13.0 - 2020-08-24

Added

  • Public: Added isCrossDevice flag to user analytics events to differentiate between cross-device and non-cross-device user analytic events
  • Public: Added DOCUMENT_TYPE_SELECT and FACIAL_CAPTURE to user analytics event list
  • Public: Added option to pass a container element containerEl instead of a container ID string containerId. If containerEl is provided, then containerId will be ignored.

Changed

  • Internal: Sass CSS pre-processor is now used instead of Less.
  • Public: Fix live camera issues on certain Android devices, such as Huawei P20, when the useLiveDocumentCapture option for documents is enabled.
  • Internal: Fix cross-device SMS number input bundle import that broke when using newer versions of @babel/preset-env.
  • Internal: Added Prettier code formatting on npm run lint
  • Internal: Hybrid devices are now detected by checking if the device has touch screen and is Windows, instead of calling getUserMedia.
  • Internal: Use Onfido API v3 endpoints for documents, live_photos, live_videos and snapshots.
  • Public: When uploadFallback option is disabled for document or face live captures, display the unsupported browser error at the beginning of the flow.

Fixed

  • Public: Fixed spelling mistakes in Spanish translations for cross_device.link.sms_option and cross_device.link.qr_code_sub_title

5.12.0 - 2020-07-08

Added

  • Public: Added new enterprise feature cobrand. This allows integrators with access to the feature to display a co-branded footer with their company name, followed by "powered by Onfido" on all screens, including cross-device. Note that this will not be displayed if the hideOnfidoLogo enterprise feature is also enabled.
  • Internal: Added bundle size limit check for dist/style.css.
  • Public: Fix empty file sometimes being sent to /snapshots endpoint on some browsers when useMultipleSelfieCapture is enabled. This results in user seeing a "Unsupported File" error on Selfie upload.

Changed

  • Public: Moved UserAnalytics event firing outside of disableAnalytics config check

Fixed

  • UI: Top and bottom of icon cut off on Camera Permission screen for Document Auto Capture

5.11.1 - 2020-07-01

Fixed

  • Public: Fix issue preventing the SDK from loading or being updated in runtime if a step with type document is not found.

5.11.0 - 2020-06-30

Added

  • Public: Added check for cross_device_url in SDK Token to be used as the link for all cross device options instead of the default HOSTED_SDK_URL, if present. cross_device_url is an enterprise feature and can only be set when creating a SDK token if the feature is enabled.
  • Public: Added new enterprise feature hideOnfidoLogo. When purchased and enabled allows integrator to hide the Onfido logo on all screens, including cross-device.
  • UI: Added passport quality guide before upload/capture.

Changed

  • Public: Use history/createBrowserHistory as the default option to manage the SDK history. This change also gives the integrators the option to use history/createMemoryHistory by passing the configuration option useMemoryHistory: true to the SDK, in case history/createBrowserHistory does not behave as expected.
  • UI: Updated to new Onfido SDK watermark design

Fixed

  • Public: Fix issue that affects Safari on iOS 13.4.1, where the SDK was showing the wrong image rotation.
  • Public: Fix false Missing keys warning for present mobilePhrases. The warning should only be displayed when translation keys are missing.
  • Internal: Fix failing IE11 UI test for Passport upload

5.10.0 - 2020-06-16

Added

  • Internal: Added basic history to SDK demo.
  • Public: Added French translation. The language tag is fr_FR.

Changed

  • Internal: Remove unused dependencies and scripts from package.json
  • Public: Update description for region queryString in CONTRIBUTING.md
  • Public: Updated Browser Compatibility section in README.md to better indicate IE11, Firefox support
  • Public: Update English copy text for error message shown when no document is in the cameras view
  • Public: The useMultipleSelfieCapture configuration option is now stable and enabled by default
  • UI: All primary/secondary buttons now use the new width styling. This change also fixes the buttons UI issues noticeable when using de_DE as a language.

Fixed

  • UI: Accessibility - Focus is at document start
  • Public: Fix unexpected back button behaviour due to createBrowserHistory usage. The SDK now uses createMemoryHistory.
  • UI: Fixed blank screen displaying instead of Cross Device screen on desktop browsers when uploadFallback is disabled and browser does not have getUserMedia API support, e.g. IE11, or device does not have a camera.

5.9.2 - 2020-05-19

Fixed

  • UI: Fixed 2000ms delay to load Document Capture screen on non-Safari browsers

5.9.1 - 2020-05-14

Fixed

  • UI: Camera not detected on Safari 13.1 on iOS 13.4.1, macOS 10.15.4

5.9.0 - 2020-04-28

Added

  • Public: Added German translation and Lokalise integration. The expected language tags are now en_US, es_ES, de_DE. For backward compatibility, the SDK can also be initialised with tags that do not include the region, e.g.en, es, de.
  • Public: Added information on api/token regions to documentation.
  • Internal: Added CA region in demo app. The region can be selected in the previewer or by using a query string.

Changed

  • Public: Updated to react-webcam-onfido@0.1.18 to have fix for camera stream not getting on some Android devices, e.g. Motorola G5, Samsung Galaxy A6

Fixed

  • Public: Fix moderate vulnerabilities in minimist, a sub-dependecy used by @babel/cli and @babel/register.
  • Public: Fixed hybrid device camera detection and access request
  • Public: Fixed bug where user is able to click/tap on the button on the Camera screen before allowing/denying permission.
  • Public: Fixed iPads on iOS13 not getting detected as mobile device on cross device flow.

5.8.0 - 2020-03-19

Added

  • Public: Changes to allow hybrid desktop/mobile devices with environment facing cameras (e.g. Surface Pro) to use the useLiveDocumentCapture feature (BETA feature)
  • Public: Added a userAnalyticsEvent to existing analytics calls for integrators to listen for.
  • Internal: Analytics can now be disabled via the disableAnalytics option
  • Internal: Test coverage for snapshot feature
  • Internal: Send additional properties to back-end in sdkMetadata object
    • isCrossDeviceFlow (true|false)
    • deviceType (mobile|desktop)
    • captureMethod (live|html5)

Changed

  • Internal: Use v2/snapshots endpoint to upload additional selfie frames.
  • Internal: Split Confirm component into multiple files.
  • UI: Accessibility - Update font colours and weight following DAC Audit report feedback
  • Internal: Pushing dist files to S3 and publishing the release to NPM has been automated using GitHub Actions
  • Internal: Improve UI tests stability when looking for and clicking on UI elements
  • Public: Documentation should use v3 for API endpoints and include links to migration guide.

Fixed

  • Public: Fixed bug where iPads on iOS13 were detected as desktop devices.
  • Public: Made fallback error message appropriate for both face and document verification
  • Public: Fixed video recording in liveness capture step not working for Firefox >= 71
  • Internal: Fix flaky modal UI tests
  • Public: Fixed bug where blob was not handled correctly when an upload event was fired on IE11
  • Public: Fixed camera permission screen layout issue on desktop Safari where buttons disappears below view height
  • Public: Prevent "submit" event from being emitted when selecting a document

5.7.1 - 2020-02-25

Fixed

  • Public: Cross-device client and link now works when desktop SDK configured with US JWT

5.7.0 - 2020-01-22

Added

  • Public: Added a troubleshooting section to the documentation with details about solving CSP related issues
  • UI: Added selfie intro screen
  • UI: Option to send cross device secure link using QR code (Note: changes introduced with this UI update include possible breaking changes for integrators with custom translations or copy)

Changed

  • UI: Unsupported browser message for mobile browsers without getUserMedia API support when uploadFallback option is disabled for live document capture and selfie/liveness capture steps
  • Internal: Redux and EventEmitter are not in the global scope anymore. The tearDown function will only unmount the SDK.
  • UI: As part of work to add the QR code option for cross device secure link the UX has been updated for the copy link and SMS options

Fixed

  • Internal: Fixed Latest Surge link version not getting updated during release process
  • UI: Fixed Liveness capture staying darkened after x-device message dismissed
  • Accessibility: Changed Liveness background colour from 66% to 80%

5.6.0 - 2019-12-09

Note: This version might be a breaking change if you are providing customised language translations. Please see MIGRATION.

Added

  • Internal: Added UI test to check Submit Verification button is not clickable multiple times if Complete step is excluded
  • Internal: Deploy source maps to Sentry using @sentry/cli within our deployment script

Changed

  • Internal: Updated react-webcam-onfido to get check(s) for stream before calling getVideoTracks/getAudioTracks method
  • Internal: Removed libphonenumber-js from main bundle. Reduced bundle size limit by 20%.
  • Internal: Use @sentry/browser instead of raven to track Sentry events
  • UI: New Document Upload screen (Note: changes introduced with this UI update include possible breaking changes for integrators with custom translations or copy)

Fixed

  • Internal: Latest Surge link gets updated only on release of a full version, not release candidates or beta releases
  • UI: Fixed missing "basic camera mode" link style on "Camera not working" timeout error message when going through flow on mobile
  • UI: Fixed Back button not taking user to the right place during liveness recording
  • UI: Fixed invalid but possible number error blocking subsequent retries
  • UI: Users should not be able to click or tap on confirmation buttons or camera buttons multiple times. This will prevent callbacks (such as the onComplete callback) or click events to be fired multiple times.

5.5.0 - 2019-10-31

Added

  • Public: useLiveDocumentCapture option added to the document capture step (BETA feature)
  • Internal: Added bundlesize script to fail the build if our bundle becomes bigger than 400kb. It also tests that cross-device chunk does not exceeds 3kb.
  • Internal: Added npm audit script to the build using audit-ci to detect dependencies vulnerabilities at PR level.

Fixed

  • UI: Accessibility - Non-interactive Header elements do not get announced with "Double tap to activate" by Android Talkback
  • UI: Custom string nextButton set for the welcome step is now displayed
  • Internal: Fixed flaky UI tests by adding functions that wait until the elements are located or clickable

5.4.0 - 2019-10-03

Added

  • UI: Added hover and active state styles for clickable UI elements (buttons, links)
  • Public: Added onError callback. Callback that fires when one of the following errors occurs: timeout errors, authorization errors, server errors and invalid and expired token errors.

Changed

  • Public: Disable console warning for client integrations that override only some strings for a supported language. If they provide partial translations for an unsupported language, warning is still displayed.
  • Public: Only upgrade to patch versions of socket.io-client. See issue here

Fixed

  • UI: Accessibility - Make camera feed view accessible to screen readers
  • UI: Accessibility - More descriptive ARIA label for camera shutter button
  • Public: Fixed user being able to submit verification multiple times on coming back to desktop from the cross device flow if integrator has opted to exclude the complete step in SDK setup
  • Public: Fix wrong cross device redirection when user is already on mobile (iOS 10)

5.3.0 - 2019-09-03

Added

  • UI: User can now drag and drop images on desktop uploader
  • Public: option to configure click on overlay behaviour when SDK presented modally using shouldCloseOnOverlayClick option
  • Internal: Added basic automated tests for accessibility features
  • UI: Accessibility - Make Liveness screens accessible to screen readers
  • UI: Accessibility - Make Cross Device phone number input accessible to screen readers
  • Internal: Added automated testing for features using camera stream
  • Public: Added useMultipleSelfieCapture option for the face step. By enabling this configuration, the SDK will attempt to take multiple applicant selfie snapshots to help improve face similarity check accuracy.
  • Internal: Fetch URLs from JWT when present, otherwise use defaults

Changed

  • Public: Unbundled dependencies for npm. This also fixes the current issue with imports (tested on Next.js, Create-react-app and Storybook) and solves #615, #668, #733
  • UI: Changed camera permission screen design
  • Internal: Disable source maps for NPM build. Source maps will still be enabled for /dist build
  • Internal: Upgraded Preact for compatibility with latest version of React DevTools

Fixed

  • Public: Fixed user seeing the video capture intro screen, followed by selfie capture screen instead of x-device intro screen when video capture is enabled but device has no camera
  • Public: Fixed wrong message displaying on the Cross Device "End of Flow" screen
  • Public: Fixed footer overlapping Proof of Address document type list at the bottom of the container
  • Public: Fixed user seeing front side of previously uploaded 2-sided document in Proof of Address upload step

5.2.3 - 2019-07-18

Fixed

  • Public: Removed tarball as a way to import wpt library. The package is now imported as a dev-dependecy and is pointing at the new Woopra repository on github.

5.2.2 - 2019-06-19

Added

  • Internal: Better automation of the release process
  • UI: Accessibility - Make screenreader navigation work in modal mode

Changed

  • Public: Use tarball when importing wpt library

Fixed

  • Public: Fixed bug where double clicking on Send Link button then skips straight to Complete screen
  • Public: Fixed scrollbar appearing on some machines/devices

5.2.1 - 2019-05-30

Added

  • UI: Accessibility - Announce validation error on cross device SMS link screen

Changed

  • UI: Accessibility - Update all visually obvious lists to use the relevant HTML list elements

Fixed

  • Public: When glare is detected, onComplete callback returns doc id

5.1.0 - 2019-05-23

Added

  • UI: Accessibility - Make H1 readable by screen readers
  • UI: Accessibility - Make buttons/links readable by screen readers, allow tabbing to them
  • UI: Accessibility - Sort out order of items when tabbing through the content of each step
  • UI: Accessibility - Announce page transition when screen changes
  • UI: Accessibility - Make capture previews readable by screen readers
  • UI: Accessibility - Announce enlargement of captured image in preview
  • UI: Accessibility - Announce camera alerts
  • UI: Accessibility - Announce validation errors and warnings on confirm screen

Changed

  • Internal: Make Permission screen and Recovery screen buttons visible on small devices
  • Internal: The third party analytics (Woopra) is now imported via a dummy window in order not to pollute the shared global window

Fixed

  • Public: Handle non JSON error responses and return a Connection Lost error to the user
  • UI: Make sure "full screen" mode is off when navigating away from enlarged preview
  • UI: Make sure all buttons have a type of a "button" set
  • Internal: Fixed vulnerabilities on some dev dependencies

5.0.0 - 2019-04-01

Fixed

  • Public: Fixed issue where the user is prompted to submit the same document capture twice and fixed broken custom input UI by adding higher CSS specificity
  • Internal: We are using an updated version of socket.io server, which allows for better horizontal scalling.

Changed

  • Public: If the SDK is initialised with only one document type, users will not see the document selection screen, instead they will see the capture screen straight away.
  • Internal: Woopra is no longer polluting the global window object

4.0.0 - 2019-03-18

Added

  • Public: Prepopulate the user's mobile phone number, when specified through the userDetails.smsNumber option
  • Public: Send through details (such as ids) of the uploaded files, in the onComplete event
  • Public: Added forceCrossDevice option to document step. The feature forces users to use their mobile to capture the document image. It defaults to false. Not available on the Proof of Address flow.
  • Public: Upload fallback for the face step can be disabled by using the option { uploadFallback: false }. The default value is true (feature released in 3.1.0 as Internal)
  • Internal: Add an internal-only warning for internal-users of the cross-device flow (a warning entirely stripped in production)

Changed

  • Public: ES style import interface has been changed to a more standard one
  • Internal: Changed the way that blob/base64 files and images are rendered and passed through the system
  • Internal: Changed CSS units to be consistently em (but still tied to px at our root, until we can fix our media queries)
  • Public: More meaningful error message for upload fallback disabled on face step
  • Internal: Map colours and use less variables instead of hard-coding colour values
  • UI: Fixed issue with footer overlapping content, prevent buttons from disappearing below viewport, prevent images from overlapping buttons.
  • Internal: Rebranding of background, border and primary colors.
  • Internal: Woopra tracker now points at the latest tag of https://github.com/Woopra/js-client-tracker
  • Internal: Upgraded to webpack 4, removed import/export transpilation. Reduced bundle size as result.

Fixed

  • Public: Users entering the cross-device flow twice would have been able to request an SMS message without re-entering their mobile number correctly (the form could submit when still blank)
  • Internal: Fix a bug that potentially allowed 3rd party tracking scripts to (in some very specific conditions) continue to send Onfido tracking events, after calling .tearDown()
  • Public: Users could previously see a flicker of other screens when loading any flow involving the camera. This should now no longer occur, except in rare circumstances (where permissions/capabilities have changed since last render)
  • Public: Workaround an iOS Safari issue that causes a possible browser crash when mounting the webcam component multiple times

3.1.0 - 2019-01-28

Added

  • Public: Added Proof of address poa step where users can capture their proof of address documents. This is a beta feature.
  • Internal: Further device metadata submitted to Onfido API
  • Internal: Upload fallback for the face step can be disabled by using the option { uploadFallback: false }. The default value is true
  • Internal: Added multi-frame capture for the standard variant of the face step (only for camera capture).

Changed

  • Internal: Cross device client can now only be opened on mobile browsers. Users trying to open the link on a desktop browsers will see an error.
  • Internal: Removed unused development dependencies which had known vulnerabilities

3.0.1 - 2018-12-19

Fixed

  • Internal: Fixed an infinite loading loop that happened when video liveness is enabled and if, and only if, users transitioned from a desktop browser that support video liveness to a mobile browser that does not support video liveness

3.0.0 - 2018-10-31

Added

  • Internal: Introduce Jest unit testing framework
  • Public: Added support for default SMS number country code. The default country for the SMS number input can be customised by passing the smsNumberCountryCode option when the SDK is initialised. The value should be a 2-characters long ISO Country code string. If empty, the SMS number country code will default to GB.
  • UI: UI improvements including adding back icon with hover state and icon to close the modal

Changed

  • Public: Remove support for buttonId initialization option
  • Internal: Use imports-loader instead of script-loader to import Woopra
  • Internal: Ensures only onfido related events are included as part of the payloads sent to Sentry
  • Internal: Stop sentry tracking after tearDown
  • Internal: Prevent Raven from using console.log output for breadcrumbs by setting autoBreadcrumbs: { console: false }

2.8.0 - 2018-09-20

Changed

  • UI: Documents can be enlarged for inspection
  • UI: Camera warnings are now dismissible
  • UI: Title copy change on video confirmation screen

Fixed

  • Public: Fixed error with missing stream recording
  • UI: Fixed document selector UI on IE11
  • UI: Fixed overlapping footer and buttons on confirmation screen on Firefox

2.7.0 - 2018-09-03

Added

  • Public: Introduced ability to capture videos on the face step. Developers can now request a preferred variant for the face step, by adding the option requestedVariant: 'standard' | 'video'. If empty, it will default to standard and a photo will be captured. If the requestedVariant is video, we will try to fulfil this request depending on camera availability and device/browser support. In case a video cannot be taken the face step will fallback to the standard option. At the end of the flow, the onComplete callback will return the variant used to capture face and this can be used to initiate the facial_similarity check.

Changed

  • Public: The onComplete callback now returns an object including the variant used for the capture step. The variant can be used to initiate the facial_similarity check. Data returned: {face: {variant: 'standard' | 'video'}}.
  • UI: Selfie UI to adopt full container layout on desktop.
  • Internal: CSS namespacing now includes the full path of the component, to mitigate chances of name collision. Only impacts components nested in another component folder.

2.6.0 - 2018-08-08

Changed

2.5.0 - 2018-07-27

Added

  • UI: Added a permission priming screen to inform the user that camera permissions must be enabled.
  • UI: Added a permission recovering screen in case user media permissions are denied.
  • UI: Added intro screen when entering cross device flow.

Changed

  • UI: Changed UI for face capture step. On small screens it will display a full screen camera component.
  • UI: Desktop - If webcam is not available, a cross device intro screen will be shown to allow the user to take a live photo on their mobile phones.

2.4.1 - 2018-05-18

Fixed

  • Public: Fixed bug where hitting Enter key on the SMS input number was causing page reload.

2.4.0 - 2018-05-17

Added

  • Public: Added documentTypes to the document step options, which allows to filter the document types.

Changed

  • Internal: Refactored layout to better handle presence of header and footer elements.
  • Internal: On cross device client clear error message when configuration is received.

2.3.0 - 2018-04-17

Added

  • Public: Added onModalRequestClose options, which is a callback that fires when the user attempts to close the modal.

Fixed

  • Public: Fixed complete step to allow string customization at initialization time.
  • Internal: Fixed the tearDown method to clear the onComplete callback functions. (issue #306)

Deprecated

  • Internal: Removed references to useWebcam option from README.md and return console warning if the option is used.

2.2.0 - 2018-02-13

Added

  • Public: Added support for internationalisation. The SDK can now be displayed in Spanish by adding {language: 'es'} to the initialization options. It can also be displayed in a custom language by passing an object containing the custom phrases and the locale. If language is not present or the wrong locale tag is provided, the language locale will default to en.
  • Public: Added support for Spanish language on the SMS body.
  • Public: Added webcam support on Safari and IE Edge.

Changed

  • UI: If the webcam is facing the user it will be mirrored

2.1.0 - 2017-11-30

Added

  • UI: The cross device feature now supports sending the link via SMS. Users will still be able to copy the link to clipboard.
  • UI: Introduced a back button that allows the user to navigate to the previous screen.
  • Internal: Introduced code splitting and lazy loading

2.0.0 - 2017-11-08

In this version, we're introducting cross-device flow that allows to continue verification on mobile in order to take photos of your document and face.

Note:

  • This version is not backwards-compatible. Migration notes can be found in MIGRATION.md

Removed

  • Public: Removed onDocumentCapture that used to be fired when the document had been successfully captured, confirmed by the user and uploaded to the Onfido API
  • Public: Removed onFaceCapture callbacks that used to be fired when the face has beed successfully captured, confirmed by the user and uploaded to the Onfido API.
  • Public: Removed getCaptures function that used to return the document and face files captured during the flow.
  • Internal: Removed confirm action

Changed

  • Public: Changed the behaviour of onComplete callback. It used to return an object that contained all captures, now it doesn't return any data.

Added

  • UI: Introducing glare detection feature for documents. Not available for documents in PDF format yet.
  • Internal: Added confirm step to router history and tracking

Changed

  • UI: Improved how errors and warnings are displayed on the UI
  • UI: Improved navigation between steps when using the browser navigation buttons
  • Internal: Improved event tracking
  • Internal: Upgraded Preact to latest version

Note

Bumping version to 1.0.0 because SDK has already been implemented in production integrations. Also SDK now integrates with Onfido API.

Changed

  • Public: Support uploading documents and live photos to the Onfido API through use of new SDK tokens (JWT v2)

Removed

  • Public: Face no longer supports PDF upload in order to align with the Onfido API.

Fixed

  • Internal: Fixed problem on certain versions of Firefox that no longer supported the old version of getUserMedia
  • Internal: Fixed the tearDown method to clear the documents and faces currently in the store
  • Internal: Fixed PDF preview issues on IE Edge, IE11 and mobile browsers.
  • Internal: Fixed lower resolution webcams not working on Firefox

Changed

  • Internal: replaced the has_webcam checker with a more robust version that periodically checks if the state changed
  • Internal: Increased the file size upper limit to 10 MB.

Changed

  • Internal: Use HTTP protocol to post documents to the server instead of websockets

Fixed

  • Public: Fixed intermittent connection problem

Changed

  • Public: Document and face captures will be returned by callbacks as File or Blob instead of base64.
  • Internal: Callbacks are now linked to the flow rather than the Redux store.

Added

  • Public: Capture the reverse side of driving licenses and ID cards.
  • Public: Add a file size limit of 4 MB in line with the Onfido API.

Fixed

  • Internal: Read exif tags to orientate images correctly.

Changed

  • Public: Change the default to use file upload rather than the webcam for document captures.
  • Internal: Fix dependencies to avoid bugs due to changes in minor updates.

0.12.0-rc.1

Install with npm install onfido-sdk-ui@0.12.0-rc.1

Changed

  • Internal: Change the signature expected from the websockets server.

Fixed

  • Public: The documentType in the capture object now corresponds to the API document_types.
  • Public: Fixed bug where URL path was removed between steps.

0.11.1 - Hotfix

Fixed

  • Public: Fixed bug where Onfido.getCaptures() and onComplete(hash) was returning a broken hash.
  • Internal: Froze dependencies which were causing the upload document and pdf preview not to work.

Changed

  • Internal: Removed preact-router.
  • Public: Removed URL routes for each step of the SDK flow.
  • Internal: Removed unused components - Dropdown and ActionBar.
  • Internal: Use the staging backend when in development.
  • Updated version of onfido-sdk-core to 0.7.1.

Added

  • Public: tearDown method to remove the SDK elements.

Changed

  • Internal: Use visibilityjs to pause captures when the tab is inactive.
  • Internal: The copy of the document not found error message was changed.
  • Internal: Changed the order of the document selection to passport, driver's license and identity card.
  • Public: The returned webcam captures now have a resolution of 960x720, or lower if the webcam does not support it.
  • Internal: The confirmation step for webcam captures now displays the new high resolution images.
  • Internal: Updated react-webcam-onfido in order to get the higher resolution functionality.

Added

  • Public: Uploaded PDF files are now supported and returned by the callbacks as base64.
  • Internal: PDF files are displayed in the confirmation step as an embedded object, which means the browser needs to support pdf files in order for them to be visible.

Changed

  • Public: document and face callback are now passed only their respective capture, instead of both their captures.
  • Public: document and face callback are now only called after the user has confirmed the capture
  • Public: document, face and complete callback can be called multiple times, if the condition that triggers them is met more than once (eg. if the user goes back to redo the capture steps)
  • Internal: callbacks' returned value now have no impact on the event dispatcher.

Fixed

  • All captures have now a default no op function. This fixes an exception raise (in case some callbacks where not defined), which caused the rest of the callbacks not to be called after the exception was raised.

Fixed

  • Updated react-webcam to the onfido fork, this fixes the issue where the webcam canvas (used to obtain screenshots) has 0 height under certain circumstances (namely on windows machines running Chrome). This bug, when it happened, caused the document capture step not to work.

Added

  • Started tracking fatal exceptions and page views of the SDK.

Fixed

  • Fixed bug of a broken layout on the document selection step. Always reproducible on IE and on other browsers too, but only when going back a step on certain conditions.
  • Fixed bug where on IE an unnecessary scrollbar appeared and the scrolling area was bigger than it should have been.

Added

  • Public: An error message is now shown if the upload file has as unsupported file type.

Fixed

  • Object.assign was being used but not polyfilled. Its occurrence was replaced with an es6 object construction.
  • UI disappeared if the browser's windows width was smaller than 481px;

Changed

  • Public: Captures are now returned as png instead of webp, although webp is still used internally for streaming to the server.
  • Public: the captures returned by Onfido.getCaptures() have a simplified signature of just {id,image,documentType}.
  • Public: It's now possible to open and close the modal by calling .setOptions({isModalOpen:boolean})
  • Internal: The modal has been refactored to be fully reactive, vanilla-modal has been replaced with a fork of react-modal.
  • Internal: Updated to onfido-sdk-core@0.6.0, selectors are now more general as in they are no longer specific to each capture type, some new selectors are also being used.
  • Internal: Camera, Capture and Uploader have been refactored, the pure part of the components have been separated from the state logic part. This adds flexibility and encapsulation.
  • Internal: The Capture component now orchestrates all the state logic of the Uploader component, this allows to join the camera and uploader state logic together.

Added

  • Public: The capture screen UI now includes an upload button fallback, for whenever the user experiences problems with the webcam.
  • Internal: When requesting to validate documents there is now a strategy to cope with slow responses from the server. If the number of unprocessed documents is 3+, the client stops sending more requests until a response is given.
  • Internal: webp falls back to jpeg in case the browser does not support it.

Changed

  • Public: onComplete event now fires only after both the document and face captures have been confirmed in the UI
  • Internal: updated onfido-sdk-core to 0.5.0 which causes the all capture event to be triggered when captured are both valid and confirmed
  • Internal: made the confirm button change the state of the capture to confirmed

Fixed

  • Internal: sometimes when document was retaken multiple times the capture ended up squashed. This was fixed by upgrading to react-webcam@0.0.14.
  • Internal: fixed Bug #36, it caused the face to be captured every second after a document retake.

Changed

  • Public: Onfido.init() now returns an object.
  • Internal: isDesktop detection is now based on DetectRTC's isMobile detection
  • Internal: improved Webcam Detection, it now takes into account wether a Webcam exists and if it the user has given the website permission to use it. Before it was only checking whether the getUserMedia API is supported by the browser or not. DetectRTC is used for this detection.

Added

  • Public: it's now possible to change the init options at runtime by calling setOptions() on the object returned by Onfido.init()
  • Public: useWebcam option added to the facial and document capture step

Fix

Added

  • API: Flow customization option steps:[]
  • UI: Overlay to the webcam document capture (Possibly breaking change)
  • DOC: Integration examples to documentation

Fixed

  • NPM (commonjs2) style of importing the library now works

Onfido Web SDK Migration Guide

The guides below are provided to ease the transition of existing applications using the Onfido SDK from one version to another that introduces breaking API changes.

6.13.0 -> 6.14.0

The English, Spanish, German, French, Italian and Portuguese copy for the following string(s) has changed:

Added strings

  • cross_device_session_linked.button_primary
  • cross_device_session_linked.info
  • cross_device_session_linked.list_item_desktop_open
  • cross_device_session_linked.list_item_sent_by_you
  • cross_device_session_linked.subtitle
  • cross_device_session_linked.title

Changed strings

  • generic.errors.request_error.message

6.11.1 -> 6.12.0

The English, Spanish, German, French, Italian and Portuguese copy for the following string(s) has changed:

Changed strings

  • video_intro.list_item_actions

6.10.2 -> 6.11.1

The English, Spanish, German, French, Italian and Portuguese copy for the following string(s) has changed:

Added strings

  • doc_capture.detail.folded_doc_front
  • doc_capture.header_folded_doc_front
  • doc_capture.prompt.button_card
  • doc_capture.prompt.button_paper
  • doc_capture.prompt.title_id
  • doc_capture.prompt.title_license
  • doc_video_capture.button_primary_fallback
  • doc_video_capture.button_primary_fallback_end
  • doc_video_capture.detail_step2
  • doc_video_capture.header
  • doc_video_capture.header_paper_doc_step2
  • doc_video_capture.header_passport
  • doc_video_capture.header_passport_progress
  • doc_video_capture.header_step1
  • doc_video_capture.header_step2
  • doc_video_capture.prompt.detail_timeout
  • doc_video_capture.stepper
  • doc_video_capture.success_accessibility
  • doc_video_confirmation.button_secondary
  • doc_video_confirmation.title
  • video_capture.prompt.header_timeout
  • video_confirmation.body
  • video_confirmation.button_primary
  • video_confirmation.button_secondary
  • welcome.list_header_doc_video
  • welcome.list_item_doc_video_timeout

6.9.0 -> 6.10.0

Added strings

  • doc_capture.detail.folded_doc_front
  • doc_capture.header_folded_doc_front
  • doc_capture.prompt.button_card
  • doc_capture.prompt.button_paper
  • doc_capture.prompt.title_id
  • doc_capture.prompt.title_license
  • doc_video_capture.button_primary_fallback
  • doc_video_capture.button_primary_fallback_end
  • doc_video_capture.detail_step2
  • doc_video_capture.header
  • doc_video_capture.header_paper_doc_step2
  • doc_video_capture.header_passport
  • doc_video_capture.header_passport_progress
  • doc_video_capture.header_step1
  • doc_video_capture.header_step2
  • doc_video_capture.prompt.detail_timeout
  • doc_video_capture.stepper
  • doc_video_capture.success_accessibility
  • doc_video_confirmation.button_secondary
  • doc_video_confirmation.title
  • video_capture.button_primary_start
  • video_capture.prompt.header_timeout
  • video_capture.header.challenge_turn_forward
  • video_confirmation.body
  • video_confirmation.button_primary
  • video_confirmation.button_secondary
  • welcome.subtitle
  • welcome.list_header_doc_video
  • welcome.list_header_webcam
  • welcome.list_item_doc
  • welcome.list_item_poa
  • welcome.list_item_doc_video_timeout
  • welcome.list_item_selfie

The English, Spanish, German, and French copy for the following string(s) has changed:

Changed strings

  • video_capture.button_primary_finish
  • video_capture.button_primary_next
  • video_capture.header.challenge_turn_left
  • video_capture.header.challenge_turn_right
  • welcome.title
  • welcome.next_button
  • cross_device_checklist.list_item_doc_multiple
  • cross_device_checklist.list_item_doc_one
  • cross_device_checklist.list_item_selfie
  • cross_device_checklist.list_item_video
  • cross_device_checklist.subtitle
  • cross_device_checklist.title
  • doc_confirmation.alert.no_doc_detail
  • doc_confirmation.alert.no_doc_title
  • doc_confirmation.body_id
  • doc_confirmation.body_license
  • doc_confirmation.body_passport
  • doc_confirmation.body_permit
  • doc_confirmation.button_primary_upload
  • doc_select.button_passport_detail
  • doc_select.title
  • generic.errors.no_face.instruction
  • generic.errors.no_face.message
  • get_link.subtitle_url
  • outro.body
  • outro.title
  • permission.body_cam
  • selfie_capture.alert.timeout.detail
  • selfie_capture.title
  • selfie_confirmation.subtitle
  • selfie_confirmation.title
  • selfie_intro.subtitle
  • upload_guide.button_primary
  • video_capture.body
  • video_capture.body_record
  • video_confirmation.title
  • video_intro.button_primary
  • video_intro.list_item_actions
  • video_intro.list_item_speak

Only the Spanish, German, and French copy for the following string(s) has changed:

  • country_select.search.input_placeholder

Removed strings

  • video_capture.body_next
  • video_capture.body_stop
  • video_capture.button_stop_accessibility
  • video_capture.header.challenge_turn_template
  • welcome.description_p_1
  • welcome.description_p_2

6.8.0 -> 6.9.0

The English, Spanish, German, and French copy for the following string(s) has changed:

Added strings

  • auth_accessibility.back_button
  • auth_cam_encrypt.loader
  • auth_cam_start.loader
  • auth_capture_start.body
  • auth_capture_start.button_primary
  • auth_capture_start.title
  • auth_capture_start.feedback.center_face
  • auth_capture_start.feedback.conditions_too_bright
  • auth_capture_start.feedback.conditions_too_dark
  • auth_capture_start.feedback.head_not_upright
  • auth_capture_start.feedback.neutral_expression
  • auth_capture_start.feedback.not_looking_straight
  • auth_capture_start.feedback.remove_sunglasses
  • auth_capture_start.feedback.steady_count_1
  • auth_capture_start.feedback.steady_count_2
  • auth_capture_start.feedback.steady_count_3
  • auth_capture.feedback.center_face
  • auth_capture.feedback.even_lighting
  • auth_capture.feedback.eye_level
  • auth_capture.feedback.face_not_found
  • auth_capture.feedback.head_not_upright
  • auth_capture.feedback.move_back
  • auth_capture.feedback.move_close
  • auth_capture.feedback.move_closer
  • auth_capture.feedback.not_looking_straight
  • auth_capture.feedback.steady
  • auth_error.cam_encryption.body
  • auth_error.cam_encryption.button_primary
  • auth_error.cam_encryption.button_primary_firefox
  • auth_error.cam_encryption.subtitle
  • auth_error.cam_encryption.table_header_1
  • auth_error.cam_encryption.table_header_2
  • auth_error.cam_encryption.table_row_1_cell_1
  • auth_error.cam_encryption.table_row_1_cell_1_firefox
  • auth_error.cam_encryption.table_row_1_cell_2
  • auth_error.cam_encryption.table_row_1_cell_2_firefox
  • auth_error.cam_encryption.table_row_2_cell_1
  • auth_error.cam_encryption.table_row_2_cell_2
  • auth_error.cam_encryption.table_row_3_cell_1
  • auth_error.cam_encryption.table_row_3_cell_2
  • auth_error.cam_encryption.title
  • auth_full_screen.body
  • auth_full_screen.button_primary
  • auth_full_screen.title
  • auth_permission_denied.body_cam
  • auth_permission_denied.button_primary_cam
  • auth_permission.body_cam
  • auth_permission.button_primary_cam
  • auth_permission.title_cam
  • auth_progress.loader
  • auth_retry.body_blur
  • auth_retry.body_neutral_expression
  • auth_retry.body_too_bright
  • auth_retry.button_primary
  • auth_retry.subtitle
  • auth_retry.title
  • auth_upload_pass.body

Changed strings

The English, Spanish, German, and French copy for the following string(s) has changed:

6.6.0 -> 6.8.0

Added strings

The English copy for the following string(s) has been added:

user_consent_load_fail.button_primary user_consent_load_fail.detail user_consent_load_fail.prompt.title

Note: The consent screen copy is only available in English

6.5.0 -> 6.6.0

Added strings

The English copy for the following string(s) has been added:

user_consent.button_primary user_consent.button_secondary user_consent.prompt.button_primary user_consent.prompt.button_secondary user_consent.prompt.no_consent_detail user_consent.prompt.no_consent_title

Note: The consent screen copy is only available in English

6.4.0 -> 6.5.0

From version 6.5.0, TypeScript is officially supported. If you previously installed the DefinitelyTyped package, you can safely remove it because the distributed NPM package already contains an index.d.ts declaration file.

6.1.0 -> 6.2.0

Changed strings

The English, Spanish, German, and French copy for the following string(s) has changed:

  • upload_guide.image_detail_blur_label
  • upload_guide.image_detail_glare_label
  • upload_guide.image_detail_good_label

6.0.1 -> 6.1.0

Introduce migrate_locales script

From version 6.1.0, Web SDK will use a new locale key naming convention that better supports scalability. As a result, many key names will be changed and this might affect the integrator's custom locale options. The migrate_locales script will help integrators migrate from the older key name convention to the new one with minimal hassle.

To use the script:

  • Upgrade onfido-sdk-ui package to latest version 6.1.0

  • Create a JSON file containing custom locales which was fed to Onfido.init() method. For instance:

    JavaScript
    Copy
    // your-custom-language.json
    {
      "locale": "en_US",  // untouched keys
      "phrases": {        // required key
        "capture": {
          "driving_licence": {
            "front": {
              "instructions": "Driving license on web"
            }
          }
        },
        "complete.message": "Complete message on web"
      },
      "mobilePhrases": {  // optional key
        "capture.driving_licence.front.instructions": "Driving licence on mobile",
        "complete": {
          "message": "Complete message on mobile"
        }
      }
    }
    
  • Consume the script directly from node_modules/.bin:

    shell
    Copy
    $ migrate_locales --help                # to see the script's usage
    
    $ migrate_locales --list-versions       # to list all supported versions
    
    Supported versions:
      * from v0.0.1 to v1.0.0
    
    $ migrate_locales \
      --from-version v0.0.1 \
      --to-version v1.0.0 \
      --in-file your-custom-language.json \
      --out-file your-custom-language-migrated.json
    
  • The migrated data should look like this:

    JavaScript
    Copy
    // your-custom-language-migrated.json
    {
      "locale": "en_US",
      "phrases": {
        "new_screen": { // renamed key in nested object
          "driving_licence": {
            "front": {
              "instructions": "Driving license on web"
            }
          }
        },
        "screen_1.complete.message": "Complete message on web", // 2 generated keys from 1 old key
        "screen_2.complete.message": "Complete message on web"
        "mobilePhrases": { // force nesting because standalone `mobilePhrases` will be deprecated soon
          "new_screen.driving_licence.front.instructions": "Driving licence on mobile", // renamed key in dot notation
          "screen_1": { // 2 generated keys from 1 old key
            "complete": {
              "message": "Complete message on mobile"
            }
          },
          "screen_2": {
            "complete": {
              "message": "Complete message on mobile"
            }
          }
        }
      },
    }
    
  • Notes: the script will preserve:

    • Order of the keys
    • Format: if your old keys are nested as an object, the migrated keys will be nested too. Otherwise, if your old keys are string with dot notation, the migrated keys will be string too.

5.10.0 -> 6.0.0

Change in UX flow for Document step

  • Document step now has a Issuing Country Selection screen after the Document Type Selection screen. This screen is never displayed for passport documents and is disabled by default when only 1 document is preselected using the documentTypes option. This screen can still be included in the document capture flow of non-passport preselected documents by enabling the showCountrySelection option in the Document step configuration.

Example of Document step with Country Selection for a preselected non-passport document

JSON
Copy
{
  "steps": [
    "welcome",
    {
      "type": "document",
      "options": {
        "documentTypes": {
          "passport": false,
          "driving_licence": false,
          "national_identity_card": true
        },
        "showCountrySelection": true
      }
    },
    "complete"
  ]
}

Example of Document step without Country Selection for a preselected non-passport document (default behaviour)

JSON
Copy
{
  "steps": [
    "welcome",
    {
      "type": "document",
      "options": {
        "documentTypes": {
          "passport": false,
          "driving_licence": false,
          "national_identity_card": true
        },
        "showCountrySelection": false
      }
    },
    "complete"
  ]
}

Example of Document step configurations with preselected documents where Country Selection will still be displayed

JSON
Copy
{
  "steps": [
    "welcome",
    {
      "type": "document",
      "options": {
        "documentTypes": {
          "passport": true,
          "driving_licence": true,
          "national_identity_card": true
        }
      }
    },
    "complete"
  ]
}
JSON
Copy
{
  "steps": [
    "welcome",
    {
      "type": "document",
      "options": {
        "documentTypes": {
          "passport": true,
          "national_identity_card": true,
          "driving_licence": false
        }
      }
    },
    "complete"
  ]
}

Added strings

  • country_selection.error
  • country_selection.dropdown_error
  • country_selection.placeholder
  • country_selection.search
  • country_selection.submit
  • country_selection.title
  • capture.residence_permit.front.title
  • capture.residence_permit.back.title
  • confirm.residence_permit.message
  • document_selector.identity.residence_permit_hint
  • residence_permit

Changed strings

The English, Spanish, German, and French copy for the following string(s) has changed:

  • document_selector.identity.title
  • document_selector.identity.hint

Changed keys

The following keys have been renamed:

  • errors.server_error.instruction => errors.request_error.instruction
  • errors.server_error.message => errors.request_error.message

Removed strings

  • SMS_BODY

5.7.0 -> 5.10.0

Added strings

  • image_quality_guide.title
  • image_quality_guide.sub_title
  • image_quality_guide.all_good
  • image_quality_guide.not_cut_off
  • image_quality_guide.no_glare
  • image_quality_guide.no_blur
  • image_quality_guide.image_alt_text
  • image_quality_guide.next_step
  • mobilePhrases.image_quality_guide.title
  • mobilePhrases.image_quality_guide.next_step

Changed strings

The English copy for the following string(s) has changed:

  • errors.invalid_capture

5.6.0 -> 5.7.0

With release 5.7.0 there are breaking changes that will affect integrators with customised languages or UI copy.

Added strings

  • capture.face.intro.title

  • capture.face.intro.subtitle

  • capture.face.intro.selfie_instruction

  • capture.face.intro.glasses_instruction

  • capture.face.intro.accessibility.selfie_capture_tips

  • continue

  • cross_device.intro.title

  • cross_device.intro.sub_title

  • cross_device.intro.description_li_1

  • cross_device.intro.description_li_2

  • cross_device.intro.description_li_3

  • cross_device.intro.action

  • cross_device.link.sms_sub_title

  • cross_device.link.copy_link_sub_title

  • cross_device.link.qr_code_sub_title

  • cross_device.link.options_divider_label

  • cross_device.link.sms_option

  • cross_device.link.copy_link_option

  • cross_device.link.qr_code_option

  • cross_device.link.qr_code.help_label

  • cross_device.link.qr_code.help_step_1

  • cross_device.link.qr_code.help_step_2

  • cross_device.link.copy_link.action

  • cross_device.link.copy_link.success

Removed strings

  • cross_device.intro.document.title

  • cross_device.intro.document.take_photos

  • cross_device.intro.document.action

  • cross_device.intro.face.title

  • cross_device.intro.face.take_photos

  • cross_device.intro.face.action

  • cross_device.link.sub_title

  • cross_device.link.link_copy.action

  • cross_device.link.link_copy.success

Changed strings

The English and Spanish copy for the following string(s) has changed:

  • cross_device.link.copy_link_label
  • cross_device.link.sms_label

5.0.0 -> 5.6.0

With release 5.6.0 there is a breaking change that will affect integrators with customised languages or UI copy.

Note: The string custom translation version scheme has changed, going forward if the strings translations change it will result in a MINOR version change, therefore you are responsible for testing your translated layout in case you are using custom translations or copy.

Added strings

  • capture.switch_device

Removed strings

  • cross_device.switch_device.submessage

Changed strings

The English and Spanish copy for the following string(s) has changed:

  • capture.upload_file
  • errors.invalid_size.message
  • errors.invalid_size.instruction

The English copy for the following string(s) has changed:

  • capture.driving_licence.front.title
  • capture.driving_licence.back.title
  • capture.national_identity_card.front.title
  • capture.national_identity_card.back.title
  • capture.passport.front.title
  • capture.bank_building_society_statement.front.title
  • capture.utility_bill.front.title
  • capture.benefit_letters.front.title
  • capture.council_tax.front.title
  • errors.invalid_type.message
  • errors.invalid_type.instruction

4.0.0 -> 5.0.0

We have changed the behaviour of the document step. If the document step is initialised with only one document type, the document selector screen will not be displayed. If your application relies on the document selector screen, even if you are picking only one document, you will have to implement that UI yourself.

3.1.0 -> 4.0.0

Import breaking changes

We have changed how the SDK is exported, in order to reduce redundant transpiled code and to better trim dead code too. This led to a size reduction overall.

However, this has potentially created a breaking change for those consuming the SDK with an ES style of import. Classic window style import and commonjs require should work the same.

Example of old behaviour

js
Copy
import Onfido from 'onfido-sdk-ui'

Onfido.init(...)

Example of new behaviour

js
Copy
import {init} from 'onfido-sdk-ui'
init(...)

or

js
Copy
import * as Onfido from 'onfido-sdk-ui'
Onfido.init(...)

Style Breaking change

  • We have internally changed the CSS units used in the SDK to be relative (em) units.

Therefore, if you previously set the font-size of .onfido-sdk-ui-Modal-inner, it is recommended that you remove this font-size override.

This is because we are looking to make the SDK compatible with em, but first we need to remove media queries which are not really compatible with that unit.

Example of old behaviour

css
Copy
.onfido-sdk-ui-Modal-inner {
  font-size: 20px;
}

Example of new behaviour

css
Copy
.a-more-specific-selector {
  font-size: 20px;
}

2.8.0 -> 3.0.0

Breaking changes

  • Removed support for buttonId. From this version you will need to create a function that launches the SDK when a trigger element (ie a button) is clicked.

Example of old behaviour

html
Copy
<script>
  Onfido.init({
    useModal: true,
    buttonId: 'onfido-btn',
    token: 'YOUR_JWT_TOKEN',
    onComplete: function (data) {
      // callback for when everything is complete
      console.log('everything is complete')
    },
  })
</script>

<body>
  <button id="onfido-btn">Verify identity</button>
  <div id="onfido-mount"></div>
</body>

Example of new behaviour

html
Copy
<script>
  var onfido = {}

  function triggerOnfido() {
    onfido = Onfido.init({
      useModal: true,
      isModalOpen: true,
      onModalRequestClose: function () {
        // Update options with the state of the modal
        onfido.setOptions({ isModalOpen: false })
      },
      token: 'YOUR_JWT_TOKEN',
      onComplete: function (data) {
        // callback for when everything is complete
        console.log('everything is complete')
      },
    })
  }
</script>

<body>
  <!-- Use a button to trigger the Onfido SDK  -->
  <button onClick="triggerOnfido()">Verify identity</button>
  <div id="onfido-mount"></div>
</body>

1.1.0 -> 2.0.0

Breaking changes

  • Removed onDocumentCapture that used to be fired when the document had been successfully captured, confirmed by the user and uploaded to the Onfido API
  • Removed onFaceCapture callbacks that used to be fired when the face has beed successfully captured, confirmed by the user and uploaded to the Onfido API.
  • Removed getCaptures function that used to return the document and face files captured during the flow.
  • Changed the behaviour of onComplete callback. It used to return an object that contained all captures, now it doesn't return any data.

Example of old behaviour

js
Copy
Onfido.init({
  token: 'YOUR_JWT_TOKEN',
  containerId: 'onfido-mount',
  onDocumentCapture: function (data) {
    /*callback for when the*/ console.log(
      'document has been captured successfully',
      data
    )
  },
  onFaceCapture: function (data) {
    /*callback for when the*/ console.log('face capture was successful', data)
  },
  onComplete: function (capturesHash) {
    console.log('everything is complete')
    // data returned by the onComplete callback including the document and face files captured during the flow
    console.log(capturesHash)
    // function that used to return the document and face files captured during the flow.
    console.log(Onfido.getCaptures())
  },
})

Example of new behaviour

js
Copy
Onfido.init({
  // the JWT token that you generated earlier on
  token: 'YOUR_JWT_TOKEN',
  // id of the element you want to mount the component on
  containerId: 'onfido-mount',
  onComplete: function () {
    console.log('everything is complete')
    // You can now trigger your backend to start a new check
  },
})