Primeiros passos

Requisitos

Antes de começar a usar o SDK Document Detector, você precisará ter o seguinte:

Um token de acesso Caf válido para autenticar o SDK (consulte esta documentação para mais informações).
Um arquivo HTML com uma <body> tag. O SDK renderizará a interface de detecção de documentos nessa tag.

Importando o SDK

Baixe o .umd.js arquivo: document-detector-7.0.0.umd.js
Baixe o .wasm arquivo: dd-validator.wasm
Coloque ambos os arquivos no mesmo diretório (por exemplo, public/sdks/caf-dd/).
Importe o .umd.js arquivo no seu arquivo HTML. Por exemplo (assumindo um public/index.html arquivo):

<script src="sdks/caf-dd/document-detector-7.0.0.umd.js"></script>

Importe o SDK como um módulo JavaScript em uma tag script:

<script type="module">
  const { DocumentDetector } = window["@combateafraude/document-detector"];
  // uso do SDK aqui
</script>

Construção e uso

Para usar o SDK Document Detector, você precisará criar uma instância da classe DocumentDetector. Essa classe permitirá inicializar o SDK, capturar documentos e fechar o SDK. Você também pode passar opções para o SDK para personalizar seu comportamento.

No construtor, o SDK recebe um único parâmetro com as configurações:

const sdk = new DocumentDetector(options);

Esse parâmetro é um objeto que contém as opções de configuração do SDK. Essas opções personalizam o comportamento do SDK de acordo com os requisitos da sua aplicação. A tabela a seguir lista as opções disponíveis:

Parâmetro

Tipo

Obrigatório?

Valor padrão

token

Token de autenticação para consumir o SDK.

String

Sim.

language

Idioma padrão das mensagens, valores válidos: en_US, pt_BR, es_MX.

String

Não.

pt_BR

blockExecutionOnDesktops

Sinalizador indicando se a execução em desktops deve ser bloqueada ou não

boolean

Não.

false

enableVisibilityChangeSecurity

Ativa a melhoria de segurança responsável por fechar o SDK quando o usuário alterna entre abas do navegador.

boolean

Não.

false

enableFramingAnalyzer

Ativa ou desativa a análise de enquadramento guiada por IA.

Quando ativado, o SDK usa um modelo de IA para analisar o fluxo da câmera e fornecer feedback em tempo real ao usuário, orientando-o a ajustar a posição e a orientação do documento para uma captura ideal.

Quando desativado, o SDK força o modo de captura para "manual" e não realiza nenhuma análise de enquadramento guiada por IA. O frame é capturado e enviado diretamente ao nosso backend para processamento. Essa abordagem pode reduzir a qualidade da imagem, mas melhora significativamente o desempenho.

Considere desativar esta opção se precisar otimizar o desempenho do SDK em dispositivos com recursos limitados e o caso de uso da sua aplicação priorizar a quantidade de capturas em vez da qualidade.

boolean

Não.

true

analytics

Especifica as configurações de analytics do SDK. Este parâmetro permite configurar o rastreamento analítico dentro do SDK.

Objeto

Não.

ver tabela

appearance

Especifica as configurações de aparência da interface do usuário (UI) do SDK. Este parâmetro permite personalizar a aparência visual dos componentes do SDK para combinar com o visual da sua aplicação.

Aprimorado na v6.8.3: Agora usa um formato de objeto aninhado para melhor organização e legibilidade.

Objeto

Não.

ver tabela

messages

Personaliza as mensagens exibidas no SDK para otimizar a experiência do usuário.

Aprimorado na v6.8.3: Agora usa um formato de objeto aninhado para melhor organização e legibilidade.

Objeto

Não.

ver tabela

Formato de configuração

A partir da versão 6.8.3, o SDK usa um formato de objeto aninhado para configurar as opções de aparência e mensagens, o que proporciona melhor organização e legibilidade:

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" }
    }
  }
}

Se você estiver atualizando a partir de uma versão anterior, suas configurações existentes com notação de ponto (por exemplo, "general.fontFamily": "arial") continuarão funcionando. No entanto, recomendamos migrar para o formato de objeto aninhado para uma melhor organização do código.

Exemplo

index.html

<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Detector de Documentos</title>
  </head>
  <body>
    <script src="sdks/caf-dd/document-detector-7.0.0.umd.js"></script>
    <script type="module" src="index.js"></script>
  </body>
</html>

index.js

const options = {
  token: "Meu token de acesso",
  language: "pt_BR",
  blockExecutionOnDesktops: false,
  enableVisibilityChangeSecurity: false,
  enableFramingAnalyzer: true,
  analytics: {
    enabled: true,
    trackingId: "Meu ID de rastreamento",
    trackingInfo: {
      myProp: "Minhas informações de rastreamento",
    },
    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);

// Este método é opcional, mas pode melhorar significativamente a
// experiência de carregamento do SDK. Recomendamos usá-lo o mais cedo possível em seu
// fluxo, até mesmo antes de chegar à tela de carregamento do SDK. No entanto, se isso
// não for viável ou não estiver alinhado com a natureza do seu fluxo ao
// integrar o SDK, o método initialize cuidará de tudo
// necessário para garantir que o SDK funcione corretamente sem a necessidade deste método.
await documentDetector.loadAiModel();

// Agora que a câmera foi permitida, podemos inicializar o SDK
await documentDetector.initialize();

// Agora que o SDK foi inicializado, podemos iniciar o processo de captura
// Este é o momento em que o SDK será exibido ao usuário por meio de um modal
// O processo de captura será iniciado e o usuário poderá capturar o documento
// O método de captura retorna uma promise que é resolvida quando o processo de captura termina
const captureResult = await documentDetector.capture({
  expectedDocument: "cnh_front",
  mode: "automatic",
  automaticCaptureMaxDuration: 30,
  personID: "my-person-id",
});

// Agora podemos fechar o SDK para parar de exibi-lo
await documentDetector.close();

// E descarte o SDK para liberar recursos
await documentDetector.dispose();

Tratamento de erros de construção

Nome do erro

Descrição

CafSdkBuildError

Ocorreu um erro durante a construção do SDK.

CafSdkBlockedError

A construção do SDK foi bloqueada.

CafInvalidOptionsError

As opções de construção do SDK são inválidas. Revise as opções fornecidas ao SDK.

CafUnsupportedError

O SDK não é suportado neste dispositivo, navegador ou sistema operacional.

Exemplo

try {
  const sdk = new DocumentDetector(options);
} catch (error) {
  switch (error.name) {
    case "CafSdkBuildError":
      console.error("Erro na construção do SDK:", error.message);
      break;
    case "CafSdkBlockedError":
      console.error("Erro de bloqueio do SDK:", error.message);
      break;
    case "CafInvalidOptionsError":
      console.error("Erro de opções inválidas:", error.message);
      break;
    case "CafUnsupportedError":
      console.error("Erro não suportado:", error.message);
      break;
    default:
      console.error("Erro inesperado de construção:", error.name, error.message);
  }
}

Para mais informações sobre os métodos e propriedades do SDK, confira os métodos do SDK .

Atualizado há 1 mês