Notas da versão

7.0.0 (24 de junho de 2026)

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.

🚨 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):

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):

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.

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.

🛠 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 .

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.

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)

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.

🆕 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.

6.2.0 (16 de dezembro de 2024)

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.

🚨 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 em vez disso)
• environmentSettings.disableDesktopExecution (use blockExecutionOnDesktops em vez disso)
• capturerSettings.disableAdvancedCapturing
• appearanceSettings (use appearance em vez disso)
• textSettings (use messages 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.

A saída do método também mudou. As seguintes propriedades foram removidas:

• imageUrl (use image.url em vez disso)
• imageKey (use image.storageInfo.key em vez disso)
• blob (use image.blob em vez disso)
• documentType (use detectedDocument.type em vez disso)
• documentSide (use detectedDocument.side em vez disso)

O método agora retorna um(a) CaptureResult 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.

📨 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.
• 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.

📷 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.
• 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.
• 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.

🔓 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.

🤖 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.

🖥️ 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.

❓ 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.

🛠 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.