Onfido Smart Capture Web SDK

npm version

Overview

The Onfido Smart Capture SDKs provide a set of screens and functionality allowing applications to implement user identity verification flows. Each SDK contains:

  • Carefully designed UX to guide your customers through the different photo or video capture processes
  • Modular design to help you seamlessly integrate the different photo or video capture processes into your application's 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
  • A suite of advanced fraud detection signals to protect against malicious users

All Onfido Smart Capture SDKs are orchestrated using Onfido Studio workflows with only minor customization differences between the available platforms.

The Onfido Web SDK is specifically designed for integrating web applications and easily managing cross-device experiences.

Various views from the SDK

Environments and testing with the SDK

Two environments exist to support the Onfido SDK integrations:

  • 'sandbox' - to be used for testing with sample documents
  • 'live' - to be used only with real documents and in production apps

The environment being used is determined by the API token that is used to generate the necessary SDK token.

Going Live

Once you are satisfied 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 that you have entered correct billing details inside your Onfido Dashboard, before going live.

Importing the library & staying up-to-date

The Onfido Web SDK can be added to your project in two ways:

  • Directly in the web application in a script tag or as an import
  • As part of your project build as a library imported from NPM

To benefit from the latest features and patches released by Onfido and minimize the size of the script used, it is highly recommended to use an integration method that leverages the Onfido CDN, as detailed in the following sections.

Note that while Onfido hosts the CDN and ensures the script availability at runtime, any project using the SDK library from NPM would require its hosting.

Direct CDN integration

The quickest and simplest way to integrate the Onfido Web SDK is to use the Onfido-hosted library.

From SDK 12.3.1 onwards, the version number you subscribe to can vary, depending on your needs:

  • subscribing to a major release (e.g. v14) means Onfido will update to the latest available patch and minor release
  • subscribing to a minor level release (e.g. v14.11) means Onfido will update to the latest available patch release
  • subscribing to a specific patch release (e.g. v14.11.0) will fix the library files to that SDK release

Importing the SDK in an html script tag

html
Copy
<!-- Replace "<version>" with the actual SDK version you want to use, example: v14.11.0 -->
<script src="https://sdk.onfido.com/<version>" charset="utf-8"></script>

Note that prior to version 12.3.1, the CDN path was https://assets.onfido.com/web-sdk-releases/<version>/onfido.min.js.

Also note that from version 14 onwards, a separate stylesheet is no longer required as it will be included with the default library.

Importing the SDK with a JavaScript import directive

The library can also be invoked directly within an object or component:

JavaScript
Copy
// ES6 module import
import { init } from 'onfido-sdk-ui'

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

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.

Integrating with an NPM package

NPM is a public repository of libraries available for download and integration into web/native apps. Onfido has been publishing all its SDKs there for convenience to customers.

The Web SDK version 14 will continue with the existing package name:

Bash
Copy
npm install onfido-sdk-ui

or

Bash
Copy
yarn add onfido-sdk-ui

From version 14 onwards, the onfido-sdk-ui package will, by default, be connected to the Onfido CDN. In addition to the benefits of using a CDN and the library being directly in your build process, core functions will also be typed when used with Typesript.

Full bundles that consist of the full library will also be made available via NPM.

From version 14 onwards, "split bundles" are no longer supported. Onfido recommends the use of either the direct or NPM CDN integration.

NPM package version pinning

In order to facilitate integration and A/B tests, the CDN-powered NPM package will also optionally support the ability to specify a version (major, minor or patch) of the Onfido Web SDK library.

More details are provided in the SDK version pinning section below.

TypeScript

From version 6.5.0 onwards, TypeScript is officially supported, providing types 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)

Loading the Onfido flow

To load the Onfido flow, add an empty HTML element for the modal interface to mount itself on:

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

With the configuration in an accompanying script:

JavaScript
Copy
Onfido.init({
  token: '<YOUR_SDK_TOKEN>',
  containerId: 'onfido-mount',
  //containerEl: <div id="root" />, an ALTERNATIVE to `containerId`
  onComplete: function (data) {
    console.log('everything is complete')
  },
  workflowRunId: '<YOUR_WORKFLOW_RUN_ID>',
})

You can see an example integration of the Onfido Web SDK in our sample app.

You may also optionally specify a different container or identifier to load the Onfido flow:

  • containerId {String} - optional

    ID value of the container element that the UI will mount to. The element itself 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

    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.

Integrating in a webview

While webviews provide a lightweight integration and simplify cross-platform development, they have limitations in terms of accessing device features such as the camera, microphone, and local files as they rely on the webview engines provided by the operating system. As such webviews don’t offer the same level of performance and user experience as the functionality of the Onfido mobile SDKs in native apps.

Where possible, Onfido recommends using its native mobile SDKs for optimal performance.

Please refer to this guide for more details about how to integrate the Onfido Web SDK in a webview.

Initializing the SDK

The Web SDK has multiple initialization and customization options that provide flexibility to your integration, while remaining easy to integrate.

Note that from version 14, it will no longer be possible to change initialization options at runtime as was previously allowed with the setOption() function.

Defining a workflow

Onfido Studio is the platform used to create highly reusable identity verification workflows for use with the Onfido SDKs. For an introduction to working with workflows, please refer to our Getting Started guide, or the Onfido Studio product guide.

SDK sessions are orchestrated by a session-specific workflow_run_id, itself derived from a workflow_id, the unique identifier of a given workflow.

For details on how to generate a workflow_run_id, please refer to the POST /workflow_runs/ endpoint definition in the Onfido API reference.

Note that in the context of the SDK the workflow_run_id property is referred to as workflowRunId.

SDK authentication

The SDK is authenticated using SDK tokens. As each SDK token must be specific to a given applicant and session, a new token must be generated each time you initialize the Onfido Web SDK.

  • token {String} - required

    A JWT is required in order to authorize with the Onfido WebSocket endpoint. If the SDK token is missing, an exception will be thrown.

For details on how to generate SDK tokens, please refer to POST /sdk_token/ definition in the Onfido API reference.

SDK tokens have a fixed expiry of 90 minutes.

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

Version pinning

Based on the same major version, the minor and patch versions of the library can be specified in the Onfido.init() object.

  • version {String} - optional

    The specific version of the Onfido Web SDK that should be loaded as part of this initialization. A full version (e.g. v14.12.1) or just a minor version (e.g. v14.13) can be specified. When a minor version is specified, the latest patch version for that minor release will be loaded. Example: version: "14.12.1"

Note: This parameter is ineffective when the library is imported as a full bundle from NPM (as opposed to the default CDN-powered NPM package).

Styling customization

The Onfido Web SDK supports customization options to adjust the fonts, the SDK main container, buttons, links, icons, background color and popups.

To customize the SDK, you can pass the required CSS values to the customUI object, in the root of the Onfido.init() object.

  • customUI {Object} - optional

    Object containing optional CSS values for the supported UI customization options. The sample below lists all possible options with some example values.

JavaScript
Copy
{
  "customUI": {
      "borderRadiusButton": "56px",
      "borderStyleSurfaceModal": "0px",
      "fontWeightBody": 400,
      "fontSizeBody": "16px",
      "fontSizeSubtitle": "16px",
      "fontSizeTitle": "40px",
      "colorBackgroundSurfaceModal": "transparent",
      "colorBackgroundIcon": "transparent",
      "colorBorderLinkUnderline": "transparent",
      "colorBackgroundLinkActive": "transparent",
      "colorBackgroundLinkHover": "transparent",
      "colorBackgroundDocTypeButton": "transparent",
      "colorContentBody": "rgb(255,255,255)",
      "colorContentTitle": "rgb(255,255,255)",
      "colorContentSubtitle": "rgb(255,255,255)",

      "colorContentButtonPrimaryText": "rgb(10,11,13)",
      "colorBackgroundButtonPrimary": "rgb(55, 115, 245)",
      "colorBackgroundButtonPrimaryHover": "rgb(55, 115, 245)",
      "colorBackgroundButtonPrimaryActive": "rgb(55, 115, 245)",

      "colorContentButtonSecondaryText": "rgb(255,255,255)",
      "colorBackgroundButtonSecondary": "rgb(50,53,61)",
      "colorBackgroundButtonSecondaryHover": "rgb(30,32,37)",
      "colorBackgroundButtonSecondaryActive": "rgb(30,32,37)",
      "colorContentLinkTextHover": "rgb(55, 115, 245)",
      "colorBorderDocTypeButton": "rgb(20, 21, 25)",
      "colorBackgroundDocTypeButtonHover": "rgb(30,32,37)",
      "colorBackgroundDocTypeButtonActive": "rgb(30,32,37)",
      "colorContentDocTypeButton": "rgb(255,255,255)",
      "colorIcon": "rgb(55, 115, 245)",
      "colorContentInfoPill": "rgb(10,11,13)",
      "colorBackgroundInfoPill": "rgb(55, 115, 245)",
      "colorBackgroundSelector": "red",
      "colorInputOutline": "rgb(87, 139, 250)",
      "colorContentButtonTertiaryText": "rgb(255,255,255)",
      "colorContentInput": "blue",
      "colorBackgroundInput": "green",
      "colorBorderInput": "yellow"
  }
}

For use in a webview on a mobile device, it is recommended to set up the SDK to use the full screen of the device. Otherwise, there may not be enough room to display all critical elements of the SDK.

Note that from version 14, the Onfido SDK options to load the screens in a modal have been deprecated. If you wish to load the Onfido screens in a modal you will have to define it as part of your own integration.

Co-branding

The Onfido SDK allows for two co-branding options that affect the display of the Onfido logo at the bottom of the Onfido screens.

For further customization, please contact your Onfido Solution Engineer or Customer Success Manager.

Text co-branding

  • cobrand {Object} - optional

    The most effective way to add your brand to the footer watermark, is by use of the cobrand property under enterpriseFeatures. This property takes a text parameter.

    Example of text cobranding

JavaScript
Copy
Onfido.init({
  ...
  enterpriseFeatures: {
    cobrand: {
      text: "Onboarding, Inc."
    }
  },
})

Logo co-branding

  • logoCobrand {Object} - optional

    As an alternative to cobrand, you may specify a set of images to be defined in the logoCobrand property under enterpriseFeatures. You must provide the path to an image for use in 'dark' mode and a separate image for 'light' mode. Both images must have a resolution of 144x32.

JavaScript
Copy
Onfido.init({
  ...
  enterpriseFeatures: {
    logoCobrand: {
        darkLogoSrc: "https://YourLogoImageUrlOrFilePath",
        lightLogoSrc: "https://YourLogoImageUrlOrFilePath",
    }
  },
})

Language selection

The Onfido SDK supports and maintains translations for over 40 languages in its SDKs.

  • language {String || Object} - optional

    You can customize the language displayed on the SDK by passing a string or object. If language is not present at the root of the Onfido.init() call, the SDK will use the browser's language setting. If the browser's language is not supported by Onfido, the SDK will default to English (en_US).

JavaScript
Copy
language: 'pt_BR' | 'es'

For the list of languages supported by Onfido, please refer to our SDK customization guide.

Language customization

In addition to selecting default languages for the SDK session, the SDK can also be displayed in a custom language for locales that Onfido does not currently support or for the addition of custom text, specific to your integration needs. This can be achieved by setting the following options in the language object:

OptionDescriptionNotes
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 currently only supports English, Spanish, French and German.
phrasesrequired
An object containing the keys you want to override and the new values.
Keys can be passed as a nested object or as a string using the dot notation for nested values. Refer to the next section for instructions on how to find the right keys.
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. Note: support for standalone mobilePhrases key will be deprecated soon. Consider nesting it inside phrases if applicable.
JavaScript
Copy
language: {
  locale: 'en_US',
  phrases: {
    'capture.driving_licence.instructions': 'This custom string will appear by default'
  },
  mobilePhrases: {
    'capture.driving_licence.instructions': 'This custom string will only appear on mobile'
  }
}

Identifying text keys in the Onfido screens

In order to identify text that can be overridden and locate their exact keys, you should use a browser inspector and indentify div blocks with the attribute name data-i18n-token.

Example of how to use an html inspector to find a text key

Cross-device navigation

The Web SDK offers a cross-device flow where desktop users are directed to continue on their mobile device browser to complete the capture process. This provides a vastly improved image quality versus a typical desktop webcam and increases the likelihood of successful live capture.

Force cross-device flow

Three options are offered to the user to resume the flow on a mobile device browser:

  • QR code that can be scanned with a camera app (default)
  • 'Copy Link' feature that can be copy/pasted into a web browser
  • One-time SMS link that can be sent diretly to the user's mobile phone

Regardless of the cross-device method, the secure URL is unique to this session.

At the end of the capture process, users will be instructed to revert back to their desktop to complete the SDK flow.

Note that during a capture sequence on a desktop device, if a camera cannot be detected, the user is forward by default to the cross-device flow in order to attempt the capture on another device.

Enforcing cross-device navigation

In order to optimize the capture quality, it is recommended to enforce the cross-device flow. The option is available in Onfido Studio, configurable in the workflow builder.

Cross-device can also be enforced at run-time using the following initialization option:

  • crossDevicePolicy {String} - optional

    By default, the cross-device flow is not enforced but shown to the user alongside a button to upload a document instead. You can force the user to capture a document or face on a mobile device by either:

  • setting the option globally (across all workflow runs) in the workflow builder

  • setting the crossDevicePolicy initialization option at runtime to either force or disable to completely remove the option

    JavaScript
    Copy
    crossDevicePolicy: 'force'
    

Customizing the cross-device experience

In addition to forcing the cross-device flow, the cross-device experience can be further customized during the SDK initialization with the following options:

  • _crossDeviceLinkMethods {List<String>} - optional

    You can specify which of the three cross-device link options are presented to the user by adding any of qr_code, copy_link and/or sms to the _crossDeviceLinkMethods using a , as a separator. The first element of the list will be the default option shown to the user. Note the underscore at the start of the string.

    JavaScript
    Copy
    _crossDeviceLinkMethods: ['qr_code', 'copy_link', 'sms']
    
  • smsNumberCountryCode {String} - optional

    You can change the default country for the SMS number input by passing the smsNumberCountryCode option at the root of the Onfido.init() call 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 can be added to the optional userDetails object at the root of the Onfido.init() call. The value should be a string containing the mobile number with a country code.
    JavaScript
    Copy
    userDetails: {
      smsNumber: '+447500123456'
    }
    
  • 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. The image referenced in the path should be no more than 144px in both height and width.

    JavaScript
    Copy
    Onfido.init({
      ...
        crossDeviceClientIntroProductLogoSrc: "path://to/logo/image/file",
    });
    

Note that from version 14, the crossDeviceClientIntroProductName option used in previous versions to modify just the customer name in the cross-device intro screen has been deprecated. Instead, you should use the standard language customization process to override the subtitle of the screen.

Completing a session

Handling callbacks

When the Onfido SDK session will conclude, one of two callback functions may be triggered:

  • onComplete: the session was successful with at least 1 document captured
  • onError: the session terminated unexpectedly

For advanced callbacks used for user analytics and returning submitted media, please refer to the Advanced Callbacks section of this document.

onComplete {Function} - optional

Callback that fires when the flow has successfully been executed with at least 1 document capture.

JavaScript
Copy
Onfido.init({
    token: "<YOUR_SDK_TOKEN>",
    ...
    onComplete: function (data) {
        console.log("everything is complete");
    },
});

The data object contains properties of the documents and face images uploaded by the user during the SDK session. The properties contain a unique identifier that can be used to retrieve the full document or face capture using the corresponding document, live_photos (for 'standard' selfies) or live_videos (for 'video' or 'motion' captures) endpoints defined in the API reference.

JSON
Copy
{
  "document_front": {
    "id": "<DOCUMENT_ID_FRONT>",
    "type": "driving_licence",
    "side": "front"
  },
  "document_back": {
    "id": "<DOCUMENT_ID_BACK>",
    "type": "driving_licence",
    "side": "back"
  },
  "face": {
    "id": "<FACE_ID>",
    "variant": "standard"
  },
  "poa": {
    "id": "<POA_DOCUMENT_ID>",
    "type": "utility_bill"
  }
}

For two-sided documents such as 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' | 'motion'.

onError {Function} - optional

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

  • invalid_token This error will be returned when the SDK token is invalid or missing.

    JavaScript
    Copy
    {
      type: "invalid_token",
      message: "The token is invalid."
    }
    
  • 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"
    }
    
  • expired_trial This error will be returned when the trial has expired.

    JavaScript
    Copy
    {
      type: "expired_trial",
      message: "The trial period is expired."
    }
    
  • geoblocked_request This error will be returned when the request is geo-blocked.

    JavaScript
    Copy
    {
      type: "geoblocked_request",
      message: "The request is not allowed from this location."
    }
    
  • permissions_unavailable This error will be returned if the SDK was unable to access or request the necessary permissions. This may occur when the Web SDK is loaded within a webview or other custom browsers.

    JavaScript
    Copy
    {
      type: "permissions_unavailable",
      message: "Unable to retrieve or access required user permissions"
    }
    
  • unsupported This error will be returned when the a module is not supported in the current environment.

    JavaScript
    Copy
    {
      type: "unsupported",
      message: "The module is not supported in the current environment."
    }
    
  • unsupported_feature This error will be returned when a feature is not supported.

    JavaScript
    Copy
    {
      type: "unsupported_feature",
      message: "The feature is no longer supported."
    }
    
  • invalid_sdk_parameter This error will be returned when the SDK is initialized with invalid parameters.

    JavaScript
    Copy
    {
      type: "invalid_sdk_parameter",
      message: "The SDK is initialized with invalid parameters."
    }
    
  • unsupported_sdk_version This error will be returned when the workflow is not supported by the SDK version.

    JavaScript
    Copy
    {
      type: "unsupported_sdk_version",
      message: "The SDK version is not compatible with the workflow."
    }
    
  • no_camera This error will be returned when the camera is not available and no other capture method is available.

    JavaScript
    Copy
    {
      type: "no_camera",
      message: "The camera is not available."
    }
    
  • user_consent_denied This error will be returned when the user exits the flow because they declined the consent.

    JavaScript
    Copy
    {
      type: "user_consent_denied",
      message: "The user has declined the consent."
    }
    
  • exception This will be returned for all unknown errors, including:

    • timeout and server errors
    • unexpected javascript errors

    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"
      exception: Error
    }
    

Note that from version 14 onwards, the optional onUserExit callback, that was used to return the USER_CONSENT_DENIED message, has been deprecated and merged with the onError callback, as detailed above.

SDK tear-down

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({...})
...
await onfidoOut.tearDown()

Warning: The tearDown method is a Promise. If you plan on mounting the SDK a second (or nth) time, please await the promise first.

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

Generating verification reports

While the SDK is responsible for capturing and uploading the user's media and data, identity verification reports themselves are generated based on workflows created using Onfido Studio.

For a step-by-step walkthrough of creating an identity verification using Onfido Studio and our SDKs, please refer to our Quick Start Guide.

If your application initializes the Onfido Web SDK using the options defined in the Advanced customization section of this document, you may create checks and retrieve report results manually using the Onfido API. You may also configure webhooks to be notified asynchronously when the report results have been generated.

Advanced flow customization

This section on 'Advanced customization' refers to the process of initializing the Onfido Web SDK without the use of Onfido Studio. This process requires a manual definition of the verification steps and their configuration. The steps parameter is mutually exclusive with workflowRunId. The other parameters under Onfido.init() remain the same.

Note that this initialization process is not recommended as the majority of new features are exclusively released for Studio workflows.

  • steps {List<String>} - optional

    The list of user verification steps, in order of appearance. Each step can either be specified as a string (when no customization is required) or an object (when customization is required). Customization options are described in the following sections.

From the possible steps listed below, only document is required:

StepDescription
welcomeWelcome screen shown to the user with preliminary instructions. Customization options include modification to the text elements and instructions shown to the user.
documentSet of screens that control the capture via photo or upload of the user's document. Numerous customization options are available to define the document list presented to the user and the overall capture experience.
faceSet of screens that control the capture of a selfie, video or motion of the user. The customization options allow the selection of the capture variant as well as fallback options.
completeScreen shown to the user at the end of the flow. Customization options include modifications to the text elements shown to the user.
JavaScript
Copy
Onfido.init({
  token: "<YOUR_SDK_TOKEN>",
  ...
  steps:  [
    {
      type: "welcome",
      options: {
        title: "Open your new bank account",
      },
    },
    "document",
    "face",
  ];
});

welcome step

This step is the introduction screen of the SDK. It introduces the process and prepares the user for the steps they will need to complete. These steps can be specified to match the flow required.

While this screen is optional, we only recommend its removal if you already have your own identity verification welcome screen in place.

The custom options are:

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

document step

The Document Capture step is typically organised in three parts:

  • The issuing country and document type selection
  • The camera capture
  • The document review and upload

Note that the document step is mandatory.

The customization options available all relate to the country and document type selection screen. By default, the selection screen is shown with the country selection being empty.

Choose documents type The above images are for web SDK versions 8.3.0+

Depending on the customization options defined in this step or the 'allowed countries' defined in your Dashboard, either the country or document type selection screens might not be shown:

  • The country selection screen will not be shown if only 1 country is selected or if only passports are allowed
  • The document selection screen will not be shown if only 1 document type is specified

You can specify allowed issuing countries and document types for the document capture step in one of three ways:

  • Onfido Studio: If you are using Onfido Studio, this is configured within the Document Capture task, as documented in the Studio Product Guide

  • Dashboard : Otherwise, the recommended approach is to apply this configuration globally in the Dashboard under Accounts \ Supported Documents. This option also ensures that the list is enforced as part of the Document Report validation. Any document that has been uploaded by an end user against your guidance will result in a Document Report sub-result of "rejected" and be flagged as Image Integrity > Supported Document.

    The Supported Documents tab in Dashboard

  • Run-time: For run-time configuration, the following options can be defined under the document step:

    • documentTypes {Object} - required

      The list of document types visible to the user can be filtered by using the documentTypes option. When documentTypes is not defined, the default value for each document type is true. When documentTypes is defined, it will override the default values. Absent types are considered false.

    • country {String} - optional

      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 documentTypes only includes one document type with a country value, users will not see the document selection screen and instead will be taken directly to the capture screen.

      ⚠️ Note: the null value is deprecated and has no effect.

      ⚠️ Note: Passports have the same format worldwide so the SDK will not show the country selection screen even if they are not restricted by country (e.g. passport: true).

    • hideCountrySelection {Boolean} - optional

      It is possible to completely remove the country selection screen, showing instead the list of all possible document types directly to the user by setting hideCountrySelection to true. This is not recommended as it will prevent document-specific optimization of the flow and detailed analytics.

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

In the example above only Spanish (ESP) driving licences, and national identity cards and residence permits for all countries will be shown

Please note:

  • Hard coding any document type and issuing country configuration in your SDK integration will fully override the Dashboard-based settings
  • Currently, only passport, national ID card, driving licence and residence permit are visible for document selection by the end user in the SDK. If you nominate other document types in your Dashboard (visa, for example), these will not be displayed in the user interface
  • If you need to add other document types to the document selection screen, you can mitigate this limitation in the near-term, using the Custom Document feature
  • If for any reason the configuration fails or is not enabled, the SDK will fallback to displaying the selection screen for the complete list of documents supported within the selection screens
Custom Documents

In case you require to capture a document that is not supported by Onfido or a supported document with a different name or scope (e.g. capturing the back of a two-sided document, even if it is not required for verification purposes), custom documents can be manually defined.

Note that if recognized, Onfido will still attempt to process them based on their detected classification.

  • genericDocumentTypes {Object} - optional

    If defined under the document step options, the custom document will be displayed at the bottom of the standard document types list after any other document types applicable to the other optional country / document type selection options defined in the previous sections.

    JavaScript
    Copy
    genericDocumentTypes:  [
      {
        id: 'my_single_side_document',
        title: 'My single side document',
        subTitle: 'Details about my document',
        country: 'ALB',
        pages: 1,
      },
      {
        id: 'my_two_sides_document',
        title: 'My two sides document',
        subTitle: 'Details about my document',
        country: 'ALB',
        pages: 2,
      },
    ]
    

    In the same way to other document types, if you wish to skip the document selection screen, you can add a single generic_document object which references the custom document declared in genericDocumentTypes.

    JavaScript
    Copy
    documentTypes: {
      generic_document: {
        id: 'my_single_side_document',
      }
    }
    

face step

This is the face capture step. Users will be asked to capture their face in the form of a photo, a video, or a motion capture. For photos and videos, they will also have a chance to check its quality before confirming.

Note that if a camera can’t be detected, the user will be forwarded to the cross-device flow in order to attempt to capture on another device. The cross-device flow will be presented to the user, before any optional fallback variants are assessed by the Web SDK.

face flow options
  • requestedVariant {String} - optional

    A preferred variant can be requested for this step, by passing the option requestedVariant: 'standard' | 'video' | 'motion', with the default version being standard. If requestedVariant is:

    • standard: a photo will be captured
    • video: a video will be captured
    • motion: a motion capture will be captured
    JSON
    Copy
    {
      "steps": [
        "welcome",
        "document",
        {
          "type": "face",
          "options": {
            "requestedVariant": "motion"
          }
        },
        "complete"
      ]
    }
    
  • showIntro {Boolean} - optional

    The instruction screen shown to the user at the beginning of the face capture step can be skipped for the video and standard variants. By default, the screen is shown (default to true). When disabled for the standard variant, the entire intro screen will be removed from the flow. When disabled for the video variant, the example video will be hidden in the intro screen, only showing the text instructions.

  • useMultipleSelfieCapture {Boolean} - optional

    This option only applies to the variant standard. By default the SDK will take additional selfie snapshots to help improve face similarity check accuracy. When disabled, only one selfie photo will be taken.

  • recordMotionAudio {Boolean} - optional

    This option only applies to the variant motion and enables the recording of the user's background audio. By default this is option is set to false.

face fallback options

The SDK will try to fulfil the request depending on camera availability, device capabilities and browser support on the user's device:

  • if the selected variant cannot be fulfilled and the user is on a desktop, the user will first be forwarded to the cross-device screen. This default step is introduced with version 14 of the Web SDK.
  • if a video cannot be taken on the mobile device, the face step can be configured to fallback to the standard variant (see photoCaptureFallback)
  • if Motion cannot be captured on the mobile device, the face step can be configured to fallback to either video or standard variants (see motionFallbackVariant)

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.

  • photoCaptureFallback {Boolean} - optional

    This feature only applies to the video variant. By default, this option is true and allows end-users to capture a selfie if their mobile browser does not support MediaRecorder (which is required by the other variants). When disabled, we will return an unsupported browser error if the end-user browser doesn’t support MediaRecorder.

  • motionFallbackVariant {String} - optional

    This feature only applies to the motion variant and allows to specify which face capture variant users will fallback to if Motion is not available on the end-user's mobile device due to MediaRecorder not being supported or to limited device capabilities.

    By default, no variant is specified which will result in users on unsupported devices receiving an unsupported browser error.

    The following example shows how to configure motionFallbackVariant to allow users on unsupported devices to fallback to Selfie:

    JavaScript
    Copy
    options: {
      requestedVariant: 'motion',
      motionFallbackVariant: 'standard'
    }
    

    The following example shows how to configure motionFallbackVariant to allow users on unsupported devices to fallback to Video:

    JavaScript
    Copy
    options: {
      requestedVariant: 'motion',
      motionFallbackVariant: 'video'
    }
    

complete step

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)

Advanced callbacks

The following 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.

Custom media callbacks

Custom media callbacks enable you to control the data collected by the Onfido SDK by using callbacks that are invoked when the end user submits their captured media. The callbacks provide all of the information that would normally be sent directly to the Onfido API and expect a promise in response, that controls what the SDK does next.

Once custom media callbacks are enabled for your account, you will need to add the optional enterpriseFeatures object at the root of Onfido.init(), set useCustomizedApiRequests to true and define the callbacks for onSubmitDocument, onSubmitVideo, onSubmitSelfie.

JavaScript
Copy
Onfido.init({
  ...
  enterpriseFeatures: {
    useCustomizedApiRequests: true,
    onSubmitDocument: (documentData) => {
      // Your callback code here
    },
    onSubmitSelfie: (selfieData) => {
      // Your callback code here
    },
    onSubmitVideo: (videoData) => {
      // Your callback code here
    },
  },
})

The callbacks return a FormData object, including the information that the SDK would send to Onfido. The callbacks are invoked when the end user confirms their image through the user interface.

Note that the data can also be returned in json format by adding the property formatter: 'raw' under the enterpriseFeatures object.

onSubmitDocument data parameter
JavaScript
Copy
{
  file: blob,
  side: string,
  type: string,
  sdk_validations: object,
  sdk_source: string,
  sdk_version: string,
  sdk_metadata: object,
}
onSubmitSelfie data parameter
JavaScript
Copy
{
  file: blob,
  snapshot: blob,
  sdk_source: string,
  sdk_version: string,
  sdk_metadata: object,
}

onSubmitVideo data parameter
JavaScript
Copy
{
  file: blob,
  challenge:  { type: 'recite' / 'movement', query: number[] / string }
  challenge_id: string,
  challenge_switch_at: number, // seconds
  languages: { source: 'sdk', language_code: string }
  sdk_source: string,
  sdk_version: string,
  sdk_metadata: object,
}

Uploading the media files to Onfido

By default, this feature will prevent the request from being sent to Onfido, requiring you to manually upload the media files to Onfido from your backend for further processing. We strongly recommend that you add all of the data provided to you through the callbacks in your request to the appropriate endpoint - /documents or /live_photos. Additionally, you should use the SDK token created for each applicant in the Authorization header of the request as shown below.

Note that the SDK token is not included in the FormData provided by the callbacks. You may want to append this, or a different unique identifier that is mapped to the applicant's SDK token, on your backend before sending it off.

Copy
Authorization: Bearer <SDK token here>

If you wish for the SDK to also upload the user-submitted data directly to Onfido you can resolve the promise with an object containing continueWithOnfidoSubmission: true.

JavaScript
Copy
  onSubmitDocument: (data) => {
    // Your callback code here
    ...
    // Once your code has executed, resolve the promise
    return Promise.resolve({ continueWithOnfidoSubmission: true })
  }

Managing the Onfido response

Once you have sent the request to Onfido yourself, you can supply the SDK with the response so it can determine what the end user should be presented with. In the case where a success response is received, the promise should be resolved with onfidoSuccessResponse: <onfidoResponse>. Otherwise reject the promise with the Onfido error response. Note: An error response could be returned due to image quality issues. In this case, the SDK will present the end user with the appropriate error message.

JavaScript
Copy
  onSubmitDocument: (data) => {
    // Send request to Onfido API /documents via your backend proxy
    .then(onfidoSuccessResponse =>
      Promise.resolve({ onfidoSuccessResponse: <onfidoResponse> }))
    .catch(onfidoError => Promise.reject(onfidoError))
  }

This is a sample openAPI YAML file you could use as an example to start your own proxy.

yaml
Copy
openapi: 3.0.0
info:
  title: Network decouple back-end sample
  description: Network decouple back-end setup skeleton
  version: '1.0'
  contact: {}
tags: []
servers: []
components:
  schemas:
    IDocumentsRequest:
      type: object
      properties:
        file:
          type: string
          format: binary
          description: Uploaded document. Passed in from the web SDK callback.
        type:
          type: string
          default: passport
          description: >-
            The type of document that was submitted. Passed in from the web SDK
            callback.
        side:
          type: string
          default: front
          description: >-
            The type side of the document that was submitted. Passed in from the
            web SDK callback.
        sdk_metadata:
          type: object
          description: >-
            The metadata that web SDK collects. Forward this to Onfido API
            without modifications. Passed in from the web SDK callback.
        sdk_validations:
          type: object
          description: >-
            This is a an object used by web SDK to seek image quality feedback
            from the API. Forward this object without modifications to Onfido
            API. Passed in from the web SDK callback.
        sdk_source:
          type: string
          default: onfido_web_sdk
          description: >-
            The source of origin of the requests. Forward this without
            modifications to the Onfido API. Passed in from the web SDK callback.
        sdk_version:
          type: string
          description: >-
            The SDK version. Forward this without modifications to the Onfido
            API. Passed in from the web SDK callback.
    IMultiFrameSelfieRequest:
      type: object
      properties:
        file:
          type: string
          format: binary
          description: Uploaded photo
        sdk_metadata:
          type: object
          description: >-
            The metadata that web SDK collects. Forward this to Onfido API
            without modifications. Passed in from the web SDK callback.
        sdk_source:
          type: string
          default: onfido_web_sdk
          description: >-
            The source of origin of the requests. Forward this without
            modifications to the Onfido API. Passed in from the web SDK callback.
        sdk_version:
          type: string
          description: >-
            The SDK version. Forward this without modifications to the Onfido
            API. Passed in from the web SDK callback.
        snapshot:
          type: string
          format: binary
          description: Uploaded snapshot taken by the Web SDK to improve fraud analysis.
paths:
  /onfido/v3.3/documents:
    post:
      operationId: OnfidoController documents
      parameters:
        - name: Authorization
          in: header
          description: Customer back-end Authentication token
          schema:
            type: string
      requestBody:
        required: true
        description: The API endpoint to intercept the document upload from the Web SDK
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/IDocumentsRequest'
      responses:
        '200':
          description: >-
            The response received from Onfido v3.3/documents API call. The
            response format might slightly vary with the use case. Forward it
            without modifications as the callback response.
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                    format: uuid
                  created_at:
                    type: string
                    format: date-time
                  file_name:
                    type: string
                  file_size:
                    type: integer
                  file_type:
                    type: string
                  type:
                    type: string
                  side:
                    type: string
                  issuing_country:
                    type: string
                  applicant_id:
                    type: string
                  href:
                    type: string
                  download_href:
                    type: string
                  sdk_warnings:
                    type: object
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
        '422':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                  fields:
                    type: object
  /onfido/v3/live_photos:
    post:
      operationId: OnfidoController
      parameters:
        - name: Authorization
          in: header
          description: Customer back-end Authentication token
          schema:
            type: string
      requestBody:
        required: true
        description: The API endpoint to intercept the live photos upload from the Web SDK
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/IMultiFrameSelfieRequest'
      responses:
        '200':
          description: >-
            The response received from Onfido v3/live_photos API call. The
            response format might slightly vary with the use case. Forward it
            without modifications as the callback response.
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                    format: uuid
                  created_at:
                    type: string
                    format: date-time
                  file_name:
                    type: string
                  file_type:
                    type: string
                  file_size:
                    type: integer
                  href:
                    type: string
                  sdk_source:
                    type: string
                  sdk_version:
                    type: string
                  download_href:
                    type: string
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object

Custom media callbacks in cross-device flows

In the context of cross-device flows, you may choose to enable the media callbacks in either the desktop session or the mobile session.

A prerequisite is that you host the cross-device experience of the Onfido SDK yourself, as described in the self-hosted cross-device URL section of this document.

Enable custom media callbacks in mobile session

Once you have a server with the Onfido Web SDK installed and set up, you must initialize the mobile session with mobileFlow: true in addition to the callbacks and useCustomizedApiRequests options shown above.

JavaScript
Copy
Onfido.init({
  ...
  enterpriseFeatures: {
    useCustomizedApiRequests: true,
    mobileFlow: true,
    onSubmitDocument: (documentData) => {
      // Your callback code here
    },
    onSubmitSelfie: (selfieData) => {
      // Your callback code here
    },
    onSubmitVideo: (videoData) => {
      // Your callback code here
    },
  },
})
Enable custom media callbacks in desktop session

Media callbacks can also be triggered in the desktop session instead of the mobile session. To do so, please contact your Onfido Solution Engineer or Customer Success Manager as additional configuration is required.

User analytics callbacks

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.

The code inside of the EventListener callback will be invoked when an event is triggered.

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

The event parameter being passed in the callback contains the following information:

  • eventName {String}: Name of the event triggered (full list below)
  • properties {Object}: Event-specific properties
  • isCrossDevice {Boolean}: Set to true when the event originates from a mobile session
eventName
WELCOME
USER_CONSENT
DOCUMENT_TYPE_SELECT
ID_DOCUMENT_COUNTRY_SELECT
CROSS_DEVICE_INTRO
CROSS_DEVICE_GET_LINK
CROSS_DEVICE_START
DOCUMENT_CAPTURE_FRONT
DOCUMENT_CAPTURE_BACK
DOCUMENT_CAPTURE_CONFIRMATION_FRONT
DOCUMENT_CAPTURE_CONFIRMATION_BACK
FACIAL_INTRO
FACIAL_CAPTURE
FACIAL_CAPTURE_CONFIRMATION
VIDEO_FACIAL_INTRO
VIDEO_FACIAL_CAPTURE_STEP_1
VIDEO_FACIAL_CAPTURE_STEP_2
MOTION_FACIAL_INTRO
MOTION_FACIAL_ALIGNMENT
MOTION_FACIAL_CAPTURE
MOTION_FACIAL_NO_FACE_DETECTED
MOTION_FACIAL_CAPTURE_ERROR_TIMEOUT
MOTION_FACIAL_CAPTURE_ERROR_TOO_FAST
MOTION_FACIAL_UPLOAD
MOTION_FACIAL_UPLOAD_COMPLETED
MOTION_FACIAL_CONNECTION_ERROR
UPLOAD

Self-hosted cross-device URL

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

This feature allows you to specify your own custom or whitelabel url that the cross-device flow will redirect to instead of the Onfido default id.onfido.com. To use this feature, generate an SDK token as shown below and use it to start the SDK.

Bash
Copy
  $ curl https://api.onfido.com/v3/sdk_token \
  -H 'Authorization: Token token=YOUR_API_TOKEN' \
  -F 'applicant_id=YOUR_APPLICANT_ID' \
  -F 'referrer=REFERRER_PATTERN' \
  -F 'cross_device_url=YOUR_CUSTOM_URL'

In addition to this, you must either:

  • Set up a server to forward the incoming HTTP request, including the path, to https://id.onfido.com

  • Set up a server to host the Onfido Web SDK yourself at the provided URL

Set up a server to forward the incoming HTTP request, including the path, to https://id.onfido.com

You can do this by setting up a server as a reverse proxy so that the URL that the end-user sees is your selected URL but the content shown is the Onfido-hosted Web SDK. An example set-up for a minimal nginx server using docker:

nginx.conf

nginx
Copy
server {
  # Change the next 2 lines as needed
  listen       80;
  server_name  localhost;

  location / {
    # This forwards the path to Onfido and is the only change
    # necessary when working with the default nginx configuration
    proxy_pass https://id.onfido.com;
  }
}

dockerfile

docker
Copy
FROM nginx:1.15.8-alpine

COPY ./nginx.conf /etc/nginx/conf.d/default.conf

Set up a server to host the Onfido Web SDK yourself at the provided URL

This server must use the same version of the Onfido Web SDK and must initialize the SDK with Onfido.init({ mobileFlow: true }). All other configuration options, except for callbacks provided for the useCustomizedApiRequests feature, will be provided by your original instance of the Onfido Web SDK.

This is an example of how you could host the Onfido Web SDK with minimal setup. This example involves using docker and an nginx image to serve an html file which starts the Onfido Web SDK using just the js and css files from the Onfido CDN (https://sdk.onfido.com/<version>).

File structure for this minimal example:

text
Copy
- dockerfile
- nginx.conf
- index.html

dockerfile

docker
Copy
FROM nginx:1.15.8-alpine

COPY ./nginx.conf /etc/nginx/conf.d/default.conf

COPY ./index.html /usr/share/nginx/html/

COPY ./dist /usr/share/nginx/sdk/

nginx.conf

nginx
Copy
server {
  # Change the next 2 lines as needed
  listen       80;
  server_name  localhost;

  location ~ ^/ [0-9a-zA-Z]+$ {
    root   /usr/share/nginx/html;
    try_files $uri /index.html =404;
  }

  location ~* \.(js|jpg|png|css)$ {
    root /usr/share/nginx/sdk/;
  }
}

index.html

html
Copy
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta
      charset="utf-8"
      name="viewport"
      content="width=device-width, initial-scale=1"
    />
    <meta name="mobile-web-app-capable" content="yes" />
    <meta name="apple-mobile-web-app-capable" content="yes" />
    <meta name="format-detection" content="telephone=no" />
    <title>Onfido Verification</title>
    <style type="text/css">
      html,
      body {
        height: 100%;
        margin: 0;
      }
      body,
      button {
        -webkit-font-smoothing: antialiased;
      }
      @media (min-width: 30em) {
        #onfido-mount {
          position: relative;
          top: 10%;
        }
        .onfido-sdk-ui-Modal-inner {
          font-family: 'Open Sans', sans-serif !important;
        }
      }
    </style>
    <script type="text/javascript">
      // commonjs style require
      var Onfido = require('onfido-sdk-ui')

      var version = window.location.pathname.substring(1, 3)

      var script = document.createElement('script')
      script.onload = function () {
        window.onfidoOut = Onfido.init({ mobileFlow: true })
      }
      document.head.appendChild(script)
    </script>
  </head>

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

More information

Supported browsers

ChromeFirefoxEdgeSafari
Latest ✔Latest ✔Latest ✔Latest ✔

Node.js supported versions

The SDK is compatible with the all supported Node.js versions (currently starting with Node.js 16).

Accessibility

The Onfido SDK has been optimized 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.

Troubleshooting

General Content Security Policy (CSP) 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 https://sdk.onfido.com;
  script-src 'self' 'unsafe-eval' https://assets.onfido.com https://sentry.io https://*.sardine.ai/;
  style-src 'self' 'unsafe-inline' https://assets.onfido.com https://sdk.onfido.com;
  font-src 'self' https://sdk.onfido.com;
  connect-src 'self' data: blob: *.onfido.com wss://*.onfido.com https://sentry.io;
  img-src 'self' data: blob: https://assets.onfido.com/ https://sdk.onfido.com;
  media-src blob: https://assets.onfido.com https://sdk.onfido.com;
  worker-src 'self' blob:;
  object-src 'self' blob:;
  frame-src 'self' data: blob: https://*.sardine.ai/;
"
/>

unsafe-eval and Content Security Policy (CSP)

Customers that have a CSP use the Web SDK npm bundle may not be able to run WebAssembly code without the unsafe-eval policy. Unfortunately, unsafe-eval is dangerous and security teams generally advise against it. Onfido uses WebAssembly in the Motion (for TensorFlow) and Document Capture (for OpenCV) modules, which prevents them from being used in that context. The recommended approach is to using an Onfido-hosted Web SDK (Smart Capture Link or CDN) as the CSP only applies to the sdk.onfido.com domain and not the customer’s domain, whereby the CSP and therefore unsafe-eval is handled by Onfido.

Iframe camera and microphone permission issues

If embedded inside a cross-origin iframe, the SDK may fail to access the camera and microphone. This is a known issue on recent Chrome versions where requests fail in a similar way as if a user had denied a permission prompt. You may need to add the following allow attribute to your iframe:

html
Copy
<iframe src="..." allow="camera;microphone"></iframe>

Upload fallback

Onfido Web SDK versions <13.0.0 have a parameter named uploadFallback that can be set on both the document step and the face step. This parameter allowed clients to present end-users with a file input capability during the SDK flow. This client-side optional parameter has been removed in Web SDK 13 and above to enhance security which means users will not have the option to upload files during the SDK flow. However, file upload can be enabled as an option for end-users as a backend configuration if requested through the Onfido Support Team.

Permissions issues when using the Web SDK in a webview

For recommendations and code samples on how to embed the Onfido Web SDK in a webview, please refer to the guide Using the Onfido web SDK in a webview.

Support

Should you encounter any technical issues during integration, please contact Onfido's Customer Support team via email, including the word ISSUE: at the start of the subject line.

Alternatively, you can search the support documentation available via the customer experience portal, public.support.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).

Licence Information

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.

[14.15.0]

Changed

13.6.0 - 2023-10-24

Changed

  • Document capture: Add integrator events 'DOCUMENT_CAPTURE_FRONT' and 'DOCUMENT_CAPTURE_BACK' for the Javascript camera.
  • Document country selection: Automatically close the keyboard after country is selected
  • Add support a selection of Google fonts

13.5.1 - 2023-10-12

Fixed

  • Fixed duplicated back button on Motion loading screen

13.5.0 - 2023-10-06

Changed

  • Add new showIntro configuration for the Standard and Video capture steps
  • New permission screen instructions were added to guide users on various devices/browsers to recover from denied access to the camera.

Fixed

  • A click on the search icon in the Country Selector will focus the input field
  • JS Document capture is now fixed for Firefox on Android
  • Show spinner while we're waiting for the next studio task to be ready

13.4.0 - 2023-09-27

Changed

  • Add new colorBackgroundDropdownItemHover and colorBackgroundDropdownItemActive UI customization option for the country selector.
  • Add ODP error handling (https://documentation.onfido.com/#original-document-present-reasons)
  • New document capture experience change: Stop rendering the fallback message after two blurry document upload tries.
  • Three changes in the Javascript "New document capture experience": One, increase timeout to see the fallback error message from 40s to 80s. Two, don't show the fallback error message when uploadFallback is disabled. Three, keep the button available even when the uploadFallback error message is shown.
  • Support customUI on self-hosted crossdevice instances

Fixed

  • Prevent the windows touch machines from using the JS camera. In some cases, the Windows Touch machines were allowed to behave as mobile devices. It's not the case anymore.
  • Fix the resolution of the new document capture experience (JS Camera) for iOS devices. It was 1443 px instead of 1440 px.

13.3.2 - 2023-09-18

Changed

Fixed

  • Fix workflow double document steps and blank screen after face capture

13.3.1 - 2023-08-22

Changed

  • Prevent Windows Touch machines from using the JS camera. In some cases, Windows Touch machines were allowed to behave as mobile devices. This is no longer the case.

13.3.0 - 2023-08-16

Changed

  • Fix loading modules when the first module is skippable (studio).
  • Add a general tips section in the README.md
  • Change the welcome screen wording to comply with video recording regulations.

13.2.0 - 2023-08-08

Changed

Fixed

  • Custom cross device URLs can now contain a path between the host and the hash. Ex: https://host:port/some/path/HASH
  • Color contrast in button and remove icons preload

13.1.0 - 2023-07-20

Changed

  • Update resend SMS copy for better user experience.
  • Add Accessibility translations for Motion.
  • Add support for Romanian national identity number in profile capture

Fixed

  • Fix issuing_country on cross-device for passport not added to payload.

13.0.1 - 2023-07-11

Changed

  • Add play pause button to motion intro animation video.

Fixed

  • Fix duplicate Motion capture uploads on SDK initialisations without a complete step.
  • Fix Motion capture recording starting too early.

13.0.0 - 2023-07-11

Changed

  • Remove uploadFallback option in the document step.
  • Remove uploadFallback option in the face step.
  • Add a new error when barcode detection issues arise.

Fixed

  • Fix workflow multi document taks step configuration.

12.4.1 - 2023-07-14

Fixed

  • Fix close button on document preview

12.4.0 - 2023-06-19

Changed

  • Add an instructional video in the Face Video intro screen.
  • Expose Motion events as user analytics.

Fixed

  • Fix custom colours on icons
  • Fix phone input to prevent country from resetting
  • Fix InvalidStateException in edge cases where webcams takes too long to initialise.
  • Fix icon sizes on intro screens with long texts

12.3.6 - 2023-06-16

Changed

  • Deprecate the tearDown method. Prefer safeTearDown, which is a promise and awaitable.

12.3.5 - 2023-06-09

Fixed

  • Public: Fix a crash in the Selfie step when the SDK is bundled

12.3.4 - 2023-06-08

Fixed

  • Public: Bump react-webcam to 7.1.1. Really fixes the bug that caused selfies to appear stretched on Safari 15.
  • Public: Fix preact version to 10.11.3. This should improve our stability when our library is rebundled (NPM).

12.3.3 - 2023-06-01

Fixed

  • Internal: Fix internal issue.

12.3.2 - 2023-05-30

Fixed

  • Public: Fix a bug that prevented document upload from the native camera application.
  • Public: Fix a bug that caused selfies to appear stretched on Safari 15.

12.3.1 - 2023-05-25

Changed

  • Public: Document selection: fix a bug where the documents were wrongly selected when the welcome screen was not in use and the documents were filtered with the Dashboard.
  • Public: Fix a bug that happens only in some cases, where Document Capture was not working because of a library import issue (preact/compat).

12.3.0 - 2023-05-24

Changed

  • Public: Updated document capture documentation
  • Public: Add disableWelcomeScreen option to disable the welcome screen for Studio workflows.
  • Public: Remove Auth SDK
  • Internal: Enhanced security around payload tampering
  • Public: Add capture of ID numbers for Vietnam
  • Internal: Auto uppercase postcode to avoid errors

10.4.0 - 2023-01-23

Changed

  • Public: Fixed a bug in the selfie/face video step, where the face would not be zoomed in correctly.
  • Public: Reduce by one the number of forced retries in case of error while submitting a document. For a max retry count of 4, the 5th attempt will be the final one (previously it was the 6th attempt).
  • Public: In the document step, if there is only a single country due to documentTypes option, show a disabled input with the country pre selected for the user.
  • Public: In the document step, add new option hideCountrySelection to bypass the country selection sub screen. Refer to the README for more information.
  • Public: Added support for dashboard document selection via /supported_documents endpoint and enableDocumentSupportRules option for overriding dashboard feature flag.

10.3.1 - 2023-01-13

Changed

  • Fix for consistent language between desktop and mobile in cross device flow

10.3.0 - 2023-01-11

Changed

  • Internal: Added isWebView SDK configuration option for enabling native featured via webview
  • Public: Prevent error during tearDown when fired from onComplete callback
  • Public: Workflow configurable forceCrossDevice to document and poa task. The features lets Studio users to set forceCrossDevice to true on a task level.
  • Public: Fixed capture icons in cross-device complete screen for face, poa workflow capture tasks.

10.2.0 - 2022-12-15

Changed

  • Public: Add a range of new languages
  • Public: Add RTL support
  • Public: Use browser language when available

10.1.0 - 2022-12-08

Changed

  • Public: For Romanian National ID back side, stop having errors displayed (new IDs have nothing on the backside).
  • Public: Fix a Cross Device issue: When the face step comes before the document step, it's asked for the type of document and issuing country on the desktop then again on the mobile.
  • Public: Add Document auto capture for the New Document Capture Experience. It will be progressively rolled out at Onfido's discretion, depending on Document Type and Document Country.
  • Public: Add the New Document Capture Experience. It will be progressively rolled out at Onfido's discretion, to replace the native camera application.
  • Public: Deprecate beta option useLiveDocumentCapture. The option was not working properly, it will be removed during next quarterly.
  • Public: Deprecate undocumented alpha option useWebcam. The option was not working, at all, it will be removed during next quarterly.
  • Public: Added support for cs_CZ, ro_RO and pl_PL locales
  • Internal: Add Performance analytics
  • Internal: Track screen transition with performance analytics
  • Internal: Add network and feature flag support for Logger
  • Internal: Add data-onfido-qas for a few elements on profile screen and country option selection
  • Public: GA workflow api 3.5 integration
  • Public: Add new colorBackgroundSelector UI customization option
  • Public: Add new colorBackgroundDocTypeButtonHover and colorBackgroundDocTypeButtonActive UI customization options

10.0.2 - 2022-11-29

10.0.2 - 2022-11-29

10.0.1 - 2022-11-24

Fixed

  • Public: Validation for the "date of birth" field (profile capture screen).

10.0.0 - 2022-11-21

Changed:

  • Public: Revert the useLiveDocumentCapture changes.
  • Public: Add UI customization options for buttons hover & active states
  • Public: Add UI customization options for giving small icons a custom color
  • Public: Add UI customization option for input outline-color
  • Public: Accept motion as a requestedVariant for the face step
  • Public: Document Content Security Policy changes related to Motion
  • Internal: Move sdkConfiguration in to store
  • Internal: Add feature flag for inhouse analytics
  • Internal: Add x-onfido-sdk-metadata header to all onfido network requests
  • Internal: Add integration & intergration-version to x-onfido-sdk-metadata header
  • Internal: Add PageVisibility
  • Internal: Add a performance benchmark
  • Public: Display the correct error screen when expired trial.
  • Public: Added translations for expired trial errors.expired_trial.instruction and errors.expired_trial.message
  • Internal: Add network and feature flag support for Logger

9.1.4 - 2022-10-26

Changed

  • Public: Add Honduras and Mexico National Identity Cards
  • Public: Change the useLiveDocumentCapture option: camera selection logic improved, resolution increased to 1920x1080.

9.1.3 - 2022-10-18

Added

  • Public: Display the correct error screen when expired trial.
  • Public: Added translations for expired trial errors.expired_trial.instruction and errors.expired_trial.message

9.1.2 - 2022-10-10

Changed

  • Public: Welcome page UI changes for trial accounts

9.1.1 - 2022-09-26

Changed

  • Fix setting "pan" value for the profile capture step

9.1.0 - 2022-09-23

Changed

  • Internal: Migrated onfido/react-webcam fork to typescript and absorbed it into this repo.
  • Internal: Add utility tool for locales
  • Internal: Add Logger module
  • Internal: Remove woopra
  • Internal: Migrate analytics from /v3 to /v4
  • Internal: Place cross device SMS feature behind a feature flag
  • Internal: Add disableAnalyticsCookies option
  • Internal: Integrate Passive Signals module

9.0.0 - 2022-09-05

Changed

  • Internal: Migrated onfido/react-webcam fork to typescript and absorbed it into this repo.
  • Internal: Collect FACE_LIVENESS_* analytics events
  • Internal: Send OS name and version information in sdk configuration request
  • Internal: Update terser to 5.14.2 & moment to 2.29.4
  • Internal: Add Network module
  • Internal: Move all network calls to the Network module
  • Internal: Add trackPropertiesBeforeMount to internal analytics api
  • Public: Add commit hash in console
  • Internal: Add x-onfido-sdk-version and x-onfido-sdk-platform headers to all onfido network requests
  • Internal: Update FaceTec SDK on Auth step from 9.4.11 to 9.4.12
  • Internal: Show connection error screen on active video upload errors

8.3.0 - 2022-08-02

Changed

  • Public: Fixed setoption, setOptions was setting unspecified values to their default value.
  • Internal: Add dynamically loaded files (except en_US)
  • Internal: Upgraded Sentry to v7, added ErrorBoundary, fingerprinting and moved into its own module
  • Internal: Move Woopra into it's own core module
  • Internal: Migrate webpack to typescript
  • Internal: Add cross device pooling
  • Public: Support for SSN (for USA only) data capture.
  • Public: Collect country of residence before other profile data
  • Public: Add translations for profile data
  • Public: Support DocumentTypes option
  • Public: Remove asterisk from required fields
  • Public: Merge country and document selection in a single screen.
  • Internal: Remove isFullScreen prop from NavigationBar
  • Internal: Add missing analytics events from DocumentLiveCapture and DocumentMultiframe

8.1.0 - 2022-06-13

Changed

  • Internal: Migrate the react-webcam code into SDK + migrate it to typescript
  • Internal: Use the max_total_retries field from SdkConfiguration to compute the max number of document capture retries after an image quality failed check. It was previously was set to 1.
  • Internal: Add video_instruction_type property to analytics event FACE_VIDEO_CAPTURE and FACE_VIDEO_CAPTURE_NEXT_BUTTON_CLICKED
  • Internal: Rename analytics event FACE_VIDEO_CAPTURE_RECORDING_NEXT_CLICKED to FACE_VIDEO_CAPTURE_NEXT_BUTTON_CLICKED
  • Internal: Add ui_alerts properties to FALLBACK_TRIGGERED analytics events
  • Internal: Add many new analytics events CAMERA_ACCESS_*, CAPTURE_*, CONFIRMATION_*
  • Internal: Add new analytics events NAVIGATION_BACK_BUTTON_CLICKED and NAVIGATION_CLOSE_BUTTON_CLICKED
  • Internal: Rename analytics event FACE_INTRO to FACE_SELFIE_INTRO
  • Internal: Add properties to analytics events for DOCUMENT_CAPTURE & DOCUMENT_CONFIRMATION
  • Internal: Remove trackComponentMode() & trackComponentAndMode()
  • Internal: Added test case configs to our demo app with queryString testCase
  • Internal: Add a css root scope to our SDK
  • Public: Scope our customization of castor components to our SDK css root
  • Public: Strip away color-scheme to prevent interference with customer styles
  • Internal: Upgrade @sentry/browser@6.19.7
  • Internal: Fix Sentry artifacts CI upload
  • Internal: Migrated MobileFlow & CrossDeviceSubmit to typescript
  • Internal: Migrated MobileFlow, CrossDeviceLink & CrossDeviceSubmit to typescript
  • Internal: Added ScreenLayout to CrossDeviceSubmit
  • Internal: Update FaceTec SDK on Auth step from 9.4.5 to 9.4.11
  • Internal: Upgrade typescript to 4.6.2
  • Public: Add UI customization option for colorBackgroundQRCode

Fixed

  • Public: Fix inline style to support Content Security Policy
  • Public: Fix for http 204 request errors due to parsing
  • Public: Fix for skipping step when using cross-device on mobile
  • Public: Fix for showing user consent multiple times
  • Public: Fix error when mobilePhrases is supplied but phrases are not

8.0.0 - 2022-04-21

Changed

  • Public: Removed userConsent step option. User Consent is controlled by Onfido API.
  • Internal: Set acceptSslCerts to true for browserstack CI test to avoid "This connection is not private" screens
  • Internal: Migrate ModalApp to typescript
  • Internal: Add support for .env file
  • Public: Update Proof of Address flow to present Country Select
  • Public: Determine Proof of Address document options from endpoint

Fixed

  • Public: Fix useLiveDocumentCapture onComplete not working (cross device capture variant missing)

6.20.1 - 2022-04-28

Fixed

  • Public: Fix useLiveDocumentCapture onComplete not working (cross device capture variant missing)

6.20.0 - 2022-04-12

Changed

  • Internal: Upgraded to webpack 5
  • Internal: Upgraded eslint, mocha, jest
  • Internal: Resolved all deprecated & vulnerability issues by removing and upgrading packages
  • Internal: Added more pollyfills for IE11
  • Internal: Upgraded react-webcam-onfido to 1.0.0
  • Internal: Removed dist & lib from repo and added to .gitignore file
  • Public: Removed *.LICENSE.txt files from lib & dist, see licenses.json instead
  • Public: Fixed CrossDeviceInfo screen layout to prevent scrolling
  • Public: Merged dist/onfido.vendors~crossDevice.min.js into dist/onfido.crossDevice.min.js
  • Public: Merged dist/onfidoAuth.6.min.js to onfidoAuth.min.js
  • Public: Rearranged dependencies & devDependencies in package.json to reflect correct usage
  • Internal: CrossDeviceMobileRouter always connects to desktop to gather the config
  • Public: Added a cookie with anonymous uuid for analytics purposes
  • Internal: Upgrade minimist to v1.2.6 to fix vulnerability
  • Public: Added a "microphone & camera" permission screen
  • Internal: Handle errors by callback instead of throw for requestChallenges and postToBackend
  • Internal: Migrated ClientSuccess to typescript
  • Internal: Added individual analytics *_upload_started & *_upload_completed events for all uploads
  • Internal: Fixed behavior for analytics event CUSTOM_API_REQUEST_COMPLETED & added CUSTOM_API_REQUEST_COMPLETED
  • Internal: Updated integratorTrackedEvents with multiple triggers for UPLOAD to reflect analytics upload events changes
  • Internal: Upgrade minimist to v1.2.6
  • Internal: Upgrade node-fetch@2.6.7 & node-forge@1.3.1

Fixed

  • Internal: Set ideal photo width for selfie step to ensure consistency across mobile devices
  • Internal: Prevent Face step (variant: video) from falling back to selfie upon camera error when uploadFallback: false is provided
  • Internal: Remove duplicated config and strip out custom locales from analytics events
  • Public: Fix issue where poa and document steps cannot be used at the same time. Adds poa key to onComplete callback.
  • Public: Fix mis-aligned text for IE11 on Welcome screen
  • Internal: Fix polyglot to hide missing locales and add warning when in development

6.19.0 - 2022-03-14

Fixed

  • Public: Add compatibility with Salesforce
  • Public: Add type DocumentTypes to DocumentResponse
  • Internal: Migrated NavigationBar to typescript
  • Internal: Migrated Pannable to typescript
  • Internal: Migrated QRCode to typescript
  • Internal: Migrated PhoneNumberInput to typescript
  • Internal: Migrated locales/polyglot to typescript

Changed

  • Internal: Refactor selfie capture step to ensure camera is ready before enabling any capture
  • Internal: Update multipleSelfieCapture feature to ensure snapshot is taken at a different time than the selfie
  • Internal: Migrate SdkConfiguration to v3.3

6.18.0 - 2022-02-28

Added

  • Public: Updated supported documents list to include Curaçao and other countries.
  • Public: Updated document capture experience for better image quality (multi-frame capture)

Changed

  • Internal: Added SdkConfigurationServiceProvider and useSdkConfigurationService to retrieve and use feature flags.
  • Vastly dereased bundle size by not publishing "webpack visualizer" files to NPM.
  • Internal: Added new analytics events for confirmation errors
  • Internal: Added new analytics events for camera, upload, http requests and sms errors
  • Internal: Update FaceTec SDK on Auth step from 9.3.4 to 9.4.5. Removed 3 hardcoded custom properties defined on Auth component UI.
  • Internal: Added events for video preview and face video recording/next buttons
  • Internal: Added new analytics events for custom callbacks
  • Internal: Prevent analytics events without mapping from being send to our api
  • Public: Update documentation for custom callbacks

Fixed

  • UI: Fixed Stick Hover State for buttons on iOS Safari
  • Public: Fix locale key mismatch for the title of the CAMERA_NOT_WORKING_NO_FALLBACK error
  • Internal: Upgrade eventemitter2 to v2.2.2
  • Public: Fix usage of removeAllListeners in ModalApp
  • Public: Fixed CSS variables naming for internal tokens

6.17.0 - 2022-01-24

Changed

  • Change the behavior when useMultipleSelfieCapture feature is enable to stop capturing periodic snapshots once the final selfie is being captured.

Fixed

  • UI: Fixed Live Document Capture flow's camera inactive warning not displaying the basic camera fallback option if uploadFallback is not defined for SDK configuration's Document step.

6.16.0 - 2021-12-15

Added

  • Public: Added support for Dutch nl_NL.
  • Internal: Added new analytics event naming convention for v3/analytics. Woopra will still receive the old events until we are ready to discontinue the integration.

Changed

  • Public: Added autoFocusOnInitialScreenTitle SDK configuration option for integrators to override the SDK auto focusing on the initial screen's title on loading. The default behaviour may not be desirable for some host apps or sites as it could cause the browser to focus on the SDK, rather than content or form inputs outside of the SDK that the end user should see and fill in first.
  • Upgrade react-phone-number-input to v3.1.38
  • Revert change which returns document type as 'unknown' in onComplete callback payload if Residence Permit is selected. The API now supports Residence Permit as a document type for document uploads.

6.15.6 - 2022-06-08

Fixed

  • Public: Added mapping to convert old to new analytics events

6.15.5 - 2021-12-2

Fixed

  • UI: Set the 'Send link' Button component on Cross Device Send SMS Link screen as type="button" to prevent the Button component defaulting to a submit type button when SDK is embedded within a form element.
  • UI: Fix live document capture overlay appearing very small compared to how it was in version 6.14.0.

6.15.4 - 2021-11-25

Fixed

  • Public: Fix issue where multiple SDK instances were sharing the same Redux store values. This was resulting in duplicate cross-device links across multiple instances. With this change, the redux store is reset every time one SDK instance is unmounted via the tearDown() function.

6.15.3 - 2021-11-10

Fixed

  • UI: Fix layout issues for Microsoft Surface tablets on some integrations, i.e. Country Selector text input height, camera stream view offset too far to the left in portrait orientation.
  • Update all Sass / division operation to use the new math.div() syntax to address Sass 2.0 deprecation warnings.
  • Upgrade react-webcam-onfido to 0.1.27 to enforce default values for video/audio bitrate to ensure generated file size is not bigger than necessary.

6.15.2 - 2021-11-01

Changed

  • UI: Host country flag icons internally and fix flag icons not being displayed on Cross Device SMS Phone Number Input, 2-sided documents' Country Selector screens.

Fixed

  • Public: Use new version of react-webcam-onfido that includes fix to correctly apply the muted attribute to the video element. This will prevent the "Live Broadcast" screen to appear on some Safari iOS versions, which is the cause of the identical snapshot and live photos issue.

6.15.1 - 2021-10-21

Fixed

  • Public: Fix error when face step selfie/video variant was requested for users on mobile devices
  • UI: Set all Button components as type="button" if not already set as that to prevent the Button component defaulting to a submit type button.
  • UI: Fix SDK only displaying a loading spinner instead of the "Something's gone wrong" error screen with messages "The link only works on mobile devices / You’ll need to restart your verification on your computer".
  • Public: Fixed Web SDK breaking with a Container wasn't rendered! console error on the Document live capture step when in Modal mode since version 6.11.1
  • Public: Fix SDK displaying "The following keys have missing data: document_front" console error and not triggering the onComplete callback to integrator if user transitioned to Cross Device flow for the Face step
  • UI: Fix UI issue where a user returning to the Desktop tab after completing the capture on cross-device flow, sees "Document" in the confirmation list even when a document was not captured.

6.15.0 - 2021-10-11

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.

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][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][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