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"
    }
}

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

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>

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

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);

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
}

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 document

Documento a ser escaneado neste respectivo passo
DocumentDetectorStepCustomizationAndroid android

Customizações visuais do respectivo passo aplicados em Android
DocumentDetectorStepCustomizationIos ios

Customizações visuais do respectivo passo aplicados em iOS
UploadSettings constructor
bool compress

Habilita/desabilita a compressão do arquivo antes de realizar o upload. O padrão é true
int maxFileSize

Define o tamanho máximo em KB do arquivo para upload. O limite padrão é 20000 KB (20MB)
List<String> fileFormats

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

Define o layout de plano de fundo do upload de documentos
String popUpLayout

Define 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 show

Habilita/Desabilita preview
String title

Título
String subTitle

Subtítulo
String confirmLabel

Texto do botão de confirmação
String retryLabel

Texto 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);
MessageSettings
Como Modificar: Caso deseje modificar o texto selecionado, modifique a String com a mensagem que deseja utilizar.
String? fitTheDocumentMessage

Padrão: "Encaixe o documento na marcação"
String? holdItMessage (somente para Android)

Padrão: "Segure assim"
String? verifyingQuality

Padrão: "Verificando qualidade…"
String? lowQualityDocument

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

Padrão: "Enviando imagem…"
boolean? showOpenDocumentMessage

Padrão: true
String? openDocumentWrongMessage

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

Padrão: "Não encontramos um documento"
String? sensorLuminosityMessage

Padrão: "Ambiente muito escuro"
String? sensorOrientationMessage

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

Padrão: "Mantenha o celular parado"
String? unsupportedDocumentMessage

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

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

Padrã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);

Android

DocumentDetectorStepCustomizationAndroid constructor
String stepLabelStringResName

Nome 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 illustrationDrawableResName

Nome 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 audioRawResName

Nome 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 customization

Customização do layout em Android da activity
SensorSettingsAndroid sensorSettings

Customização das configurações dos sensores de captura
List<CaptureStage> captureStages

Array 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 compressQuality

Permite 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 enableSwitchCameraButton

Permite habilitar ou desabilitar o botão de inversão da câmera. O padrão é True
Resolution resolution

Permite 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 enableGoogleServices

Permite 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 enableEmulator

Permite o uso de emulador quando true
bool enableRootDevices

Permite o uso de dispositivos root quando true
bool useDebug

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

Permite 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 useDAdb

Permite 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 durationMillis

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

Flag que indica se este estágio deve/não deve passar pela validação dos sensores
QualitySettings qualitySettings

Configuraçõ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 detectionSettings

Configuraçõ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 captureMode

Modo 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 styleResIdName

Nome 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 layoutResIdName

Nome 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 greenMaskResIdName

Nome 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 redMaskResIdName

Nome 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 whiteMaskResIdName

Nome 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 maskType

Define 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 sensorLuminositySettings

Configurações do sensor de luminosidade à ser aplicado em todos os passos do SDK
SensorOrientationSettingsAndroid sensorOrientationSettings

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

Configurações do sensor de orientação à ser aplicado em todos os passos do SDK
SensorLuminositySettingsAndroid constructor
int luminosityThreshold

Limiar inferior entre luminosidade aceitável/não aceitável, em lx. O padrão é 5 lx
SensorOrientationSettingsAndroid constructor
double orientationThreshold

Limiar 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 stabilityStabledMillis

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

Limiar 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 detectionThreshold

Limiar de aceitação do documento, em um valor de 0.0 a 1.0. O padrão é 0.95
bool verifyQuality

Flag que indica se deseja verificar a qualidade do documento capturado
double qualityThreshold

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

Customização visual do DocumentDetector
SensorSettingsIos sensorSettings

Configurações personalizadas dos sensores em iOS, null para desabilitar
Bool enableManualCapture

Habilita modo de captura manual
double timeEnableManualCapture

Tempo para habilitar o botão de captura manual
double compressQuality

Permite 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 resolution

Permite 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 colorHex

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

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

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

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

Nome 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 showStepLabel

Flag que indica se deseja mostrar o label do passo atual
bool showStatusLabel

Flag que indica se deseja mostrar o label do status atual
double? buttonSize

Valor que define o tamanho do botão de "fechar" o SDK
String? buttonContentMode

Atributo que define o content mode do botão de "fechar" o SDK. Escolha entre esses valores.
SensorSettingsIos constructor
SensorLuminositySettingsIos sensorLuminosity

Configurações do sensor de luminosidade à ser aplicado em todos os passos do SDK
SensorOrientationSettingsIos sensorOrientation

Configurações do sensor de orientação à ser aplicado em todos os passos do SDK
SensorStabilitySettingsIos sensorStability

Configurações do sensor de estabilidade à ser aplicado em todos os passos do SDK
SensorLuminositySettingsIos constructor
String message

String à ser mostrada quando o ambiente estiver escuro
double luminosityThreshold

Limiar inferior entre luminosidade aceitável/não aceitável. O padrão é -3
SensorOrientationSettingsAndroid constructor
String message

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

Limiar inferior entre orientação correta/incorreta. O padrão é 0.3
SensorStabilitySettingsAndroid constructor
String message

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

Limiar 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> captures

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

Tipo 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 trackingId

Identificador 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 imagePath

Endereço completo da imagem no dispositivo
-
String imageUrl

URL 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 label

Label 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 quality

Qualidade 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 message

Mensagem amigável explicando o motivo da falha do SDK
String type

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