Onfido logo home page
Watch a demo
Get in touch
Arrow back Back to guides

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.

SDK tokens are required to authenticate the SDKs for workflows. You can generate SDK tokens using the Onfido API.

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>"
  },
}

Import the library

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

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

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.

Onfido

Our solutions

Onfido uses 256-bit SSL encryption 100% of the time on every device.

BSI ISO/IEC27001

Onfido has been certified by BSI to ISO 27001 under certificate number IS 660122.

© Onfido™, 2022. All rights reserved.
Company Registration Number: 07479524.