DocumentDetector - Ionic 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 e CRLV. 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.

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

Importe o pacote e chame o método add() dentro da inicialização em android/app/src/main/java/io/ionic/starter/MainActivity.java:

import com.example.plugin.DocumentDetectorPlugin;

public class MainActivity extends BridgeActivity {
  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    registerPlugin(DocumentDetectorPlugin.class);
  }
}

iOS

No arquivo ROOT_PROJECT/ios/App/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 a permissão de câmera no arquivo ROOT_PROJECT/ios/App/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>To read the documents</string>

Ionic

Adicione o plugin no seu arquivo ROOT_PROJECT/package.json:

"dependencies": {
    "document-detector-ionic": "https://github.com/combateafraude/Ionic/archive/refs/tags/document-detector-v6.6.0.tar.gz"
}

Após, execute:

1. npm install
2. ionic capacitor build < platform > [ options ]

Importando

import {DocumentDetector, DocumentDetectorStep, DocumentType} from 'document-detector-ionic';

Utilizando

    let documentDetector = new DocumentDetector();
    
    documentDetector.setMobileToken = '<your mobile token>';

    var documentDetectorSteps: Array<DocumentDetectorStep> = [
        new DocumentDetectorStep(DocumentType.RG_FRONT, null, null),
        new DocumentDetectorStep(DocumentType.RG_BACK, null, null)];

    documentDetector.setDocumentDetectorSteps = documentDetectorSteps;

    var response = await documentDetector.start();

    if(response.result == "SUCCESS"){
      // Sucesso
    }else if(response.result == "FAILURE"){
      // Falha. Confira reponse.type e response.message
    }else{
      // Usuário fechou a tela
    }

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 | | .setAndroidSettings(DocumentDetectorAndroidSettings androidSettings)Customizações somente aplicadas em Android | | .setIosSettings(DocumentDetectorIosSettings iosSettings)Customizações somente aplicadas em iOS |

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

| ShowPreview | |Caso deseje personalizar os valores, crie uma String em ROOT_PROJECT/android/app/src/main/res/values/strings.xml com o nome e valor desejado e parametrize| | --------- | | bool showHabilita/Desabilita preview | | String titleTítulo | | String subTitleSubtítulo | | String confirmLabelTexto do botão de confirmação | | String retryLabelTexto do botão de capturar novamente |

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 | |bool enableSwitchCameraButtonPermite habilitar ou desabilitar o botão de inversão da câmera. O padrão é True | | bool useEmulatorPermite habilitar/desabilitar o uso de dispositivos emulados no SDK, recomendamos desabilitar o uso dos emuladores por questões de segurança. O padrão é false | | bool useRootPermite habilitar/desabilitar o uso de dispositivos com root no SDK, recomendamos desabilitar o uso desses dispositivos por questões de segurança. O padrão é false | |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 useAdbPermite 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 |

Exemplo de uso

   let documentDetector = new DocumentDetector();
   documentDetector.setAndroidSettings = new DocumentDetectorAndroidSettings({useEmulator: false, useDebug: true});

| 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, MaskType.DETAILED, que detalha cada documento e MaskType.NONE, que remove completamente 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 | | --------- | | String messageResourceIdNameNome do string resource à ser mostrado quando o ambiente estiver escuro. A mensagem padrão é "Ambiente muito escuro". 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_luminosity_string e valor "Teste" e parametrize "my_custom_luminosity_string" | | int luminosityThresholdLimiar inferior entre luminosidade aceitável/não aceitável, em lx. O padrão é 5 lx |

| SensorOrientationSettingsAndroid constructor | | --------- | | String messageResourceIdNameNome do string resource à ser mostrado quando o celular não estiver na horizontal. A mensagem padrão é "Celular não está na horizontal". 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_orientation_string e valor "Teste" e parametrize "my_custom_orientation_string" | | 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 | | --------- | | String messageResourceIdNameNome do string resource à ser mostrado quando o celular não estiver estável. A mensagem padrão é "Mantenha o celular parado". 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_stability_string e valor "Teste" e parametrize "my_custom_stability_string" | | 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 |

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

| 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 terá o atributo result que contém uma string SUCCESS, FAILURE ou CLOSED. O retorno terá o padrão DocumentDetectorSuccess, DocumentDetectorFailure e DocumentDetectorClosed, respectivamente, para cada um dos casos.

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;

DocumentDetectorClosed

Objeto vazio indicando fechamento da tela de captura pelo usuário.