Technical reference
- Web SDK
- Android SDK
- iOS SDK
- API Reference
- SDK 6
- - 6.5.0
- - 6.4.0
- - 6.3.1
- - 6.3.0
- - 6.2.1
- - 6.2.0
- - 6.1.0
- - 6.0.1
- - 6.0.0
- SDK 5
- - 5.13.0
- - 5.11.3
Overview
Onfido's Web input-capture SDK provides a set of components for JavaScript applications. These allow the capture of identity documents, live photos and live videos for identity verification. The Web SDK offers a number of benefits to help you create the best onboarding and identity verification experience for your customers:
- carefully designed UI to guide your customers through the entire photo and video-capture process
- modular design to help you seamlessly integrate the photo and video-capture process into your application flow
- advanced image quality detection technology to ensure the quality of the captured images meets the requirement of the Onfido identity verification process, guaranteeing the best success rate
- direct image upload to the Onfido service, to simplify integration
The SDK is only responsible for capturing photos and videos. You still need to access the Onfido API to manage applicants and checks.
1. Obtaining an API token
In order to start integration, you will need an API token. You can use our sandbox environment to test your integration, and you can generate sandbox tokens in your Dashboard.
Regions
Onfido offers region-specific environments. Refer to the Regions section in the API documentation for token format and API base URL information.
2. Creating an applicant
You can create an applicant by making a request to the 'create applicant' endpoint from your server, using a valid API token.
For Document and Facial Similarity reports, you must at least specify the applicant's first and last names in the body of the request.
$ curl https://api.onfido.com/v3/applicants \ -H 'Authorization: Token token=YOUR_API_TOKEN' \ -d 'first_name=John' \ -d 'last_name=Smith'
You will receive a response containing the applicant_id
which will be used to create an SDK token.
3. Generating an SDK token
For security reasons, instead of using an API token directly in your client-side code, you will need to generate an SDK token every time you initialise the SDK. Each authenticated instance of the SDK corresponds to a single Onfido applicant.
To generate an SDK token use your API token to make a request to the 'generate SDK token' endpoint in the Onfido API from your server, including the applicant ID you created in the previous step and a valid referrer.
$ 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'
Parameter | Notes |
---|---|
applicant_id (required) | Specifies the applicant for the SDK instance |
referrer (required) | The referrer URL pattern |
cross_device_url (optional enterprise feature) | Specifies the URL to be used for the cross device flow (Max 24 characters) |
You will recieve a response containing the token
value which will be used when initialising the SDK.
Tokens expire 90 minutes after creation.
Referrer
The referrer argument specifies the URL of the web page where the Web SDK will be used. It guarantees that other malicious websites cannot reuse the SDK token in case it is lost.
The referrer sent by the browser must match the referrer URL pattern in the SDK token for the SDK to successfully authenticate.
You must use a site referrer policy that lets the
Referrer
header be sent. If your policy does not allow this (e.g.
Referrer-Policy: no-referrer
), then you'll receive a 401 bad_referrer
error when trying to use the Web SDK.
Read more about referrer policy in Mozilla's documentation.
An example of a valid referrer is https://*.example.com/example_page/*
. You
can read about valid referrer patterns in our API reference.
Cross device URL
The cross_device_url
argument allows you to specify your own custom URL that the cross-device flow will redirect to instead of the Onfido default. This argument has a limit of 24 characters (including https://
).
To use this feature generate an SDK token as shown below and use it to start the SDK.
$ 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'
4. Including/Importing the library
HTML script tag include
You can import directly into your HTML page. To do this, include the library as a regular script tag on your page:
<script src="dist/onfido.min.js"></script>
And include the standard CSS styles:
<link rel="stylesheet" href="dist/style.css" />
Example app
Simple JSFiddle example using script tags.
NPM style import
You can also import it as a module into your own JS build system (tested with Webpack). You should only use the Web SDK as part of the frontend of your application. We do not provide server-side (Node.js) application support with the Web SDK.
$ 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.
The library is Browser only, it does not support the Node Context.
Example App
Example Webpack Sample App repository which uses the npm style of import.
6. Initialising the SDK
You are now ready to initialise the SDK:
Onfido.init({ // the JWT token that you generated earlier on token: 'YOUR_JWT_TOKEN', // ID of the element you want to mount the component on containerId: 'onfido-mount', // ALTERNATIVE: if your integration requires it, you can pass in the container element instead // (Note that if `containerEl` is provided, then `containerId` will be ignored) containerEl: <div id="root" />, onComplete: function (data) { console.log('everything is complete') // `data` will be an object that looks something like this: // // { // "document_front": { // "id": "5c7b8461-0e31-4161-9b21-34b1d35dde61", // "type": "passport", // "side": "front" // }, // "face": { // "id": "0af77131-fd71-4221-a7c1-781f22aacd01", // "variant": "standard" // } // } // // For two-sided documents like `driving_licence` and `national_identity_card`, the object will also // contain a `document_back` property representing the reverse side: // // { // ... // "document_back": { // "id": "6f63bfff-066e-4152-8024-3427c5fbf45d", // "type": "driving_licence", // "side": "back" // } // // You can now trigger your backend to start a new check // `data.face.variant` will return the variant used for the face step // this can be used to perform a facial similarity check on the applicant }, })
Congratulations! You have successfully started the flow.
Carry on reading the next sections to learn how to:
- handle callbacks
- remove the SDK from the page
- customise the SDK
- create checks
Handling callbacks
onComplete {Function} optional
This callback fires when both the document and face have successfully been captured and uploaded. At this point you can trigger your backend to create a check by making a request to the 'create check' endpoint in the Onfido API.
The callback returns an object with the variant
used for the face capture. The variant can be used to initiate a facial_similarity_photo
or a facial_similarity_video
check.
The data will be formatted as follows: {face: {variant: 'standard' | 'video'}}
.
Here is an onComplete
callback example:
Onfido.init({ token: 'your-jwt-token', containerId: 'onfido-mount', onComplete: function (data) { console.log('everything is complete') // tell your backend service that it can create the check // when creating a facial similarity check, you can specify // whether you want to start a `facial_similarity_photo` check // or a `facial_similarity_video` check based on the value within `data.face.variant` }, })
onError {Function} optional
This callback fires when an error occurs. The callback returns the following errors types:
exception
This type will be returned for the following errors:- timeout and server errors
- authorization
- invalid token
The data returned by this type of error should be used for debugging purposes.
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.
Here is an example of the data returned by the onError
callback:
// Example of data returned for an `exception` error type { type: "exception", message: "The request could not be understood by the server, please check your request is correctly formatted" } // Example of data returned for an `expired_token` error type { type: "expired_token", message: "The token has expired, please request a new one" }
onModalRequestClose {Function} optional
This callback fires when the user attempts to close the modal.
It is your responsibility to decide to then close the modal or not
by changing the property isModalOpen
.
Removing the SDK
If you are embedding 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-initialise the SDK inside the same webpage later on.
onfidoOut = Onfido.init({...}) ... onfidoOut.tearDown()
Customising the SDK
A number of options are available to allow you to customise the SDK:
token {String} required
A JWT is required in order to authorise with our WebSocket endpoint. If one isn’t present, an exception will be thrown.
useModal {Boolean} optional
Turns the SDK into a modal, which fades the background and puts the SDK into a contained box.
Example:
<script> var onfido = {} function triggerOnfido() { onfido = Onfido.init({ useModal: true, isModalOpen: true, onModalRequestClose: function() { // Update options with the state of the modal onfido.setOptions({isModalOpen: false}) }, token: 'token', onComplete: function(data) { // callback for when everything is complete console.log("everything is complete") } }); }; </script> <body> <!-- Use a button to trigger the Onfido SDK --> <button onClick="triggerOnfido()">Verify identity</button> <div id='onfido-mount'></div> </body>
isModalOpen {Boolean} optional
In case useModal
is set to true
, this defines whether the modal is open or closed.
To change the state of the modal after calling init()
you need to later use setOptions()
to modify it.
The default value is false
.
shouldCloseOnOverlayClick {Boolean} optional
In case useModal
is set to true
, the user by default can close the SDK by clicking on the close button or on the background overlay. You can disable the user from closing the SDK on background overlay click by setting the shouldCloseOnOverlayClick
to false.
containerId {String} optional
A string of the ID of the container element that the UI will mount to. This needs to be an empty element. The default ID is onfido-mount
. If your integration needs to pass the container element itself, use containerEl
as described next.
containerEl {Element} optional
The container element that the UI will mount to. This needs to be an empty element. This can be used as an alternative to passing in the container ID string previously described for containerId
. Note that if containerEl
is provided, then containerId
will be ignored.
smsNumberCountryCode {String} optional
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
.
Example:
smsNumberCountryCode: 'US'
userDetails {Object} optional
Some user details can be specified ahead of time, so that the user doesn't need to fill them in themselves.
The following details can be used by the SDK:
smsNumber
(optional) : The user's mobile number, which can be used for sending any SMS messages to the user. An example SMS message sent by the SDK is when a user requests to use their mobile device to take photos. This should be formatted as a string, with a country code (e.g."+447500123456"
)JavaScriptCopyuserDetails: { smsNumber: '+447500123456' }
Language localisation
language {String || Object} optional
The SDK language can be customised by passing a String or an Object.
Onfido currently supports and maintains translations for English (default), Spanish, German and French using the following locale tags respectively: en_US
, es_ES
, de_DE
, fr_FR
.
To leverage one of these languages, the language
option should be passed as a string containing a supported language tag.
Example:
language: 'es_ES' | 'es'
The SDK can also be displayed in a custom language by passing an object containing the locale tag and the custom phrases. The object should include the following keys:
locale
: A locale tag. This is required when providing phrases for an unsupported language. You can also use this to partially customise the strings of a supported language (e.g. Spanish), by passing a supported language locale tag (e.g.es_ES
). For missing keys, the values will be displayed in the language specified within the locale tag if supported, otherwise they will be displayed in English. The locale tag is also used to override the language of the SMS body for the cross device feature. This feature is owned by Onfido and is currently only supporting English, Spanish, French and German.phrases
(required) : An object containing the keys you want to override and the new values. The keys can be found in the Onfido Web SDK GitHub repository. They can be passed as a nested object or as a string using the dot notation for nested values. See the examples below.mobilePhrases
(optional) : An object containing the keys you want to override and the new values. The values specified within this object are only visible on mobile devices. Please refer to themobilePhrases
property in the Onfido Web SDK GitHub repository.Support for standalone `mobilePhrases` keys will be deprecated soon. Consider nesting it inside `phrases` if applicable.JavaScriptCopylanguage: { locale: 'en_US', phrases: { welcome: { title: 'My custom title' } }, mobilePhrases: { 'capture.driving_licence.instructions': 'This string will only appear on mobile' } }
If
language
is not present the default copy will be in English.
Flow customisation
steps {List} optional
List of the different steps and their custom options. Each step can either be specified as a string (when no customisation is required) or an object (when customisation is required):
steps: [ { type: 'welcome', options: { title: 'Open your new bank account', }, }, 'document', 'face', ]
In the example above, the SDK flow consists of 3 steps: welcome
, document
and face
. Note that the title
option of the welcome
step is being overridden, while the other steps are not being customised.
The SDK can also be used to capture Proof of Address documents. This can be achieved by using the poa
step.
Below are descriptions of the steps and the custom options that you can specify inside the options
property. Unless overridden, the default option values will be used.
document
In this step, a user can pick the document type and its issuing country before providing images of their selected document. They will also have a chance to check the quality of the image(s) before confirming.
The custom options are:
documentTypes
(object)The list of document types visible to the user can be filtered by using the
documentTypes
option. The default value for each document type istrue
. IfdocumentTypes
only includes one document type, users will not see both the document selection screen and country selection screen and instead will be taken to the capture screen directly.showCountrySelection
(boolean - default:false
)The
showCountrySelection
option controls what happens when only a single document is preselected indocumentTypes
. It has no effect when the SDK has been set up with multiple documents preselected.The country selection screen is never displayed for a passport document.
By default, if only one document type is preselected, and the document type is not
passport
, the country selection screen will not be displayed. If you would like to have this screen displayed still, setshowCountrySelection
totrue
.JavaScriptCopyoptions: { documentTypes: { passport: boolean, driving_licence: boolean, national_identity_card: boolean, residence_permit: boolean }, showCountrySelection: boolean (note that this will only apply for certain scenarios, see example configurations below) }
Example of Document step without Country Selection screen for a preselected non-passport document (default behaviour)
```json { "steps": [ "welcome", { "type": "document", "options": { "documentTypes": { // Note that only 1 document type is selected here "passport": false, "driving_licence": false, "national_identity_card": true }, "showCountrySelection": false } }, "complete" ] } ```
Examples of Document step configuration with more than one preselected documents where Country Selection will still be displayed
Example 1: All document type options enabled, "showCountrySelection": false
has no effect
```json { "steps": [ "welcome", { "type": "document", "options": { "documentTypes": { "passport": true, "driving_licence": true, "national_identity_card": true }, "showCountrySelection": false (NOTE: has no effect) } }, "complete" ] } ```
Example 2: 2 document type options enabled, "showCountrySelection": false
has no effect
```json { "steps": [ "welcome", { "type": "document", "options": { "documentTypes": { "passport": true, "national_identity_card": true, "driving_licence": false }, "showCountrySelection": false (NOTE: has no effect) } }, "complete" ] } ```
forceCrossDevice
(boolean - default:false
)When set to
true
, the cross device flow is mandatory for all users who will be required to complete the capture process on a mobile device browser. Users will be redirected via a secure link that they can receive by SMS or QR code to complete the flow. Use this option if you want to prevent file upload from desktops. Configuring this option minimises the risk of fraudulent upload by ensuring a higher likelihood of live capture.JavaScriptCopyoptions: { forceCrossDevice: true }
useLiveDocumentCapture
(boolean - default:false
) This BETA feature is only available on mobile devices.When set to
true
, users on mobile browsers with camera support will be able to capture document images using an optimised camera UI, where the SDK directly controls the camera feed to ensure live capture. For unsupported scenarios, see theuploadFallback
section below. Tested on Android Chrome78.0.3904.108
, iOS Safari13
.uploadFallback
(boolean - default:true
) Only available whenuseLiveDocumentCapture
is enabled.When
useLiveDocumentCapture
is set totrue
, the SDK will attempt to open an optimised camera UI for the user to take a live photo of the selected document. When this is not possible, because of an unsupported browser or mobile devices with no camera, by default the user will be presented with an HTML5 File Input upload because ofuploadFallback
. In this scenario, they will be able to use their mobile device's default camera application to take a photo, but will not be presented with an optimised camera UI.This method does not guarantee live capture, because certain mobile device browsers and camera applications may also allow uploads from the user's gallery of photos.
If the mobile device does not have a camera or there is no camera browser support, and
uploadFallback
is set tofalse
, the user will not be able to complete the flow.JavaScriptCopyoptions: { useLiveDocumentCapture: true, uploadFallback: false }
poa
country
(default:GBR
)documentTypes
JavaScriptCopyoptions: { country: string, documentTypes: { bank_building_society_statement: boolean, utility_bill: boolean, council_tax: boolean, // GBR only benefit_letters: boolean, // GBR only government_letter: boolean // non-GBR only } }
face
In this step, users will be asked to capture their face in the form of a photo or video. They will also have a chance to check the quality of the photos or video before confirming.
The custom options are:
requestedVariant
(string)A preferred variant can be requested for this step, by passing the option
requestedVariant: 'standard' | 'video'
. If empty, it will default tostandard
and a photo will be captured. If therequestedVariant
isvideo
, we will try to fulfil this request depending on camera availability and device and browser support. In case a video cannot be taken the face step will fallback to thestandard
option. At the end of the flow, theonComplete
callback will return thevariant
used to capture the user's face which can be used to initiate afacial_similarity_photo
or afacial_similarity_video
check.uploadFallback
(boolean - default:true
)By default, the SDK will attempt to open an optimised camera UI for the user to take a live photo or video. When this is not possible, because of an unsupported browser or mobile device with no camera, by default the user will be presented with an HTML5 File Input upload because of
uploadFallback
. In this scenario, they will be able to use their mobile device's default camera application to take a photo, but will not be presented with an optimised camera UI.This method does not guarantee live capture, because certain mobile device browsers and camera applications may also allow uploads from the user's gallery of photos.
If the mobile device does not have a camera or there is no camera browser support, and
uploadFallback
is set tofalse
, the user will not be able to complete the flow.JavaScriptCopyoptions: { requestedVariant: 'standard' | 'video', uploadFallback: false }
useMultipleSelfieCapture
(boolean - default:true
)When enabled, this feature allows the SDK to take additional selfie snapshots to help improve face similarity check accuracy. When disabled, only one selfie photo will be taken.
Changing options in runtime
It's possible to change the options initialised at runtime. The new options will be shallowly merged with the previous one. So one can pass only the differences to a get a new flow.
onfidoOut = Onfido.init({...}) ... //Change the title of the welcome screen onfidoOut.setOptions({ steps: [ { type:'welcome', options:{title:"New title!"} }, 'document', 'face', 'complete' ] }); ... //replace the jwt token onfidoOut.setOptions({ token:"new token" }); ... //Open the modal onfidoOut.setOptions({ isModalOpen:true });
Creating checks
The Web SDK is only responsible for capturing and uploading photos and videos. It does not actually perform the full document and face checks against our API.
In order to perform a full document and face check, you need to call our API to create a check for the applicant on your backend.
Creating a check
You can create a check by making a request to the 'create check' endpoint in the API, using a valid API token and applicant_id
.
If you are just verifying a document, you only have to include a document report as part of the check. If you are verifying a document and a live photo or video, you will also have to include a facial similarity report.
The facial similarity check can be performed in two different variants: facial_similarity_photo
and facial_similarity_video
.
If the SDK is initialised with the requestedVariant
option for the face step, make sure you use the data returned in the onComplete
callback to request the right report.
The value of variant
indicates whether a photo or video was captured and it needs to be used to determine the report name you should include in your request.
Example of data returned by the onComplete
callback:
{face: {variant: 'standard' | 'video'}}
When the variant
returned is standard
, you should include facial_similarity_photo
in the report_names
array.
If the variant
returned is video
, you should include facial_similarity_video
in the report_names
array.
$ curl https://api.onfido.com/v3/checks \ -H 'Authorization: Token token=YOUR_API_TOKEN' \ -d '{ "applicant_id": "<APPLICANT_ID>", "report_names": ["document", "facial_similarity_photo" | "facial_similarity_video"] }'
You will receive a response containing the check_id
instantly. As document and facial similarity reports do not always return actual results straightaway, you are able to set up webhooks in order to get notified when the results are ready.
You can learn more about sandbox responses here.
Setting up webhooks
Refer to the Webhooks section in the API documentation for details.
User Analytics
The Web SDK allows you to track a user's journey through the verification process via a dispatched event. This is meant to give some insight into how your users make use of the SDK screens.
Overriding the hook
In order to expose 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 and might look something like the following:
addEventListener('userAnalyticsEvent', (event) => /*Your code here*/);
The code inside of the EventListener
will now be called when a particular event is triggered, usually when the user reaches a new screen. See our full list of tracked events.
The parameter being passed in is an Event
object. The details related to the user analytics event can be found at the path event.detail
and are as follows:
eventName
: AString
indicating the type of event. Currently this will always be returned as"Screen"
because each tracked event is a user visiting a screen. In the future more event types may become available for tracking.properties
: AMap
object containing the specific details of an event. This will contain things such as thename
of the screen visited.
Tracked events
Below is the list of potential events currently being tracked by the hook:
WELCOME - User reached the "Welcome" screen DOCUMENT_TYPE_SELECT - User reached the "Choose document" screen where the type of document to upload can be selected ID_DOCUMENT_COUNTRY_SELECT - User reached the "Select issuing country" screen where the the appropriate issuing country can be searched for and selected if supported DOCUMENT_CAPTURE_FRONT - User reached the "document capture" screen for the front side (for one-sided or two-sided document) DOCUMENT_CAPTURE_BACK - User reached the "document capture" screen for the back side (for two-sided document) DOCUMENT_CAPTURE_CONFIRMATION_FRONT - User reached the "document confirmation" screen for the front side (for one-sided or two-sided document) DOCUMENT_CAPTURE_CONFIRMATION_BACK - User reached the "document confirmation" screen for the back side (for two-sided document) FACIAL_INTRO - User reached the "selfie intro" screen FACIAL_CAPTURE - User reached the "selfie capture" screen FACIAL_CAPTURE_CONFIRMATION - User reached the "selfie confirmation" screen VIDEO_FACIAL_INTRO - User reached the "liveness intro" screen VIDEO_FACIAL_CAPTURE_STEP_1 - User reached the 1st challenge during "liveness video capture", challenge_type can be found in eventProperties VIDEO_FACIAL_CAPTURE_STEP_2 - User reached the 2nd challenge during "liveness video capture", challenge_type can be found in eventProperties UPLOAD - User's file is uploading
Going live
Once you are happy with your integration and are ready to go live, please contact client-support@onfido.com to obtain a live version of the API token. The sandbox token in your code will need to be replaced by the live token.
A few things to check before you go live:
- make sure you have set up webhooks to receive live events
- make sure you have entered correct billing details inside your Onfido Dashboard
Accessibility
The Onfido Web SDK has been optimised to provide the following accessibility support by default:
- screen reader support: accessible labels for textual and non-textual elements available to aid screen reader navigation, including dynamic alerts
- keyboard navigation: all interactive elements are reachable using a keyboard
- sufficient color contrast: default colors have been tested to meet the recommended level of contrast
- sufficient touch target size: all interactive elements have been designed to meet the recommended touch target size
Refer to our accessibility statement for more details.
Support
Please open an issue through GitHub. Please be as detailed as you can. Remember not to submit your token in the issue. Also check the closed issues to see whether it has been previously raised and answered.
If you have any issues that contain sensitive information please send us an email with the ISSUE: at the start of the subject to web-sdk@onfido.com.
Previous versions of the SDK will be supported for a month after a new major version release. Note that when the support period has expired for an SDK version, no bug fixes will be provided, but the SDK will keep functioning (until further notice).
Troubleshooting
Content Security Policy issues
In order to mitigate potential cross-site scripting issues, most modern browsers use Content Security Policy (CSP). These policies might prevent the SDK from correctly displaying the images captured during the flow or to 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.
<meta http-equiv="Content-Security-Policy" content=" default-src 'self' https://assets.onfido.com; script-src 'self' https://www.woopra.com https://assets.onfido.com https://sentry.io; style-src 'self' https://assets.onfido.com; connect-src blob: *.onfido.com wss://*.onfido.com https://www.woopra.com https://sentry.io; img-src 'self' data: blob: https://lipis.github.io/flag-icon-css/; media-src blob:; object-src 'self' blob:; frame-src 'self' data: blob:; " />
SDK navigation issues
In rare cases, the SDK back button might not work as expected within the application history. This is due to the interaction of history/createBrowserHistory
with the browser history API.
If you notice that, by clicking on the SDK back button, you get redirected to the page that preceded the SDK initialisation you might want to consider using the following configuration option when initialising the SDK: useMemoryHistory: true
. This option allows the SDK to use the history/createMemoryHistory
function, instead of the default history/createBrowserHistory
. This option is intended as workaround, while a more permanent fix is implemented.
Example:
Onfido.init({ useMemoryHistory: true, })
Onfido Web SDK Migration Guide
The guides below are provided to ease the transition of existing applications using the Onfido SDK from one version to another that introduces breaking API changes.
6.1.0
-> 6.2.0
Changed strings
The English, Spanish, German, and French copy for the following string(s) has changed:
upload_guide.image_detail_blur_label
upload_guide.image_detail_glare_label
upload_guide.image_detail_good_label
6.0.1
-> 6.1.0
Introduce migrate_locales
script
From version 6.1.0
, Web SDK will use a new locale key naming convention that better supports scalability.
As a result, many key names will be changed and this might affect the integrator's custom locale options.
The migrate_locales
script will help integrators migrate from the older key name convention
to the new one with minimal hassle.
To use the script:
Upgrade
onfido-sdk-ui
package to latest version6.1.0
Create a JSON file containing custom locales which was fed to
Onfido.init()
method. For instance:JavaScriptCopy// your-custom-language.json { "locale": "en_US", // untouched keys "phrases": { // required key "capture": { "driving_licence": { "front": { "instructions": "Driving license on web" } } }, "complete.message": "Complete message on web" }, "mobilePhrases": { // optional key "capture.driving_licence.front.instructions": "Driving licence on mobile", "complete": { "message": "Complete message on mobile" } } }
Consume the script directly from
node_modules/.bin
:shellCopy$ migrate_locales --help # to see the script's usage $ migrate_locales --list-versions # to list all supported versions Supported versions: * from v0.0.1 to v1.0.0 $ migrate_locales \ --from-version v0.0.1 \ --to-version v1.0.0 \ --in-file your-custom-language.json \ --out-file your-custom-language-migrated.json
The migrated data should look like this:
JavaScriptCopy// your-custom-language-migrated.json { "locale": "en_US", "phrases": { "new_screen": { // renamed key in nested object "driving_licence": { "front": { "instructions": "Driving license on web" } } }, "screen_1.complete.message": "Complete message on web", // 2 generated keys from 1 old key "screen_2.complete.message": "Complete message on web" "mobilePhrases": { // force nesting because standalone `mobilePhrases` will be deprecated soon "new_screen.driving_licence.front.instructions": "Driving licence on mobile", // renamed key in dot notation "screen_1": { // 2 generated keys from 1 old key "complete": { "message": "Complete message on mobile" } }, "screen_2": { "complete": { "message": "Complete message on mobile" } } } }, }
Notes: the script will preserve:
- Order of the keys
- Format: if your old keys are nested as an object, the migrated keys will be nested too. Otherwise, if your old keys are string with dot notation, the migrated keys will be string too.
5.10.0
-> 6.0.0
Change in UX flow for Document step
- Document step now has a Issuing Country Selection screen after the Document Type Selection screen. This screen is never displayed for passport documents and is disabled by default when only 1 document is preselected using the
documentTypes
option. This screen can still be included in the document capture flow of non-passport preselected documents by enabling theshowCountrySelection
option in the Document step configuration.
Example of Document step with Country Selection for a preselected non-passport document
{ "steps": [ "welcome", { "type": "document", "options": { "documentTypes": { "passport": false, "driving_licence": false, "national_identity_card": true }, "showCountrySelection": true } }, "complete" ] }
Example of Document step without Country Selection for a preselected non-passport document (default behaviour)
{ "steps": [ "welcome", { "type": "document", "options": { "documentTypes": { "passport": false, "driving_licence": false, "national_identity_card": true }, "showCountrySelection": false } }, "complete" ] }
Example of Document step configurations with preselected documents where Country Selection will still be displayed
{ "steps": [ "welcome", { "type": "document", "options": { "documentTypes": { "passport": true, "driving_licence": true, "national_identity_card": true } } }, "complete" ] }
{ "steps": [ "welcome", { "type": "document", "options": { "documentTypes": { "passport": true, "national_identity_card": true, "driving_licence": false } } }, "complete" ] }
Added strings
country_selection.error
country_selection.dropdown_error
country_selection.placeholder
country_selection.search
country_selection.submit
country_selection.title
capture.residence_permit.front.title
capture.residence_permit.back.title
confirm.residence_permit.message
document_selector.identity.residence_permit_hint
residence_permit
Changed strings
The English, Spanish, German, and French copy for the following string(s) has changed:
document_selector.identity.title
document_selector.identity.hint
Changed keys
The following keys have been renamed:
errors.server_error.instruction
=>errors.request_error.instruction
errors.server_error.message
=>errors.request_error.message
Removed strings
SMS_BODY
5.7.0
-> 5.10.0
Added strings
image_quality_guide.title
image_quality_guide.sub_title
image_quality_guide.all_good
image_quality_guide.not_cut_off
image_quality_guide.no_glare
image_quality_guide.no_blur
image_quality_guide.image_alt_text
image_quality_guide.next_step
mobilePhrases.image_quality_guide.title
mobilePhrases.image_quality_guide.next_step
Changed strings
The English copy for the following string(s) has changed:
errors.invalid_capture
5.6.0
-> 5.7.0
With release 5.7.0 there are breaking changes that will affect integrators with customised languages or UI copy.
Added strings
capture.face.intro.title
capture.face.intro.subtitle
capture.face.intro.selfie_instruction
capture.face.intro.glasses_instruction
capture.face.intro.accessibility.selfie_capture_tips
continue
cross_device.intro.title
cross_device.intro.sub_title
cross_device.intro.description_li_1
cross_device.intro.description_li_2
cross_device.intro.description_li_3
cross_device.intro.action
cross_device.link.sms_sub_title
cross_device.link.copy_link_sub_title
cross_device.link.qr_code_sub_title
cross_device.link.options_divider_label
cross_device.link.sms_option
cross_device.link.copy_link_option
cross_device.link.qr_code_option
cross_device.link.qr_code.help_label
cross_device.link.qr_code.help_step_1
cross_device.link.qr_code.help_step_2
cross_device.link.copy_link.action
cross_device.link.copy_link.success
Removed strings
cross_device.intro.document.title
cross_device.intro.document.take_photos
cross_device.intro.document.action
cross_device.intro.face.title
cross_device.intro.face.take_photos
cross_device.intro.face.action
cross_device.link.sub_title
cross_device.link.link_copy.action
cross_device.link.link_copy.success
Changed strings
The English and Spanish copy for the following string(s) has changed:
cross_device.link.copy_link_label
cross_device.link.sms_label
5.0.0
-> 5.6.0
With release 5.6.0 there is a breaking change that will affect integrators with customised languages or UI copy.
Note: The string custom translation version scheme has changed, going forward if the strings translations change it will result in a MINOR version change, therefore you are responsible for testing your translated layout in case you are using custom translations or copy.
Added strings
capture.switch_device
Removed strings
cross_device.switch_device.submessage
Changed strings
The English and Spanish copy for the following string(s) has changed:
capture.upload_file
errors.invalid_size.message
errors.invalid_size.instruction
The English copy for the following string(s) has changed:
capture.driving_licence.front.title
capture.driving_licence.back.title
capture.national_identity_card.front.title
capture.national_identity_card.back.title
capture.passport.front.title
capture.bank_building_society_statement.front.title
capture.utility_bill.front.title
capture.benefit_letters.front.title
capture.council_tax.front.title
errors.invalid_type.message
errors.invalid_type.instruction
4.0.0
-> 5.0.0
We have changed the behaviour of the document step. If the document step is initialised with only one document type, the document selector screen will not be displayed. If your application relies on the document selector screen, even if you are picking only one document, you will have to implement that UI yourself.
3.1.0
-> 4.0.0
Import breaking changes
We have changed how the SDK is exported, in order to reduce redundant transpiled code and to better trim dead code too. This led to a size reduction overall.
However, this has potentially created a breaking change for those consuming the SDK with an ES style of import. Classic window style import and commonjs require should work the same.
Example of old behaviour
import Onfido from 'onfido-sdk-ui' Onfido.init(...)
Example of new behaviour
import {init} from 'onfido-sdk-ui' init(...)
or
import * as Onfido from 'onfido-sdk-ui' Onfido.init(...)
Style Breaking change
- We have internally changed the CSS units used in the SDK to be relative (
em
) units.
Therefore, if you previously set the font-size of .onfido-sdk-ui-Modal-inner
, it is recommended that you remove this font-size
override.
This is because we are looking to make the SDK compatible with em
, but first we need to remove media queries which are not really compatible with that unit.
Example of old behaviour
.onfido-sdk-ui-Modal-inner { font-size: 20px; }
Example of new behaviour
.a-more-specific-selector { font-size: 20px; }
2.8.0
-> 3.0.0
Breaking changes
- Removed support for
buttonId
. From this version you will need to create a function that launches the SDK when a trigger element (ie a button) is clicked.
Example of old behaviour
<script> Onfido.init({ useModal: true, buttonId: 'onfido-btn', token: 'YOUR_JWT_TOKEN', onComplete: function (data) { // callback for when everything is complete console.log('everything is complete') }, }) </script> <body> <button id="onfido-btn">Verify identity</button> <div id="onfido-mount"></div> </body>
Example of new behaviour
<script> var onfido = {} function triggerOnfido() { onfido = Onfido.init({ useModal: true, isModalOpen: true, onModalRequestClose: function () { // Update options with the state of the modal onfido.setOptions({ isModalOpen: false }) }, token: 'YOUR_JWT_TOKEN', onComplete: function (data) { // callback for when everything is complete console.log('everything is complete') }, }) } </script> <body> <!-- Use a button to trigger the Onfido SDK --> <button onClick="triggerOnfido()">Verify identity</button> <div id="onfido-mount"></div> </body>
1.1.0
-> 2.0.0
Breaking changes
- Removed
onDocumentCapture
that used to be fired when the document had been successfully captured, confirmed by the user and uploaded to the Onfido API - Removed
onFaceCapture
callbacks that used to be fired when the face has beed successfully captured, confirmed by the user and uploaded to the Onfido API. - Removed
getCaptures
function that used to return the document and face files captured during the flow. - Changed the behaviour of
onComplete
callback. It used to return an object that contained all captures, now it doesn't return any data.
Example of old behaviour
Onfido.init({ token: 'YOUR_JWT_TOKEN', containerId: 'onfido-mount', onDocumentCapture: function (data) { /*callback for when the*/ console.log( 'document has been captured successfully', data ) }, onFaceCapture: function (data) { /*callback for when the*/ console.log('face capture was successful', data) }, onComplete: function (capturesHash) { console.log('everything is complete') // data returned by the onComplete callback including the document and face files captured during the flow console.log(capturesHash) // function that used to return the document and face files captured during the flow. console.log(Onfido.getCaptures()) }, })
Example of new behaviour
Onfido.init({ // the JWT token that you generated earlier on token: 'YOUR_JWT_TOKEN', // id of the element you want to mount the component on containerId: 'onfido-mount', onComplete: function () { console.log('everything is complete') // You can now trigger your backend to start a new check }, })
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.
[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
to10.5.4
. - Internal: Replace
react-modal-onfido
with version3.11.2
ofreact-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.
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
toWeb SDK
andjs-sdk
toweb-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 ifissuing_country
is present. This fixes the issue that was preventing documents upload whenshowCountrySelection
was disabled andissuing_country
wasundefined
.
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 thedocument
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 theMIGRATION.md
file. - Internal: Send additional
system
data insdk_metadata
which containsos
,os_version
,browser
&browser_version
info of the current session.
Changed
- Internal: Changed resolution constraints for live document captures from
720
to1080
. - 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
andFACIAL_CAPTURE
to user analytics event list - Public: Added option to pass a container element
containerEl
instead of a container ID stringcontainerId
. IfcontainerEl
is provided, thencontainerId
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
andsnapshots
. - 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
andcross_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 thehideOnfidoLogo
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 ofdisableAnalytics
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 usehistory/createMemoryHistory
by passing the configuration optionuseMemoryHistory: true
to the SDK, in casehistory/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 inCONTRIBUTING.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 usescreateMemoryHistory
. - 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
objectisCrossDeviceFlow
(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 ofraven
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 usingaudit-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 thewelcome
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 theface
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
id
s) of the uploaded files, in theonComplete
event - Public: Added
forceCrossDevice
option todocument
step. The feature forces users to use their mobile to capture the document image. It defaults tofalse
. 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 istrue
(feature released in3.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 topx
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 istrue
- 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 toGB
. - 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 tostandard
and a photo will be captured. If therequestedVariant
isvideo
, 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 thestandard
option. At the end of the flow, theonComplete
callback will return thevariant
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 thevariant
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
- Internal: Changed assets url to point at https://assets.onfido.com/
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 thedocument
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. Iflanguage
is not present or the wrong locale tag is provided, the language locale will default toen
. - 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.
1.1.0
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
1.0.0
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.
0.15.1
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.
0.15.0
Changed
- Internal: Use HTTP protocol to post documents to the server instead of websockets
Fixed
- Public: Fixed intermittent connection problem
0.14.0
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.
0.13.0
Changed
- Public: Change the default to use file upload rather than the webcam for document captures.
- Internal: Fix dependencies to avoid bugs due to changes in minor updates.
0.12.0-rc.1
Install with npm install onfido-sdk-ui@0.12.0-rc.1
Changed
- Internal: Change the signature expected from the websockets server.
Fixed
- Public: The documentType in the capture object now corresponds to the API document_types.
- Public: Fixed bug where URL path was removed between steps.
0.11.1 - Hotfix
Fixed
- Public: Fixed bug where
Onfido.getCaptures()
andonComplete(hash)
was returning a broken hash. - Internal: Froze dependencies which were causing the upload document and pdf preview not to work.
0.11.0
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.
0.10.0
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.
0.9.0
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.
0.8.4
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.
0.8.3
Added
- Started tracking fatal exceptions and page views of the SDK.
0.8.2
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.
0.8.1
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;
0.8.0
Changed
- Public: Captures are now returned as
png
instead ofwebp
, althoughwebp
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 ofreact-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
andUploader
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 theUploader
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 tojpeg
in case the browser does not support it.
0.7.0
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.
0.6.1
Changed
- Public:
Onfido.init()
now returns an object. - Internal:
isDesktop
detection is now based on DetectRTC'sisMobile
detection - Internal: improved Webcam Detection, it now takes into account wether a Webcam exists and if it the user has given the website permission to use it. Before it was only checking whether the getUserMedia API is supported by the browser or not. DetectRTC is used for this detection.
Added
- Public: it's now possible to change the init options at runtime by calling
setOptions()
on the object returned byOnfido.init()
- Public:
useWebcam
option added to the facial and document capture step
0.5.1
Fixed
- SDK Core dependency update, fixes issue https://github.com/onfido/onfido-sdk-ui/issues/25Note: This update only changes the dist folder release, npm releases get the dependency update if they do
npm install
0.5.0
Added
- API: Flow customization option
steps:[]
- UI: Overlay to the webcam document capture (Possibly breaking change)
- DOC: Integration examples to documentation
Fixed
- NPM (commonjs2) style of importing the library now works