Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

DocumentDetector v7 ou inferior (Descontinuado)

Documentos suportados

Atualmente, os documentos suportados no Android são:

public enum Document {
    RG_FRONT, // frente do RG, parte onde está a foto
    RG_BACK, // verso do RG, onde estão os dados
    RG_FULL, // RG aberta, mostrando tanto a frente quanto o verso
    CNH_FRONT, // frente da CNH, parte onde está a foto
    CNH_BACK, // verso da CNH, parte onde está a assinatura
    CNH_FULL, // CNH aberta, mostrando tanto a frente quanto o verso
    CRLV, // CRLV
    RNE_FRONT, // frente do RNE e do RNM, onde estão os dados
    RNE_BACK, // verso do RNE e do RNM, onde está a foto
    PASSPORT, // Passaporte, apenas um lado, mostrando todos os dados
    CTPS_FRONT, // frente da CTPS, onde contém a foto
    CTPS_BACK, // verso da CTPS, onde contém os dados
    OTHERS, // outros documentos de identificação em geral, como RNE, Identidade Militar, OAB e CRLV
    ANY; // permite o envio de qualquer tipo de documento, todos os citados acima, inclusive qualquer outro documento, pois não são feitas tipificações
}

Tamanho do SDK

O tamanho do SDK é de aproximadamente 3,3 MB, o que pode diminuir devido a estes elementos.

Permissões em tempo de execução

Permissão
Motivo
Obrigatório?

CÂMERA

Para capturar fotos dos documentos.

Somente para o recurso de captura.

READ_EXTERNAL_STORAGE

Para acessar o armazenamento externo do dispositivo e selecionar documentos no fluxo de upload.

Somente para o recurso de upload.

ACCESS_FINE_LOCATION

Para coletar dados de conexão com a torre de sinal, apenas para fins analíticos.

Não.

Instanciando o SDK

Primeiramente, instancie um objeto do tipo DocumentDetector. Este objeto conterá todas as suas regras de negócio para o SDK:

Todos os parâmetros anotados com @Nullable podem receber null valores, útil se você quiser configurar apenas um dos parâmetros do mesmo método.

Método builder

Parâmetro
Obrigatório

String mobileToken

Token associado à sua conta, para usar o SDK.

Sim.

.setDocumentSteps(DocumentDetectorStep[] documentSteps)

Define o fluxo de captura do documento conforme explicado aqui

Sim.

.setPeopleId(String peopleId)

Identificador do usuário para fins de identificação do perfil de fraude e para auxiliar na identificação de logs do Analytics em casos de bugs e erros.

Não. Usado apenas para analytics fins.

.setAnalyticsSettings(boolean useAnalytics)

Ativa/desativa a coleta de dados para analytics.

Não. O valor padrão é true.

.setCaptureStages(CaptureStage[] captureStages)

Configura os requisitos para cada etapa de captura. Normalmente variando da mais exigente, que requer a maior qualidade, até a menos exigente, com a menor qualidade, conforme explicado aqui.

Não.

.setPopupSettings(boolean show)

Ativa/desativa os pop-ups exibidos antes de cada captura de documento.

Não. O valor padrão é true.

.setLayout(@Nullable @LayoutRes Integer layoutId)

Substitui o layout padrão do SDK. Crie um arquivo na pasta layout do seu projeto, copie este modelo e faça as alterações que desejar.

Não.

.setMask(MaskType type)

Define o design da máscara exibida durante as capturas. Há três tipos:

  • MaskType.DEFAULT, com o padrão pontilhado no formato do documento;

  • MaskType.DETAILED, que mostra uma ilustração do documento solicitado, juntamente com a máscara pontilhada;

  • MaskType.NONE, que remove completamente a máscara.

Não. O valor padrão é MaskType.DEFAULT.

.setMask(@DrawableRes Integer greenMask, @DrawableRes Integer whiteMask, @DrawableRes Integer redMask)

Permite a personalização completa das máscaras exibidas durante a captura do documento. São necessários três tipos, um para cada feedback de validação do documento durante a captura: SUCCESS (greenMask), NORMAL (whiteMask) e ERROR (redMask). Ao optar por esta opção, use máscaras com a mesma área de detecção do documento; isso é extremamente importante para que o algoritmo faça as validações durante a captura.

Não. Veja nossos modelos de máscara para obter a área de detecção:

NORMAL

SUCESSO

ERRO

.setStyle(@StyleRes int styleResourceId)

Configure uma nova diretriz de estilo para o SDK. Crie um arquivo styles.xml no seu projeto com este modelo e personalize-o.

Não.

.setAudioSettings(boolean enable)

Ativa/desativa a reprodução de áudio do SDK.

Não. O valor padrão é true.

.setNetworkSettings(int requestTimeout)

Define o das requisições tempo limite.

Não. O valor padrão é 60 (segundos).

.setLuminositySensorSettings(@Nullable SensorLuminositySettings sensorLuminositySettings)

Define o limite entre brilho ambiente aceitável/não aceitável. Defina null se você não quiser usar este sensor.

Não. As configurações padrão são 5 (lx).

.setOrientationSensorSettings(@Nullable SensorOrientationSettings sensorOrientationSettings)

Define o limite entre a orientação correta/incorreta do dispositivo. Quanto maior o valor, mais flexível ele será. Defina null se você não quiser usar este sensor.

Não. A configuração padrão é 3 (m/s²).

.setStabilitySensorSettings(@Nullable SensorStabilitySettings sensorStabilitySettings)

Define as configurações do sensor de estabilidade. Defina null se você não quiser usar este sensor.

Não. A configuração padrão é tempo 2000 (ms) e limite 0,5 (m/s²).

.setProxySettings(@Nullable ProxySettings proxySettings)

Define as configurações de proxy. Siga o este guia.

Não. A configuração padrão é null.

.setPreviewSettings(@NonNull PreviewSettings previewSettings)

Ativa/desativa e permite configurar a visualização da captura realizada, solicitando a confirmação do usuário para prosseguir.

Não. O padrão é desativado.

.setAutoDetection(boolean enable)

Ativa/desativa a detecção automática e as verificações dos sensores. Use false para desativar todas as verificações no dispositivo. Dessa forma, todas as validações serão realizadas no backend após a captura.

Não. O padrão é true.

.setCurrentStepDoneDelay(boolean showDelay, int delay)

Atraso a atividade após a conclusão de cada etapa. Este método pode ser usado para exibir uma mensagem de sucesso na própria tela após a captura, por exemplo.

Não. O padrão é false.

.setMessageSettings(MessageSettings messageSettings)

Permite personalizar as mensagens exibidas no balão de "status" durante o processo de captura e análise. Veja os atributos disponíveis aqui.

Não.

.enableSwitchCameraButton(boolean enable)

Ativa/desativa o botão para o usuário alternar entre as câmeras frontal e traseira.

Não. O padrão é true.

.setResolutionSettings(Resolution resolution)

Permite definir a resolução de captura. O método recebe como parâmetro uma Resolução que possui as seguintes opções:

  • HD: 720x1280

  • FULL_HD: 1080x1920

  • QUAD_HD: 1440x2560

  • ULTRA_HD: 2160x3840

Não. O padrão é Resolution.ULTRA_HD.

.setCompressSettings(@IntRange(from = 50, to = 100) int compressQuality)

Permite configurar a qualidade no processo de compressão. Por padrão, todas as capturas passam por compressão. O método espera como parâmetro valores entre 50 e 100, sendo 100 a compressão de melhor qualidade (recomendada).

Não. O padrão é 100.

.enableGoogleServices(boolean enable)

Permite ativar/desativar recursos do SDK que consomem GoogleServices no SDK; não recomendamos desativar os serviços devido à perda de segurança.

Não. O padrão é true.

.setUseEmulator(boolean use)

Permite o uso de emuladores quando true. Não é recomendado ativar esta opção; use-a apenas para fins de teste.

Não. O padrão é false.

.setUseRoot(boolean use)

Permite o uso de dispositivos com root quando true. Não é recomendado ativar esta opção; use-a apenas para fins de teste.

Não. O padrão é false.

.setUseDeveloperMode(boolean use)

Ativa o uso do modo desenvolvedor quando true. Não é recomendado ativar esta opção; use-a apenas para fins de teste.

Não. O padrão é false.

.setUseAdb(boolean use)

Ativa o modo de depuração do Android Debug Bridge (ADB) quando true. Não é recomendado ativar esta opção; use-a apenas para fins de teste.

Não. O padrão é false.

.setUseDebug(boolean use)

Permite usar o app em modo de depuração quando true. Não é recomendado ativar esta opção; use-a apenas para fins de teste.

Não. O padrão é false.

.setGetImageUrlExpireTime (String expireTime)

Define por quanto tempo a URL da imagem ficará no servidor até expirar. Espere receber um intervalo de tempo entre "30m" e "30d".

Exemplos:

  • setGetImageUrlExpireTime("30m"): Para configurar apenas minuto(s)

  • setGetImageUrlExpireTime("24h"): Para configurar apenas hora(s)

  • setGetImageUrlExpireTime("1h 10m"): Para definir hora(s) e minuto(s)

  • setGetImageUrlExpireTime("10d"): Para configurar dia(s)

Não. O padrão é 3h.

.setUploadSettings(UploadSettings uploadSettings)

Define as configurações para o envio de documentos. Ao ativar esta opção, o fluxo do SDK solicitará que o usuário envie os arquivos do documento em vez de capturá-los com a câmera do dispositivo. Esta opção também inclui verificações de qualidade do documento. Veja como configurá-la aqui.

Não. Por padrão, esta opção está desativada.

.setAllowedPassportCountriesList(CountryCodeList[] countryList)

Ativa a opção de permitir passaportes de apenas um determinado país emissor ou de uma lista de países. Veja a lista completa em: ISO 3166-1 alpha-3

Exemplo:

  • .setAllowedPassportCountriesList(new CountryCodesList[]{CountryCodesList.BRA})

Não. Por padrão, são aceitos passaportes emitidos por qualquer país.

.setStage(CafStage stage)

Permite escolher o ambiente em que o SDK será executado (produção, beta). O método recebe como parâmetro um enum CafStage para selecionar o ambiente:

Não. O padrão é CafStage.PROD

Enum

Descrição

CafStage.PROD

Usará a Trust Platform produção para registrar as execuções do SDK.

CafStage.BETA

Usará a Trust Platform beta para registrar as execuções do SDK.

Cada ambiente (beta e produção) requer seu próprio mobileToken específico, gerado na Trust Platform do respectivo ambiente.

DocumentDetectorStep

Para criar um fluxo de captura, você precisará criar um array de DocumentDetectorStep, em que cada elemento será uma etapa de captura. Para construir cada DocumentDetectorStep objeto, você pode inserir os seguintes elementos:

Parâmetro
Obrigatório

documento Document

Identifica qual documento você deseja capturar na respectiva etapa. Veja os tipos de documentos suportados aqui.

Sim.

.setStepLabel(@StringRes int stepLabel)

Define o texto a ser exibido na parte inferior do layout.

Não. Existe um padrão por Documento tipo.

.setIllustration(@StringRes int illustration)

Define a ilustração a ser exibida no pop-up antes da captura.

Não. Existe um padrão por Documento tipo.

.setStepAudio(@RawRes int stepAudio)

Define o áudio que será reproduzido no início da etapa.

Não. Existe um padrão por Documento tipo.

.setMask(@DrawableRes Integer whiteMaskResId, @DrawableRes Integer greenMaskResId, @DrawableRes Integer redMaskResId)

Define as máscaras para cada tipo de documento. O uso deste método substitui as máscaras definidas no .setMask método da DocumentDetector.Builder.

Não. O padrão é definido pelo .setMask método do DocumentDetector.Builder.

CaptureStage

Para melhorar a UX do cliente, recomendamos criar etapas de dificuldade para o DocumentDetector. Para isso, oferecemos o objeto CaptureStage, no qual você pode definir os seguintes parâmetros:

Parâmetro

Long durationMillis

Duração da etapa, em milissegundos. Se você não quiser um tempo limite, defina null.

boolean wantSensorCheck

Ativa/desativa o uso de sensores para capturar a foto.

QualitySettings qualitySettings

Configurações da verificação de qualidade do documento. Se você não quiser verificar a qualidade do documento, defina null.

DetectionSettings detectionSettings

Configurações para detecção automática de documentos. Se você não quiser usar a detecção automática, defina null.

CaptureMode captureMode

Modo de captura do documento, que pode ser CaptureMode.AUTOMATIC ou CaptureMode.MANUAL. Na captura manual, um botão será habilitado para o usuário realizar a captura.

Como o .setCaptureStages parâmetro não é obrigatório; se ele não for usado, o DocumentDetector usará este padrão:

QualitySettings

Parâmetro
Observações

double threshold

Limite que define se a captura do documento tem qualidade ou não.

Varia de 1,0 a 5,0, sendo 1,8 o limite recomendado.

DetectionSettings

Parâmetro
Observações

double threshold

Limite que define se o documento exibido pelo usuário é ou não o documento solicitado.

Um valor entre 0,0 e 1,0, sendo 0,95 o recomendado.

int consecutiveFrames

Número de quadros consecutivos corretos para aceitação do documento.

5 é o recomendado. Quanto mais quadros, mais tempo levará para detectar o documento.

UploadSettings

Para habilitar a funcionalidade de envio de documentos, é necessário instanciar um objeto do tipo UploadSettings(boolean enable) e definir seus parâmetros:

Parâmetro
Obrigatório

.setEnable(Boolean enable)

Ativa/desativa este recurso.

Não. O padrão é true.

.setCompress(Boolean enable)

Ativa/desativa a compressão de arquivos antes do envio.

Não. O padrão é true.

.setFileFormats(FileFormat[] fileFormats)

Define o(s) formato(s) de arquivo que serão aceitos para envio.

Não. Por padrão, .PDF, .JPG, .JPEG, .PNG, .HEIF são aceitos.

.setMaxFileSize(Integer maxFileSize)

Define o limite máximo em KB do arquivo a ser enviado.

Não. O limite padrão é 10000 KB (10 MB).

.setActivityLayout ( Integer activityLayout)

Define o layout de fundo do envio do documento.

Não.

.setPopUpLayout (Integer popUpLayout)

Define o layout do pop-up de solicitação de envio do documento.

Não.

Atualmente, os formatos de arquivo suportados são:

MessageSettings

Para usar, basta instanciar um MessageSettings objeto e usar os métodos conforme necessário para personalização.

Método
Valor padrão

.setPopupDocumentSubtitleMessage(@NonNull @StringRes Integer message)

Mensagem exibida no subtítulo do pop-up que traz a ilustração do documento cuja captura está sendo solicitada.

“Posicione o documento em uma mesa, centralize-o na marcação e aguarde a captura automática.”

.setFitTheDocumentMessage(Integer message)

Mensagem informando para encaixar o documento na máscara.

"Encaixe o documento na marcação"

.setHoldItMessage(Integer message)

Mensagem exibida no momento em que a captura está sendo realizada.

"Segure assim"

.setVerifyingQualityMessage(Integer message)

Mensagem exibida quando o SDK faz uma requisição ao backend, verificando a qualidade.

"Verificando qualidade…"

.setLowQualityDocumentMessage(Integer message)

Mensagem exibida quando a qualidade da captura falha.

"Ops, não foi possível ler as informações. Por favor, tente novamente"

.setUploadingImageMessage(Integer message)

Mensagem exibida quando não há verificação de qualidade e a captura está sendo salva nos servidores.

"Enviando imagem…"

.setShowOpenDocumentErrorMessage(boolean show, @Nullable Integer message)

Mensagem exibida ao mostrar um documento aberto; a mensagem será exibida junto com a mensagem de erro no documento em uso. Exemplo: se o usuário apresentar uma CNH aberta (carteira de motorista brasileira), a mensagem de erro padrão "Essa é uma CNH Aberta" + a mensagem definida será exibida.

"Use o documento fechado e tente novamente"

.setWaitMessage(boolean show, @Nullable Integer message)

Mensagem exibida ao iniciar a câmera.

"Aguarde..."

.setSensorLuminosityMessage(@NonNull @StringRes Integer message)

Mensagem exibida quando o limite de brilho é menor do que o esperado.

"Ambiente muito escuro"

.setSensorOrientationMessage(@NonNull @StringRes Integer message)

Mensagem exibida quando o limite de orientação é menor do que o esperado.

"Celular não está na vertical"

.setSensorStabilityMessage(@NonNull @StringRes Integer message)

Mensagem exibida quando o limite de orientação é menor do que o esperado.

"Mantenha o celular parado"

.setWrongDocumentMessage_RG_FRONT(Integer message)

Mensagem exibida quando a frente do RG (carteira de identidade brasileira) é exibida em um fluxo diferente do esperado.

"Ops, esta é a frente do RG"

.setWrongDocumentMessage_RG_BACK(Integer message)

Mensagem exibida quando a versão do RG (carteira de identidade brasileira) é exibida em um fluxo diferente do esperado.

"Ops, este é o verso do RG"

.setWrongDocumentMessage_RG_FULL(Integer message)

Mensagem exibida quando o RG aberto (carteira de identidade brasileira) é exibido em um fluxo diferente do esperado.

"Ops, este é o RG aberto"

.setWrongDocumentMessage_CNH_FRONT(Integer message)

Mensagem exibida quando a frente da CNH (Carteira Nacional de Habilitação) é exibida em um fluxo diferente do esperado.

"Ops, esta é a frente da CNH"

.setWrongDocumentMessage_CNH_BACK(Integer message)

Mensagem exibida quando a versão da CNH (Carteira Nacional de Habilitação) é exibida em um fluxo diferente do esperado.

"Ops, este é o verso da CNH"

.setWrongDocumentMessage_CNH_FULL(Integer message)

Mensagem exibida quando a CNH aberta (Carteira Nacional de Habilitação) é exibida em um fluxo diferente do esperado.

"Ops, esta é a CNH aberta"

.setWrongDocumentMessage_CRLV(Integer message)

Mensagem exibida quando o CRLV (Certificado de Registro e Licenciamento de Veículo) é exibido em um fluxo diferente do esperado.

"Ops, este é o CRLV"

.setWrongDocumentMessage_RNE_FRONT(Integer message)

Mensagem exibida quando a frente do RNE (Registro Nacional de Estrangeiros) é exibida em um fluxo diferente do esperado.

"Ops, esta é a frente do RNE"

.setWrongDocumentMessage_RNE_BACK(Integer message)

Mensagem exibida quando o verso do RNE (Registro Nacional de Estrangeiros) é exibido em um fluxo diferente do esperado.

"Ops, este é o verso do RNE"

.setPositiveButtonMessage(Integer message)

Permite personalizar a mensagem do botão de confirmação.

Não. O padrão é "Ok, entendi!"

.setUploadedImageIsTooLargeTitle

Define o título do pop-up de envio quando o arquivo enviado excede o tamanho máximo permitido.

Não. O padrão é "Tamanho do arquivo excedido"

.setUploadedImageIsTooLargeMessage

Define a mensagem do pop-up de envio quando o arquivo enviado excede o tamanho máximo permitido.

Não. O padrão é "Parece que o arquivo que você escolheu excede o tamanho permitido. Tente enviar um arquivo menor."

.setUploadedImageHasInvalidFormatTitle

Define o título do pop-up de envio quando o formato do arquivo enviado não é válido.

Não. O padrão é "Formato inválido."

.setUploadedImageNotSupportedFormatMessage

Define a mensagem do pop-up de envio quando o formato do arquivo enviado não é válido.

Não. O padrão é "Parece que o formato do arquivo não é suportado. Tente reenviar usando os formatos JPG, PNG ou PDF."

.setUploadedImageGenericErrorTitle

Define o título genérico de erro do pop-up de envio.

Não. O padrão é "Ops, algo deu errado."

.setUploadedImageWrongMessage

Define a mensagem de erro genérica do pop-up de envio.

Não. O padrão é "Parece que o documento não é o esperado. Envie um arquivo com o tipo de documento solicitado."

.setUploadedImageLowQualityTitle

Define o título do pop-up de envio quando a qualidade da imagem enviada falha.

Não. O padrão é "Ops, qualidade baixa"

.setUploadedImageLowQualityMessage

Define a mensagem do pop-up de envio quando a qualidade da imagem enviada falha.

Não. O padrão é "Parece que a qualidade da imagem do documento está muito baixa. Tente enviar um arquivo com melhor qualidade."

.setUploadPopupLoadingMessage

Define a mensagem exibida no pop-up de envio enquanto o arquivo está sendo enviado.

Não. O padrão é "Enviando documento"

Exemplo

Validações de segurança

Estamos constantemente tomando medidas para tornar o produto cada vez mais seguro, mitigando uma série de ataques observados no processo de captura e, consequentemente, reduzindo ao máximo possível as fraudes de identidade. O SDK possui alguns bloqueios que podem impedir sua execução em determinados contextos. Para desativá-las, você pode usar os métodos conforme mostrado no exemplo abaixo:

A desativação das validações de segurança é recomendada apenas para fins de teste. Para publicar seu aplicativo em produção, recomendamos usar as configurações padrão.

Iniciando a Activity

Depois de criar o DocumentDetector, inicie a DocumentDetectorActivity passando este objeto como parâmetro via extra do intent:

Obtendo o resultado

Para obter o DocumentDetectorResult objeto, que contém as capturas feitas pelo SDK, sobrescreva o onActivityResult método na mesma Activity em que você iniciou a DocumentDetectorActivity:

DocumentDetectorResult

Parâmetro
Permitir nulo

Capture[] captures

A matriz com as respectivas capturas dos documentos parametrizados.

Sim, em caso de erro

String type

A classe do fluxo do documento lido. Este parâmetro é útil em uma integração com nossa rota de OCR.

Sim, em caso de erro ou quando você não conseguir verificar a qualidade.

String trackingId

Identificador desta execução em nossos servidores. Se possível, salve este campo e envie-o para nossa API. Dessa forma, teremos mais dados sobre como o usuário se comportou durante a execução.

Sim, se o usuário definir useAnalytics = false ou as chamadas de analytics não funcionam.

SDKFailure sdkFailure

Objeto que informa o motivo do encerramento do SDK. Para mais informações, veja aqui.

Sim, em caso de sucesso

Captura

Parâmetro
Permitir nulo

String imagePath

Caminho completo da imagem no dispositivo do usuário.

Não.

String imageUrl

URL do documento no servidor da CAF.

Não.

String label

Identificação do tipo do documento capturado, entre as seguintes possibilidades: ["blank", "cnh_back", "cnh_front", "cnh_full", "new_cnh_back", "new_cnh_front", "new_cnh_full", "crlv", "crlv_new", "generic", "rg_back", "rg_front", "rg_full", "rg_new_back", "rg_new_front", "rg_new_full", "rne_back", "rne_front", "rnm_back", "rnm_front", "ctps_back", "ctps_front", "passport", "cin_front", "cin_back"].

Sim, quando você não conseguir verificar a qualidade.

Qualidade dupla

A qualidade é inferida pelo algoritmo de qualidade do documento quando ativado. Varia de 1,0 a 5,0.

Sim, quando você não conseguir verificar a qualidade.

int lensFacing

Define o lado da câmera que foi usado. Use DocumentDetectorResult.LENS_FACING_FRONT ou DocumentDetectorResult.LENS_FACING_FRONT para validar.

Não.

Atualizado