> 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 do NFC de documentos de identidade e passaportes. Seus principais processos são:

* Gerenciamento interno do sensor de NFC.
* Gerenciamento de permissões.
* Análise de documento.
* Análise do progresso.
* Assistente nos processos de leitura.
* Retorno de todas as informações possíveis a serem lidas
* 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, o componente poderá ser acionado. 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 iniciar 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úm. suport.
    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>

O acionamento retornará as informações no formato SdkResult. Sendo possível diferenciar entre um acionamento correto e um incorreto:

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

### Recepção 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 são nulos.
* NFC\_NO\_DATA\_ERROR: Os dados de entrada são nulos ou não foi recebido resultado da leitura.
* 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: Não há nenhuma operação em andamento.
* NFC\_TIMEOUT: Timeout no processo.

### Recebimento 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 convertê-lo para base64, pode-se utilizar a função:

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

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

Os campos retornados no resultado são os seguintes:

**nfcRawData**

Informação obtida por cada tipo de dado em formato bruto.

**nfcDocumentInformation**

Informação obtida do documento ordenada por:

* documentNumber
* expirationDate
* issuer
* mrzString
* type

**nfcPersonalInformation**

Informação obtida do documento ordenada por:

* address
* birthdate
* city
* gender
* name
* nationality
* personalNumber
* placeOfBirth
* surname

**nfcImages**

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

* facialImage
* fingerprintImage
* signatureImage
* tokenFacialImage
* tokenSignatureImage

**nfcSecurityData**

Informação dos dados de segurança do documento ordenada por:

* dataGroupsHashes
* dataGroupsRead
* documentSigningCertificateData
* issuerSigningCertificateData
* ldsVersion

**nfcValidations**

Informação das validações do documento ordenada 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 iniciar 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 a ser lido.

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 para realizar a leitura.

**showReadingScreen**

Define se deseja mostrar a tela modal inferior com a leitura que está sendo realizada. Se desativado, nenhuma visualização é mostrada e os estados retornados pelo controlador deverão ser ouvidos.

**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 se deseja realizar apenas a leitura BAC de NFC. É uma leitura com informações mais simples e rápidas, que permite a leitura de uma maior variedade de documentos.

**showDiagnostic**

Mostrar 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 usado para alterar a visualização do tutorial e fazer com que mostre os diferentes documentos.

**showPreviousTip**

Exibe uma tela prévia ao início da captura com informações sobre o processo a ser realizado e um botão para iniciar.

**readingProgressStyle**

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

* ReadingProgressStyle.DOTS: O progresso é marcado visualmente com pontos
* ReadingProgressStyle.PERCENTAGE: O progresso é mostrado com uma porcentagem

***

## Personalização do componente <a href="#id-8-personalizacion-del-componente" id="id-8-personalizacion-del-componente"></a>

Além das alterações 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 particular 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 substituindo 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 do 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 seu 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 melhor leitura, remova a capa do seu celular.</string>
    <string name="nfc_widget_ready_to_scan">Pronto para escanear</string>
    <string name="nfc_widget_reading_device">Lendo dispositivo</string>
    <string name="nfc_widget_start_message">Encoste o chip no 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 os dados do documento.</string>
    <string name="nfc_widget_reading_images_message">Extraindo imagens.</string>
    <string name="nfc_widget_close_alt">Fechar processo</string>
    <string name="nfc_widget_reading_title">Lendo 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 de NFC cancelado</string>
    <string name="nfc_widget_cancelled_desc">Feche a visualização para continuar.</string>
    <string name="nfc_widget_cancelled_animation_desc">Fluxo de 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;após&lt;/b&gt; 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 fim 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. A captura não pôde ser realizada</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 o 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á preciso 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,
    )
}

```

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