> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/componentes-modulos/captura-de-nfc.md).

# Captura de NFC

## Introdução <a href="#id-1-introduccion" id="id-1-introduccion"></a>

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](/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) 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 href="#id-2-dependencia" id="id-2-dependencia"></a>

A dependência específica do componente é:

```kts
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:

```kts
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 <a href="#id-4-lanzamiento-simplificado" id="id-4-lanzamiento-simplificado"></a>

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:

<pre class="language-kotlin"><code class="lang-kotlin"><strong>val response = SDKController.launch(
</strong><strong>    NfcController(
</strong>        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
}
</code></pre>

## Configuração básica <a href="#id-5-configuracion-basica" id="id-5-configuracion-basica"></a>

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:

```kotlin
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 href="#id-6-recepcion-del-resultado" id="id-6-recepcion-del-resultado"></a>

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

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

### Recebimento de erros <a href="#id-61-recepcion-de-errores" id="id-61-recepcion-de-errores"></a>

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* <a href="#id-62-recepcion-del-resultado-correcto-data" id="id-62-recepcion-del-resultado-correcto-data"></a>

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

{% hint style="info" %}
Os campos criptografados no resultado passam a ser incorporados a partir da versão 2.6.0
{% endhint %}

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 <a href="#id-7-informacion-avanzada" id="id-7-informacion-avanzada"></a>

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

### Configuração avançada do componente <a href="#id-71-configuracion-avanzada-del-componente" id="id-71-configuracion-avanzada-del-componente"></a>

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 <a href="#id-8-personalizacion-del-componente" id="id-8-personalizacion-del-componente"></a>

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](/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/personalizacion.md)), este componente em específico permite a modificação de sua interface.

### Textos <a href="#id-81-textos" id="id-81-textos"></a>

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

```kotlin
<?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 <a href="#id-82-animaciones" id="id-82-animaciones"></a>

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 <a href="#id-83-vistas-externas" id="id-83-vistas-externas"></a>

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

```kotlin

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

```

```kotlin

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

```

```kotlin

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

```

```kotlin

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.