Composition

In addition to supporting implementation via Activity (described in quick setup) the SDK also supports implementation via Jetpack Compose.

Basic Usage

Simply call DocumentScannerScreen in any composition scope to launch the document scanner. While basic permission handling is included, we strongly recommend implementing your own permission flow.

@Composable
fun AnyComposable() {
    DocumentScannerScreen(
        documentCameraResultHandler = object : DocumentCameraResultHandler {
            override fun onResult(
                result: DocumentProcessingState.Result,
                metadata: DocumentProcessingMetadata?
            ) {
                when (result) {
                    is DocumentProcessingState.Failure -> {
                        // Handle failure, e.g. show error message
                        val causeOrNull: Throwable? = result.cause
                        val errorComponent: ErrorComponent = result.component
                        val errorMessage: String = result.message
                    }
                    is DocumentProcessingState.Success -> {
                        // Handle success, e.g. preview or upload captured image
                        val documentImageBitmap = result.image.toBitmap(rotate = true)
                    }
                }
            }
        },
    )
}

DocumentCameraResultHandler is required to receive the capture result. This callback provides either a successful capture or an error. Document scanner is stopped automatically once DocumentProcessingState.Result is returned; any further actions must be handled manually.

/**
 * Callback invoked when the document captures process completes, providing either captured
 * image data upon success or error details upon failure.
 *
 * @param result returns [DocumentProcessingState.Failure] or [DocumentProcessingState.Success]
 * @param metadata holds detailed information about document capture process such as how many
 * frames were processed and/or duration of the entire process.
 */
interface DocumentCameraResultHandler {
    fun onResult(
        result: DocumentProcessingState.Result,
        metadata: DocumentProcessingMetadata? = null
    )
}

Configuring DocumentScannerScreen

To customize behavior, pass a DocumentScannerConfig when calling the Composable. You can control:

• Whether to show the auto-capture toggle
• Which side of the document is being captured

The document side parameter is used to tailor UI for a specific document capture use case. For example, passing DocumentSide.FRONT will configure animation, instructions and help screen for capturing the front side of the identity document.

💡 Note: DocumentScannerConfig is stateful, updating it will restart the scanner with the new configuration. This is useful for multi-step flows like capturing both the front and the back of a document.

/**
 * This class is used to configure document camera UI such as
 * help screen, instructions, animations and auto capture toggle.
 */
@Parcelize
data class DocumentScannerConfig(
    val autoCaptureToggleConfig: AutoCaptureToggleConfig = AutoCaptureToggleConfig.Show,
    val documentSide: DocumentSide = DocumentSide.UNSPECIFIED,
) : Parcelable

enum class DocumentSide {
    FRONT, BACK, UNSPECIFIED
}

sealed interface AutoCaptureToggleConfig : Parcelable {

    @Parcelize
    data object Show : AutoCaptureToggleConfig

    @Parcelize
    data class ShowDelayed(
        val durationMs: Long = 15_000L
    ) : AutoCaptureToggleConfig {
        init {
            require(durationMs > 0) { "duration must be > 0" }
        }
    }

    @Parcelize
    data object Hide : AutoCaptureToggleConfig
}

Controlling the DocumentScanner

For a more fine-grained control, you can send pause/resume/restart commands to the document scanner by passing a SharedFlow<DocumentScannerCommand> as a parameter to the Composable. Pause/resume commands are useful if you want to intercept the scanning process with some custom overlay UI. For example, you can override back handler to show a dialog and while it's being shown the scanner should be paused. Restart command might be needed, if you want to restart the capture process without changing the config.

/**
 * Document scanner commands for advanced control of the document scanner component.
 */
sealed class DocumentScannerCommand {

    /**
     * Pauses document camera feed and frame processing.
     */
    data object Pause : DocumentScannerCommand()

    /**
     * Resumes document camera feed and frame processing.
     */
    data object Resume : DocumentScannerCommand()

    /**
     * Restarts document camera with the latest [DocumentScannerConfig].
     */
    data object Restart : DocumentScannerCommand()
}