App Drop-in Setup
Integrations guide
Android SDK
This page sets out step-by-step instructions for setting up your App Drop-in via the Android SDK.
Prerequisites & configuration
You will need your tenantId
provided by Fourthline.
Operating system specifications:
- Minimum API version: 23
- Language: The SDK is written in Kotlin but is also compatible with Java.
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
Flow
Follow these steps:
1. Add SDK to project
You can add the SDK to your project using Gradle.
- 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")
}
}
}
}
-
To access Fourthline's repository, in your GitHub account, go to Settings > Account security > Enable two-factor authentication.
-
Go to Settings > Developer settings > Personal access tokens > Generate a new token.
-
Select the scope "read:packages", and then generate a new token.
-
Store the access token in a secure, but accessible location, e.g.
local.properties
.
If you have to share it, use a password manager.
Example code for local.properties
:
//..
github_token=YOUR_ACCESS_TOKEN
- 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")
}
2. Set up analytics
The FourthlineCore
module collects and processes Android SDK metrics.
To enable analytics data collection and sharing:
- Initialize
FourthlineAnalytics
with your FourthlinetenantId
.
TrackingConsent
determines what data the SDK should collect and send to Fourthline, using. Set it to one of the following values:
Value | Description |
---|---|
.pending (default) | The SDK starts collecting and batching the data but doesn't send it to Fourthline. It waits for a new tracking consent value to decide what to do with the batched data. |
.granted | The SDK collects data and sends it to Fourthline. Any already batched data is sent to Fourthline. |
.notGranted | The SDK doesn't collect any data and events aren't sent to Fourthline. Any batched data is wiped. |
Debug mode | The SDK doesn't collect or send any data when running attached to the debugger. |
Example code:
// To initialize analytics, call `FourthlineAnalytics.initialize(TENANT_ID, context)` when suitable, usually in `Application.onCreate()`, using your `tenantId`.
try {
FourthlineAnalytics.initialize(tenantId = "<tenantId>", context = applicationContext)
} catch (e: AnalyticsError) {
when (e) {
is AnalyticsError.DatadogNotImported -> TODO()
is AnalyticsError.InvalidTenantId -> TODO()
}
}
FourthlineAnalytics.setTrackingConsent(consent = TrackingConsent.GRANTED)
Set up analytics observer
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()
.
Example code:
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)
3. Add 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.
Example code:
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 -> }
4. Delete 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()
.
Example code:
context.deleteFourthlineFiles()
FourthlineFileManager.deleteFourthlineFiles(context);
5. Handle errors
You need to handle the following error values:
Name | Description |
---|---|
invalidValidationCode | The validation code for the SDK session is invalid. Action: Get a new validation code. |
clientRejected | The client isn't eligible for the Identity Verification workflow. You can't retry. |
canceled | The client canceled the workflow. |
unexpected | An unexpected error occurred. Action: Contact your implementation manager immediately. |
configurationNotSupported | The workflow created with the validation code isn't supported. Action: Consider updating to the latest SDK version. |
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. |
6. Configure workflow modules
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.
To integrate your solutions, see the Integration Guides.
Updated 16 days ago