Onfido Studio: Web SDK integration

Start here

This is an introductory guide to integrating Onfido Studio - our drag and drop interface for building, managing, and deploying identity verification journeys - with Onfido’s Web SDK. For more general information regarding Onfido Studio, please see our product guide.

Getting started

All of the interactive tasks of an end-user’s verification journey designed and built using Onfido Studio are managed by our SDKs.

The Onfido Web SDK communicates directly and dynamically with active Studio workflows to display the relevant screens to ensure the correct capture and upload of user information, such as identity documents, selfie photos and videos. As a result, the SDK flow will vary depending on the workflow configuration. You won't need to specify any steps directly in the SDK integration as these will be overridden when the workflow run ID is passed into the SDK initialization.

The minimum supported Web SDK version for workflows is onfido-sdk-ui@9.0.0 and API v3.4.

Create a workflow run

As a first step, you will need to create a Workflow Run by making a call to the Onfido API. At a minimum, you will need to provide a workflow_id from a valid, active workflow, as well as an Applicant ID. More details on creating a workflow run can be found in our API reference.

The server will return a workflow run object, with a workflow run ID contained in the response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<WORKFLOW_RUN_ID>",
  "applicant_id": "<APPLICANT_ID>",
  "workflow_id": "<WORKFLOW_ID>",
  "workflow_version_id": 11,
  "status": "approved",
  "dashboard_url":"https://dashboard.onfido.com/results/<WORKFLOW_RUN_ID>"
  "output": {"prop1": "val_1", "prop2": 10}, 
  "reasons": ["reason_1", "reason_2"],
  "error": null,
  "created_at": "2022-06-28T15:39:42Z",
  "updated_at": "2022-07-28T15:40:42Z",
  "link": {
      "completed_redirect_url": "https://example.onfido.com",
      "expired_redirect_url": "https://example.onfido.com",
      "expires_at": "2022-10-17T14:40:50Z",
      "language": "en_US",
      "url": "https://eu.onfido.app/l/<WORKFLOW_RUN_ID>"
  },
}

Generate an SDK token

SDK tokens are required to authenticate the SDKs for Studio workflows, generated by making a call to the Onfido API.

More detailed documentation about SDK tokens can be found in our API reference.

Import the library

Next, you will need to import the library, which can be done in one of three ways:

use our CDN
import the library directly into your HTML page
use npm (valid from version 9+)

CDN

You can use hosted versions of the library files from Onfido's CDN.

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

subscribing to a specific patch release (e.g. v12.3.1) will fix the library files to that SDK release
subscribing to a minor level release (e.g. v12.3) means Onfido will update to the latest available patch release
subscribing to a major release (e.g. v12) means Onfido will update to the latest available patch and minor release

<!-- Replace "<version>" with the actual SDK version you want to use, example: v12 -->
<script src="https://sdk.onfido.com/<version>"></script>
<link
  href="https://sdk.onfido.com/<version>/style.css"
  rel="stylesheet"
/>

For versions prior to 12.3.1, specifying a precise release only, see our previous documentation.

HTML Script Tag Include

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

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

And the CSS styles:

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

A simple example using script tags can be found here.

NPM style import

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

$ npm install --save onfido-sdk-ui

// 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.

You can see an example using the npm style import in our sample app.

Add basic HTML markup

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

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

Initialize the SDK for Studio

You’re now ready to initialize the SDK, using your generated SDK token and workflow run ID.

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>',
})

ATTRIBUTE	FORMAT	NOTES
token	string	required Your Web SDK token
containerId	string	optional A string containing the ID of the container element that the UI will mount to. This must be an empty element. The default is `onfido-mount`. Alternatively, if your integration requires it, you can pass in the container element instead. Note that if `containerEl` is provided, then `containerId` will be ignored
onComplete		optional A callback function that executes after all interactive tasks in the workflow have been completed
workflowRunId	string	required The ID of the workflow run. An existing workflow id is required to extract the dynamic flow

Handling callbacks

Onfido.init({
  token: '<YOUR_SDK_TOKEN>',
  containerId: 'onfido-mount',
  workflowRunId: '<WORKFLOW_RUN_ID>',
  onComplete: function (data) {
    console.log('everything is complete')
  },
  onUserExit: function (userExitCode) {
    console.log(userExitCode)
  },
  onError: function (error) {
    console.log(error)
  },
})

ATTRIBUTE	FORMAT
onComplete	{Function} optional Callback that fires when all interactive tasks in the workflow have been completed. On success, if you have configured webhooks, a notification will be sent to your backend confirming the workflow run has finished. You do not need to create a check using your backend as this is handled directly by the workflow
onError	{Function} optional Callback that fires when an error occurs
onUserExit	{Function} optional Callback that fires when the user abandons the flow without completing it. The reason can be an exitCode, e.g `USER_CONSENT_DENIED`

Customizing the SDK

The Web SDK has multiple customizable features that provide flexibility, while also being easy to integrate. For more detailed documentation, read our SDK customization guide.

UI customization

customUI {Object} optional

Our SDK UI customization documentation has more details regarding the supported UI customization options that can be set in this property.

Language localization

The SDK supports and maintains multiple languages. Please refer to the Web SDK language localization documentation for more details.