@onfido/cordova-sdk

Table of contents

• Table of contents
• Overview
• Getting started
  • 1. Obtaining an API token
  • 2. Creating an Applicant
  • 3. Configuring SDK with Tokens
  • 4. Adding the Onfido Cordova SDK to your project
    • This SDK supports Cordova versions 11.0.0 and later
    • 4.1 Adding SDK dependency through npm
    • 4.2 Update your Android build.gradle files
    • 4.3 Update your iOS configuration files
• Usage
  • 1. Creating the SDK configuration
  • 2. Parameter details
  • 3. Success Response
  • 4. Failure Response
  • 5. Localization
• Creating checks
  • 1. Obtaining an API token
  • 2. Creating a check
• Theme Customization
• Going live
• More Information
  • Support
  • Troubleshooting
• How is the Onfido Cordova SDK licensed?

Overview

This SDK provides a drop-in set of screens and tools for Cordova applications to allow the capture of identity documents and face photos/live videos for the purpose of identity verification with Onfido. The SDK offers a number of benefits to help you create the best onboarding/identity verification experience for your customers:

• Carefully designed UI to guide your customers through the entire photo/video-capturing process
• Modular design to help you seamlessly integrate the photo/video-capturing 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*

ℹ️

If you are integrating using Onfido Studio please see our Studio integration guide

* Note: the SDK is only responsible for capturing and uploading photos/videos. You still need to access the Onfido API to create and manage checks.

• Supports iOS 11+
• Supports Xcode 13+
• Supports Android API level 21+
• Supports iPads and tablets

Getting started

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 will find the API tokens inside your Onfido Dashboard. You can create API tokens inside your Onfido Dashboard as well.

2. Creating an Applicant

You must create an Onfido Applicant before you start the SDK flow.

For a document or face check, the minimum applicant details required are firstName and lastName.

You must create applicants from your server:

$ curl https://api.onfido.com/v3/applicants \
    -H 'Authorization: Token token=YOUR_API_TOKEN' \
    -d 'first_name=Theresa' \
    -d 'last_name=May'

The JSON response has an id field containing a UUID that identifies the applicant. All documents or live photos/videos uploaded by that instance of the SDK will be associated with that applicant.

3. Configuring the SDK with Tokens

You will need to generate and include a short-lived JSON Web Token (JWT) every time you initialise the SDK.

To generate an SDK Token, you should perform a request to the SDK Token endpoint in the Onfido API:

$ curl https://api.onfido.com/v3/sdk_token \
  -H 'Authorization: Token token=YOUR_API_TOKEN' \
  -F 'applicant_id=YOUR_APPLICANT_ID' \
  -F 'application_id=YOUR_APPLICATION_BUNDLE_IDENTIFIER'

Make a note of the token value in the response, as you will need it later on when initialising the SDK.

Warning: SDK tokens expire 90 minutes after creation.

The application_id is the "Application ID" or "Bundle ID" that was already set up during development.

• For iOS, this is usually in the form of com.your-company.app-name.
  • To get this value manually, open xcode ios/YourProjectName, click on the project root, click the General tab, under Targets click your project name, and check the Bundle Identifier field.
  • To get this value programmatically in native iOS code, see Stack Overflow Page.
• For Android, this is usually in the form of com.example.yourapp.
  • To get this file manually, you can find it in your app's build.config. For example, in android/app/build.gradle, it is the value of applicationId.
  • To get this value programmatically in native Java code, see Stack Overflow Page.

4. Adding the Onfido Cordova SDK to your project

This SDK supports Cordova versions 11.0.0 and later

If you are starting from scratch, you can follow the Cordova Documentation. A short instruction would look like this:

1. Install Node.js and Cordova:

• Go to the Node.js website and download and install the latest version of Node.js.
• Open a command prompt or terminal window and install Cordova by running the following command: npm install -g cordova

2. Create a new Cordova project:

• Open a command prompt or terminal window and navigate to the directory where you want to create the project.
• Run the following command to create a new Cordova project: cordova create myapp. Replace "myapp" with the name you want to give to your application.

3. Add platforms:

• Navigate into the newly created "myapp" directory.
• Run the following command to add the platforms you want to build your app for: cordova platform add android (for Android), cordova platform add ios (for iOS)

4. Add your code and resources:

• Place your HTML, CSS, JavaScript, and any other resources your application requires in the "www" directory.

5. Build your app:

• Run the following command to build your application: cordova build
• This will create an app package for the platform you added earlier.

6. Test your app:

• Connect a device or an emulator to your computer and run the following command to deploy and test your app: cordova run <platform>. Replace "platform" with the name of the platform you want to test your app on (e.g., "android" or "ios").

NOTE: You will need to download and install Android Studio and Xcode.

4.1 Adding SDK dependency through npm

Navigate to the root directory of your Cordova project. The rest of this section (section 4) will assume you are in the root directory. Run the following command:

$ npm install @onfido/cordova-sdk --save
$ cordova plugin add @onfido/cordova-sdk

4.2 Update your Android build.gradle files

Onfido Cordova SDK is available for Android 21+. Add these preferences into your application config.xml file:

 <preference name="android-targetSdkVersion" value="33" />
 <platform name="android">
        <config-file target="res/xml/config.xml" parent="/*">
            <feature name="OnfidoSdk">
                <param name="android-package" value="com.plugin.OnfidoSdk.OnfidoSdkModule"/>
                <param name="android-package-Response" value="com.plugin.OnfidoSdk.Response"/>
                <param name="android-package-OnfidoSdkActivityEventListener" value="com.plugin.OnfidoSdk.OnfidoSdkActivityEventListener"/>
                <param name="onload" value="true"/>
            </feature>
        </config-file>

        <source-file src="src/android/OnfidoSdkModule.java" target-dir="src/com/plugin/OnfidoSdk"/>
        <source-file src="src/android/OnfidoSdkActivityEventListener.java" target-dir="src/com/plugin/OnfidoSdk"/>
        <source-file src="src/android/Response.java" target-dir="src/com/plugin/OnfidoSdk"/>
        <framework src="src/android/onfido.gradle" custom="true" type="gradleReference"/>
    </platform>

4.3 Update your iOS configuration files

Onfido Cordova SDK is available for iOS 11+ and requires Swift version 5. Add these preferences into your application config.xml file:

    <platform name="ios">
        <preference name="deployment-target" value="11.0" />
        <preference name="SwiftVersion" value="5" />
    </platform>

Usage

You can launch the app with a call to Onfido.start. For example, once you have the sdkTokenFromOnfidoServer, your code might look like this:

async function runOnfidoSdk(withDocSelfy, withMotion, workflowRunId) {    
     const config = {
        sdkToken: 'TOKEN', // IMPORTANT: see notes
        hideLogo: false,
        logoCoBrand: false,
        enableNFC: false,
        flowSteps: {
            welcome: false,
            captureDocument: {
                countryCode: "FRA",
                docType: "PASSPORT",
                alpha2CountryCode: "FR"
            },
            captureFace: {
                type: "MOTION"
            }
        }
   }
   
   const onComplete = (completeResponse) => {
    console.log("success callback has been hit");   
    alert(completeResponse)
   }

   const onError = (completeResponse) => {
    console.log("error callback has been hit");
    alert(completeResponse)
}
   
   window.cordova.plugins.onfido.start(onComplete, onError, config);
}

1. Creating the SDK configuration

Once you have added the SDK as a dependency and you have a SDK token, you can configure the SDK:

Example configuration:

config = {
  sdkToken: “EXAMPLE-TOKEN-123”,
  flowSteps: {
    welcome: true,
    captureDocument: {
      docType: OnfidoDocumentType.DRIVING_LICENSE,
      countryCode: OnfidoCountryCode.USA
    },
    captureFace: {
      type: OnfidoCaptureType.VIDEO
    },
  },
  enableNFC: true
}

2. Parameter details

• sdkToken: Required. This is the JWT sdk token obtained by making a call to the SDK token API. See section Configuring SDK with Tokens.

• flowSteps: Required. This object is used to toggle individual screens on and off and set configurations inside the screens.

• welcome: Optional. This toggles the welcome screen on or off. If omitted, this screen does not appear in the flow.

  • Valid values: true, false

• captureDocument: Optional. This object contains configuration for the capture document screen. If docType and countryCode are not specified, a screen will appear allowing the user to choose these values. If omitted, this screen does not appear in the flow.

• docType: Required if countryCode is specified.

  • Valid values in OnfidoDocumentType: PASSPORT, DRIVING_LICENCE, NATIONAL_IDENTITY_CARD, RESIDENCE_PERMIT, RESIDENCE_PERMIT, VISA, WORK_PERMIT, GENERIC. Note: GENERIC document type doesn't offer an optimised capture experience for a desired document type.

• countryCode: Required if docType is specified.

  • Valid values in OnfidoCountryCode: Any ISO 3166-1 alpha-3 code. For example: OnfidoCountryCode.USA.

• enableNFC: Optional. This toggles the ePassport NFC extraction feature. If omitted, this feature is not enabled in the flow. There are also application configuration changes needed to use this feature. To do that please follow Onfido Developer Hub

  • Valid values: true, false.

• captureFace: Optional. This object contains options for the capture face screen. If omitted, this screen does not appear in the flow.

• type: Required if captureFace is specified.

  • Valid values in OnfidoCaptureType: PHOTO, VIDEO, MOTION.

• localisation: Optional. This object contains localisation configuration. See section Localization for the details.

  • Example usage:

  config = {
    sdkToken: “EXAMPLE-TOKEN-123”,
    localisation: {
      ios_strings_file_name: 'Localizable',
    },
    flowSteps: {
      ...
    },
  }

3. Success Response

The response will include a face section if captureFace was specified, document section if captureDocument was specified, or both sections if they were both requested in the config.

Example:

{
 document: {
   front: { id: "123-abc" },
   back: { id: "345-def" }
 },
 face: {
   id: "456-567",
   variant: "VIDEO" // PHOTO or VIDEO
 },
}

4. Failure Response

The SDK will reject the promise any time the Onfido SDK exits without a success. This includes cases where:

• the configuration was invalid,
• the mobile user clicked the back button to exit the Onfido SDK.

Example

{
  code: "config_error",
  message: "sdkToken is missing"
}

5. Localization

The SDK supports and maintains the following 44 languages:

• Arabic: ar
• Armenian: hy
• Bulgarian: bg
• Chinese (Simplified): zh_Hans
• Chinese (Traditional): zh_Hant
• Croatian: hr
• Czech: cs
• Danish: da
• Dutch: nl
• English (United Kingdom): en_GB
• English (United States): en_US
• Estonian: et
• Finnish: fi
• French (Canadian): fr_CA
• French: fr
• German: de
• Greek: el
• Hebrew: he
• Hindi: hi
• Hungarian: hu
• Indonesian: id
• Italian: it
• Japanese: ja
• Korean: ko
• Latvian: lv
• Lithuanian: lt
• Malay: ms
• Norwegian: nb
• Persian: fa
• Polish: pl
• Portuguese (Brazil): pt_BR
• Portuguese: pt
• Romanian: ro
• Russian: ru
• Serbian: sr_Latn
• Slovak: sk
• Slovenian: sl
• Spanish (Latin America): es_419
• Spanish: es
• Swedish: sv
• Thai: th
• Turkish: tr
• Ukrainian: uk
• Vietnamese: vi

However, you can add your own translations.

Android

By default, custom localisation is enabled on Android. There is no configuration needed on Cordova SDK to enable it. You could also provide custom translation for a locale that we don’t currently support, by having an additional XML strings file inside your resources folder for the desired locale. See Localisation section of Android SDK repo for the details.

iOS

You can also provide a custom translation for a locale that Onfido doesn't currently support. There is a simple configuration needed on the Cordova SDK to enable custom localisation.

1. Add this statement to your configuration object:

localisation: {
  ios_strings_file_name: '<Your .strings file name in iOS app bundle>',
},

2. Navigate to the iOS folder cd ios, and open your XCode workspace.
3. Follow the instructions for iOS Localisation to add a new custom language or override existing translations.
4. You can find the keys that need to be translated in the iOS SDK repo.

Creating checks

As the SDK is only responsible for capturing and uploading photos/videos, you would need to start a check on your backend server using the Onfido API.

1. Obtaining an API token

All API requests must be made with an API token included in the request headers. You can find your API token (not to be mistaken with the mobile SDK token) inside your Onfido Dashboard.

Refer to the Authentication section in the API documentation for details. For testing, you should be using the sandbox, and not the live token.

2. Creating a check

You will need to create a check by making a request to the create check endpoint, using the applicant id. If you are just verifying a document, you only have to include a document report as part of the check. On the other hand, if you are verifying a document and a face photo/live video, you will also have to include a facial similarity report with the corresponding values: facial_similarity_photo for the photo option and facial_similarity_video for the video option.

$ curl https://api.onfido.com/v3/checks \
    -H 'Authorization: Token token=YOUR_API_TOKEN' \
    -d 'applicant_id=YOUR_APPLICANT_ID' \
    -d 'report_names=[document,facial_similarity_photo]'

Note: You can also submit the POST request in JSON format.

You will receive a response containing the check id instantly. As document and facial similarity reports do not always return actual results straightaway, you need to set up a webhook to get notified when the results are ready.

Finally, as you are testing with the sandbox token, please be aware that the results are pre-determined. You can learn more about sandbox responses here.

Note: If you're using API v2, please check out API v2 to v3 migration guide to understand which changes need to be applied before starting to use API v3.

Theme Customization

You can customize the SDK by adding a colors.json file to your project at the same level as your node_modules directory. The file should contain a single json object with the desired keys and values. For example:

{
  "onfidoPrimaryColor": "#FF0000",
  "onfidoPrimaryButtonTextColor": "#008000",
  "onfidoPrimaryButtonColorPressed": "#FFA500",
  "onfidoAndroidStatusBarColor": "#A52A2A",
  "onfidoAndroidToolBarColor": "#800080",
  "onfidoIosSupportDarkMode": true
}

Below is a description of all available keys:

• onfidoPrimaryColor: Defines the background color of views such as the document type icon, capture confirmation buttons, and back navigation button.
• onfidoPrimaryButtonTextColor: Defines the text color of labels included in views such as capture confirmation buttons.
• onfidoPrimaryButtonColorPressed: Defines the background color of capture confirmation buttons when pressed.
• onfidoAndroidStatusBarColor: Android only. Defines the background color of the Toolbar that guides the user through the flow.
• onfidoAndroidToolBarColor: Android only. Defines the color of the status bar above the Toolbar.
• onfidoIosSupportDarkMode: iOS Only. Defines if Dark Mode will be supported on SDK screens. The value is true by default.

You should add the colors.json file to your xcode project as bundle resource. You can create symbolic link (rather than copy paste) to prevent redundancy. You can check out SampleApp project to see example usage. Then when running on an iOS device, the values will be picked up dynamically at runtime. For Android devices, to pick up the values, you will need to run the following command at the same level of your node_modules directory. This will also be run when running the npm --prefix node_modules/@onfido/onfido-cordova-sdk/ run updateOnfido command.

$ npm --prefix node_modules/@onfido/onfido-cordova-sdk/ run updateColors

Going live

Once you are happy with your integration and are ready to go live, please contact [e-mail] to obtain live versions of the API token and the mobile SDK token. You will have to replace the sandbox tokens in your code with the live tokens.

A few things to check before you go live:

• Make sure you have entered correct billing details inside your Onfido Dashboard

More Information

Troubleshooting

Resolving dependency conflicts

Here are some helpful resources if you are experiencing dependency conflicts between this Cordova SDK and other packages your app uses:

• Gradle: Dependency Resolution
• Gradle: Dependency Constraints

General advice

If you see issues, you can try removing node_modules, build directories, and cache files. Remove the platform specific projects and try to regenerate them.

Discrepancies between underlying Onfido native SDKs

Below is a list of known differences in expected behavior between the Onfido Android and iOS SDKs this Cordova SDK wraps:

• Documents with the type passport uploaded through the iOS SDK will have the side attribute set to null, while those uploaded via Android will have side as front.

Support

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

If you have any issues that contain sensitive information please send us an email with the ISSUE: at the start of the subject to [e-mail]

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

Copyright 2023 Onfido, Ltd. All rights reserved.

How is the Onfido Cordova SDK licensed?

The Onfido Cordova SDK is available under the MIT license.