API¶

This section covers the native Android API: how to start the flow, configure the SDK, and implement the available delegates.

Listeners¶

Use these listeners to receive lifecycle callbacks and events:

DocumentCaptureListener
- fun onDocumentCaptureResults(results: DocumentCaptureResult)
- fun onDocumentCaptureStarted()
- fun onDocumentCaptureFinished(error: DocumentCaptureError)
DocumentCaptureEventsListener
- fun onDocumentCaptureEvent(event: DocumentCaptureEvent)

Starting a flow¶

1) Create a DocumentCaptureConfiguration (build it in code or decode from JSON).

2) Set the events listener (optional but recommended).

3) Start the SDK with your listener and configuration.

import androidx.activity.ComponentActivity
import com.veridas.sdk.document.entrypoint.DocumentCapture
import com.veridas.sdk.document.entrypoint.DocumentCaptureEventsListener
import com.veridas.sdk.document.entrypoint.DocumentCaptureListener
import com.veridas.sdk.document.error.DocumentCaptureError
import com.veridas.sdk.document.event.DocumentCaptureEvent
import com.veridas.sdk.document.result.DocumentCaptureResult

class DocumentIntegratorActivity : 
    ComponentActivity(), 
    DocumentCaptureListener, 
    DocumentCaptureEventsListener {
    private companion object {
        private val TAG = DocumentIntegratorActivity::class.simpleName
    }

    fun startCapture() {
        DocumentCapture.start(
            listener = this,
            configuration = getConfigurationFromAsset(fileName),
            context = this
        )
        DocumentCapture.setEventsListener(this)
    }

    // DocumentCaptureListener
    override fun onDocumentCaptureStarted() {
        Log.i(TAG, "Document SDK -- Started")
    }

    override fun onDocumentCaptureResults(results: DocumentCaptureResult) {
        Log.i(TAG, "Document SDK -- Capture Results: $results")
    }

    override fun onDocumentCaptureFinished(error: DocumentCaptureError) {
        Log.i(TAG, "Document SDK -- Finished with error $error")
    }

    // DocumentCaptureEventsListener
    override fun onDocumentCaptureEvent(event: DocumentCaptureEvent) {
        Log.i(TAG, "$TAG - Document SDK -- Event: $event")
    }
}

Example helper for loading JSON configs (shared by all SDKs):

import kotlinx.serialization.ExperimentalSerializationApi
import kotlinx.serialization.json.Json

@OptIn(ExperimentalSerializationApi::class)
private val json = Json {
    ignoreUnknownKeys = true
    explicitNulls = false
}

fun getConfigurationFromAsset(fileName: String): DocumentCaptureConfiguration {
    val jsonString = applicationContext
        .assets
        .open(fileName)
        .bufferedReader()
        .use { it.readText() }

    return json.decodeFromString<DocumentCaptureConfiguration>(jsonString)
}

Dispatched events¶

The SDK dispatches a set of events to communicate that the corresponding actions have been taken. Each event is sent to onDocumentCaptureEvent(event: DocumentCaptureEvent), which receives a data class object:

    data class DocumentCaptureEvent

This object contains 2 main attributes, type with the event identifier and detail with all the information related to the event.

Event Name	Event Detail	Event Trigger
`VD_instructions`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When initial instructions are displayed.
`VD_mounted`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the SDK is mounted.
`VD_unmounted`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the SDK is unmounted.
`VD_loaded`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the SDK is fully loaded.
`VD_cameraPermissionsGranted`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the user grants camera permissions.
`VD_cameraStarted`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the camera starts successfully.
`VD_cameraVideoPlayStarted`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the camera video playback begins.
`VD_cameraFailureDefaultError`	`"sdkName": "VD-DOCUMENT", "type": "error", "flowType": "document"`	When camera can't be initialised for any reason.
`VD_cameraFailurePermissionError`	`"sdkName": "VD-DOCUMENT", "type": "error", "flowType": "document"`	When camera permissions are denied.
`VD_successTickFinish`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the success tick animation finishes.
`VD_reviewImage`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document", "stage": "OBVERSE_REVIEW"`	When the review screen is shown.
`VD_continueClicked`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the continue button is clicked in review.
`VD_capture`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document", "size": {"height: 1920, "width": 1440"}, "stage": "obverseDetection"`	When the front or back side of the document is captured.
`VD_processFinished`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the process ends, either by completion or timeout.
`VD_closeClicked`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the close button is clicked and user exits from confirmation modal.
`VD_repeatClicked`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the repeat button is clicked in the review screen.
`VD_detectionTimeout`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the process times out.
`VD_restartClicked`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the restart button is clicked after feedback.
`VD_restartProcess`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the process needs to be restarted due to an error.
`VD_manualCaptureButton`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the user captures the document manually.
`VD_loseFocus`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the user has lost the focus on the browser tab.