Cordova plugin

This page sets out step-by-step instructions for setting up your App Drop-in with the Cordova plugin.

Prerequisites & configuration

You will need your:

fourthlineGithubToken
tenantId provided by your implementation manager

Check the following prerequisites and specifications for your operating system:

Android prerequisites

Minimum API version: 23
Minimum supported Android API level: 23
Language: The SDK is written in Kotlin but is also compatible with Java.

The plugin contains the following:

Content	Description
Source file `Fourthline.kt`	Subclasses the mobile `CordovaPlugin` object that bridges the Cordova web environment and the `fourthline-scanners` framework
`fourthline-scanners` Android library	Contains the following drop-in modules: • Identity Verification flow • Workflows API • Document, Biometrics, and NFC scanners • Location provider • Identity data validator and zipper
`fourthline-adapters-json` Android library	Provides JSON interfacing with `fourthline-scanners`
Android frameworks	Provide functionalities for `fourthline-scanners`: • `fourthline-core`: Orchestration and analytics functionality • `fourthline-vision`: Document and Biometrics scanners • `fourthline-nfc`: NFC scanner • `fourthline-nfc-assets`: NFC chip processing functionality • `fourthline-kyc`: Identity data management functionality • `fourthline-sdk` • `Lottie`: Animations functionality

To resolve the dependencies on Fourthline's Android SDK, declare and authenticate in our Maven repository:

Add your fourthlineGithubToken as a Gradle Property for your environment.

Tip

It is good practice to prevent committing tokens with your source code.
Consider configuring the token from your Gradle Home directory or providing it via the command line.

To support Kotlin and Androidx, make sure you have [email protected] platform.
Because Kotlin 1.9 doesn't use the kotlin-android-extensions plugin generated by the Cordova framework, in the /platforms/android/app/build.gradle file, remove the line apply plugin: 'kotlin-android-extensions'.

Note

Data is transferred between Cordova and our plugin API via JSON formatted Strings, both as input configuration options and payload responses.

iOS prerequisites

Minimum iOS version: 12
Minimum XCode version: 14.3
Minimum iOS deployment target: 12.0
MRZ detection in the document scanner requires minimum iOS 13.

The plugin contains the following:

Content	Description
Source file `Fourthline.swift`	Subclasses the `CordovaPlugin` object that bridges the Cordova web environment and the `FourthlineScanners` framework
`FourthlineScanners` iOS framework	Contains the following drop-in modules: • Identity Verification flow • Workflows API • Document, Biometrics, and NFC scanners • Location provider • Identity data validator and zipper
`fourthline-adapters-json` iOS library	Provides JSON interfacing with `FourthlineScanners`
iOS frameworks	Provide functionalities for `FourthlineScanners`: • `FourthlineCore`: Orchestration and analytics functionality • `FourthlineVision`: Document and Biometrics scanners • `FourthlineNFC`: NFC scanner • `FourthlineKYC`: Identity data management functionality • `FourthlineSDK`

Before you set up the plugin, make the following preparations:

In the Info.plist file, add the following keys required to access the camera and NFC functionalities:

<key>NSCameraUsageDescription</key>
<string>To verify your identity, please allow us to access your camera once only.</string>

To enable NFC functionality, in the XCode Signing & Capabilities tab, enable the Near Field Communication Tag Reading capability, containing the following values:

Tag-Specific Data Protocol (TAG)
Password Authenticated Connection Establishment (PACE)

Note

The YOUR_PROJECT_NAME.entitlements file is added to your project automatically.

Entitlements file source code:

 <dict>
 <key>com.apple.developer.nfc.readersession.formats</key>
 <array>
 <string>TAG</string>
 <string>PACE</string>
 </array>
 </dict>

To access the NFC functionality, in the Info.plist file, add the following keys:

<key>NFCReaderUsageDescription</key>
<string>To read the chip in your ID document, please enable NFC.</string>

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
 <string>A0000002471001</string>
 <string>A00000045645444C2D3031</string>
</array>

Optionally, to access the microphone functionality to record audio in the document and selfie videos, in the Info.plist file, add the following key:

<key>NSMicrophoneUsageDescription</key>
<string>To verify your identity, please allow access to your microphone.</string>

Optionally, to access the client's device geolocation, in the Info.plist file, add the following keys:

<key>NSLocationWhenInUseUsageDescription</key>
<string>To verify your identity, please allow access to your location.</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>To verify your identity, please allow access to your location.</string>

<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dictionary>
	<key>FourthlineFullAuthorizationPurposeKey</key>
 <string>To verify your identity, your exact location is shared with us once only.</string>
</dictionary>

If customizing the fonts in the UI, add the font files to your project and to the projects' Info.plist file:

<key>UIAppFonts</key>
	<array>
		<string>Your-Font-Medium.ttf</string>
		<string>Your-Font-Regular.ttf</string>
	</array>

Notes

• Data is transferred between Cordova and our plugin API via JSON formatted Strings, both as input configuration options and payload responses.
• Fourthline's scanners are designed to be implemented and tested on a real mobile device. Launching them on the iOS simulator throws a scanner error.

GitHub credentials

Provide your implementation manager with the GitHub usernames and email addresses of your staff who need access to our repositories.

Identity data

Configurable

If you want to receive a copy of the identity data gathered by the App Drop-in when it's uploaded to our backend (before case processing), let your implementation manager know.

Document data

Configurable

Discuss with your implementation manager what data to extract from ID document photos via optical character recognition (OCR):

Data type	Description
MRZ data	Document data is extracted from the MRZ only and is processed offline by the SDK.
MRZ & VIZ data	For greater accuracy, document data is extracted from the MRZ and VIZ and processed by our AI agent in real time.

Supported devices

More information

For questions about supported devices, contact your implementation manager.

Flow

Follow these steps:

1. Set up plugin

To setup the plugin, in package.json, add com-fourthline-plugin-cordova using the following command:

cordova plugin add https://github.com/Fourthline-com/Fourthline-Cordova

2. Set up analytics

The FourthlineCore module collects and processes metrics.

You can set up an analytics observer for the SDK to forward Fourthline events to.

Events are only forwarded when you initialize FourthlineAnalytics by calling FourthlineAnalytics.initialize(...) and TrackingConsent is set to granted.

To set up the observer, call FourthlineAnalytics.setObserver(...).
To remove the observer, call FourthlineAnalytics.removeObserver().

Example code:

Fourthline.setAnalyticsObserver(
    function(eventData) {
        // Handle eventData
    }
);

Example code for tracked event:

{
  "event": string,
  "attributes": Object
}

3. Configure workflow

Pass the following JSON configuration to the workflow:

{
 "configuration": WorkflowConfiguration,
 "customization": WorkflowCustomization
}

WorkflowConfiguration has the following format:

{
 "networkEnvironment": NetworkEnvironment, // To test a workflow locally use .mock, and to test workflow networking use .sandbox
 "validationCode": string, // Returned in the Create SDK session response
}

NetworkEnvironment can have the following values:

Value	Description
`production`	Live environment
`sandbox`	Remote testing environment
`mock`	Local testing environment with stubbed data

To get the ValidationCode, make a Create SDK session request.

WorkflowCustomization is an optional field.
To customize the look and feel of the UI, see App Drop-in UI Customization.
It has the following format:

{
 "flavor": string
}

Example code:

var config = `{
 "configuration": {
 "validationCode": "123456",
 "networkEnvironment": "sandbox"
 },
 "customization": {
 "flavor": {
 "colors": ${orcaColors},
 "fonts": ${orcaFonts},
 "localization": ${orcaLocalization},
 "layouts": ${orcaLayout}
 }
 }
}`;

Fourthline.startWorkflow(config,
 function(msg) {
 // Client has successfully completed the workflow
 // No further action required
 },
 function(error) {
 // Extract and process the information received in JSON error string format
 var jsonError = JSON.parse(error.message);
 }
);

If the workflow is:

Successful: All results are already processed and no additional response is returned.
Unsuccessful: The following JSON string is returned:

{
 "errorCode": number,
 "errorDescription": string
}

The following error codes are possible:

Error code	Description	Action
`800`	Decoding error	Check the `errorDescription` for more information.
`802`	Invalid or missing font	Check the `errorDescription` for more information.
`803`	User canceled	The client explicitly canceled the workflow.
`830`	JSON parse error	Check the JSON provided.
`850`	Incorrect configuration	Ensure the workflow is configured correctly.
`870`	Unexpected + message	Inform your implementation manager immediately.
`1000`	ClientRejected	The client isn't eligible for the workflow. You can't retry.
`1001`	InvalidValidationCode	Make a new Create SDK session request.
`1002`	Module error + message	The client encountered an error in one of the workflow modules. Check the message for more information.
`1003`	ConfigurationNotSupported + message	The workflow created using the `validationCode` isn't supported. Consider updating to the latest plugin version.
`1004`	InvalidWorkflowStatus	Check if the workflow module is already completed successfully or with an error.

4. Add data observer

To receive notifications for each data group that the SDK uploads to Fourthline and a copy of the data itself, add a data observer.

Example code:

Fourthline.setWorkflowDataObserver(
 function(dataJson) {
 // Handle dataJson
 }
);

// Remove observer
Fourthline.removeWorkflowDataObserver();

The notifications per data type have the following JSON structure:

"idv":{
  "document":{
    "type":"string",
    "number":"string",
    "issueDate":"string", // Optional, format YYYY-MM-DD
    "expirationDate":"string", // Optional, format YYYY-MM-DD
    "images":[
      {
        "image":"string",
        "fileSide":"string",
        "isAngled":"boolean",
        "timestamp":"string", // Optional, format "YYYY-MM-dd'T'HH:mm:ssZZZZZ"
        "location":{
          "latitude":"number",
          "longitude":"number"
        }
      }
    ]
  }
}

"idv":{
  "documentVideo":{
    "url":"string",
    "duration":"string", // Default / extended
    "location":{ // Optional
      "latitude":"number",
      "longitude":"number"
    }
  }
}

"idv":{
  "selfie":{
    "image":"string",
    "timestamp":"string", // Optional
    "location":{ // Optional
      "latitude":"number",
      "longitude":"number"
    }
  }
}

"idv":{
  "selfieVideo":{
    "url":"string",
    "duration":"string", // Default / extended
    "location":{ // Optional
      "latitude":"number",
      "longitude":"number"
    }
  }
}

"idv":{
  "nfc":{
    "image":"string", // Optional
    "timestamp":"string",
    "location":{ // Optional
      "latitude":"number",
      "longitude":"number"
    },
    "mrz":"string",
    "dataGroups":[ // Optional
      {
        "groupNumber":"Int",
        "data":"string"
      }
    ]
  }
}

"idv":{
  "address":{
    "street":"string",
    "streetNumber":"Int",
    "streetNumberSuffix":"string", // Optional
    "postalCode":"string",
    "city":"string",
    "countryCode":"string",
    "region":"string" // Optional
  }
}

"idv":{
  "person":{
    "firstName":"string",
    "middleName":"string", // Optional
    "lastName":"string",
    "gender":"string",
    "nationalityCode":"string",
    "birthCountryCode":"string", // Optional
    "birthPlace":"string", // Optional
    "birthDate":"string" // Format YYYY-MM-DD
  }
}

"idv":{
  "deviceMetadata":{
    "model":"string",
    "sdkVersion":"string",
    "osVersion":"string",
    "language":"string",
    "osCompromised":"string",
    "location":{ // Optional
      "latitude":"number",
      "longitude":"number"
    }
  }
}

5. Delete temporary files

The plugins store some data collected during workflows (e.g. selfie and document videos) in the tmp/fourthline folder in the client's device filesystem. This is because the videos must remain available until collected, packaged into the case zipfile, and uploaded to our backend.

You must delete the temporary files when they are no longer needed, e.g. after the SDK has uploaded all data to Fourthline or immediately before the app is terminated in:

Android: onDestroy()
iOS: applicationWillTerminate

Example code:

Fourthline.deleteFourthlineFiles(
 function() {
 // Fourthline files deleted
 }
);

Success

You have configured and set up your App Drop-in!
To integrate your solutions, see the Integration Guides.

Top of page

Accordion in HTML5