> 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/web-javascript/getting-started/document-detector/documentdetector.md). # Getting started ## **Requirements** Before you start using the Document Detector SDK, you will need to have the following: * A valid Caf access token to authenticate the SDK (check [this documentation](https://docs.caf.io/sdks/sdk_integration_documentation) for more information). * A HTML file with a `` tag. The SDK will render the document detection UI in this tag. ## **Importing the SDK** 1. Download the **`.umd.js`** file: [document-detector-7.0.0.umd.js](https://repo.combateafraude.com/javascript/release/document-detector/7.0.0/document-detector-7.0.0.umd.js) 2. Download the **`.wasm`** file: [dd-validator.wasm](https://repo.combateafraude.com/javascript/release/document-detector/7.0.0/dd-validator.wasm) 3. Place both files in the same directory (e.g. **`public/sdks/caf-dd/`**). 4. Import the **`.umd.js`** file in your HTML file. For example (assuming a **`public/index.html`** file): ```html ``` 5. Import the SDK as a JavaScript module in a script tag: ```html ``` ## Construction and usage To use the Document Detector SDK, you will need to create an instance of the DocumentDetector class. This class will allow you to initialize the SDK, capture documents, and close the SDK. You can also pass options to the SDK to customize its behavior. In the builder, the SDK receives a single parameter with the settings: ```javascript const sdk = new DocumentDetector(options); ``` This parameter is an object containing the configuration options for the SDK. These options customize the behavior of the SDK according to your application's requirements. The following table lists the available options:
ParameterTypeRequired?Default Value

token

Authentication token for consuming the SDK.

StringYes.-

language

Default message language, valid values: en_US, pt_BR, es_MX.

StringNo.pt_BR

blockExecutionOnDesktops

Flag indicating whether execution on desktops should be blocked or not

booleanNo.false

enableVisibilityChangeSecurity

Enables the security enhancement responsible for closing the SDK when the user switches browser tabs.

booleanNo.false

enableFramingAnalyzer

Toggles the AI-guided framing analysis on or off.

When enabled, the SDK uses an AI model to analyze the camera feed and provide real-time feedback to the user, guiding them to adjust the document's position and orientation for optimal capture.

When disabled, the SDK forces the capture mode to "manual" and does not perform any AI-guided framing analysis. The frame is captured and sent directly to our backend for processing. This approach can reduce image quality but significantly improves performance.

Consider disabling this option if you need to optimize the SDK performance on devices with limited resources and your application's use case prioritizes quantity of captures over quality.

booleanNo.true

analytics

Specifies the analytics settings for the SDK. This parameter allows you to configure analytics tracking within the SDK.

ObjectNo.view table

appearance

Specifies the appearance settings for the SDK user interface (UI). This parameter allows you to customize the visual appearance of the SDK components to match the look and feel of your application.

Enhanced in v6.8.3: Now uses a nested object format for better organization and readability.

ObjectNo.view table

messages

Customizes displayed messages within the SDK to optimize user experience.

Enhanced in v6.8.3: Now uses a nested object format for better organization and readability.

ObjectNo.view table
### **Configuration Format** Starting with version 6.8.3, the SDK uses a **nested object format** for configuring appearance and messages options, which provides better organization and readability: ```javascript appearance: { general: { fontFamily: "arial", closeButtonIconColor: "#FFFFFF", }, capture: { captureButtonIconSize: "100%", captureButtonColor: "#FFFFFF", hideCaptureTitle: false, }, upload: { backgroundColor: "#BDBDBD", card: { backgroundColor: "#FFFFFF", }, startScreen: { title: { color: "#323232" }, details: { color: "#828282" }, allowButton: { backgroundColor: "#323232", label: { color: "#FFFFFF" } } }, loadingScreen: { icon: { color: "#000000" }, text: { color: "#323232" } }, failureScreen: { icon: { color: "#E21B45", shadowColor: "#FFE4E6" }, title: { color: "#323232" }, details: { color: "#828282" }, retryButton: { backgroundColor: "#E21B45", label: { color: "#FFFFFF" } } }, successScreen: { icon: { color: "#0BAA43", shadowColor: "#DAFEE5" }, text: { color: "#0BAA43" } } } } ``` {% hint style="info" %} If you're upgrading from a previous version, your existing dot notation configurations (e.g., `"general.fontFamily": "arial"`) will continue to work. However, we recommend migrating to the nested object format for better code organization. {% endhint %} ### **Example** **index.html** ```html Document Detector ``` **index.js** ```javascript const options = { token: "My Access Token", language: "pt_BR", blockExecutionOnDesktops: false, enableVisibilityChangeSecurity: false, enableFramingAnalyzer: true, analytics: { enabled: true, trackingId: "My Tracking ID", trackingInfo: { myProp: "My Tracking Info", }, enableDebugMode: false, }, appearance: { general: { fontFamily: "arial", closeButtonIconColor: "#FFFFFF", }, capture: { captureButtonIconSize: "100%", captureButtonColor: "#FFFFFF", hideCaptureTitle: false, }, upload: { backgroundColor: "#BDBDBD", card: { backgroundColor: "#FFFFFF", }, startScreen: { title: { color: "#323232" }, details: { color: "#828282" }, allowButton: { backgroundColor: "#323232", label: { color: "#FFFFFF" }, }, }, loadingScreen: { icon: { color: "#000000" }, text: { color: "#323232" }, }, failureScreen: { icon: { color: "#E21B45", shadowColor: "#FFE4E6" }, title: { color: "#323232" }, details: { color: "#828282" }, retryButton: { backgroundColor: "#E21B45", label: { color: "#FFFFFF" }, }, }, successScreen: { icon: { color: "#0BAA43", shadowColor: "#DAFEE5" }, text: { color: "#0BAA43" }, }, }, }, }; const documentDetector = new DocumentDetector(options); // This method is optional, but it can significantly improve the SDK's // loading experience. We recommend using it as early as possible in your // workflow, even before reaching the SDK's loading screen. However, if it's // not feasible or doesn't align with the nature of your flow when // integrating the SDK, the initialize method will handle everything // necessary to ensure the SDK functions properly without the need for this method. await documentDetector.loadAiModel(); // Now that the camera is allowed, we can initialize the SDK await documentDetector.initialize(); // Now that the SDK is initialized, we can start the capture process // This is the moment that the SDK will be displayed to the user via a modal // The capture process will start and the user will be able to capture the document // The capture method returns a promise that resolves when the capture process is finished const captureResult = await documentDetector.capture({ expectedDocument: "cnh_front", mode: "automatic", automaticCaptureMaxDuration: 30, personID: "my-person-id", }); // Now we can close the SDK to stop displaying it await documentDetector.close(); // And dispose the SDK to free up resources await documentDetector.dispose(); ``` ### **Handling build errors** | Error Name | Description | | ---------------------- | ---------------------------------------------------------------------- | | CafSdkBuildError | An error occurred during the SDK build/construction. | | CafSdkBlockedError | SDK build has been blocked. | | CafInvalidOptionsError | SDK build options are invalid. Review the options provided to the SDK. | | CafUnsupportedError | SDK is not supported on this device, browser or operating system. | **Example** ```javascript try { const sdk = new DocumentDetector(options); } catch (error) { switch (error.name) { case "CafSdkBuildError": console.error("SDK build error:", error.message); break; case "CafSdkBlockedError": console.error("SDK blocked error:", error.message); break; case "CafInvalidOptionsError": console.error("Invalid options error:", error.message); break; case "CafUnsupportedError": console.error("Unsupported error:", error.message); break; default: console.error("Unexpected build error:", error.name, error.message); } } ``` For more information on the SDK's methods and properties, check the [SDK methods](/caf-sdk/web-javascript/getting-started/document-detector/methods.md) documentation. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.caf.io/caf-sdk/web-javascript/getting-started/document-detector/documentdetector.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.