Cordova Plugin

Integrations guide

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

Prerequisites

  • You will need your:

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

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

ContentDescription
Source file Fourthline.ktSubclasses the mobile CordovaPlugin object that bridges the Cordova web environment and the fourthline-scanners framework
fourthline-scanners Android libraryContains 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 libraryProvides JSON interfacing with fourthline-scanners
Android frameworksProvide 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:

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

2. To support Kotlin and Androidx, make sure you have [email protected] platform.

3. 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
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:

ContentDescription
Source file Fourthline.swiftSubclasses the CordovaPlugin object that bridges the Cordova web environment and the FourthlineScanners framework
FourthlineScanners iOS frameworkContains 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 libraryProvides JSON interfacing with FourthlineScanners
iOS frameworksProvide 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:

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

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

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

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

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

6. 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>
Note
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.


Configuration

Age requirement

Configurable

You can dynamically configure the minimum client age requirement and the related checks during Identity Verification workflows.

Document data

Configurable

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

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

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.

Real-time feedback

Configurable

Agree with your implementation manager whether you want to enable real-time feedback. The SDKs send the document photos to our backend as soon as they are captured, where we assess the image quality and provide the client feedback in the UI in real time. This ensures higher-quality photos are ultimately uploaded, reduces sendbacks, and improves user experience.

Supported devices

Support
For questions about supported devices, contact your implementation manager.


Identity Verification

Setup

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

ValueDescription
productionLive environment
sandboxRemote testing environment
mockLocal testing environment with stubbed data

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

WorkflowCustomization is an optional field with the following format:

{
 "flavor": string
}

To customize the look and feel of the UI, see App UI Customization.

Example

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

Success handling

If the workflow is successful, all results are already processed and no additional response is returned.

Error handling

If the workflow is unsuccessful, the following JSON string is returned:

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

The following error codes are possible:

Error codeDescriptionAction
800Decoding errorCheck the errorDescription for more information.
802Invalid or missing fontCheck the errorDescription for more information.
803User canceledThe client explicitly canceled the workflow.
830JSON parse errorCheck the JSON provided.
850Incorrect configurationEnsure the workflow is configured correctly.
870Unexpected + messageInform your implementation manager immediately.
1000ClientRejectedThe client isn't eligible for the workflow.
You can't retry.
1001InvalidValidationCodeMake a new Create SDK session request.
1002Module error + messageThe client encountered an error in one of the workflow modules.
Check the message for more information.
1003ConfigurationNotSupported + messageThe workflow created using the validationCode isn't supported.
Consider updating to the latest plugin version.
1004InvalidWorkflowStatusCheck if the workflow module is already completed successfully or with an error.

Testing

To view a mock version, launch the various modules using the following mock validation codes:

ProductMock validation code
Identity VerificationIDV
Qualified Electronic Signature moduleQES
Bank Account Verification moduleBAV
CombinationsIDVandBAV
IDVandQES
IDVandBAVandQES
IDVandQESandBAV

Example code:

var config = `{
 "configuration": {
 "validationCode": "123456",
 "networkEnvironment": "mock"
 }
}`;


Fourthline.startWorkflow(config,
 function(msg) {
 // User has successfully completed the Workflow process.
 },
 function(error) {
 // Extract and process information from the error String received in JSON format
 }
);

Client Authentication

Setup

The configuration passed has the following JSON format:

{
  "customization": CcrCustomization
}

customization is an optional field. For more information, see App UI Customization.

CcrCustomization has the following format:

{
  "flavor": String
}

Example

// Use an empty json config if you do not wish to customize the Ccr flow
var config = `{}`;
// or pass the desired customization
var config = `{
  "customization": {
    "flavor": {
      "colors": ${orcaColors},
      "fonts": ${orcaFonts},
      "localization": ${orcaLocalization},
      "layouts": ${orcaLayout}
    }
  }
}`;

Fourthline.startCcr(config,
      function(msg) {
         // Extract and process information from the result String received in JSON format
         var jsonResult = JSON.parse(msg);
      },
      function(error) {
         // Extract and process information from the error String received in JSON format
         var jsonError = JSON.parse(error.message);
      }
);

Success handling

If the flow ends successfully, the outcome is returned as a JSON string:

{
    "image": String,
    "video": {
        "url": String,
        "duration": String,
        "location": {
            "latitude": String,
            "longitude": String
        }
    },
    "metadata": {
        "location": {
            "latitude": String,
            "longitude": String
        },
        "ipAddress": String,
        "region": String,
        "analyticsID": String,
        "osVersion": String,
        "model": String,
        "sdkVersion": String,
        "language": String,
        "osCompromised": Bool
    }
}
Attributes
AttributeDescriptionRequired
image
String
The absolute filepath to the selfie photo.
video
Object
The selfie video data.
Important: Delete the video files when they are no longer needed.
video.url
String
The absolute url filepath to the selfie video.
video.duration
String
The length of the selfie video.
The selfie scanner duration parameter is always set to default.
video.location
Object
The coordinates of the selfie video.
video.location.latitude
String
The latitude of the selfie video.
Format: Float between -90 and 90
Example: 45.464664
video.location.longitude
String
The longitude of the selfie video.
Format: Float between -90 and 90
Example: 45.464664
metadata
Object
The metadata of the client's device.
metadata.location
Object
The coordinates of the client's device.
metadata.location.latitude
String
The latitude of the client's device.
Format: Float between -90 and 90
Example: 45.464664
metadata.location.longitude
String
The longitude of the client's device.
Format: Float between -90 and 90
Example: 45.464664
metadata.ipAddress
String
The IP address of the client's device.
metadata.region
String
The region code of the client's device.Auto-filled
metadata.analyticsID
String
The analytics identifier.Auto-filled
metadata.osVersion
String
The OS version of the client's device.Auto-filled
metadata.model
String
The client's device model.Auto-filled
metadata.sdkVersion
String
The version of Fourthline's SDK.Auto-filled
metadata.language
String
The language of the client's device.Auto-filled
metadata.osCompromised
Bool
True: The client's device was jailbroken.
False: The client's device wasn't jailbroken.
Auto-filled

Error handling

If the flow ends unsuccessfully, the error is returned as a JSON string:

{
  "errorCode": Number,
  "errorDescription": String
}

You need to handle the following error values:

ErrorDescription
800 Decoding errorThere was an input decoding error.
For more information, see errorDescription.
802 Invalid or missing fontThe font provided wasn't found.
For more information, see errorDescription.
803 User canceledThe client explicitly canceled the flow.
830 Json parse errorWe couldn't parse the json provided.
850 Incorrect configurationThe configuration is incorrect.
870 UnexpectedAn unexpected error occurred. Immediately report this issue to Fourthline along with the errorDescription.

Testing

Example code:

var config = `{
  "enableTestMe": true
}`;

Fourthline.startCcr(config,
      function(msg) {
         // will never be called
      },
      function(error) {
         // will never be called
      }
);
Caution
Only use TestMe in debug mode because it doesn't return an outcome or CDD Report and isn't configurable. It throws an IllegalStateException when started outside a debuggable build.


Document Authentication

Setup

The configuration passed has the following JSON format:

{
  "configuration": CdrConfiguration,
  "customization": CdrCustomization
}

CdrConfiguration requires a list of supported countries and has the following format:

{
  "supportedCountries": Array
}

CdrCustomization has the following format:

{
  "flavor": String
}

customization is an optional field. For more information, see App UI Customization.

// or pass the desired customization
var config = '{
  "configuration":{
      "supportedCountries": $supportedCountries
   },
  "customization": {
    "flavor": {
      "colors": $orcaColors,
      "fonts": $orcaFonts,
      "localization": $orcaLocalization,
      "layouts": $orcaLayout
    }
  }
}';

Fourthline.startCdr(config,
        function(msg) {
            var jsonResult = JSON.parse(msg);
        },
        function(error) {
            var jsonError = JSON.parse(error.message);
        }
    );

Success handling

If the flow ends successfully, the outcome is returned as a JSON string:

{
   "document":{
      "expirationDate": String,
      "images":[
         {
            "fileSide": String,
            "image": String,
            "isAngled": Boolean,
            "timestamp": String
         }
      ],
      "number": String,
      "type": String,
      "videoRecording":{
         "duration": String,
         "url":  String
      }
   },
   "person":{
      "birthDate": String,
      "firstName": String,
      "gender": String,
      "lastName": String,
      "nationalityCode": String
   }
}
Attributes
AttributeDescription
document
Object
The ID document data.
document.expirationDate
String
The ID document expiry date.
Format: Date YYYY-MM-DD
document.images
Object
The document photo data.
document.images.fileSide
String
The side of the ID document.
document.images.image
String
The absolute filepath to the document photo.
document.images.isAngled
Boolean
True: The photo is tilted.
False: The photo is flat.
document.images.timestamp
String
The timestamp for when the document photo was captured.
document.number
String
The ID document number.
document.type
String
The ID document type.
document.videoRecording
Object
The document video data.
document.videoRecording.duration
String
The length of the document video.
document.videoRecording.url
String
The URL to the document video.
person
Object
The client's personal data.
person.birthDate
String
The client's date of birth.
Format: Date YYYY-MM-DD
person.firstName
String
The client's first name.
Format: Alphabetical characters, spaces, hyphens, and apostrophes
person.gender
String
The client's sex.
Female: Female in line with ID document
Male: Male in line with ID document
Other: ID document contains a value other than Male or Female
Unknown: ID document contains no gender field
person.lastName
String
The client's last name.
Format: Alphabetical characters, spaces, hyphens, and apostrophes
person.nationalityCode
String
The client's nationality.
Format: ISO 3166-1 alpha-3 country code

Error handling

If the flow ends unsuccessfully, the error is returned as a JSON string:

{
  "errorCode": Number,
  "errorDescription": String
}

You need to handle the following error values:

ErrorDescription
800 Decoding errorThere was an input decoding error.
For more information, see errorDescription.
802 Invalid or missing fontThe font provided wasn't found.
For more information, see errorDescription.
803 User canceledThe client explicitly canceled the flow.
830 Json parse errorWe couldn't parse the json provided.
850 Incorrect configurationThe configuration is incorrect.
870 UnexpectedAn unexpected error occurred. Immediately report this issue to Fourthline along with the errorDescription.
900 Document expiredThe client's ID document has expired.
901 Document type not supportedThe client's ID document type isn't supported.
902 Issuing country not supportedThe ID document issuing country isn't supported.
903 Nationality not supportedThe client's nationality isn't supported.
904 Person not adultThe client is underage.
905 Document type is invalidThe client's ID document type isn't valid.

Testing

Example code:

var config = '
{
  "enableTestMe": true
}
';


Fourthline.startCdr(config,
        function(msg) {
            // will never be called
        },
        function(err) {
            // will never be called
        }
    );
Caution
Only use TestMe in debug mode because it doesn't return an outcome or CDD Report and isn't configurable. It throws an IllegalStateException when started outside a debuggable build.


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().
Fourthline.setAnalyticsObserver(
    function(eventData) {
        // Handle eventData
    }
);

Example code for tracked event:

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

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.

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

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
Fourthline.deleteFourthlineFiles(
 function() {
 // Fourthline files deleted
 }
);

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

Top of page

Accordion in HTML5