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
Os campos sem valor padrão são obrigatórios.
Campo | Tipo | Valor padrão | Descrição |
---|---|---|---|
token | string | Token de autenticação para consumir o SDK | |
environmentSettings.disableDesktopExecution | bool | false | Flag indicando se a execução em desktops deve ser bloqueada |
capturerSettings.disableAdvancedCapturing | bool | false | Flag indicando se a captura avançada deve ser desabilitada* |
(DEPRECATED) appearenceSettings.hideCaptureTitle | bool | false | Flag indicando se o texto no topo da tela de captura deve ser oculto |
(DEPRECATED) appearenceSettings.hideCaptureMask | bool | false | Flag indicando se a máscara deve ser oculta |
(DEPRECATED) appearenceSettings.hideCameraSwitchButton | bool | false | Flag indicando se o botão para alternar entre câmeras deve ser oculto |
(DEPRECATED) appearenceSettings.useGenericMask | bool | false | Flag indicando se a máscara utilizada na captura deve ser genérica (igual para todos os tipos de documento) |
* 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)
** As opções de aparência foram depreciadas pois um sistema mais avançado de customização será lançado.
Exemplo
const sdk = new DocumentDetectorSdk({
token: `my-sdk-token`,
environmentSettings: {
disableDesktopExecution: false,
},
appearenceSettings: {
hideCaptureTitle: false,
hideCaptureMask: false,
hideCameraSwitchButton: false,
useGenericMask: false,
},
capturerSettings: {
disableAdvancedCapturing: false,
}
});
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
open(container: HTMLElement): Promise<void>
Método utilizado para carregar o SDK na tela.
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 | Descrição |
---|---|---|---|
container | HTMLElement | - | Elemento no DOM em que o SDK será carregado (e.g. div ) |
Exemplo
// div or another element on DOM
const sdkContainer = document.getElementById('sdk-displayer');
await sdk.open(sdkContainer);
Captura de documento
capture(type: SupportedDocumentType, side: DocumentSide, captureSettings?: CaptureSettings): Promise<Result>
Método utilizado para fazer a captura de um tipo de documento
Parâmetros
Parâmetro | Tipo | Valores válidos | Descrição |
---|---|---|---|
type | string | any ¹, rg , cnh , crlv , ctps , passport , rne , other ² | Tipo de documento a ser capturado |
side ³ | string | front , back , both ⁴, not_applicable | Tipo de documento a ser capturado |
captureSettings.mode ⁵ | string | automatic , manual | Configura a captura como automática ou manual |
captureSettings.automaticCaptureTimeoutInSeconds ⁶ | number | Números. | Timeout antes da captura automática alternar para manual (se não encontrar documento). Use 0 para nunca alternar. |
¹ O tipo any
aceita captura de qualquer tipo e lado de documento, independente do side
especificado.
² O tipo other
corresponde a outros documentos (não incluindo os já especificados), como: passaporte, carteira de vacinação, etc.
³ O parâmetro side
depende do tipo de documento informado em type
. Ver tabela abaixo.
⁴ O lado both
corresponde ao documento mostrando ambos os lados na mesma foto (e.g. CNH aberta)
⁵ Se não especificado, a captura automática é utilizada
⁶ Se não especificado, usa-se um valor padrão de 30 segundos
Lados aceitos para cada tipo de documento
Tipo de documento | Lados aceitos |
---|---|
rg | front , back , both |
cnh | front , back , both |
rne | 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 |
blob | Blob | Blob da imagem capturada |
documentType | SupportedDocumentType | Tipo do documento capturado |
documentSide | DocumentSide | Lado do documento capturado |
Exemplo
const captureSettings = { mode: 'automatic', automaticCaptureTimeoutInSeconds: 10 };
const result = await sdk.capture('any', 'not_applicable', captureSettings);
// { imageUrl: '[link da imagem]', blob: Blob, documentType: 'rg', documentSide: 'front' }
Fechar SDK
close(): Promise<void>
Método utilizado para remover o SDK na tela.
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.