Captura de NFC

Introdução

A captura facial é realizada com o Componente NFC.

Este componente é responsável por realizar a leitura NFC dos documentos de identidade e passaportes. Seus principais processos são:

• Gerenciamento interno do sensor NFC.

• Gerenciamento de permissões.

• Análise do documento.

• Análise do progresso.

• Assistente nos processos de leitura.

• Retorno de todas as informações possíveis de leitura

• Retorno de imagens quando estiverem disponíveis para leitura

Na seção de Lançamento simplificado são detalhados os passos necessários para a integração básica do SDK. Nesta seção é adicionada a informação para o lançamento deste componente.

Dependência

A dependência específica do componente é:

implementation "com.facephi.androidsdk:nfc_component:$sdk_nfc_component_version"{
      exclude group : "org.bouncycastle", module : "bcprov-jdk15on"
      exclude group : "org.bouncycastle", module : "jetified-bcprov-jdk15on-1.68"
  }

Além disso, será necessário adicionar no Gradle:

android {
  ...
 packaging {
      resources {
          pickFirsts.add("META-INF/versions/9/OSGI-INF/MANIFEST.MF")
      }
  }
}

Controladores disponíveis

Controlador	Descrição
NFCController	Controlador principal de leitura NFC

Lançamento simplificado

Uma vez iniciado o SDK e criada uma nova operação, será possível iniciar o componente. Será possível usar qualquer um de seus controladores para executar sua funcionalidade.

Início da captura:

val response = SDKController.launch(
    NfcController(
        componentData = NfcConfigurationData(...),
        state = { state ->
            Napier.d("NFC: State: ${state.name}")
        },
        debugLogs = {
            Napier.d("NFC Logs: $it")
        }
    )
)
when (response) {
    is SdkResult.Error -> Napier.d("NFC: ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}

Configuração básica

Para lançar o componente atual, deverá ser criado um objeto NFCConfigurationData que será a configuração do controlador do componente.

A configuração básica necessária é a seguinte:

NfcConfigurationData(
    documentNumber = NFC_SUPPORT_NUMBER, // Número de suporte.
    birthDate = NFC_BIRTH_DATE, // "dd/MM/yyyy"
    expirationDate = NFC_EXPIRATION_DATE, // "dd/MM/yyyy",
)

Os dados necessários são os do documento que será capturado.

Recebimento do resultado

A execução retornará as informações no formato SdkResult. Sendo possível diferenciar entre uma execução correta e uma incorreta:

when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error}")
    is SdkResult.Success -> response.data
}

Recebimento de erros

Os erros serão retornados como um objeto 'NfcError'.

Lista de erros:

• NFC_APPLICATION_CONTEXT_ERROR: O contexto de aplicação necessário é nulo.

• NFC_CANCEL_BY_USER: O usuário cancelou o processo.

• NFC_CANCEL_LAUNCH: Foi feito um cancelamento geral do SDK.

• NFC_COMPONENT_LICENSE_ERROR: A licença do componente não está correta.

• NFC_EMPTY_LICENSE: A string de licença está vazia.

• NFC_EXTRACT_DATA_ERROR: Erro nos dados extraídos.

• NFC_FETCH_DATA_ERROR: Erro na coleta do resultado.

• NFC_FLOW_ERROR: Erro no processo de flow.

• NFC_INITIALIZATION_ERROR: Erro de inicialização.

• NFC_LAST_COMMAND_EXPECTED: Erro no comando de finalização

• NFC_MANAGER_NOT_INITIALIZED: Os managers estão nulos.

• NFC_NO_DATA_ERROR: Os dados de entrada estão nulos ou nenhum resultado da leitura foi recebido.

• NFC_ERROR: Erro geral

• NFC_ERROR_DATA: Erro nos dados de entrada

• NFC_ERROR_DISABLED: NFC desabilitado

• NFC_ERROR_ILLEGAL_ARGUMENT: NFC com uma tag incorreta

• NFC_ERROR_IO: Erro de entrada/saída

• NFC_ERROR_NOT_SUPPORTED: NFC não suportado

• NFC_ERROR_TAG_LOST: Conexão perdida

• NFC_OPERATION_NOT_CREATED: Nenhuma operação está em andamento.

• NFC_TIMEOUT: Timeout no processo.

Recepção do resultado correto - data

Na parte de SdkResult.Success - data, teremos a classe NfcResult.

O resultado retorna as imagens no formato SdkImage, é possível extrair o bitmap acessando image.bitmap. Se quiser converter para base64, é possível usar a função:

Base64.encodeToString(this.toByteArray(), Base64.NO_WRAP)

Os campos criptografados no resultado passam a ser incorporados a partir da versão 2.6.0

Os campos retornados no resultado são os seguintes:

nfcRawData

Informações obtidas por cada tipo de dado em formato bruto.

nfcDocumentInformation

Informações obtidas do documento organizadas por:

• documentNumber

• expirationDate

• issuer

• mrzString

• type

nfcPersonalInformation

Informações obtidas do documento organizadas por:

• address

• birthdate

• city

• gender

• name

• nationality

• personalNumber

• placeOfBirth

• surname

nfcImages

Informações de imagens obtidas do documento organizadas por:

• facialImage

• fingerprintImage

• signatureImage

• tokenFacialImage

• tokenSignatureImage

nfcSecurityData

Informações dos dados de segurança do documento organizadas por:

• dataGroupsHashes

• dataGroupsRead

• documentSigningCertificateData

• issuerSigningCertificateData

• ldsVersion

nfcValidations

Informações das validações do documento organizadas por:

• accessType

• activeAuthenticationSupported

• activeAuthenticationValidation

• chipAuthenticationSupported

• chipAuthenticationValidation

• dataGroupsHashesValidation

• documentSigningValidation

• issuerSigningValidation

tokenOcr

Dados do OCR criptografados

Informações avançadas

Esta seção amplia as informações do componente.

Configuração avançada do componente

Para lançar o componente atual, deverá ser criado um objeto NFCConfigurationData que será a configuração do controlador do componente.

A seguir, são detalhados todos os campos que fazem parte desta classe.

documentNumber

Indica o número do documento ou número de suporte dependendo do documento cuja leitura será realizada.

Este campo é obrigatório.

birthDate

Indica a data de nascimento que aparece no documento ("dd/MM/yyyy").

Este campo é obrigatório.

expirationDate

Indica a data de expiração que aparece no documento ("dd/MM/yyyy").

Este campo é obrigatório.

extractionTimeout

Define o tempo máximo que a leitura pode durar.

showReadingScreen

Define se deseja exibir a tela modal inferior com a leitura que está sendo realizada. Se desativada, nenhuma visualização será exibida e será necessário escutar os estados retornados pelo controlador.

showTutorial

Indica se o componente ativa a tela de tutorial. Nesta visualização é explicado de forma intuitiva como a captura é realizada.

vibrationEnabled

Indica se deseja um feedback de vibração ao final do processo.

skipPace

Indica que deseja realizar apenas a leitura BAC de NFC. É uma leitura com informações mais simples e rápida que permite a leitura de uma variedade maior de documentos.

showDiagnostic

Exibir telas de diagnóstico ao final do processo

extractFacialImage

Indica se deseja extrair a imagem do rosto.

extractSignatureImage

Indica se deseja extrair a imagem da assinatura.

documentType

Campo utilizado para alterar a visualização do tutorial e exibir os diferentes documentos.

showPreviousTip

Mostra uma tela prévia ao lançamento da captura com informações sobre o processo a ser realizado e um botão para o lançamento.

readingProgressStyle

Alteração de estilo na tela de leitura do documento:

• ReadingProgressStyle.DOTS: O progresso é indicado visualmente por pontos

• ReadingProgressStyle.PERCENTAGE: O progresso é exibido com uma porcentagem

---

Personalização do componente

Além das mudanças que podem ser feitas no nível do SDK (as quais são explicadas no documento de Personalização do SDK), este componente em específico permite a modificação de sua interface.

Textos

Os textos podem ser personalizados adicionando um arquivo XML de recursos no aplicativo cliente e sobrescrevendo os valores padrão.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="nfc_widget_previous_tip_title_passport">Leitor NFC</string>
    <string name="nfc_widget_previous_tip_title_id">Leitor NFC</string>
    <string name="nfc_widget_previous_tip_description">&lt;b&gt;Encoste&lt;/b&gt; o documento na parte traseira do seu dispositivo.</string>
    <string name="nfc_widget_start_button">Iniciar</string>
    <string name="nfc_widget_tutorial_button">Confira estas dicas</string>
    <string name="nfc_widget_close_button">Fechar</string>
    <string name="nfc_widget_info_button">Mais informações</string>
    <string name="nfc_widget_previous_tip_animation_desc">Dicas anteriores de NFC</string>
    <string name="nfc_widget_mandatory_tutorial_title">Leitor NFC</string>
    <string name="nfc_widget_tutorial_tip_1">Quando passamos um cartão por um sensor, há uma troca de informações chamada NFC.</string>
    <string name="nfc_widget_tutorial_tip_2">No seu celular, o sensor está na área marcada. Aqui você deve aproximar o documento.</string>
    <string name="nfc_widget_tutorial_tip_3_passport">Mantenha o passaporte &lt;b&gt;fechado&lt;/b&gt; para fazer a leitura.</string>
    <string name="nfc_widget_tutorial_tip_3_id">Para uma leitura melhor, remova a capa do seu celular.</string>
    <string name="nfc_widget_ready_to_scan">Pronto para escanear</string>
    <string name="nfc_widget_reading_device">Leitura do dispositivo</string>
    <string name="nfc_widget_start_message">Aproxime o chip do seu celular.\nQuando ele o detectar, mantenha-o imóvel.</string>
    <string name="nfc_widget_reading_message">Mantenha a posição.</string>
    <string name="nfc_widget_reading_document_message">Extraindo dados do documento.</string>
    <string name="nfc_widget_reading_images_message">Extraindo imagens.</string>
    <string name="nfc_widget_close_alt">Encerrar processo</string>
    <string name="nfc_widget_reading_title">Leitura do chip NFC</string>
    <string name="nfc_widget_reading_animation_desc">Animação de leitura NFC</string>
    <string name="nfc_widget_cancel_button">Cancelar</string>
    <string name="nfc_widget_success_title">Leitura concluída</string>
    <string name="nfc_widget_success_document_prefix">Documento:</string>
    <string name="nfc_widget_success_animation_desc">Leitura concluída</string>
    <string name="nfc_widget_error_title">Leitura incompleta</string>
    <string name="nfc_widget_error_animation_desc">Leitura cancelada</string>
    <string name="nfc_widget_retry_button">Tentar novamente</string>
    <string name="nfc_widget_close_action">Fechar</string>
    <string name="nfc_widget_cancelled_title">Fluxo NFC cancelado</string>
    <string name="nfc_widget_cancelled_desc">Feche a visualização para continuar.</string>
    <string name="nfc_widget_cancelled_animation_desc">Fluxo NFC cancelado</string>
    <string name="nfc_widget_timeout_title">Siga as instruções</string>
    <string name="nfc_widget_timeout_desc">Aproxime o documento &lt;b&gt;depois&lt;/b&gt; de clicar no &lt;b&gt;botão Iniciar.&lt;/b&gt;</string>
    <string name="nfc_widget_tag_lost_title">Leitura não concluída</string>
    <string name="nfc_widget_tag_lost_desc">Mantenha a posição até o final da leitura</string>
    <string name="nfc_widget_data_error_title">Não foi possível ler o documento</string>
    <string name="nfc_widget_data_error_desc">Revise os dados inseridos</string>
    <string name="nfc_widget_internal_error_title">Houve um problema técnico</string>
    <string name="nfc_widget_internal_error_desc">Pedimos desculpas. Não foi possível realizar a captura</string>
    <string name="nfc_widget_state_waiting_for_tag">Deslize o documento até que o sensor o detecte.</string>
    <string name="nfc_widget_state_preparing">Preparando a leitura do chip...</string>
    <string name="nfc_widget_state_secure_access">Validando o acesso seguro ao documento...</string>
    <string name="nfc_widget_state_reading_data">Lendo os dados do documento...</string>
    <string name="nfc_widget_state_reading_images">Lendo as imagens do documento...</string>
    <string name="nfc_widget_state_io_error">Foi detectado um problema de comunicação com NFC.</string>
    <string name="nfc_widget_state_finished">Leitura concluída.</string>
</resources>

Animações

Se desejar modificar as animações (lottie) do SDK, será necessário incluir as animações com o mesmo nome na pasta res/raw/ da aplicação.

nfc_anim_reader.json
nfc_anim_tuto_1.json
nfc_anim_tuto_2.json
nfc_anim_tuto_3.json
nfc_anim_tuto_3_pass.json
nfc_anim_tuto_id.json
nfc_anim_tuto_passport.json

Visualizações externas

É possível modificar as telas inferiores de leitura do componente mantendo sua funcionalidade e navegação. A partir da versão 2.8.0, a personalização externa fica limitada às bottom sheets de leitura; as visualizações legadas de dica prévia e diagnóstico já não fazem parte do contrato público. Para isso, devem ser implementadas as seguintes interfaces:

Telas do diálogo de leitura:

interface INfcWaitingBottomView {
    @Composable
    fun Content(
        onClose: () -> Unit,
    )
}

interface INfcReadingBottomView {
    @Composable
    fun Content(
        state: NfcReadState,
        onClose: () -> Unit
    )
}

interface INfcSuccessBottomView {
    @Composable
    fun Content(
        onContinue: () -> Unit,
    )
}

interface INfcErrorBottomView {
    @Composable
    fun Content(
        error: NfcError,
        onContinue: () -> Unit,
    )
}

Depois de criadas as classes que implementam as interfaces, no lançamento do componente será possível adicionar o parâmetro "customViews" para que sejam usadas no SDK.