Native onboarding components

3 min read

The native onboarding components run a KYC flow inline in your own SwiftUI or UIKit 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. All methods are async and throws.

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

Native document and selfie capture requires the opt-in FootprintDocumentCapture product (see Collect documents). Without it, collect documents through the hosted flow.

Initialize

Initialize with an onboarding session token created by your backend:

swift
1import Footprint
2
3let auth = try await Footprint.shared.initialize(authToken: "obtok_...")
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:

swift
1try await Footprint.shared.createChallenge(email: "jane@acme.com", phoneNumber: nil)
2let response = try await Footprint.shared.verify(verificationCode: "123456")

Read requirements

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

swift
1let requirements = try await Footprint.shared.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:

swift
1let data = VaultData(idFirstName: "Jane", idLastName: "Doe", idDob: "1990-01-01")
2try await Footprint.shared.vault(data: data)

Collect custom data

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

swift
1let data = VaultData(customFields: VaultData.companion.customField(fieldName: "membership_id", value: "AB-12345"))
2try await Footprint.shared.vault(data: 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:

swift
1let vaulted = try await Footprint.shared.getVaultData(fields: [.idFirstName, .idLastName])

Collect documents

Native document and selfie capture comes from the opt-in FootprintDocumentCapture product. Add it to your Package.swift dependencies alongside Footprint, then register it once at launch:

swift
1import FootprintDocumentCapture
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:

swift
1let docConfig = try await Footprint.shared.getDocumentConfig()
2if docConfig?.shouldCollectConsent == true {
3    try await Footprint.shared.submitConsent(consentLanguageText: myConsentText, mlConsent: true)
4}
5
6let result = try await Footprint.shared.captureDocument(
7    options: FootprintDocumentCaptureOptions(kind: .passport, countryCode: .us)
8)
9// 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 FootprintDocumentCapture linked and registered, captureDocument throws E_NO_CAMERA_MODULE. You render the document-type and country picker.

Add NSCameraUsageDescription (and NSPhotoLibraryUsageDescription if you enable gallery upload) to your app's Info.plist. iOS requires a usage-description string to access the camera. Swift Package Manager can't add it for you, and the app crashes on capture without it.

Finalize

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

swift
1let validationToken = try await Footprint.shared.process()
2// Send validationToken to your backend to complete onboarding.