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