App Components

Integration Options

App Components are standalone functionality modules for Android and iOS mobile apps. They capture images and data for you to upload via the API, leveraging Fourthline's data extraction AI services, and provide real-time feedback to the client. If you build custom user journeys, with your own UI, business logic, and orchestration, components reduce development time and effort.

Fourthline provides the UI for the components, which you can customize in the same way as the App Drop-in.
You can dynamically adjust functionality during workflows, e.g. disable the tilted photo step.

App Drop-in vs App Components

App Drop-in vs App Components


How it works

SDKs

We offer the following SDKs:

  • Android SDK and iOS SDK
  • Cordova, Flutter, and React Native plugins

Supported solutions

You can use App Components for the following solutions:

Workflow

The workflow is as follows:

Components workflow

Components workflow


Configuration

Error handling

You need to handle the following error values:

Android & iOS errors

Android & iOS errors

You need to handle the following error values:

ErrorDescription
CanceledThe client canceled the workflow.
Action: Consider creating a new validationCode.
ClientRejectedThe client was rejected.
Action: You cannot create a new workflow for this client.
ConfigurationNotSupportedThe workflowName created with the validationCode isn't supported.
Action: Consider updating your SDK to the latest version.
InvalidSessionThe WorkflowSession is invalid, e.g.
• "InvalidValidationCode": The validationCode is invalid.
• "SessionExpired": The WorkflowSession expired.
Action: Create a new validationCode.
InvalidWorkflowStatusThe workflow modules may have been completed successfully or finished with an error.
ModuleErrorThe client encountered an error in one of the workflow modules, e.g.:
• IdentityVerification.DocumentExpired:
The client's identity document has expired.
• IdentityVerification.DocumentTypeInvalid:
The MRZ of the identity document in the document photo is different from the document type selected by the client.
• IdentityVerification.DocumentTypeMismatch:
The scanned document type must match the selected document type.
• IdentityVerification.DocumentTypeNotSupported:
The client's document type isn't supported.
• IdentityVerification.IssuingCountryNotSupported:
The issuing country of the client's identity document isn't supported.
• IdentityVerification.NationalityNotSupported:
The client's nationality isn't supported.
• IdentityVerification.NoDocumentDetected:
No identity document was detected in the document photos.
• IdentityVerification.PersonNotAdult:
The client is underage.
UnexpectedAn unexpected error occurred.
Action: Immediately report this issue to Fourthline along with the message code.
Plugin errors

The error is returned as a JSON string with the following format:

{
  "errorCode": Integer,
  "errorDescription": String
}
Error codeError description
800Decoding Error
There was an error while decoding the workflow input.
Action: Check the errorDescription for more information.
802Invalid or missing font
The font wasn’t found.
Action: Check the errorDescription for more information.
803User canceled
The client explicitly canceled the workflow.
830JSON parse error
We couldn’t parse the JSON provided.
Action: Check the JSON provided.
850Incorrect configuration
The workflow wasn’t configured correctly.
Action: Check your workflow configuration.
870Unexpected message
An unexpected error occurred.
Action: Inform your Fourthline delivery manager immediately and provide the message code.
1000ClientRejected
The client was rejected.
You can’t retry.
1001InvalidSession
The current WorkflowSession is invalid.
• InvalidValidationCode: The validationCode is invalid.
• SessionExpired: The WorkflowSession expired.
Action: Create a new validationCode.
1002Module error
The client encountered an error in one of the workflow modules.
Action: For more information, check the message.

Possible module errors:
• IdentityVerification.DocumentExpired: The client’s identity document has expired.
• IdentityVerification.DocumentTypeInvalid: The MRZ of the identity document doesn’t match the selected document type.
• IdentityVerification.DocumentTypeMismatch: The scanned document type must match the selected document type.
• IdentityVerification.DocumentTypeNotSupported: The client’s document type isn’t supported.
• IdentityVerification.IssuingCountryNotSupported: The issuing country isn’t supported.
• IdentityVerification.NationalityNotSupported: The client’s nationality isn’t supported.
• IdentityVerification.NoDocumentDetected: No identity document was detected.
• IdentityVerification.PersonNotAdult: The client is underage.
1003ConfigurationNotSupported
The workflow configuration created using the validationCode isn’t supported.
Action: Update to the latest plugin version.
Action: For more information, check the message.
1004InvalidWorkflowStatus
The workflow status is invalid.
Action: Check if the workflow module ended successfully or with an error.

iOS configuration

To ensure the client has granted camera and location permissions, in the Info.plist file, add Privacy - Camera Usage Description and Privacy - Location When In Use Usage Description entries.

Real-time feedback

The components can send document/selfie 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. The component displays an additional screen where we perform further validations.

This ensures higher-quality photos are ultimately uploaded, reduces sendbacks, and improves the user experience.

Agree with your Fourthline delivery manager whether you want to enable real-time feedback for App Components.

UI customization

To customize each component's UI, create an OrcaFlavor object.

See App UI Customization.


Document, Biometrics, and QES Components

Use the Document Component to capture the client's identity document photos and video, based on your workflow configuration.

App Drop-in vs App Components

Document Component


Issuing country

The issuing country is only required for the client's primary identity document, not for Physical Proof of Address or tax documents.

When launching the Document Component, we check if you support the document type and issuing country.


Document types

The Document Component supports the following document types:

Document typeDescription
driversLicenseDriving license
dutchDriversLicenseDutch driving license
frenchIdCardFrench ID card
idCardID card
paperIdPaper ID
passportPassport
proofOfAddressProof of Address
residencePermitResidence permit
tinReferenceDocumentTIN document

Success handling

If the workflow ends successfully, the component returns the following result:

  • A documentResult object containing the document photos, document video, and the data extracted from the MRZ
  • A documentAnalysis object containing the data extracted from the document photos
struct DocumentComponentResult {
 let documentResult: WorkflowResults.Component.Document
 let documentAnalysis: WorkflowResults.Component.DocumentAnalysis?
}
{
  "documentResult":{
    "documentType":"String",
    "images":[
      {
        "image":"String",
        "isAngled":"Boolean",
        "timestamp":"String",
        "fileSide":"String",
        "location":{
          "latitude":"String",
          "longitude":"Number"
        }
      }
    ],
    "mrtdMrzInfo":{
      "rawMrz":"String",
      "documentCode":"String",
      "issuingCountry":"String",
      "documentNumber":"String",
      "expirationDate":"String",
      "firstNames":[
        "String"
      ],
      "lastNames":[
        "String"
      ],
      "birthDate":"String",
      "nationality":"String",
      "gender":"String",
      "validationErrors":[
        "ValidationError"
      ]
    },
    "idlMrzInfo":{
      "rawMrz":"String",
      "documentNumber":"String",
      "validationErrors":[
        "ValidationError"
      ]
    },
    "videoRecording":{
      "url":"String",
      "duration":"String",
      "location":{
        "latitude":"String",
        "longitude":"Number"
      }
    }
  },
  "documentAnalysis":{
    "firstName":"String",
    "lastName":"String",
    "initials":"String",
    "gender":"String",
    "nationality":"String",
    "issuingCountry":"String",
    "issueDate":"String",
    "expirationDate":"String",
    "dateOfBirth":"String",
    "birthPlace":"String",
    "documentNumber":"String",
    "documentType":"String",
    "taxIdentificationNumber":"String"
  }
}
Plugins documentResult attributes

All attributes are optional.

AttributeDescription
documentType
String
The identity document type.
images
Array of objects
Information about each document photo.
images.image
String
The absolute filepath to the document photo.
images.isAngled
Boolean
•True: The photo is tilted.
• False: The photo is flat.
images.timestamp
String
The timestamp for when the document photo was captured.
images.fileSide
String
The side of the identity document.
images.location
Object
The coordinates of the document photo.
images.location.latitude
String
The latitude of the document photo.
Format: Float between -90 and 90
Example: 45.464664
images.location.longitude
String
The longitude of the document photo.
Format: Float between -90 and 90
Example: 45.464664
mrtdMrzInfo
Object
The data extracted from the MRZ of a frenchIdCard, idCard, passport, or residencePermit.
mrtdMrzInfo.rawMrz
String
The raw data from the MRZ.
mrtdMrzInfo.documentCode
String
[Is this document type?]
mrtdMrzInfo.issuingCountry
String
The country that issued the identity document.
mrtdMrzInfo.documentNumber
String
The identity document number.
mrtdMrzInfo.expirationDate
String
The identity document expiry date.
Format: Date YYYY-MM-DD
mrtdMrzInfo.firstNames
Array of strings
The client's first name(s).
Format: Alphabetical characters, spaces, hyphens, and apostrophes
mrtdMrzInfo.lastNames
Array of strings
The client's last name(s).
Format: Alphabetical characters, spaces, hyphens, and apostrophes
mrtdMrzInfo.birthDate
String
The client's date of birth.
Format: Date YYYY-MM-DD
mrtdMrzInfo.nationality
String
The client's nationality.
Format: ISO 3166-1 alpha-3 country code
mrtdMrzInfo.gender
String
The client's sex.
• Female
• Male
• Other: identity document contains a value other than Female or Male
• Unknown: identity document contains no gender field
mrtdMrzInfo.validationErrors
Array of strings [Or integers?]
The validation error code(s).
idlMrzInfo
Object
The data extracted from the MRZ of a Dutch driving license.
idlMrzInfo.rawMrz
String
The raw data from the MRZ.
idlMrzInfo.documentNumber
String
The identity document number.
idlMrzInfo.validationErrors
Array of strings
The validation error code(s).
videoRecording
Object
Information about the document video.
videoRecording.url
String
The absolute url filepath to the document video.
videoRecording.duration
String
The length of the document video. [What unit of time? Seconds?]
videoRecording.location
Object
The coordinates of the document video.
videoRecording.location.latitude
String
The latitude of the document video.
Format: Float between -90 and 90
Example: 45.464664
videoRecording.location.longitude
String
The longitude of the document video.
Format: Float between -90 and 90
Example: 45.464664
Plugins documentAnalysis attributes

All attributes are optional.

AttributeDescription
firstName
String
The client's first name.
Format: Alphabetical characters, spaces, hyphens, and apostrophes
lastName
String
The client's last name.
Format: Alphabetical characters, spaces, hyphens, and apostrophes
initials
String
The client's initials.
Format: Alphabetical characters, spaces, hyphens, and apostrophes
gender
String
The client's sex.
• Female
• Male
• Other: identity document contains a value other than Female or Male
• Unknown: identity document contains no gender field
nationality
String
The client's nationality.
Format: ISO 3166-1 alpha-3 country code
issuingCountry
String
The country that issued the identity document.
issueDate
String
The date the identity document was issued.
Format: Date YYYY-MM-DD
expirationDate
String
The date the identity document expires.
Format: Date YYYY-MM-DD
dateOfBirth
String
The client's date of birth.
Format: Date YYYY-MM-DD
birthPlace
String
The city where the client was born.
documentNumber
String
The identity document number.
documentType
String
The identity document type.
taxIdentificationNumber
String
The client's TIN.

Testing

Start a TestMe session using any mock validation code:

import com.fourthline.networking.NetworkEnvironment
import com.fourthline.orca.Orca
import com.fourthline.orca.workflow.WorkflowConfig
import com.fourthline.orca.workflow.WorkflowSession
import com.fourthline.orca.workflow.workflowSession 

fun startSession(context: Context) {
  val config = WorkflowConfig(networkEnvironment = NetworkEnvironment.Mock)

  Orca
    .workflowSession(
      context = context,
      validationCode = "IDV",
    )
    .configure(config)
    .start { result ->
      result.fold(
        onSuccess = { session ->
          launchDocumentComponent(context, session)
        },
        onFailure = { workflowError ->
          print("Handle error... $workflowError")
        }
      )
    }

}

fun launchDocumentComponent(context: Context, session: WorkflowSession) {
  val flavor = OrcaFlavor()
  val documentConfig = DocumentComponentConfig(
    type = documentType, /// See the `DocumentType` table.
    issuingCountry = issuingCountry /// Format: ISO3 country code
  )

  session
    .documentComponent(context, documentConfig)
    .customize(DocumentCustomizationConfig(flavor))
    .present { result ->
      result.fold(
        onSuccess = { documentResult ->
          print("Upload document result...")
        },
        onFailure = { workflowError ->
          print("Handle error... $workflowError")
        }
      )
    }
}
import FourthlineSDK

override func viewDidLoad() {
  super.viewDidLoad()
  
  let customization = WorkflowConfig(
    networkEnvironment: .mock
  )
  Orca
  .workflowSession(validationCode: "IDV")
  .configure(with: customization)
  .start { [weak self] result in
      switch result {
      case let .success(session):
         launchDocumentComponent(session)
      case let .failure(workflowError):
         print("Handle error...\(workflowError)")
      }
  }		
}

func launchDocumentComponent(_ session: WorkflowSession) {
   session
   .documentComponent(with:
       DocumentComponentConfig(
         type: documentType, /// See the `DocumentType` table.
         issuingCountry: issuingCountry /// Format: ISO3 country code
       )
    )
   .customize(with: DocumentCustomizationConfig(flavor: orcaFlavor)
   .present { [weak self] result in
      switch result {
      case let .success(documentResult):
         print("Upload document result...")
      case let .failure(workflowError):
         print("Handle error...\(workflowError)")
      }
   }
}
function startWorkflowSession() {
  var config = `{
    "configuration": {
      "validationCode": "IDV",
      "networkEnvironment": "mock"
    }
  }`;
    
    
  FourthlinePlugin.startWorkflowSession(
    config,
    function(msg) {
       // The client has successfully started a workflow session.
       // You can now start a workflow component.
    },
    function(error) {
       // Extract and process information from the error.
       // See Error handling.
       
       var jsonError = JSON.parse(error.message);
    }
  );
}

function startWorkflowDocumentComponent() {
  var config = `{
    "configuration": {
      "documentType": "passport",
      "issuingCountry": "NLD"
    },
  }`;

  FourthlinePlugin.startWorkflowComponentDocument(
    config,
    function(msg) {
       // Use the componentResult to continue the user experience on your side.
    },
    function(error) {
       // Extract and process information from the error.
       // See Error handling.
       
       var jsonError = JSON.parse(error.message);
    }
  );
}

final _fourthlinePlugin = Fourthline();

startWorkflowSession() async {
  String config = """
    {
      "configuration": {
        "validationCode": "IDV",
        "networkEnvironment": "mock"
      }
    }
    """;

  try {
    String sessionResult = await _fourthlinePlugin.startWorkflowSession(config) ?? "Could not start Workflow Session";
    // The client has successfully started a workflow session.
    // You can now start a workflow component.
    startWorkflowComponent();
  } on PlatformException catch (e) {
    // Extract and process information from the error.
    // See Error handling.
  };
}

startWorkflowComponent() async {
  String config = """
    {
      "configuration": {
        "documentType": "passport",
        "issuingCountry": "NLD"
      },
    }
    """;

  try {
    String componentResult = await _fourthlinePlugin.startWorkflowComponentDocument(config) ?? "Could not start Workflow Document Component";
    // Use the componentResult to continue the user experience on your side.
  } on PlatformException catch (e) {
    // Extract and process information from the error.
    // See Error handling.
  };
}
function startWorkflowSession() {
  var config = `
    {
      "configuration": {
        "validationCode": "IDV",
        "networkEnvironment": "mock"
      }
    }
  `;

  NativeModules.Fourthline.startWorkflowSession(config)
       .then((result) => {
            // The client has successfully started a workflow session.
            // You can now start a workflow component.
	    startWorkflowComponent();
       })
       .catch((error) => {
            // Extract and process information from the error.
   	    // See Error handling.
       });
}


startWorkflowComponent() async {
  var config = `
    {
      "configuration": {
        "documentType": "passport",
        "issuingCountry": "NLD"
      },
    }
  `;

  NativeModules.Fourthline.startWorkflowComponentDocument(config)
       .then((result) => {
            // Use the componentResult to continue the user experience on your side.
       })
       .catch((error) => {
            // Extract and process information from the error.
            // See Error handling.
       });
}

Example

The following is a complete example:

import com.fourthline.networking.NetworkEnvironment
import com.fourthline.orca.Orca
import com.fourthline.orca.core.flavor.OrcaFlavor
import com.fourthline.orca.core.flavor.OrcaFonts
import com.fourthline.orca.document.DocumentCustomizationConfig
import com.fourthline.orca.workflow.DocumentComponentConfig
import com.fourthline.orca.workflow.WorkflowConfig
import com.fourthline.orca.workflow.WorkflowSession
import com.fourthline.orca.workflow.workflowSession
import java.io.File

fun startSession(context: Context) {
    // Make a POST Create SDK session request: https://{{baseUrl}}/v1/workflows/{{workflowId}}/validationcode.
    val validationCode = "xxxxxxxx"

    // To test the workflow offline, use Mock. To test networking, use Sandbox or Production.
    val config = WorkflowConfig(networkEnvironment = NetworkEnvironment.Mock)

    Orca
      .workflowSession(
        context = context,
        validationCode = validationCode,
      )
      .configure(config)
      .start { result ->
        result.fold(
          onSuccess = { session ->
            launchDocumentComponent(context, session)
          },
          onFailure = { workflowError ->
            print("Handle error... $workflowError")
          }
        )
      }
  }

  fun launchDocumentComponent(context: Context, session: WorkflowSession) {
    val customFlavor = OrcaFlavor(
      fonts = OrcaFonts(
        screenHeader = OrcaFonts.Font.FromFontRes(fontRes = R.font.roboto_medium, size = 20),
        primaryButton = OrcaFonts.Font.FromFile(file = File(...), size = 18
      ),
    )

    val documentConfig = DocumentComponentConfig(
      type = documentType, /// See the `DocumentType` table.
      issuingCountry = issuingCountry /// Format: ISO3 country code
    )

    session
      .documentComponent(context, documentConfig)
      .customize(DocumentCustomizationConfig(customFlavor))
      .present { result ->
        result.fold(
          onSuccess = { documentResult ->
            print("Upload document result...")
          },
          onFailure = { workflowError ->
            print("Handle error... $workflowError")
          }
        )
      }
  }
import FourthlineSDK

override func viewDidLoad() {
  super.viewDidLoad()
  
  let customization = WorkflowConfig(
    networkEnvironment: .mock // To test the workflow offline, use .mock. To test networking, use .sandbox or .production.
  )

  let validationCode = "xxxxxxxx" // Make a POST Create SDK session request: https://{{baseUrl}}/v1/workflows/{{workflowId}}/validationcode.
  
  Orca
  .workflowSession(validationCode: validationCode)
  .configure(with: customization)
  .start { [weak self] result in
     switch result {
     case let .success(session):
       launchDocumentComponent(session)
     case let .failure(workflowError):
       print("Handle error...\(workflowError)")
    }
  }		
}

func launchDocumentComponent(_ session: WorkflowSession) {
  var orcaFlavor = OrcaFlavor()
  
  // Configure the colors
  var palette = OrcaPalette()
  palette.primary = UIColor(red: 82.0 / 255.0, green: 30.0 / 255.0, blue: 135.0 / 255.0, alpha: 1)
  
  var colors = OrcaColors(colorPalette: palette)
  colors.hint.backgroundColor = UIColor(red: 221.0 / 255.0, green: 210.0 / 255.0, blue: 232.0 / 255.0, alpha: 0.5)
  colors.box.borderColor = UIColor.gray
  colors.screen.tableCells.cellStyle2.iconColor = UIColor(red: 221.0 / 255.0, green: 210.0 / 255.0, blue: 3.0 / 255.0, alpha: 1)
  orcaFlavor.colors = colors

  let documentType = .passport 
  let issuingCountry = "NLD"

  session
  .documentComponent(with:
     DocumentComponentConfig(
        type: documentType,
        issuingCountry: issuingCountry
     )
  )
  .customize(with: DocumentCustomizationConfig(flavor: orcaFlavor)
  .present { [weak self] result in
     switch result {
     case let .success(documentResult):
       print("Upload document result...")
     case let .failure(workflowError):
       print("Handle error...\(workflowError)")
     }
  }
}
// Call this after starting a valid WorkflowSession.
function startWorkflowDocumentComponent() {
  var config = `{
    "configuration": {
      "documentType": "passport",
      "issuingCountry": "NLD"
    },
    "customization": {
      ...
    }
  }`;

  FourthlinePlugin.startWorkflowComponentDocument(
    config,
    function(msg) {
       // Use the componentResult to continue the user experience on your side.
    },
    function(error) {
       // Extract and process information from the error.
       // See Error handling.
       
       var jsonError = JSON.parse(error.message);
    }
  );
}

final _fourthlinePlugin = Fourthline();

// Call this after starting a valid WorkflowSession.
startWorkflowComponent() async {
  String config = """
    {
      "configuration": {
        "documentType": "passport",
        "issuingCountry": "NLD"
      },
      "customization": {
        ...
      }
    }
    """;

  try {
    String componentResult = await _fourthlinePlugin.startWorkflowComponentDocument(config) ?? "Could not start Workflow Document Component";
    // Use the componentResult to continue the user experience on your side.
  } on PlatformException catch (e) {
    // Extract and process information from the error.
    // See Error handling.
  };
}
// Call this after starting a valid WorkflowSession.
startWorkflowComponent() async {
  String config = `
    {
      "configuration": {
        "documentType": "passport",
        "issuingCountry": "NLD"
      },
      "customization": {
       	"flavor": {
     	    "colors": ${orcaColors},
            "fonts": ${orcaFonts},
            "localization": ${orcaLocalization},
            "layouts": ${orcaLayout}
        }
     }
  }
  `;

  NativeModules.Fourthline.startWorkflowComponentDocument(config)
       .then((result) => {
            // Use the componentResult to continue the user experience on your side.
       })
       .catch((error) => {
            // Extract and process information from the error.
            // See Error handling.
       });
}

Plugin helpers

Clear workflow session

To delete any workflow resources after a Document, Biometrics, or QES component finishes and clear the workflow session, use the clearWorkflowSession function.

Before launching the component, call startWorkflowSession.

Fourthline.clearWorkflowSession(
  function(msg) {
    ...
  });
await _fourthlinePlugin.clearWorkflowSession()
NativeModules.Fourthline.clearWorkflowSession((error, success) => {});

Workflow session availability

To confirm that the workflow session is available before launching a Document, Biometrics, or QES component, use the isWorkflowSessionAvailable function.

Before launching the component, call startWorkflowSession.

Fourthline.isWorkflowSessionAvailable(
  function(msg) {
      if (msg == "true") {
      ...
      } else {
      ...
      }
)
if (await _fourthlinePlugin.isWorkflowSessionAvailable() ?? false) {
  ...
}
NativeModules.Fourthline.isWorkflowSessionAvailable((error, isAvailable) => {});