> 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-1.md). # Release notes ## 7.0.0 (June 24, 2026) {% hint style="warning" %} **Important Notice: Breaking Changes**\ This version includes a significant breaking change to the `capture()` method output. The method now returns a **signed JWT string** instead of the previous `Result` object. Please review the migration guide below before upgrading. {% endhint %} ### 🚨 Breaking changes #### Capture method output: JWT signed response The `capture()` method no longer returns a structured `Result` object. Instead, it returns a **signed JWT string** (`signedResponse`) that encodes the capture metadata. This JWT is generated and signed by the backend, enabling server-side verification of capture integrity. **Before (v6.x):** ```javascript const result = await documentDetector.capture(options); // result was a structured object: // { // image: { // url: "https://...", // blob: Blob, // storageInfo: { key: "...", bucket: "..." } // }, // detectedDocument: { // type: "cnh", // e.g. "rg", "cnh_new", "passport" // side: "front" // e.g. "front", "back", "both" // }, // isCaptureValid: true // } const imageUrl = result.image.url; const documentType = result.detectedDocument.type; const isValid = result.isCaptureValid; ``` **After (v7.0.0):** ```javascript const signedResponse = await documentDetector.capture(options); // signedResponse is a JWT string: "eyJhbGciOiJIUzI1NiJ9..." // Decode it to access capture details. Example: const payload = decodeJwt(signedResponse); // payload contains: // { // captures: [ // { // scannedLabel: "new_cnh_front", // imageUrl: "https://..." // } // ], // documentType: "NEW_CNH", // trackingId: "", // iat: 1781646936 // } const imageUrl = payload.captures[0].imageUrl; const scannedLabel = payload.captures[0].scannedLabel; const documentType = payload.documentType; ``` #### Field mapping reference The following table maps the previous `Result` object fields to their equivalent in the decoded JWT payload: | Previous field (v6.x) | New field (v7.0.0 JWT payload) | Notes | | --------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------- | | `result.image.url` | `payload.captures[0].imageUrl` | Pre-signed S3 URL. | | `result.image.blob` | — | No longer available. The image is accessible via the `imageUrl` only. | | `result.image.storageInfo.key` | — | No longer exposed in the JWT payload. | | `result.image.storageInfo.bucket` | — | No longer exposed in the JWT payload. | | `result.detectedDocument.type` | `payload.documentType` | Now uppercase (e.g. `"NEW_CNH"` instead of `"cnh_new"`). | | `result.detectedDocument.side` | `payload.captures[0].scannedLabel` | The side is embedded in the label (e.g. `"new_cnh_front"`, `"rg_back"`, `"cnh_full"`). | | `result.isCaptureValid` | — | No longer exposed. A successful `capture()` call (no error thrown) indicates a valid capture. | #### New error: CafSdkCanceledError The `capture()` method now throws a `CafSdkCanceledError` when the user cancels the capture (e.g., closes the modal). Previously, the method would resolve silently with `undefined`. ```javascript try { const signedResponse = await documentDetector.capture(options); } catch (error) { if (error.name === "CafSdkCanceledError") { // User canceled — handle gracefully } } ``` For more details on error handling and state management after errors, see the updated [capture method documentation](/caf-sdk/web-javascript/getting-started/document-detector/methods.md#bxk99swpyysw). ### 🛠 Improvements/Fixes #### Logger resilience after dispose * Fixed an error that could occur when asynchronous operations attempted to log after the SDK was disposed. The logger now safely handles calls made after `dispose()`. ## 6.13.0 (March 16, 2026) ### 🆕 New features #### New event listeners Added three new event listeners that allow tracking of key moments in the capture lifecycle and reacting accordingly: * **`capture_ready`**: Triggered when the SDK capture screen (camera preview or upload UI) is rendered and ready for user interaction. The event detail includes the capture mode (`manual` or `upload`) and the expected document (type and side). * **`upload_button_clicked`**: Triggered when the user clicks the upload button in upload mode. * **`capture_result`**: Triggered after a document is successfully captured and validated. The event detail includes the capture mode, the expected document (type and side) and a boolean indicating if the capture is valid. For more details, check the [Event listeners](/caf-sdk/web-javascript/getting-started/document-detector/sdk-event-listeners.md) documentation. ## 6.12.1 (March 03, 2026) ### 🛠 Improvements/Fixes #### Improved file upload type detection * Fixed an issue where the SDK could reject valid documents during upload when the file type metadata was missing or inaccurate. This commonly occurred with files selected from cloud storage services (e.g., Google Drive), WebViews, or iframes. The SDK now validates the actual file content rather than relying solely on file metadata. ## 6.12.0 (February 03, 2026) ### 🛠 Improvements/Fixes #### Intelligent capture optimization Addresses intermittent freezes and capture reliability issues reported in version 6.11.1. * **Adaptive learning**: The SDK automatically detects and remembers the best capture settings for each device, eliminating repeated failed attempts and improving reliability. * **Persistent across sessions**: Optimization is saved to the browser and applied immediately on return visits. ## 6.11.1 (December 01, 2025) ### 🛠 Improvements/Fixes #### Enhanced frame capture quality and reliability * Added **automatic quality validation** to prevent the capture of images that are too dark, too bright, or of low quality. * Introduced intelligent **capture fallback mechanism**: the SDK now automatically attempts alternative capture methods if the primary high-quality method fails or is unsupported. * Added **context-specific error messages** to guide users when capture fails due to environmental conditions (e.g., "Environment is too dark" or "Environment is too bright"). #### Enhanced SDK Analytics * Improved logging by adding information about capture attempts and specific quality metrics. * Added **abandonment tracking**: when a user abruptly leaves the journey before completion, such as closing the browser window, minimizing the tab, or navigating to a different page, the SDK will track this event to provide better insights about the user journey and possible reasons for abandonment. ## 6.11.0 (November 17, 2025) ### 🆕 New features #### Standardized error handling * More consistent and predictable error handling experience with standardized error types. All errors thrown by the SDK follow a unified structure, making it easier to identify and handle specific error scenarios in your integration. ## 6.10.0 (November 03, 2025) ### 🆕 New features #### Enhanced analytics tracking * Improved analytics events tracking, providing better error monitoring and debugging capabilities of the SDK. ## 6.8.5 (September 25, 2025) ### 🛠 Improvements/Fixes #### Fixed image processing errors during document capture * Fixed image processing errors that could cause capture failures with certain formats ## 6.8.4 (September 08, 2025) ### 🛠 Improvements/Fixes #### Upload mode reliability enhancements * Fixed upload failures when selecting files from cloud services (e.g., Google Drive) * Resolved cases where uploads could hang; now error messages are shown * Improved upload behavior across different browsers and mobile environments ## 6.8.3 (August 12, 2025) ### 🛠 Improvements/Fixes #### Configuration options enhancements * Enhanced appearance and messages configuration to support nested object format for better organization and readability * Fixed issues where appearance and messages customizations might not be applied correctly in certain scenarios * Improved reliability of custom styling application across all SDK components * Maintained full backward compatibility with existing dot notation configurations ## 6.8.1 (April 29, 2025) ### 🛠 Improvements/Fixes #### SDK analytics architecture refactoring Fixed analytics data transmission by removing external analytics library dependencies and migrating to a more reliable and direct communication system. ## 6.7.3 (March 31, 2025) ### 🛠 Improvements/Fixes #### Upload mode stability Fixed an issue where document upload mode would incorrectly trigger camera-specific operations, potentially causing unexpected behavior. This improvement ensures that the SDK correctly handles different capture modes with appropriate functionality. ## 6.7.2 (March 20, 2025) ### 🛠 Improvements/Fixes #### Image capture reliability in social media WebViews Fixed an issue where document captures within Instagram WebViews would occasionally result in blurry or invalid images. ## 6.7.1 (March 13, 2025) ### 🛠 Improvements/Fixes #### Camera stream autoplay in mobile WebView Fixed an issue where the camera stream wasn't playing automatically when initializing the SDK inside a mobile WebView. ## 6.7.0 (March 10, 2025) ### 🚀 Performance Improvement #### Faster SDK loading time * Simplified the camera initialization process, reducing unnecessary operations and improving efficiency. ### 🛠 Improvements/Fixes #### Removal of camera switching options The following appearance options have been **removed**: * `hideCameraSwitchButton` * `cameraSwitchButtonIconSize` * `cameraSwitchButtonIconColor` * `cameraSwitchButtonIcon` #### Fixes for screen rotation issues * Fixed issues where the interface was not correctly rendered when switching between portrait and landscape mode on Android and iOS devices. * Improved the consistency of the modal display when changing screen orientation. ## 6.6.1 (February 26, 2025) ### 🛠 Improvements/Fixes #### Modal display issues on iOS and during screen orientation changes * Fixed an issue on iOS devices where the SDK modal was not displayed correctly when starting the capture process in portrait mode. * Fixed issues on some devices where the SDK modal was not displayed correctly when the screen orientation was changed. * Improved event listener management to prevent unexpected behavior and memory leaks. ## 6.5.2 (February 04, 2025) ### 🐛 Bug fix Add upload error invalid document title and details. More details can be found [here](/caf-sdk/web-javascript/getting-started/document-detector/sdk-builder-options/messages.md#guau2es7dwb3). ## 6.5.1 (January 31, 2025) ### 🐛 Bug fix Improve camera choice on iPhone ## 6.5.0 (January 30, 2025) ### 🚨 Breaking change #### Removal of permissions initialization method The method `initPermissions` has been removed in this version. The SDK now automatically initializes the required permissions when the SDK is initialized. ### 🆕 New feature #### ⛔ Prevent camera access requests in upload mode The SDK now prevents unnecessary camera access requests during the upload mode. The camera access request is only triggered when the user starts the capture on "automatic" or "manual" mode. ### 🛠 Improvements/Fixes * Enhanced SDK UI behavior with animations and better handling of modal states. * Fixed bugs related to camera initialization, UI behavior, and error handling. ## 6.4.0 (January 29, 2025) {% hint style="warning" %} **Important Notice: Experimental Feature**\ This version introduces an experimental feature flag that may undergo changes in the future. When using this flag, it is important to be prepared for code updates in future versions. {% endhint %} ### 🆕 New feature #### Auto-detect file extension during upload The feature flag `uploadMimeDetection` enables the SDK to automatically detect the file extension of the uploaded document. This feature is disabled by default. For this feature to work, the `expectedDocument` must be `RG_FULL` or `CNH_FULL`. When enabled, the SDK will apply the following validations: * If the uploaded document is a **PDF**, it must contain **both the front and back sides** in the same file. * If the uploaded document is an **image**, you must upload **two separate images**: the first with the **front** and the second with the **back** of the document. This feature allows users to upload `RG_FULL` and `CNH_FULL` documents without manually specifying the file extension. ## 6.3.0 (December 26, 2024) ### 🆕 New features #### 📷 Framing Analyzer Toggle Added a new option to enable or disable the AI-guided framing analysis. This AI guides the user to correctly position the document in the camera, and it is enabled by default. More details can be found [here](/caf-sdk/web-javascript/getting-started/document-detector/documentdetector.md#xtquz7g7g6lm). ## 6.2.0 (December 16, 2024) {% hint style="warning" %} **Important Notice: Breaking Changes Ahead**\ This version includes significant breaking changes that will impact how you use the SDK. We highly recommend reviewing the full release notes and the updated documentation before upgrading to this version. {% endhint %} ### 🚨 Breaking changes #### 🛠 SDK instanciation/builder The SDK class `DocumentDetectorSdk` has been renamed to `DocumentDetector`. The following parameters have been removed from the `options` object: * `analyticsSettings` (use [`analytics`](/caf-sdk/web-javascript/getting-started/document-detector/sdk-builder-options/analytics.md) instead) * `environmentSettings.disableDesktopExecution` (use [`blockExecutionOnDesktops`](/caf-sdk/web-javascript/getting-started/document-detector/documentdetector.md#xtquz7g7g6lm) instead) * `capturerSettings.disableAdvancedCapturing` * `appearanceSettings` (use [`appearance`](/caf-sdk/web-javascript/getting-started/document-detector/sdk-builder-options/appearance.md) instead) * `textSettings` (use [`messages`](/caf-sdk/web-javascript/getting-started/document-detector/sdk-builder-options/messages.md) instead) #### 📷 Capture method The following parameters have been removed from the `capture` method: * `container` (now the SDK will be displayed as a modal) * `stages` Now, the `capture` method only takes a single parameter: [`captureOptions`](/caf-sdk/web-javascript/getting-started/document-detector/methods.md). The method output has also changed. The following properties have been removed: * `imageUrl` (use [`image.url`](/caf-sdk/web-javascript/getting-started/document-detector/methods.md) instead) * `imageKey` (use [`image.storageInfo.key`](/caf-sdk/web-javascript/getting-started/document-detector/methods.md) instead) * `blob` (use [`image.blob`](/caf-sdk/web-javascript/getting-started/document-detector/methods.md) instead) * `documentType` (use [`detectedDocument.type`](/caf-sdk/web-javascript/getting-started/document-detector/methods.md) instead) * `documentSide` (use [`detectedDocument.side`](/caf-sdk/web-javascript/getting-started/document-detector/methods.md) instead) The method now returns a [`CaptureResult`](/caf-sdk/web-javascript/getting-started/document-detector/methods.md) object. ### 🆕 New features #### 🖼️ New UI The SDK now displays a new UI that improves the user experience and the document capture process. Instead of displaying the SDK in a container, the SDK is now displayed as a modal that covers the entire screen, making it easier for the user to capture the document. #### 🧠 New AI model The SDK now uses a new AI model to help the user to correctly position the document in the camera. This new model increases the percentage of successful captures and the OCR accuracy. #### 📊 Analytics options Added debug mode to the SDK. This mode will display additional information in the console. To enable it, set the `analytics.enableDebugMode` option to `true` when creating the SDK instance. #### 🎨 Appearance options * Added an option to customize the icon color of the SDK close button. Use the `appearance.general.closeButtonIconColor` option to set the color. * Added an object to customize the appearance of the SDK on "upload" mode. Use the `appearance.upload` option to set the appearance. More details for each property can be found [here](/caf-sdk/web-javascript/getting-started/document-detector/sdk-builder-options/appearance.md#cy8sf4ohycir). #### 📨 Customize messages * Added more options to customize the messages displayed by the SDK. Use the `messages` option to define the SDK messages. More details for each property can be found [here](/caf-sdk/web-javascript/getting-started/document-detector/sdk-builder-options/messages.md). * Added an object to customize the messages displayed by the SDK on "upload" mode. Use the `messages.upload` option to define the messages. More details for each property can be found [here](/caf-sdk/web-javascript/getting-started/document-detector/sdk-builder-options/messages.md#guau2es7dwb3). #### 📷 Capture process * Added an option for the "upload" mode to define which document types are accepted. Use the `captureOptions.upload.uploadFileType` option to set the accepted document types. More details can be found [here](/caf-sdk/web-javascript/getting-started/document-detector/methods.md#capture). * Added an option to pass an identifier of the user that is capturing the document. Use the `captureOptions.personID` option to set the user identifier. More details can be found [here](/caf-sdk/web-javascript/getting-started/document-detector/methods.md#capture). * Added a property to the capture output to indicate if the capture is valid. Use the `CaptureResult.isCaptureValid` property to check if the capture was successful. More details can be found [here](/caf-sdk/web-javascript/getting-started/document-detector/methods.md#capture). #### 🔓 Init permissions method Added a new method to initialize the permissions required to use the SDK. More details can be found [here](/caf-sdk/web-javascript/getting-started/document-detector/methods.md#initpermissions). #### 🤖 Load AI model method Added a new method to load the AI model used by the SDK. More details can be found [here](/caf-sdk/web-javascript/getting-started/document-detector/methods.md#loadaimodel). #### 🖥️ Browser support checker Added a new method to check if the current browser is supported by the SDK. More details can be found [here](/caf-sdk/web-javascript/getting-started/document-detector/methods.md#issupported). #### ❓ SDK initialization checker Added a new method to check if the SDK is correctly initialized. More details can be found [here](/caf-sdk/web-javascript/getting-started/document-detector/methods.md#getisinitialized). ### 🛠 Improvements/Fixes * Added a mechanism to force the SDK capture mode to "manual" when the user device is not performing well with the "automatic" mode. * Fixed an issue where the SDK would not display the whole camera view to the user, causing the captured image to be different from what is displayed. * Removed incorrect constraints causing slowness during the capture process, particularly in two-sided document captures. * Improved the frame analysis process to avoid being performed concurrently, which caused performance issues on some cases. * Fixed an issue where the frame captured was not the same as the one analyzed by the AI model, which could cause incorrect results. --- # 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-1.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.