Usage¶

The Document IAD capture library helps you detect identity documents in real‑time and capture high‑quality photos for Injection Attack Detection (IAD) analysis.

Key Components¶

Component	Responsibility
`DefaultDocumentDetector`	Detects documents and evaluates capture conditions.
`DocumentIadCameraController`	Orchestrates camera, detector, and lifecycle.

Quick Start¶

1. Add `PreviewView` to your layout¶

<androidx.constraintlayout.widget.ConstraintLayout
        xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:app="http://schemas.android.com/apk/res-auto"
        android:layout_width="match_parent"
        android:layout_height="match_parent">

    <androidx.camera.view.PreviewView
            android:id="@+id/previewView"
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            app:layout_constraintTop_toTopOf="parent"
            app:layout_constraintBottom_toBottomOf="parent"
            app:layout_constraintStart_toStartOf="parent"
            app:layout_constraintEnd_toEndOf="parent"/>
</androidx.constraintlayout.widget.ConstraintLayout>

2. Create `DefaultDocumentDetector`¶

class CaptureActivity : AppCompatActivity() {

    private lateinit var documentDetector: DefaultDocumentDetector
    private val detectionListener = OnDocumentQualityCheckResultListener { result ->
        // Inform the user about the current capture conditions
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        documentDetector = DefaultDocumentDetector(this, detectionListener)
    }

    override fun onDestroy() {
        super.onDestroy()
        documentDetector.close()
    }
}

3. Initialize `DocumentIadCameraController`¶

private lateinit var cameraController: DocumentIadCameraController

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    cameraController = DocumentIadCameraController(
        documentDetector = documentDetector,
        previewView = findViewById(R.id.previewView),
        lifecycleOwner = this
    )
}

override fun onDestroy() {
    super.onDestroy()
    cameraController.close()
}

Note: Only one instance of DocumentIadCameraController can be active at a time.

4. Bind to the `Activity` lifecycle¶

override fun onStart() {
    super.onStart()
    cameraController.openCamera()
}
override fun onResume() {
    super.onResume()
    cameraController.startPreview()
    cameraController.startDetection()
}
override fun onPause() {
    super.onPause()
    cameraController.stopDetection()
    cameraController.stopPreview()
}
override fun onStop() {
    super.onStop()
    cameraController.closeCamera()
}

5. Register processors & listeners¶

cameraController.apply {
    onCameraErrorListener = OnCameraErrorListener { error ->
        // Handle camera errors
    }

    onDetectionErrorListener = OnDetectionErrorListener { error ->
        // Handle detector errors
    }

    photoProcessor = ImageProcessor { image ->
        // Display photo preview or show a progress bar
    }

    bundleProcessor = BundleProcessor { bundle ->
        // Send bundle to the IAD backend and receive injection attack probability
    }
}

6. Trigger document capture¶

// Manual capture (skips condition checks)
cameraController.takePhoto()

Document Detection¶

Only identity documents are officially supported. This includes booklets (e.g., passports) and card document fronts (including driver's licenses and identity cards). Although DefaultDocumentDetector can successfully process other document images, the accuracy of the findings may be reduced. For more information about specific document types and best practices, please consult your ID R&D representative.

Document Quality Status¶

DefaultDocumentDetector emits a DocumentQualityStatus indicating why capture may be blocked:

Status	Meaning
`OK`	Conditions are good – a photo can be taken automatically.
`DocumentBordersOutsideOfFrame`	At least one edge is out of the preview.
`DocumentNotFound`	No document detected in the frame.
`DocumentTooCloseToBorder`	Document touches the frame border.
`MultipleDocumentsInFrame`	More than one document detected.
`RelativeDocumentSizeLowerThen10Percent`	Document area < 10% of the frame.

Example App¶

A runnable sample is included in the release archive under document-iad-capture-android-vX.X.X/iad-example.