> 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/caf-sdk-pt-br/web-javascript/getting-started/document-detector/documentdetector-1.md). # Notas de versão ## 7.0.0 (24 de junho de 2026) {% hint style="warning" %} **Aviso importante: alterações incompatíveis**\ Esta versão inclui uma alteração incompatível significativa no `capture()` saída do método. O método agora retorna uma **string JWT assinada** em vez do(a) anterior `Result` objeto. Revise o guia de migração abaixo antes de atualizar. {% endhint %} ### 🚨 Alterações incompatíveis #### Saída do método capture: resposta JWT assinada O `capture()` método não retorna mais um(a) estruturado(a) `Result` objeto. Em vez disso, retorna um(a) **string JWT assinada** (`signedResponse`) que codifica os metadados da captura. Esse JWT é gerado e assinado pelo backend, permitindo a verificação da integridade da captura no lado do servidor. **Antes (v6.x):** ```javascript const result = await documentDetector.capture(options); // result era um objeto estruturado: // { // image: { // url: "https://...", // blob: Blob, // storageInfo: { key: "...", bucket: "..." } // }, // detectedDocument: { // type: "cnh", // ex.: "rg", "cnh_new", "passport" // side: "front" // ex.: "front", "back", "both" // }, // isCaptureValid: true // } const imageUrl = result.image.url; const documentType = result.detectedDocument.type; const isValid = result.isCaptureValid; ``` **Depois (v7.0.0):** ```javascript const signedResponse = await documentDetector.capture(options); // signedResponse é uma string JWT: "eyJhbGciOiJIUzI1NiJ9..." // Decodifique-a para acessar os detalhes da captura. Exemplo: const payload = decodeJwt(signedResponse); // o payload contém: // { // 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; ``` #### Referência de mapeamento de campos A tabela a seguir mapeia os `Result` campos do objeto anterior para seus equivalentes no payload JWT decodificado: | Campo anterior (v6.x) | Novo campo (payload JWT v7.0.0) | Observações | | --------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------ | | `result.image.url` | `payload.captures[0].imageUrl` | URL pré-assinada do S3. | | `result.image.blob` | — | Não está mais disponível. A imagem pode ser acessada por meio de `imageUrl` somente. | | `result.image.storageInfo.key` | — | Não é mais exposto no payload JWT. | | `result.image.storageInfo.bucket` | — | Não é mais exposto no payload JWT. | | `result.detectedDocument.type` | `payload.documentType` | Agora em maiúsculas (ex. `"NEW_CNH"` em vez de `"cnh_new"`). | | `result.detectedDocument.side` | `payload.captures[0].scannedLabel` | O lado está embutido no rótulo (ex. `"new_cnh_front"`, `"rg_back"`, `"cnh_full"`). | | `result.isCaptureValid` | — | Não é mais exposto. Uma chamada bem-sucedida `capture()` (sem erro lançado) indica uma captura válida. | #### Novo erro: CafSdkCanceledError O `capture()` método agora lança um(a) `CafSdkCanceledError` quando o usuário cancela a captura (ex.: fecha o modal). Antes, o método era resolvido silenciosamente com `undefined`. ```javascript try { const signedResponse = await documentDetector.capture(options); } catch (error) { if (error.name === "CafSdkCanceledError") { // Usuário cancelou — trate com elegância } } ``` Para mais detalhes sobre o tratamento de erros e o gerenciamento de estado após erros, consulte a documentação atualizada do [documentação do método capture](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md#bxk99swpyysw). ### 🛠 Melhorias/Correções #### Resiliência do logger após dispose * Corrigido um erro que podia ocorrer quando operações assíncronas tentavam registrar logs após o SDK ser descartado. O logger agora lida com segurança com chamadas feitas após `dispose()`. ## 6.13.0 (16 de março de 2026) ### 🆕 Novos recursos #### Novos ouvintes de eventos Adicionados três novos ouvintes de eventos que permitem acompanhar momentos-chave no ciclo de vida da captura e reagir de acordo: * **`capture_ready`**: Disparado quando a tela de captura do SDK (pré-visualização da câmera ou interface de envio) é renderizada e fica pronta para interação do usuário. O detalhe do evento inclui o modo de captura (`manual` ou `upload`) e o documento esperado (tipo e lado). * **`upload_button_clicked`**: Disparado quando o usuário clica no botão de envio no modo de envio. * **`capture_result`**: Disparado após um documento ser capturado e validado com sucesso. O detalhe do evento inclui o modo de captura, o documento esperado (tipo e lado) e um booleano indicando se a captura é válida. Para mais detalhes, consulte a [documentação de ouvintes de eventos](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/sdk-event-listeners.md) . ## 6.12.1 (03 de março de 2026) ### 🛠 Melhorias/Correções #### Detecção aprimorada do tipo de arquivo enviado * Corrigido um problema em que o SDK podia rejeitar documentos válidos durante o envio quando os metadados do tipo de arquivo estavam ausentes ou incorretos. Isso ocorria com frequência com arquivos selecionados de serviços de armazenamento em nuvem (ex.: Google Drive), WebViews ou iframes. Agora o SDK valida o conteúdo real do arquivo em vez de depender apenas dos metadados do arquivo. ## 6.12.0 (03 de fevereiro de 2026) ### 🛠 Melhorias/Correções #### Otimização inteligente da captura Resolve travamentos intermitentes e problemas de confiabilidade da captura relatados na versão 6.11.1. * **Aprendizado adaptativo**: O SDK detecta e memoriza automaticamente as melhores configurações de captura para cada dispositivo, eliminando tentativas malsucedidas repetidas e melhorando a confiabilidade. * **Persistente entre sessões**: A otimização é salva no navegador e aplicada imediatamente em visitas posteriores. ## 6.11.1 (01 de dezembro de 2025) ### 🛠 Melhorias/Correções #### Qualidade e confiabilidade aprimoradas da captura de quadros * Adicionada **validação automática de qualidade** para evitar a captura de imagens muito escuras, muito claras ou de baixa qualidade. * Introduzido um **mecanismo inteligente de fallback de captura**: o SDK agora tenta automaticamente métodos alternativos de captura se o método principal de alta qualidade falhar ou não for compatível. * Adicionada **mensagens de erro específicas de contexto** para orientar os usuários quando a captura falha devido a condições ambientais (ex.: "O ambiente está muito escuro" ou "O ambiente está muito claro"). #### Análise aprimorada do SDK * Melhoramos o registro ao adicionar informações sobre tentativas de captura e métricas específicas de qualidade. * Adicionada **rastreamento de abandono**: quando um usuário sai abruptamente do fluxo antes de concluí-lo, como ao fechar a janela do navegador, minimizar a aba ou navegar para outra página, o SDK registrará esse evento para fornecer melhores insights sobre a jornada do usuário e possíveis motivos para o abandono. ## 6.11.0 (17 de novembro de 2025) ### 🆕 Novos recursos #### Tratamento de erros padronizado * Experiência de tratamento de erros mais consistente e previsível com tipos de erro padronizados. Todos os erros lançados pelo SDK seguem uma estrutura unificada, facilitando identificar e lidar com cenários de erro específicos na sua integração. ## 6.10.0 (03 de novembro de 2025) ### 🆕 Novos recursos #### Rastreamento aprimorado de analytics * Melhorado o rastreamento de eventos de analytics, oferecendo melhores recursos de monitoramento de erros e depuração do SDK. ## 6.8.5 (25 de setembro de 2025) ### 🛠 Melhorias/Correções #### Corrigidos erros de processamento de imagem durante a captura de documentos * Corrigidos erros de processamento de imagem que podiam causar falhas de captura com determinados formatos ## 6.8.4 (08 de setembro de 2025) ### 🛠 Melhorias/Correções #### Melhorias de confiabilidade no modo de envio * Corrigidas falhas de envio ao selecionar arquivos de serviços em nuvem (ex.: Google Drive) * Resolvidos casos em que os envios podiam travar; agora as mensagens de erro são exibidas * Comportamento de envio aprimorado em diferentes navegadores e ambientes móveis ## 6.8.3 (12 de agosto de 2025) ### 🛠 Melhorias/Correções #### Melhorias nas opções de configuração * Configuração de aparência e mensagens aprimorada para suportar formato de objeto aninhado para melhor organização e legibilidade * Corrigidos problemas em que as personalizações de aparência e mensagens podiam não ser aplicadas corretamente em certos cenários * Confiabilidade aprimorada da aplicação de estilos personalizados em todos os componentes do SDK * Mantida a compatibilidade total com configurações de notação com ponto já existentes ## 6.8.1 (29 de abril de 2025) ### 🛠 Melhorias/Correções #### Refatoração da arquitetura de analytics do SDK Corrigida a transmissão de dados de analytics removendo dependências de bibliotecas externas de analytics e migrando para um sistema de comunicação mais confiável e direto. ## 6.7.3 (31 de março de 2025) ### 🛠 Melhorias/Correções #### Estabilidade do modo de envio Corrigido um problema em que o modo de envio de documentos disparava incorretamente operações específicas da câmera, podendo causar comportamento inesperado. Esta melhoria garante que o SDK trate corretamente os diferentes modos de captura com a funcionalidade apropriada. ## 6.7.2 (20 de março de 2025) ### 🛠 Melhorias/Correções #### Confiabilidade da captura de imagem em WebViews de redes sociais Corrigido um problema em que capturas de documentos dentro de WebViews do Instagram ocasionalmente resultavam em imagens borradas ou inválidas. ## 6.7.1 (13 de março de 2025) ### 🛠 Melhorias/Correções #### Reprodução automática do fluxo da câmera em WebView móvel Corrigido um problema em que o fluxo da câmera não era reproduzido automaticamente ao inicializar o SDK dentro de uma WebView móvel. ## 6.7.0 (10 de março de 2025) ### 🚀 Melhoria de desempenho #### Tempo de carregamento do SDK mais rápido * Simplificamos o processo de inicialização da câmera, reduzindo operações desnecessárias e melhorando a eficiência. ### 🛠 Melhorias/Correções #### Remoção das opções de troca de câmera As seguintes opções de aparência foram **removidas**: * `hideCameraSwitchButton` * `cameraSwitchButtonIconSize` * `cameraSwitchButtonIconColor` * `cameraSwitchButtonIcon` #### Correções para problemas de rotação de tela * Corrigidos problemas em que a interface não era renderizada corretamente ao alternar entre os modos retrato e paisagem em dispositivos Android e iOS. * Melhorada a consistência da exibição do modal ao alterar a orientação da tela. ## 6.6.1 (26 de fevereiro de 2025) ### 🛠 Melhorias/Correções #### Problemas de exibição do modal no iOS e durante mudanças de orientação da tela * Corrigido um problema em dispositivos iOS em que o modal do SDK não era exibido corretamente ao iniciar o processo de captura no modo retrato. * Corrigidos problemas em alguns dispositivos em que o modal do SDK não era exibido corretamente quando a orientação da tela era alterada. * Gerenciamento de ouvintes de eventos aprimorado para evitar comportamento inesperado e vazamentos de memória. ## 6.5.2 (04 de fevereiro de 2025) ### 🐛 Correção de bug Adiciona título e detalhes de erro de envio de documento inválido. Mais detalhes podem ser encontrados [aqui](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/sdk-builder-options/messages.md#guau2es7dwb3). ## 6.5.1 (31 de janeiro de 2025) ### 🐛 Correção de bug Melhorar a escolha da câmera no iPhone ## 6.5.0 (30 de janeiro de 2025) ### 🚨 Alteração incompatível #### Remoção do método de inicialização de permissões O método `initPermissions` foi removido nesta versão. O SDK agora inicializa automaticamente as permissões necessárias quando é inicializado. ### 🆕 Nova funcionalidade #### ⛔ Impedir solicitações de acesso à câmera no modo de envio O SDK agora impede solicitações desnecessárias de acesso à câmera durante o modo de envio. A solicitação de acesso à câmera só é disparada quando o usuário inicia a captura no modo "automatic" ou "manual". ### 🛠 Melhorias/Correções * Comportamento da UI do SDK aprimorado com animações e melhor tratamento dos estados do modal. * Corrigidos bugs relacionados à inicialização da câmera, ao comportamento da UI e ao tratamento de erros. ## 6.4.0 (29 de janeiro de 2025) {% hint style="warning" %} **Aviso importante: recurso experimental**\ Esta versão introduz um sinalizador de recurso experimental que pode sofrer alterações no futuro. Ao usar esse sinalizador, é importante estar preparado para atualizações de código em versões futuras. {% endhint %} ### 🆕 Nova funcionalidade #### Detectar automaticamente a extensão do arquivo durante o envio O sinalizador de recurso `uploadMimeDetection` permite que o SDK detecte automaticamente a extensão do arquivo do documento enviado. Este recurso está desativado por padrão. Para que este recurso funcione, o `expectedDocument` deve ser `RG_FULL` ou `CNH_FULL`. Quando habilitado, o SDK aplicará as seguintes validações: * Se o documento enviado for um **PDF**, ele deve conter **tanto a frente quanto o verso** no mesmo arquivo. * Se o documento enviado for uma **imagem**, você deve enviar **duas imagens separadas**: a primeira com a **frente** e a segunda com o **verso** do documento. Este recurso permite que os usuários enviem `RG_FULL` e `CNH_FULL` documentos sem especificar manualmente a extensão do arquivo. ## 6.3.0 (26 de dezembro de 2024) ### 🆕 Novos recursos #### 📷 Alternância do Analisador de Enquadramento Adicionada uma nova opção para ativar ou desativar a análise de enquadramento guiada por IA. Esta IA orienta o usuário a posicionar corretamente o documento na câmera, e ela está ativada por padrão. Mais detalhes podem ser encontrados [aqui](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/documentdetector.md#xtquz7g7g6lm). ## 6.2.0 (16 de dezembro de 2024) {% hint style="warning" %} **Aviso importante: alterações incompatíveis à frente**\ Esta versão inclui alterações incompatíveis significativas que afetarão a forma como você usa o SDK. Recomendamos fortemente revisar as notas de versão completas e a documentação atualizada antes de atualizar para esta versão. {% endhint %} ### 🚨 Alterações incompatíveis #### 🛠 instanciação/construtor do SDK A classe SDK `DocumentDetectorSdk` foi renomeada para `DocumentDetector`. Os seguintes parâmetros foram removidos do `options` objeto: * `analyticsSettings` (use [`analytics`](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/sdk-builder-options/analytics.md) em vez disso) * `environmentSettings.disableDesktopExecution` (use [`blockExecutionOnDesktops`](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/documentdetector.md#xtquz7g7g6lm) em vez disso) * `capturerSettings.disableAdvancedCapturing` * `appearanceSettings` (use [`appearance`](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/sdk-builder-options/appearance.md) em vez disso) * `textSettings` (use [`messages`](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/sdk-builder-options/messages.md) em vez disso) #### 📷 Método capture Os seguintes parâmetros foram removidos do `capture` método: * `container` (agora o SDK será exibido como um modal) * `stages` Agora, o `capture` método agora aceita apenas um único parâmetro: [`captureOptions`](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md). A saída do método também mudou. As seguintes propriedades foram removidas: * `imageUrl` (use [`image.url`](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md) em vez disso) * `imageKey` (use [`image.storageInfo.key`](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md) em vez disso) * `blob` (use [`image.blob`](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md) em vez disso) * `documentType` (use [`detectedDocument.type`](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md) em vez disso) * `documentSide` (use [`detectedDocument.side`](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md) em vez disso) O método agora retorna um(a) [`CaptureResult`](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md) objeto. ### 🆕 Novos recursos #### 🖼️ Nova interface O SDK agora exibe uma nova interface que melhora a experiência do usuário e o processo de captura de documentos. Em vez de exibir o SDK em um contêiner, o SDK agora é exibido como um modal que cobre toda a tela, facilitando a captura do documento pelo usuário. #### 🧠 Novo modelo de IA O SDK agora usa um novo modelo de IA para ajudar o usuário a posicionar corretamente o documento na câmera. Esse novo modelo aumenta a porcentagem de capturas bem-sucedidas e a precisão do OCR. #### 📊 Opções de analytics Adicionado o modo de depuração ao SDK. Esse modo exibirá informações adicionais no console. Para ativá-lo, defina a `analytics.enableDebugMode` opção para `true` ao criar a instância do SDK. #### 🎨 Opções de aparência * Adicionada uma opção para personalizar a cor do ícone do botão de fechar do SDK. Use a `appearance.general.closeButtonIconColor` opção para definir a cor. * Adicionado um objeto para personalizar a aparência do SDK no modo "upload". Use a `appearance.upload` opção para definir a aparência. Mais detalhes sobre cada propriedade podem ser encontrados [aqui](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/sdk-builder-options/appearance.md#cy8sf4ohycir). #### 📨 Personalizar mensagens * Adicionadas mais opções para personalizar as mensagens exibidas pelo SDK. Use a `messages` opção para definir as mensagens do SDK. Mais detalhes sobre cada propriedade podem ser encontrados [aqui](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/sdk-builder-options/messages.md). * Adicionado um objeto para personalizar as mensagens exibidas pelo SDK no modo "upload". Use o `messages.upload` opção para definir as mensagens. Mais detalhes sobre cada propriedade podem ser encontrados [aqui](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/sdk-builder-options/messages.md#guau2es7dwb3). #### 📷 Processo de captura * Adicionada uma opção para o modo "upload" definir quais tipos de documento são aceitos. Use o `captureOptions.upload.uploadFileType` opção para definir os tipos de documento aceitos. Mais detalhes podem ser encontrados [aqui](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md#capture). * Adicionada uma opção para passar um identificador do usuário que está capturando o documento. Use o `captureOptions.personID` opção para definir o identificador do usuário. Mais detalhes podem ser encontrados [aqui](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md#capture). * Adicionada uma propriedade na saída da captura para indicar se a captura é válida. Use o `CaptureResult.isCaptureValid` propriedade para verificar se a captura foi bem-sucedida. Mais detalhes podem ser encontrados [aqui](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md#capture). #### 🔓 Método de inicialização de permissões Adicionado um novo método para inicializar as permissões necessárias para usar o SDK. Mais detalhes podem ser encontrados [aqui](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md#initpermissions). #### 🤖 Método de carregamento do modelo de IA Adicionado um novo método para carregar o modelo de IA usado pelo SDK. Mais detalhes podem ser encontrados [aqui](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md#loadaimodel). #### 🖥️ Verificador de suporte do navegador Adicionado um novo método para verificar se o navegador atual é compatível com o SDK. Mais detalhes podem ser encontrados [aqui](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md#issupported). #### ❓ Verificador de inicialização do SDK Adicionado um novo método para verificar se o SDK foi inicializado corretamente. Mais detalhes podem ser encontrados [aqui](/caf-sdk/caf-sdk-pt-br/web-javascript/getting-started/document-detector/methods.md#getisinitialized). ### 🛠 Melhorias/Correções * Adicionado um mecanismo para forçar o modo de captura do SDK para "manual" quando o dispositivo do usuário não estiver performando bem com o modo "automático". * Corrigido um problema em que o SDK não exibia toda a visualização da câmera para o usuário, fazendo com que a imagem capturada fosse diferente do que era exibido. * Removidas restrições incorretas que causavam lentidão durante o processo de captura, particularmente em capturas de documentos frente e verso. * Melhorado o processo de análise de quadros para evitar que fosse executado simultaneamente, o que causava problemas de desempenho em alguns casos. * Corrigido um problema em que o quadro capturado não era o mesmo analisado pelo modelo de IA, o que podia causar resultados incorretos. --- # 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/caf-sdk-pt-br/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.