> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/react-native/document-smart-capture.md).

# Document Smart Capture

Install and launch Smart Capture for React Native. Learn configuration options, event handling, and result handling.

## Overview

**Smart Capture** is a rebuilt, more intelligent document capture experience. Instead of telling the SDK which document type and side to expect at each step, you just declare which document types your app accepts (`acceptedDocuments`) — the user captures and/or uploads a document photo (depending on the `validationType` you configure — camera capture, gallery/file upload, or both), and Smart Capture identifies the document type and side on its own and validates it against that list. It also detects on its own whether a document is single-page (`FULL`) or two-sided (`FRONT/BACK`), prompting for the second side only when needed. It also includes optional auto capture and preview, and uses the same Certta session as Face Liveness and Document Detector: configure your credentials once with `useCerttaSdk().configureSDK(...)`, then open the capture UI with `useCerttaSmartCapture().open(...)`.

{% content-ref url="/pages/dWbxPXsbZgjDP2HzpPoi" %}
[Text Customization](https://docs.caf.io/caf-sdk/react-native/document-smart-capture/text-customization.md)
{% endcontent-ref %}

{% content-ref url="/pages/Voj44CZkD3KEXNTWN4Nt" %}
[Color Customization](https://docs.caf.io/caf-sdk/react-native/document-smart-capture/color-customization.md)
{% endcontent-ref %}

{% content-ref url="/pages/k8WFBOtnoAdrUpBiqSIp" %}
[Image Customization](https://docs.caf.io/caf-sdk/react-native/document-smart-capture/image-customization.md)
{% endcontent-ref %}

## Prerequisites

Before proceeding, ensure the Certta React Native SDK is properly installed. If you haven't done this yet, please refer to our Installation Guide.

{% content-ref url="/pages/tC8MaVHQnCi3YdHr6s0p" %}
[Installation Guide](https://docs.caf.io/caf-sdk/react-native/installation-guide.md)
{% endcontent-ref %}

## Dependencies

Smart Capture is enabled from `caf-modules-config.json` at the app root (the file CocoaPods and Gradle read when you install native deps). You do not add Gradle artifacts or CocoaPods by hand — the plugin pulls them from this config.

```json
{
  "modules": {
    "smartCapture": {
      "enabled": true,
      "autoCapture": false
    }
  }
}
```

<table><thead><tr><th>Field</th><th width="105.05078125">Required?</th><th>Adds</th></tr></thead><tbody><tr><td><code>modules.smartCapture.enabled</code></td><td>Required</td><td>Smart Capture bridge (Android and iOS) and the <code>useCerttaSmartCapture</code> hook.</td></tr><tr><td><code>modules.smartCapture.autoCapture</code></td><td>Optional</td><td>Android LiteRT auto capture provider. Needed for <code>enableAutoCapture</code> to actually do anything on Android.</td></tr></tbody></table>

{% hint style="info" %}
The auto capture dependency will add \~3 MB to the Android app size — this includes the model and the engine needed to actually detect documents automatically.
{% endhint %}

{% hint style="warning" %}
If `autoCapture` is not `true` in `caf-modules-config.json`, Smart Capture falls back to manual capture only. This isn't a thrown error or a `CerttaError` — the flow still opens and works — but Smart Capture does log an INFO-level message (`"Missing auto capture dependency."`) on the Certta log stream (`useCerttaSdk().logs`). If you're not reading that stream, nothing will look overtly wrong; capture will just always be manual.

Manual capture (the shutter button) always works, with or without auto capture.
{% endhint %}

{% hint style="info" %}
**Auto capture on Android requires Google Play Services on the device.** The optional provider runs its detection model through Play Services LiteRT, so on devices without Play Services — or where it's outdated/unavailable — that initialization fails and Smart Capture falls back to manual capture, the same as if the dependency weren't added at all. Manual capture doesn't depend on Play Services.
{% endhint %}

***

## Starting Smart Capture

To start the Smart Capture flow, call `open()` from `useCerttaSmartCapture()` and pass a `CerttaSmartCaptureConfiguration` object. Results arrive on the hook's `event` (`success` / `error`).

{% hint style="info" %}
Make sure `configureSDK(...)` has already been called for the current session before calling `open()`.
{% endhint %}

```typescript
import { useEffect } from 'react';
import { Button } from 'react-native';
import {
  useCerttaSdk,
  useCerttaSmartCapture,
  CafEnvironment,
  CerttaAcceptedDocumentType,
  type CerttaSmartCaptureConfiguration,
} from '@caf.io/react-native-sdk';

const config: CerttaSmartCaptureConfiguration = {
  acceptedDocuments: [CerttaAcceptedDocumentType.IDENTITY_CARD],
  showInstructions: true,
  enablePreview: true,
};

export function SmartCaptureScreen() {
  const { configureSDK } = useCerttaSdk();
  const { open, event } = useCerttaSmartCapture();

  useEffect(() => {
    configureSDK({
      mobileToken: '<MOBILE_TOKEN>',
      userId: '<USER_ID>',
      environment: CafEnvironment.PROD,
      securityEnabled: true,
    }).catch(console.error);
  }, [configureSDK]);

  useEffect(() => {
    if (event.success?.response) {
      // event.success.response
    }
    if (event.error) {
      // event.error.type, event.error.cause
    }
  }, [event]);

  return (
    <Button
      title="Open Smart Capture"
      onPress={() => {
        open(config).catch(console.error);
      }}
    />
  );
}
```

{% hint style="warning" %}
`open()` returns a Promise that rejects if the native bridge cannot process the call (module not enabled, invalid JSON). Runtime failures during the flow (permission, network, cancel) arrive on `event.error`, not as a Promise rejection. Handle both.
{% endhint %}

### `CerttaSmartCaptureConfiguration` parameters

All parameters except `acceptedDocuments` have defaults; override only what you need.

| Parameter            | Type                           | Default              | Description                                                                                                                                                        |
| -------------------- | ------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `acceptedDocuments`  | `CerttaAcceptedDocumentType[]` | None                 | Document types permitted for capture or upload. Required — Smart Capture fails at `open()` if empty.                                                               |
| `showInstructions`   | `boolean`                      | `true`               | Shows instructional screens before any capture/upload.                                                                                                             |
| `enablePreview`      | `boolean`                      | `true`               | Shows a preview of the captured image for user confirmation before sending.                                                                                        |
| `enableAutoCapture`  | `boolean`                      | `true`               | Requests automatic capture when alignment criteria are met. On Android, requires `modules.smartCapture.autoCapture: true`; falls back to manual capture if absent. |
| `skipSuccessScreen`  | `boolean`                      | `false`              | Skips the success screen shown after a successful capture/upload.                                                                                                  |
| `validationType`     | `CerttaValidationType`         | `CAPTURE_AND_UPLOAD` | Which flows are allowed: `CAPTURE`, `UPLOAD`, or `CAPTURE_AND_UPLOAD`.                                                                                             |
| `allowedUploadTypes` | `CerttaFileAcceptedType[]`     | all values           | File formats accepted from gallery/files (`JPEG`, `PNG`, `PDF`, `HEIF`, `HEIC`). An empty array is treated as all types.                                           |

#### `CerttaAcceptedDocumentType`

| Value                     | Local document types accepted |
| ------------------------- | ----------------------------- |
| `DRIVER_LICENSE`          | CNH                           |
| `IDENTITY_CARD`           | RG, CIN                       |
| `RESIDENCE_IDENTITY_CARD` | RNM, RNE                      |
| `EMPLOYMENT_CARD`         | CTPS                          |
| `VEHICLE_LICENSE`         | CRLV                          |
| `PASSPORT`                | Passport                      |
| `ANY`                     | Any document type             |

***

### Behavior and limits

* **Accepted documents are required.** `acceptedDocuments` must contain at least one value. An empty array dismisses the flow before the camera or the capture provider starts.
* **One flow at a time.** Only one Smart Capture flow may run per process. Starting a second one while the first is active fails with a message stating that a capture session is already in progress.
* **Upload file size.** Files larger than **10 MB** are rejected. This limit is not configurable.
* **Upload file count.** The upload path accepts either one file containing the whole document or two files for front and back.

### **Understanding Smart Capture events and results**

The hook listens to `SmartCaptureEvent.Success` and `SmartCaptureEvent.Error` and exposes them as `event.success` and `event.error`.

#### Success — `CerttaSuccess`

`response` is a signed JWT/string containing the server-side validation results and document metadata. Your backend or Certta integration documentation defines how to validate, decode, and store it.

```json
{ response?: string }
```

#### Error — `CerttaError`

```json
{ type: CerttaErrorType; cause: string }
```

| Type                  | Meaning                                                                              |
| --------------------- | ------------------------------------------------------------------------------------ |
| `InitializationError` | Session not configured or invalid config (e.g. empty `acceptedDocuments`).           |
| `PermissionError`     | Missing runtime permission (e.g. camera).                                            |
| `SecurityError`       | Security validation failed (when `securityEnabled` is active on the Certta session). |
| `NetworkError`        | Network/request failure.                                                             |
| `UnknownError`        | Unexpected/unmapped failure.                                                         |
| `Cancelled`           | The user dismissed the flow.                                                         |

### Subpages

{% content-ref url="/pages/dWbxPXsbZgjDP2HzpPoi" %}
[Text Customization](https://docs.caf.io/caf-sdk/react-native/document-smart-capture/text-customization.md)
{% endcontent-ref %}

{% content-ref url="/pages/Voj44CZkD3KEXNTWN4Nt" %}
[Color Customization](https://docs.caf.io/caf-sdk/react-native/document-smart-capture/color-customization.md)
{% endcontent-ref %}

{% content-ref url="/pages/k8WFBOtnoAdrUpBiqSIp" %}
[Image Customization](https://docs.caf.io/caf-sdk/react-native/document-smart-capture/image-customization.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/caf-sdk/react-native/document-smart-capture.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
