@onfido/cordova-sdk

Table of contents

• Table of contents
• Overview
  • Environments and testing with the SDK
  • Going Live
• Adding the SDK dependency
  • Adding the Onfido Cordova SDK to your project
  • Adding SDK dependency through npm
  • NFC capture using Onfido Studio
• Initializing the SDK
  • Defining a workflow
  • SDK authentication
  • Starting the flow
  • UI customization
  • Dark theme
  • Language localization
• Completing a session
  • onComplete - Success Callback
  • onError - Failure Callback
  • Generating verification reports
• More Information
  • Troubleshooting
  • Discrepancies between underlying Onfido native SDKs
• Support
• License Information

Overview

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

• Carefully designed UX to guide your customers through the different photo or video capture processes
• Modular design to help you seamlessly integrate the different photo or video capture processes into your application's flow
• Advanced image quality detection technology to ensure the quality of the captured images meets the requirement of the Onfido identity verification process, guaranteeing the best success rate
• Direct image upload to the Onfido service, to simplify integration
• A suite of advanced fraud detection signals to protect against malicious users

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

Environments and testing with the SDK

Two environments exist to support the Onfido SDK integrations:

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

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

Going Live

Once you are satisfied with your integration and are ready to go live, please contact [e-mail] to obtain a live API token. You will have to replace the sandbox token in your code with the live token.

Check that you have entered correct billing details inside your Onfido Dashboard, before going live.

Adding the SDK dependency

• Supports iOS 13+
• Supports Xcode 15+
• Supports Android API level 21+

Adding the Onfido Cordova SDK to your project

Note: 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

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

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

1. Add your code and resources:

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

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

1. 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 ("android" or "ios").

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

Adding SDK dependency through npm

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

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

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

Update your iOS configuration files

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

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

NFC capture using Onfido Studio

Recent passports, national identity cards and residence permits contain a chip that can be accessed using Near Field Communication (NFC). The Onfido SDKs provide a set of screens and functionalities to extract this information, verify its authenticity and provide the resulting verification as part of a Document report.

From version 11.0.0 onwards, NFC is enabled by default in the Onfido Cordova SDK for Android and iOS and offered to customers when both the document and the device support NFC.

For more information on how to configure NFC and the list of supported documents, please refer to the NFC for Document Report guide.

Enabling NFC extraction for iOS

For iOS, the NFC feature requires Near Field Communication Tag Reading capability in your app target. If you haven't added it before, please follow the steps in Apple's documentation.

Additionally to support NFC PACE documents (such as European National ID cards), you need to edit app entitlements:

• Add a new entry nested under the Near Field Communication Tag Reader Session Formats key
• Select Password Authenticated Connection Establishment (PACE) from the dropdown list Alternatively you can also edit your entitlements as shown in the sample file below.

To support NFC in your target app, your application's config.xml file should contain the following:

<platform name="ios">
    <config-file target="*-Info.plist" parent="NFCReaderUsageDescription">
        <string>Required to read ePassports</string>
    </config-file>

    <config-file target="*-Info.plist" parent="com.apple.developer.nfc.readersession.felica.systemcodes">
        <array>
            <string>12FC</string>
        </array>
    </config-file>

    <config-file target="*-Info.plist" parent="com.apple.developer.nfc.readersession.iso7816.select-identifiers">
        <array>
            <string>A0000002471001</string>
            <string>A0000002472001</string>
            <string>00000000000000</string>
            <string>D2760000850101</string>
        </array>
    </config-file>

    <!-- Required for NFC PACE (Password Authenticated Connection Establishment) -->
    <config-file target="*-Debug.plist" parent="com.apple.developer.nfc.readersession.formats">
        <array>
            <string>PACE</string>
            <string>TAG</string>
        </array>
    </config-file>

    <config-file target="*-Release.plist" parent="com.apple.developer.nfc.readersession.formats">
        <array>
            <string>PACE</string>
            <string>TAG</string>
        </array>
    </config-file>
</platform>

Disabling NFC

NFC is enabled by default. To disable NFC, include the disableNFC parameter while configuring the Onfido.start function:

config = {
	sdkToken: "<YOUR_SDK_TOKEN>",
	workflowRunId: "<YOUR_WORKFLOW_RUN_ID>",
	disableNFC: "true",
};

For Android, a range of NFC library dependencies are included in the build automatically. In addition to configuring the disableNFC parameter, you must remove any libraries from the build process.

Exclude dependencies required for NFC from your build:

dependencies {
  implementation 'com.onfido.sdk.capture:onfido-capture-sdk:20.+' {
    exclude group: 'net.sf.scuba', module: 'scuba-sc-android'
    exclude group: 'org.jmrtd', module: 'jmrtd'
    exclude group: 'com.madgag.spongycastle', module: 'prov'
  }
}

If your application already uses the same libraries that the Onfido SDK needs for the NFC feature, you may encounter some dependency conflicts that will impact and could interfere with the NFC capture in our SDK. In such cases, we propose using the dependency resolution strategy below, by adding the following lines to your build.gradle file:

implementation ("com.onfido.sdk:onfido-capture-sdk:20.+"){
     exclude group: "org.bouncycastle"
 }
 implementation ("the other library that conflicts with Onfido on BouncyCastle") {
     exclude group: "org.bouncycastle"
 }

 implementation "org.bouncycastle:bcprov-jdk15to18:1.69"
 implementation "org.bouncycastle:bcutil-jdk15to18:1.69"

Initializing the SDK

The Onfido Cordova SDK has multiple initialization and customization options that provide flexibility to your integration.

Defining a workflow

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

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

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

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

Applicant ID reuse

When defining workflows and creating identity verifications, we highly recommend saving the applicant_id against a specific user for potential reuse. This helps to keep track of users should you wish to run multiple identity verifications on the same individual, or in scenarios where a user returns to and resumes a verification flow.

SDK authentication

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

Parameter	Notes
applicant_id	required Specifies the applicant for the SDK instance.
application_id	required The application ID (for iOS "application bundle ID") that was set up during development.

• For iOS, the application_id 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, refer to this Stack Overflow Page.
• For Android, the application_id 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, refer to this Stack Overflow Page.

It's important to note that SDK tokens expire after 90 minutes.

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

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

Starting the flow

You can launch the app with a call to Onfido.start with the following configuration options:

• workflowRunId: Required. This is the identifier derived from your current active workflow. See section Defining a Workflow
• sdkToken: Required. This is the JWT sdk token obtained by making a call to the SDK token API. See section SDK Authentication.
• localisation: Optional. This object contains localization configuration. See section Localization for the details.

For more information on the onComplete and onError callbacks, see section Completing a Session.

Once you have the sdkTokenFromOnfidoServer, your code might look like this:

async function runOnfidoSdk(withDocSelfy, withMotion, workflowRunId) {
  const config = {
    sdkToken: <<SDK_TOKEN>>,
    workflowRunId: "my-workflow-run-uuid",
    localisation: {
      ios_strings_file_name: 'Localizable',
    },
  }

  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);
}

UI customization

For both iOS and Android, the Cordova SDK supports the customization of colors, fonts and strings used in the SDK flow.

Android

The customization of colors and other appearance attributes for Android is implemented according to the same methodology as the native Android SDK. You can find detailed documentation here.

For a complete list and visualizations of the customizable attributes, refer to our SDK customization guide.

Customizing Dimensions

To customize supported dimensions, you can add an Android resource file called dimens.xml in the following directory of your project: platforms/android/app/src/main/res/values.

For example:

<resources>
  <dimen name="onfidoButtonCornerRadius">8dp</dimen>
</resources>

The following dimension is currently supported:

• onfidoButtonCornerRadius: The corner radius of all buttons in the SDK, provided in the dp unit

iOS

For iOS, you can customize colors and other appearance attributes by adding a colors.json file to your Xcode project as a bundle resource. The file should contain a single json object with the desired keys and values. For example:

{
  "onfidoPrimaryColor": "#FF0000",
  "backgroundColor": {
    "light": "#FCFCFD",
    "dark": "#000000"
  },
  "onfidoPrimaryButtonTextColor": "#FFFFFF",
  "onfidoPrimaryButtonColorPressed": "#FFA500",
  "interfaceStyle": <"unspecified" | "light" | "dark">,
  "secondaryTitleColor": "#FF0000",
  "secondaryBackgroundPressedColor": "#FF0000",
  "buttonCornerRadius": 20,
  "fontFamilyTitle": "FONT_NAME_FOR_TITLES",
  "fontFamilyBody": "FONT_NAME_FOR_CONTENT",
}

For a complete list and visualizations of the customizable attributes, refer to our SDK customization guide.

Dark theme

The Cordova SDK supports the dark theme. By default, the user's active device theme will be automatically applied to the Onfido SDK. However, you can opt out from dynamic theme switching at run time and instead set a theme statically at the build time as shown below. In this case, the flow will always be displayed in the selected theme regardless of the user's device theme.

Android

Dark theme customization for Android is implemented according to the same methodology as the native Android SDK. You can find detailed documentation here.

iOS

Dark theme customization for iOS is implemented according to the same methodology as the native Android SDK. You can find detailed documentation here.

Language localization

The Cordova SDK supports and maintains translations for over 40 languages, available for use with both Android and iOS.

The SDK will detect and use the end user's device language setting. If the device's language is not supported by Onfido, the SDK will default to English (en_US).

For a complete list of the languages Onfido supports, refer to our SDK customization guide.

Custom languages for Android

You can also provide a custom translation for a specific language or locale that Onfido does not currently support, by having an additional XML strings file inside your resources folder for the desired locale. See our Android localization documentation for more details.

Custom languages for iOS

For iOS, you can also provide a custom translation for a specific language or locale that Onfido does not currently support. To configure this on the Cordova SDK:

1. Add this statement to your configuration object.

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

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

Completing a session

When the Onfido SDK session concludes, a range of callback functions may be triggered.

For documentation regarding handling callbacks, please refer to our native iOS and Android documentation.

onComplete - Success Callback

Depending on the tasks present in your workflow, the onComplete callback may include a face and document section.

Example:

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

onError - Failure Callback

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.

The onError callback will include a payload as below:

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

Generating verification reports

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

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

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

Should you encounter any technical issues during integration, please contact Onfido's Customer Support.

Alternatively, you can search the support documentation available via the customer experience portal, public.support.onfido.com.

We recommend that you update your SDK to the latest version release as frequently as possible. Customers on newer versions of the Onfido SDK consistently see better performance across user onboarding and fraud mitigation, so we strongly advise keeping your SDK integration up-to-date.

You can review our full SDK versioning policy here.

License Information

The Onfido Cordova SDK is available under the MIT license.

Copyright 2024 Onfido, Ltd. All rights reserved.