Importando o SDK

Para utilizar o DocumentDetector, você pode tanto importar remotamente o arquivo .js como baixá-lo localmente.

Remotamente

Inclua o arquivo .js diretamente do CDN:

<script src="https://repo.combateafraude.com/javascript/release/document-detector/<VERSION>.umd.js" type="text/javascript"></script>

Você pode recuperar a classe do SDK utilizando o seguinte código:

const { DocumentDetectorSdk } = window['@combateafraude/document-detector'];

Localmente

Baixe o arquivo .js e importe-o como um módulo ES6:

import { DocumentDetectorSdk } from '../assets/js/document-detector-<VERSION>.js'

Construção

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

const sdk = new DocumentDetectorSdk(options);

Parâmetros suportados

Parâmetro	Obrigatório?
`token` Token de autenticação para consumir o SDK.	Sim
`language` Idioma das mensagens padrões, valores válidos: `pt_BR`, `en_US`, `es_MX`.	Não. O padrão é `pt_BR`
`environmentSettings.disableDesktopExecution` Flag indicando se a execução em desktops deve ser bloqueada.	Não. O padrão é `false`
`capturerSettings.disableAdvancedCapturing` Flag indicando se a captura avançada deve ser desabilitada*.	Não. O padrão é `false`
`appearenceSettings.captureButtonIcon` Customização do ícone de captura, aceita valores como url de imagem ou base64 de svgs.	Não
`appearenceSettings.captureIconSize` Customização do tamanho do ìcone referente ao campo captureButtonIcon.	Não
`appearenceSettings.captureButtonColor` Customização da cor do botão default de captura de imagem.	Não
`appearenceSettings.switchButtonIcon` Customização do ícone de troca de câmera, aceita valores como url de imagem ou base64 de svgs.	Não
`appearenceSettings.switchIconSize` Customização do tamanho do ícone referente ao campo switchButtonIcon.	Não
`appearenceSettings.switchIconColor` Customização da cor do ícone default de troca de câmera.	Não
`appearenceSettings.fontFamily` Altera a fonte de todos os elementos contidos no Sdk.	Não. O padrão é herdado da página
`textSettings.messages.processMessage` Customização da mensagem de processamento de imagem.	Não. O padrão é `"Processando sua foto, aguarde um momento"`
`textSettings.messages.wrongDocumentMessage` Customização da mensagem de documento inválido.	Não. O padrão é `"Este não é o documento esperado"`
`textSettings.messages.bothWrongSideMessage` Customização da mensagem de lado incorreto ao selecionar um lado `frente` ou `verso` e capturar ambos os lados.	Não. O padrão é `"Por favor, realize a captura com o documento fechado e com o lado correto para a câmera"`
`textSettings.messages.wrongSideMessage` Customização da mensagem de lado incorreto.	Não. O padrão é `"Este não é o lado esperado para este document"o`
`textSettings.messages.lowQualityMessage` Customização da mensagem de retorno da API por baixa qualidade de imagem.	Não. O padrão é `"A qualidade da captura não ficou legal. Certifique-se que está em um ambiente iluminado e tente novamente"`
`textSettings.messages.captureFailedMessage` Customização da mensagem de falha na captura.	Não. O padrão é `"Ops! Tivemos um problema ao processar sua imagem."`

* A captura avançada consiste no uso de APIs mais complexas e não tão estáveis em navegadores que oferecem suporte à mesma (e.g. ImageCapture)

Exemplo

const sdk = new DocumentDetectorSdk({
    token: `my-sdk-token`,
    language: `pt_BR`,
    environmentSettings: {
        disableDesktopExecution: false,
    },
    appearenceSettings: {
        hideCaptureTitle: false,
        hideCaptureMask: false,
        hideCameraSwitchButton: false,
        useGenericMask: false,
    },
    capturerSettings: {
        disableAdvancedCapturing: false,
    },
    textSettings: {
        messages: {
            processMessage: '',
            wrongDocumentMessage: '',
            bothWrongSideMessage: '',
            wrongSideMessage: '',
            lowQualityMessage: '',
            captureFailedMessage: '',
        }
});

CaptureStage

O CaptureStage permite que o cliente configure as etapas . Para isso, oferecemos o objeto CaptureStage, onde você pode definir os seguintes parâmetros:

Parâmetro
`mode` Modo de captura desejado. Podendo ser utilizado `manual`, `automatic` ou `upload`. Na captura manual, um botão será habilitado para o usuário realizar a captura, no upload será exibida a funcionalidade de upload de documentos ao invés da captura.
`attempts` Quantidade de tentativas do stage atual. Caso seja o único stage deve ser passado o valor `0`.
`duration` Tempo de duração do stage atual. Caso seja configurado mais de um stage, pode ser parametrizado o tempo total de cada stage, onde ao atingir o tempo total, será passado ao stage seguinte. Defina como `0` caso não deseje configurar um tempo para o stage.

Exemplo CaptureStage

const stages =[{mode: 'automatic', attempts: 3, duration: 60}, {mode: 'manual', attempts: 3, duration: 60}, {mode: 'upload', attempts: 0, duration: 0}];

Inicialização

`initialize(): Promise<void>`

O SDK conta com um método isolado de inicialização, para permitir um maior controle de quando ela ocorre.

Durante essa inicialização, o SDK irá inicializar suas variáveis internas e fazer download dos recursos necessários para sua execução.

[!] Você deve chamar este método antes de utilizar outros métodos do SDK.

[!] A inicialização do SDK pode levar alguns segundos. Recomendamos que você chame essa função o mais cedo possível no seu fluxo, para que a abertura do SDK seja suave para o usuário.

Exemplo

await sdk.initialize();

Utilização

Abertura e captura de documentos

`capture(container: HTMLElement, stages, {type: SupportedDocumentType, side: DocumentSide, totalAttempts?: Number}): Promise<Result>`

Método utilizado para carregar o SDK na tela e realizar a capture de documentos.

Irá inicializar a stream de vídeo (solicitando permissões se necessário) e carregá-la no container.

Parâmetros

Parâmetro	Tipo	Valores válidos
`type` Tipo de documento a ser capturado.	`string`	`any`¹, `rg`, `cnh`, `crlv`, `rne`, `passaporte`, `ctps`, `other`²
`side`⁶ Tipo de documento a ser capturado.	`string`	`front`, `back`, `both`⁴, `not_applicable`

¹ O tipo any não possui as validações de qualidade e tipo de documento, aceitando assim qualquer lado ou documento - recomendado para documentos não suportados como carteira da OAB.

² O tipo other corresponde a outros documentos (não incluindo os já especificados), como: carteira de vacinação, etc.

³ Se não especificado, usa-se um valor padrão de 30 segundos

⁴ O lado both corresponde ao documento mostrando ambos os lados na mesma foto (e.g. CNH aberta)

⁵ O parâmetro side depende do tipo de documento informado em type. Ver tabela abaixo.

Exemplo

// div or another element on DOM
const sdkContainer = document.getElementById('sdk-displayer');
await sdk.capture(sdkContainer, stages, {documentType ,documentSide, totalAttempts});

Lados aceitos para cada tipo de documento

Tipo de documento	Lados aceitos
`rg`	`front`, `back`, `both`
`cnh`	`front`, `back`, `both`
`rne`	`front`, `back`
`rnm`	`front`, `back`
`crlv`	`not_applicable`
`ctps`	`front`, `back`
`passport`	`both`
`any`	`not_applicable`
`other`	`front`, `back`, `both`

Retorno

O retorno consiste em um objeto com o seguintes campos:

Campo	Tipo	Descrição
`imageUrl`	`string`	Link temporário para a imagem, gerado pela nossa API
`imageKey`	`string`	Chave temporária para a imagem
`blob`	`Blob`	Blob da imagem capturada
`documentType`	`SupportedDocumentType`	Tipo do documento capturado
`documentSide`	`DocumentSide`	Lado do documento capturado

Exemplo

const result = sdk.capture(sdkContainer, stages, {documentType ,documentSide, totalAttempts});
// { imageUrl: '[link da imagem]', blob: Blob, documentType: 'rg', documentSide: 'front' }

Fechar SDK

`close(): Promise<void>`

Método utilizado para remover o SDK na tela, removendo os elementos visuais do SDK do DOM.

Irá remover os elementos visuais do SDK do DOM.

De-inicializar o SDK

`dispose(): Promise<void>`

Método utilizado para remover o SDK na tela.

Irá de-inicializar a stream de vídeo e limpar as variáveis internas do SDK

Exemplo completo

Em breve.