This page sets out step-by-step instructions for setting up your App Drop-in via the Android SDK.

Prerequisites

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

Operating system specifications:

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

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 type	Description
MRZ data	Document 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

You can add the SDK to your project using Gradle.

1. In your top-level build.gradle file, link to Fourthline's repository:

allprojects {
 repositories {
 //...
 maven {
 url "https://maven.pkg.github.com/Fourthline-com/FourthlineSDK-Android"
 credentials {
 username ""
 password getLocalProperty("github_token")
 }
 }
 }
}

allprojects {
 repositories {
 //...
 maven {
 url = URI("https://maven.pkg.github.com/Fourthline-com/FourthlineSDK-Android")
 credentials {
 username = ""
 password = getLocalProperty("github_token")
 }
 }
 }
}

2. To access Fourthline's repository, in your GitHub account, go to Settings > Account security > Enable two-factor authentication.

3. Go to Settings > Developer settings > Personal access tokens > Generate a new token.

4. Select the scope "read:packages", and then generate a new token.

5. Store the access token in a secure, but accessible location, e.g. local.properties.

Tip

Treat the token as a password. Don't add it to your version control system.
If you have to share it, use a password manager.

Example code for local.properties:

//..
github_token=YOUR_ACCESS_TOKEN

6. In your module-level build.gradle file, add a dependency to the Fourthline SDK:

dependencies {
 // ...
 def fourthlineSdkVersion = "%%LATEST_SDK_VERSION%%"
 implementation "com.fourthline:fourthline-sdk:$fourthlineSdkVersion"
}

dependencies {
 // ...
 val fourthlineSdkVersion = "%%LATEST_SDK_VERSION%%"
 implementation("com.fourthline:fourthline-sdk:$fourthlineSdkVersion")
}

Error handling

You need to handle the following error values:

Name	Description
`Canceled`	The client canceled the workflow.
`ClientRejected`	The client isn't eligible for the Identity Verification workflow. You can't retry.
`ConfigurationNotSupported`	The workflow created with the validation code isn't supported. Action: Consider updating to the latest SDK version.
`InvalidValidationCode`	The validation code for the SDK session is invalid. Action: Get a new validation code.
`InvalidWorkflowStatus`	The status of the workflow is invalid, e.g. because the modules were completed successfully or with an error.
`ModuleError`	The client encountered an error in a workflow module.
	Identity Verification
	• `PersonNotAdult`: The client is underage.
	• `NationalityNotSupported`: The client's nationality isn't supported.
	• `IssuingCountryNotSupported`: The ID document issuing country isn't supported.
	• `DocumentExpired`: The ID document has expired.
	• `DocumentTypeNotSupported`: The ID document type isn't supported.
	Bank Account Verification
	• `Failed`: An unexpected generic error occurred.
	• `KycRequired`: The client must first pass Identity Verification.
	Qualified Electronic Signature
	• `TooManyResendOtpAttempts`: The one-time passcode was resent to the client too many times.
	• `TooManyAuthorizationAttempts`: The client tried to approve the documents to sign too many times.
	• `KycRequired`: The client must first pass Identity Verification.
`Unexpected`	An unexpected error occurred. Action: Contact your implementation manager immediately.

Testing

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

Product	Mock validation code
Identity Verification	`IDV`
Qualified Electronic Signature module	`QES`
Bank Account Verification module	`BAV`
Combinations	`IDVandBAV` `IDVandQES` `IDVandBAVandQES` `IDVandQESandBAV`

Example code:

val validationCode: String
val config = WorkflowConfig(networkEnvironment = Mock)

Orca.workflow(context, validationCode)
 .configure(config)
 .present { result -> }

Bank Account Verification

If your workflow includes Bank Account Verification, this module redirects to the Web SDK.

To redirect the client back to your app after completing the module in the web browser, you need to register a URL scheme.

For instructions, see Apple – Register your URL scheme.

Client Authentication

Setup

Configure the Client Authentication module:

import com.fourthline.orca.Orca
import com.fourthline.orca.ccr.ccr
val completionBlock: CcrCompletionBlock
val customization: CcrCustomizationConfig

Orca.ccr(context)
  .configure()
  .customize(customization)
  .present(completionBlock)

CcrCompletionBlock: The Client Authentication module uses callbacks to provide feedback. The output at the end of the flow is kotlin.Result, which is invoked once only, immediately after the App Drop-in shuts down. Our activity calls finish()).

Success handling

If the flow ends successfully, the onSuccess lambda is invoked:

import com.fourthline.orca.ccr.CcrCompletionBlock

CcrCompletionBlock { ccrResult ->
        ccrResult.fold(
            onSuccess = { TODO() },
            onFailure = { TODO() },
        )
    }

Error handling

If the flow fails for any reason, the onFailure lambda is invoked and Throwable is passed in:

import com.fourthline.orca.ccr.CcrCompletionBlock
import com.fourthline.orca.ccr.Canceled
import com.fourthline.orca.ccr.Unexpected

CcrCompletionBlock { ccrResult ->
  ccrResult.fold(
            onSuccess = { TODO() },
            onFailure = { error ->
                when (error) {
                    is CcrError -> when (error) {
                        is Canceled -> TODO()
                        is Unexpected -> TODO()
                    }
                    else -> TODO("Things went really bad, e.g. VirtualMachineError etc")
                }
            }
        )
    }

You need to handle the following error values:

Error	Description
`Canceled`	The client canceled the flow.
`Unexpected`	An unexpected error occurred. Immediately report this issue along with the message code.

Testing

Example code:

import com.fourthline.orca.Orca
import com.fourthline.orca.ccr.ccr

Orca.ccr(context).testMe()

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 Document Authentication configuration requires a list of supported countries:

import com.fourthline.orca.Orca
import com.fourthline.orca.cdr.CdrCompletionBlock
import com.fourthline.orca.cdr.CdrConfig
import com.fourthline.orca.cdr.CdrCustomizationConfig
import com.fourthline.orca.cdr.cdr

val completionBlock: CdrCompletionBlock
val customization: CdrCustomizationConfig
val configuration = CdrConfig(
    supportedCountries = listOf(...)
)

Orca.cdr(context)
  .configure(configuration)
  .customize(customization)
  .present(completionBlock)

CdrCompletionBlock: The Document Authentication module uses callbacks to provide feedback. The output at the end of the flow is kotlin.Result, which is invoked once only, immediately after the App Drop-in shuts down. Our activity calls finish()).

Success handling

If the flow ends successfully, the onSuccess lambda is invoked:

import com.fourthline.orca.cdr.CdrCompletionBlock

CdrCompletionBlock { cdrResult ->
        cdrResult.fold(
            onSuccess = { TODO() },
            onFailure = { TODO() },
        )
    }

Error handling

If the flow fails for any reason, the onFailure lambda is invoked and Throwable is passed in:

import com.fourthline.orca.cdr.CdrCompletionBlock
import com.fourthline.orca.cdr.*

CdrCompletionBlock { cdrResult ->
  cdrResult.fold(
            onSuccess = { TODO() },
            onFailure = { error ->
                when (error) {
                    is CdrError -> when (error) {
                      is Canceled -> TODO()
                      is DocumentExpired -> TODO()
                      is DocumentTypeInvalid -> TODO()
                      is DocumentTypeNotSupported -> TODO()
                      is IssuingCountryNotSupported -> TODO()
                      is NationalityNotSupported -> TODO()
                      is PersonNotAdult -> TODO()
                      is Unexpected -> TODO()
                    }
                    else -> TODO("Things went really badly, e.g. VirtualMachineError etc")
                }
            }
        )
    }

You need to handle the following error values:

Error	Description
`Canceled`	The client canceled the flow.
`DocumentExpired`	The client's ID document has expired.
`DocumentTypeInvalid`	The MRZ of the ID document in the document photo is different from the document type selected by the client.
`DocumentTypeNotSupported`	The client's document type isn't supported. Check the list of supported countries and documents.
`IssuingCountryNotSupported`	The issuing country of the client's ID document isn't supported. Check the list of supported countries and documents.
`NationalityNotSupported`	The client's nationality isn't supported. Check the list of supported countries and documents.
`PersonNotAdult`	The client is underage.
`Unexpected`	An unexpected error occurred. Immediately report this issue to Fourthline along with the message code.

Testing

Example code:

import com.fourthline.orca.Orca
import com.fourthline.orca.cdr.cdr

Orca.cdr(context).testMe()

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 Android SDK 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(...) with TrackingConsent set to granted.

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

import com.fourthline.analytics.AnalyticsObserver
import com.fourthline.analytics.FourthlineAnalytics

val observer = object : AnalyticsObserver {
    override fun log(event: String, attributes: Map<String, Any?>) {
        // Log the Fourthline event
    }
}

FourthlineAnalytics.setObserver(observer)

Data delegate

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

import com.fourthline.orca.Orca
import com.fourthline.orca.workflow.WorkflowResults.*
import com.fourthline.orca.workflow.workflow

Orca.workflow(context, validationCode)
  .configure(config)
  .customize(customisationConfig)
  .addDelegate { results ->
    when(results){
      is IDV.Address -> TODO()
      is IDV.DeviceMetadata -> TODO()
      is IDV.Document -> TODO()
      is IDV.DocumentVideo -> TODO()
      is IDV.Nfc -> TODO()
      is IDV.Person -> TODO()
      is IDV.Selfie -> TODO()
      is IDV.SelfieVideo -> TODO()
    }
  }
  .present { result -> }

Temporary files

The SDK stores 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 a 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 onDestroy().

context.deleteFourthlineFiles()

FourthlineFileManager.deleteFourthlineFiles(context);

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