Native onboarding components

3 min read

The native onboarding components run a KYC flow inline in your own screens: you identify the user, collect data, and finalize, instead of presenting the hosted flow. The SDK owns the API calls; you own the UI. Installation is covered in the introduction.

The native flow is KYC only. KYB (business data and beneficial owners) is not supported natively; use the hosted flow for KYB.

All methods are suspend (call them from a coroutine) and most take an Android Context. Native document and selfie capture requires the opt-in document-capture module (see Collect documents); without it, collect documents through the hosted flow.

Initialize

Initialize with an onboarding session token created by your backend:

kotlin
1import com.onefootprint.native_onboarding_components.Footprint
2
3val auth = Footprint.initialize(authToken = "obtok_...", context = context)
4if (auth.requiresAuth) {
5    // The user still needs to identify — run the challenge / verify flow below.
6}

initializeWithAuthToken and initializeWithPublicKey are deprecated in favor of initialize. They still work until the next major version removes them.

Identify (OTP)

If the user isn't identified yet, send a one-time passcode and verify it:

kotlin
1Footprint.createChallenge(email = "jane@acme.com", phoneNumber = null)
2val response = Footprint.verify(verificationCode = "123456", context = context)

Read requirements

getRequirements() returns the fields still missing, the pending requirement kinds, and whether process() can finalize now:

kotlin
1val requirements = Footprint.getRequirements()
2// requirements.fields.missing      -> data identifiers still required
3// requirements.pendingKinds        -> pending requirement kinds (e.g. "collect_custom_data")
4// requirements.canProcessInline    -> whether process() can finalize now

Collect identity data

Build your own form for the missing id.* fields, then vault them:

kotlin
1val data = VaultData(idFirstName = "Jane", idLastName = "Doe", idDob = "1990-01-01")
2Footprint.vault(data)

Collect custom data

Custom fields work the same way, under the custom.* namespace:

kotlin
1val data = VaultData(customFields = VaultData.customFields("membership_id" to "AB-12345"))
2Footprint.vault(data)

You can read previously vaulted values back with getVaultData. id.ssn9, id.ssn4, id.us_tax_id, and document.* are omitted because they require a step-up the SDK doesn't support:

kotlin
1val vaulted = Footprint.getVaultData(listOf(DataIdentifier.idFirstName, DataIdentifier.idLastName))

Collect documents

Native document and selfie capture comes from the opt-in document-capture module. Add it to your app's dependencies alongside the onboarding components, then register it once at startup:

kotlin
1import com.onefootprint.native_onboarding_components.documentcapture.registerFootprintDocumentCapture
2
3registerFootprintDocumentCapture()

If the playbook requires consent, submit it first. The text you submit is recorded as the disclosure the user agreed to, so pass the full consent language you displayed. Then capture, passing your ComponentActivity:

kotlin
1val docConfig = Footprint.getDocumentConfig()
2if (docConfig?.shouldCollectConsent == true) {
3    Footprint.submitConsent(consentLanguageText = myConsentText, mlConsent = true)
4}
5
6val result = Footprint.captureDocument(
7    activity = activity,
8    options = FootprintDocumentCaptureOptions(kind = DocumentKind.passport, countryCode = Iso3166TwoDigitCountryCode.US),
9)
10// result.uploadedSides -> e.g. [front, selfie]; result.canceled -> user backed out

The camera module owns the capture screen and the per-side loop; the SDK owns the upload and processing and enforces the backend retry limit. Without the document-capture module linked and registered, captureDocument throws E_NO_CAMERA_MODULE. You render the document-type and country picker.

The document-capture module declares the CAMERA permission (merged into your app) and requests it at runtime, so it appears in your Play Store listing. It also declares <uses-feature android:name="android.hardware.camera" android:required="false" /> so your app isn't filtered from camera-less devices. If you manage permissions yourself, override it in your manifest with tools:node="remove".

Finalize

process() finalizes the onboarding and returns a validation token to send to your backend:

kotlin
1val validationToken = Footprint.process()
2// Send validationToken to your backend to complete onboarding.