document_detector

Description:

document detector

DocumentDetector - Flutter Plugin #
Plugin que chama os SDKs nativos em Android e iOS. Caso tenha alguma dúvida, envie um email para o nosso Head of Mobile
Atualmente, os documentos suportados são RG, CNH, RNE, CRLV, CTPS, Passaporte. Caso tenha alguma sugestão de outro documento, contate-nos!
Políticas de privacidade e termos e condições de uso #
Ao utilizar nosso plugin, certifique-se que você concorda com nossas Políticas de privacidade e nossos Termos e condições de uso.
Pré requisitos #



Configuração mínima
Versão




Flutter
1.12+


Dart
2.12+


Android API
21+


Compile SDK Version
30+


iOS
11.0+



Caso você utilize Dart em uma versão abaixo de 2.12, confira a versão compatível aqui.
Configurações #
Android #
No arquivo ROOT_PROJECT/android/app/build.gradle, adicione:
android {

...

dataBinding.enabled = true

compileOptions {
sourceCompatibility = JavaVersion.VERSION_1_8
targetCompatibility = JavaVersion.VERSION_1_8
}

aaptOptions {
noCompress "tflite"
}
}
copied to clipboard
iOS #
No arquivo ROOT_PROJECT/ios/Podfile, adicione no final do arquivo:
source 'https://github.com/combateafraude/iOS.git'
source 'https://cdn.cocoapods.org/' # ou 'https://github.com/CocoaPods/Specs' se o CDN estiver fora do ar
copied to clipboard
Por último, adicione as permissões no arquivo ROOT_PROJECT/ios/Runner/Info.plist:
<key>NSCameraUsageDescription</key>
<string>To read the documents</string>

// Obrigatória somente para o fluxo de upload de documento
<key>NSPhotoLibraryUsageDescription</key>
<string>To select images</string>
copied to clipboard
Para habilitar texto e voz em Português, em seu projeto, no diretório ROOTPROJECT/ios, abra o arquivo .xcworkspace no Xcode e adicione em Project > Info > Localizations o idioma Portuguese (Brazil).
Flutter #
Adicione o plugin no seu arquivo ROOT_PROJECT/pubspec.yaml:
dependencies:
document_detector:
git:
url: https://github.com/combateafraude/Flutter.git
ref: document-detector-v5.23.0
copied to clipboard
Desativando validações de segurança para teste #
Estamos constantemente realizando ações para tornar o produto cada vez mais seguro, mitigando uma série de ataques observados ao processo de captura e, consequentemente, reduzindo o maior número de possíveis fraudes de identidade. O SDK possui alguns bloqueios que podem impedir a execução em certos contextos. Para desabilitá-los, você pode utilizar os métodos conforme o exemplo abaixo:
DocumentDetectorAndroidSettings androidSettings =
DocumentDetectorAndroidSettings(
emulatorSettings: true,
rootSettings: true,
useDeveloperMode: true,
useAdb: true,
useDebug: true,
);

documentDetector.setAndroidSettings(androidSettings);
copied to clipboard

Atenção! Desabilitar as validações de segurança são recomendadas apenas para ambiente de testes. Para publicação do seu aplicativo em produção, recomendamos utilizar as configurações padrão.

Utilização #
DocumentDetector documentDetector = new DocumentDetector(mobileToken: mobileToken);
documentDetector.setDocumentFlow(List<DocumentDetectorStep> documentSteps);

// Outros parâmetros de customização

DocumentDetectorResult documentDetectorResult = await documentDetector.start();

if (documentDetectorResult is DocumentDetectorSuccess) {
// O SDK foi encerrado com sucesso e as fotos dos documentos foram capturadas
} else if (documentDetectorResult is DocumentDetectorFailure) {
// O SDK foi encerrado devido à alguma falha e as fotos dos documentos não foram capturadas
} else {
// O usuário simplesmente fechou o SDK, sem nenhum resultado
}
copied to clipboard
Customizações gerais #



DocumentDetector




.setPeopleId(String peopleId)CPF do usuário que está utilizando o plugin à ser usado para detecção de fraudes via analytics


.setAnalyticsSettings(bool useAnalytics)Habilita/desabilita a coleta de dados para maximização da informação antifraude. O padrão é true


.setDocumentFlow(List<DocumentDetectorStep> documentSteps)Fluxo de documentos à serem capturados no SDK


.setPopupSettings(bool show)Altera a configuração dos popups inflados antes de cada documento. O padrão é true


.enableSound(bool enable)Habilita/desabilita os sons. O padrão é true


.setNetworkSettings(int requestTimeout)Altera as configurações de rede padrão. O padrão é 60 segundos


.setShowPreview(ShowPreview showPreview) Preview para verificação da qualidade da foto


.setAutoDetection(bool enable)Habilita/desabilita a autodetecção e verificações de sensores. Utilize false para desabilitar todas as verificações no dispositivo. Assim, todas validações serão executadas no backend, após a captura. O padrão é true


.setCurrentStepDoneDelay(bool showDelay, int delay) Aplica delay na activity após a finalização de cada etapa. Esse método pode ser utilizado para exibir uma mensagem de sucesso na própria tela após a captura, por exemplo. O padrão é false


.setMessageSettings(MessageSettings messageSettings) Permite personalizar mensagens exibidas no balão de "status" durante o processo de captura e análise.


.setGetImageUrlExpireTime(String expireTime) Define o tempo de duração da URL da imagem no servidor até ser expirada. Espera receber um intervalo de tempo entre "30m" à "30d". O padrão é 3h


.setAndroidSettings(DocumentDetectorAndroidSettings androidSettings)Customizações somente aplicadas em Android


.setIosSettings(DocumentDetectorIosSettings iosSettings)Customizações somente aplicadas em iOS


.setUploadSettings(UploadSettings uploadSettings)Define as configurações para o upload de documentos. Ativando esta opção, o fluxo do SDK irá solicitar que o usuário envie os arquivos do documento ao invés de realizar a captura com a câmera do dispositivo. Esta opção também inclui as verificações de qualidade do documento. Por padrão, esta opção de fluxo não está habilitada






DocumentDetectorStep constructor




DocumentType documentDocumento a ser escaneado neste respectivo passo


DocumentDetectorStepCustomizationAndroid androidCustomizações visuais do respectivo passo aplicados em Android


DocumentDetectorStepCustomizationIos iosCustomizações visuais do respectivo passo aplicados em iOS






UploadSettings constructor




bool compressHabilita/desabilita a compressão do arquivo antes de realizar o upload. O padrão é true


int maxFileSizeDefine o tamanho máximo em KB do arquivo para upload. O limite padrão é 20000 KB (20MB)


List<String> fileFormatsDefine o(os) formatos de arquivos que serão aceitos para upload. Por padrão são aceitos: .PDF , .JPG, .JPEG, .PNG, .HEIF


String activityLayoutDefine o layout de plano de fundo do upload de documentos


String popUpLayoutDefine o layout do popup de solicitação do documento para upload






ShowPreview




Como Modificar: Caso deseje modificar o texto selecionado, modifique a String com a mensagem que deseja utilizar.


bool showHabilita/Desabilita preview


String titleTítulo


String subTitle Subtítulo


String confirmLabelTexto do botão de confirmação


String retryLabelTexto do botão de capturar novamente



| Exemplo de uso |
ShowPreview showPreview = new ShowPreview(
show: true,
title: "A foto ficou boa?",
subtitle: "Veja se a foto está nítida",
confirmLabel: "Sim, ficou boa!",
retryLabel: "Tirar novamente");

documentDetector.setShowPreview(showPreview);
copied to clipboard



MessageSettings




Como Modificar: Caso deseje modificar o texto selecionado, modifique a String com a mensagem que deseja utilizar.


String? fitTheDocumentMessagePadrão: "Encaixe o documento na marcação"


String? holdItMessage (somente para Android)Padrão: "Segure assim"


String? verifyingQualityPadrão: "Verificando qualidade…"


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


String? uploadingImagePadrão: "Enviando imagem…"


boolean? showOpenDocumentMessagePadrão: true


String? openDocumentWrongMessagePadrão: "Esse é o {'document'} aberto, você deve fecha-lo"


String? documentNotFoundMessagePadrão: "Não encontramos um documento"


String? sensorLuminosityMessagePadrão: "Ambiente muito escuro"


String? sensorOrientationMessagePadrão: "Celular não está na vertical"


String? sensorStabilityMessagePadrão: "Mantenha o celular parado"


String? unsupportedDocumentMessagePadrão: "Ops, parece que este documento não é suportado. Contate-nos!"


String? popupDocumentSubtitleMessagePadrão: "Posicione o documento em uma mesa, centralize-o na marcação e aguarde a captura automática."


String? setPositiveButtonMessagePadrão: "Ok, entendi!"


String? wrongDocumentMessage_RG_FRONT (somente para Android)Padrão: "Ops, esta é a frente do RG"


String? wrongDocumentMessage_RG_BACK (somente para Android)Padrão: "Ops, este é o verso do RG"


String? wrongDocumentMessage_RG_FULL (somente para Android)Padrão: "Ops, este é o RG aberto"


String? wrongDocumentMessage_CNH_FRONT (somente para Android)Padrão: "Ops, esta é a frente da CNH"


String? wrongDocumentMessage_CNH_BACK (somente para Android)Padrão: "Ops, este é o verso da CNH"


String? wrongDocumentMessage_CNH_FULL (somente para Android)Padrão: "Ops, esta é a CNH aberta"


String? wrongDocumentMessage_CRLV (somente para Android)Padrão: "Ops, este é o CRLV"


String? wrongDocumentMessage_RNE_FRONT (somente para Android)Padrão: "Ops, esta é a frente do RNE"


String? wrongDocumentMessage_RNE_BACK (somente para Android)Padrão: "Ops, este é o verso do RNE"






Exemplo de uso



MessageSettings messageSettings = new MessageSettings(
fitTheDocumentMessageResIdName: "Mensagem de exemplo",
holdItMessageResIdName:"Mensagem de exemplo",
verifyingQualityMessageResIdName: "Mensagem de exemplo"
lowQualityDocumentMessageResIdName:"Mensagem de exemplo" ,
uploadingImageMessageResIdName:"Mensagem de exemplo",
openDocumentWrongMessage: "Mensagem de exemplo",
showOpenDocumentMessage: true);
documentDetector.setMessageSettings(messageSettings);
copied to clipboard
Android



DocumentDetectorStepCustomizationAndroid constructor




String stepLabelStringResNameNome do string resource à ser mostrado no label do nome do documento. Por exemplo, caso deseje mostrar a String "Teste", crie uma String em ROOT_PROJECT/android/app/src/main/res/values/strings.xml com o nome R.string.my_custom_string e valor "Teste" e parametrize "my_custom_string"


String illustrationDrawableResNameNome do drawable resource à ser mostrado no popup de introdução da captura. Por exemplo, caso deseje mostrar uma ilustração customizada, salve-a em ROOT_PROJECT/android/app/src/main/res/drawable/my_custom_illustration.png e parametrize "my_custom_illustration"


String audioRawResNameNome do raw resource à ser executado no início da captura. Por exemplo, caso deseje executar um áudio customizado, salve-o em ROOT_PROJECT/android/app/src/main/res/raw/my_custom_audio.mp3 e parametrize "my_custom_audio"






DocumentDetectorAndroidSettings constructor




DocumentDetectorCustomizationAndroid customizationCustomização do layout em Android da activity


SensorSettingsAndroid sensorSettingsCustomização das configurações dos sensores de captura


List<CaptureStage> captureStagesArray de estágios para cada captura. Esse parâmetro é útil caso você deseje modificar a maneira com qual o DocumentDetector é executado, como configurações de detecção, captura automática ou manual, verificar a qualidade da foto, etc


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


bool enableSwitchCameraButtonPermite habilitar ou desabilitar o botão de inversão da câmera. O padrão é True


Resolution resolutionPermite configurar a resolução de captura. O método espera como parâmetro uma Resolution que fornece as opções HD, FULL_HD, QUAD_HD e ULTRA_HD. O padrão é Resolution.ULTRA_HD


bool enableGoogleServicesPermite habilitar/desabilitar recursos do SDK que consomem GoogleServices no SDK, não recomendamos desabilitar os serviços por conta da perda de segurança. O padrão é True


bool enableEmulatorPermite o uso de emulador quando true


bool enableRootDevicesPermite o uso de dispositivos root quando true


bool useDebugHabilita/desabilita o uso do app em modo depuração. O padrão é false


bool useDeveloperModePermite habilitar/desabilitar o uso de dispositivos com o modo de desenvolvedor Android ativado. Recomendamos desabilitar o uso desses dispositivos por questões de segurança. O padrão é false


bool useDAdbPermite habilitar/desabilitar o uso do modo de depuração Android Debug Bridge (ADB). Recomendamos desabilitar o uso desses dispositivos por questões de segurança. O padrão é false






CaptureStage constructor




int durationMillisDuração em milissegundos deste respectivo passo antes de passar para o próximo, se houver. null para infinito


bool wantSensorCheckFlag que indica se este estágio deve/não deve passar pela validação dos sensores


QualitySettings qualitySettingsConfigurações de verificação de qualidade do documento. O único parâmetro de QualitySettings é o limiar de aceitação da verificação da qualidade, de 1.0 a 5.0, onde 1.8 é o recomendado


DetectionSettings detectionSettingsConfigurações de detecção do documento pela câmera. Os parâmetros de DetectionSettings são, respectivamente, o limiar de aceitação do documento, em um valor de 0.0 a 1.0 com 0.91 de recomendado e a quantidade de frames consecutivos corretos necessários, onde o recomendado é 5


CaptureMode captureModeModo de captura da foto. Pode ser CaptureMode.AUTOMATIC para a captura automática ou CaptureMode.MANUAL para a aparição de um botão para o usuário efetuar a captura






DocumentDetectorCustomizationAndroid constructor




String styleResIdNameNome do style resource que define as cores do DocumentDetector. Por exemplo, caso deseje mudar as cores do SDK, crie um style em ROOT_PROJECT/android/app/src/main/res/values/styles.xml com o nome R.style.my_custom_style seguindo o template e parametrize "my_custom_style"


String layoutResIdNameNome do layout resource que substituirá o layout padrão do DocumentDetector. Por exemplo, caso deseje mudar o layout do SDK, crie um layout em ROOT_PROJECT/android/app/src/main/res/layout/my_custom_layout.xml seguindo o template e parametrize "my_custom_layout"


String greenMaskResIdNameNome do drawable resource à substituir a máscara verde padrão. Caso for usar este parâmetro, use uma máscara com a mesma área de corte, é importante para o algoritmo de detecção. Por exemplo, salve a imagem da máscara em ROOT_PROJECT/android/app/src/main/res/drawable/my_custom_green_mask.png e parametrize "my_custom_green_mask"


String redMaskResIdNameNome do drawable resource à substituir a máscara vermelha padrão. Caso for usar este parâmetro, use uma máscara com a mesma área de corte, é importante para o algoritmo de detecção. Por exemplo, salve a imagem da máscara em ROOT_PROJECT/android/app/src/main/res/drawable/my_custom_red_mask.png e parametrize "my_custom_red_mask"


String whiteMaskResIdNameNome do drawable resource à substituir a máscara branca padrão. Caso for usar este parâmetro, use uma máscara com a mesma área de corte, é importante para o algoritmo de detecção. Por exemplo, salve a imagem da máscara em ROOT_PROJECT/android/app/src/main/res/drawable/my_custom_white_mask.png e parametrize "my_custom_white_mask"


MaskType maskTypeDefine o tipo de máscara utilizada nas capturas. Existem três tipos: MaskType.DEFAULT, com o padrão pontilhado no formato do documento; MaskType.DETAILED, que apresenta uma ilustração do documento solicitado, junto com a máscara pontilhada; MaskType.NONE, que remove totalmente a máscara. O padrão é MaskType.DEFAULT






SensorSettingsAndroid constructor




SensorLuminositySettingsAndroid sensorLuminositySettingsConfigurações do sensor de luminosidade à ser aplicado em todos os passos do SDK


SensorOrientationSettingsAndroid sensorOrientationSettingsConfigurações do sensor de orientação à ser aplicado em todos os passos do SDK


SensorStabilitySettingsAndroid sensorStabilitySettingsConfigurações do sensor de orientação à ser aplicado em todos os passos do SDK






SensorLuminositySettingsAndroid constructor




int luminosityThresholdLimiar inferior entre luminosidade aceitável/não aceitável, em lx. O padrão é 5 lx






SensorOrientationSettingsAndroid constructor




double orientationThresholdLimiar inferior entre orientação correta/incorreta, em variação de m/s² da orientação totalmente horizontal. O padrão é 3 m/s²






SensorStabilitySettingsAndroid constructor




int stabilityStabledMillisQuantos milissegundos o celular deve se manter no limiar correto para ser considerado estável. O padrão é 2000 ms


double stabilityThresholdLimiar inferior entre estável/instável, em variação de m/s² entre as últimas duas coletas do sensor. O padrão é 0.5 m/s²



iOS



DocumentDetectorIosSettings constructor




double detectionThresholdLimiar de aceitação do documento, em um valor de 0.0 a 1.0. O padrão é 0.95


bool verifyQualityFlag que indica se deseja verificar a qualidade do documento capturado


double qualityThresholdLimiar de aceitação da qualidade, entre 1.0 e 5.0. 1.8 é o recomendado para um futuro OCR


DocumentDetectorCustomizationIos customizationCustomização visual do DocumentDetector


SensorSettingsIos sensorSettingsConfigurações personalizadas dos sensores em iOS, null para desabilitar


Bool enableManualCaptureHabilita modo de captura manual


double timeEnableManualCaptureTempo para habilitar o botão de captura manual


double compressQualityPermite configurar a qualidade no processo de compressão. Por padrão, todas capturas passam por compressão. O método espera como parâmetro valores entre 0 e 1.0, sendo 1.0 a compressão com melhor qualidade (recomendado).O padrão é 1.0


String resolutionPermite configurar a resolução de captura. O método espera como parâmetro uma String IosResolution (O padrão é hd1280x720), que possui as seguintes opções:






Resolution
Descrição




low
Especifica as configurações de captura adequadas para vídeo de saída e taxas de bits de áudio adequadas para compartilhamento em 3G


medium
Especifica as configurações de captura adequadas para as taxas de bits de áudio e vídeo de saída adequadas para compartilhamento via WiFi


high
Especifica as configurações de captura adequadas para saída de áudio e vídeo de alta qualidade


photo
Especifica as configurações de captura adequadas para saída de qualidade de foto de alta resolução


inputPriority
Especifica as configurações de captura adequadas para saída de qualidade de foto de alta resolução


hd1280x720
Especifica as configurações de captura adequadas para saída de vídeo com qualidade de 720p (1280 x 720 pixels)


hd1920x1080
Configurações de captura adequadas para saída de vídeo com qualidade 1080p (1920 x 1080 pixels)


hd4K3840x2160
Configurações de captura adequadas para saída de vídeo com qualidade 2160p (3840 x 2160 pixels)










DocumentDetectorCustomizationIos constructor




String colorHexCor tema do SDK. Por exemplo, caso deseje usar a cor preta, utilize "#000000"


String greenMaskImageNameNome da imagem à substituir a máscara verde padrão. Lembre de adicionar a imagem em Assets Catalog Document no seu projeto do XCode


String whiteMaskImageNameNome da imagem à substituir a máscara branca padrão. Lembre de adicionar a imagem em Assets Catalog Document no seu projeto do XCode


String redMaskImageNameNome da imagem à substituir a máscara vermelha padrão. Lembre de adicionar a imagem em Assets Catalog Document no seu projeto do XCode


String closeImageNameNome da imagem à substituir o botão de fechar o SDK. Lembre de adicionar a imagem em Assets Catalog Document no seu projeto do XCode


bool showStepLabelFlag que indica se deseja mostrar o label do passo atual


bool showStatusLabelFlag que indica se deseja mostrar o label do status atual


double? buttonSizeValor que define o tamanho do botão de "fechar" o SDK


String? buttonContentModeAtributo que define o content mode do botão de "fechar" o SDK. Escolha entre esses valores.






SensorSettingsIos constructor




SensorLuminositySettingsIos sensorLuminosityConfigurações do sensor de luminosidade à ser aplicado em todos os passos do SDK


SensorOrientationSettingsIos sensorOrientationConfigurações do sensor de orientação à ser aplicado em todos os passos do SDK


SensorStabilitySettingsIos sensorStabilityConfigurações do sensor de estabilidade à ser aplicado em todos os passos do SDK






SensorLuminositySettingsIos constructor




String messageString à ser mostrada quando o ambiente estiver escuro


double luminosityThresholdLimiar inferior entre luminosidade aceitável/não aceitável. O padrão é -3






SensorOrientationSettingsAndroid constructor




String messageString à ser mostrada quando o celular não estiver na horizontal


double orientationThresholdLimiar inferior entre orientação correta/incorreta. O padrão é 0.3






SensorStabilitySettingsAndroid constructor




String messageString à ser mostrada quando o celular não estiver estável


double stabilityThresholdLimiar inferior entre estável/instável, em variação de m/s² entre as últimas duas coletas do sensor. O padrão é 0.3 m/s²



Coletando o resultado #
O objeto de retorno do DocumentDetector é do tipo abstrato DocumentDetectorResult. Ele pode ser uma instância de DocumentDetectorSuccess, DocumentDtetectorFailure ou DocumentDetectorClosed.
DocumentDetectorSuccess



Campo
Observação




List<Capture> capturesLista de capturas dos documentos
Terá o mesmo tamanho e a mesma ordem do parâmetro List<DocumentDetectorStep>


String typeTipo de documento detectado pelo próprio SDK, util para a integração com nossa rota externa de OCR. Por exemplo, se você capturar DocumentType.CNH_FRONT e DocumentType.CNH_BACK, este parâmetro será "cnh"
Será nulo se o SDK não conseguir verificar o tipo do documento ou se a detecção for desabilitada


String trackingIdIdentificador dessa execução em nossos servidores. Se possível, salve este campo e mande-o junto para nossa API. Assim, teremos mais dados de como o usuário se comportou durante a execução
Será nulo se o usuário configurar useAnalytics = false ou as chamadas de analytics não funcionarem



Capture



Campo
Observação




String imagePathEndereço completo da imagem no dispositivo
-


String imageUrlURL da imagem armazenada temporariamente nos servidores da CAF
Será nulo se o SDK não conseguir verificar a qualidade ou se a mesma estiver desabilitada


String labelLabel de detecção da captura. Por exemplo, se a captura for referente a um DocumentType.RG_FRONT, este label pode ser "rg_front" ou "rg_new_front", que se refere aos novos modelos de RG
Será nulo se a foto for coletada em um estágio onde a detecção está desativada


double qualityQualidade da foto do documento, em um valor de 1.0 a 5.0
Será nulo se a foto for coletada em um estágio onde a verificação de qualidade está desativada



DocumentDtetectorFailure



Campo




String messageMensagem amigável explicando o motivo da falha do SDK


String typeTipo de falha que encerrou o SDK



Os tipos de falha existentes são:

InvalidTokenReason: quando o token informado é inválido. Não deve ocorrer em um ambiente de produção;
PermissionReason: quando alguma permissão obrigatória não foi concedida pelo usuário. Só ocorrerá em um ambiente de produção se o seu app não solicitar ao seu usuário ou o mesmo desabilitar manualmente antes de iniciar;
NetworkReason: falha de conexão com o servidor. Ocorrerá em produção se o dispositivo do usuário estiver sem internet;
ServerReason: falha em alguma requisição com nossos servidores. Ocorrerá em produção somente no caso de uma falha nossa;
SecurityReason: quando o dispositivo não é seguro para executar o SDK. Se esta falha ocorrer, avise-nos;
StorageReason: quando o dispositivo não possui espaço suficiente para a captura de alguma foto. Pode ocorrer em produção;
LibraryReason: quando alguma falha interna impossibilitou a execução do SDK. Pode ocorrer devico à erros de configuração do projeto, não deve ocorrer em produção;

Customizando view iOS #
Para customização iOS, é necessário que os plugins Flutter estejam adicionados localmente no projeto. A customizção é realizada nativamente com a abordagem ViewCode.
Clique aqui e acesse um exemplo com um guia para utilização desse recurso.