Conceitos básicos da NFC

Este documento descreve as tarefas básicas de NFC que são realizadas no Android. Ele explica como enviar e receber dados NFC na forma de mensagens NDEF e descreve as APIs do framework do Android que oferecem suporte a esses recursos. Para tópicos mais avançados, incluindo uma discussão sobre como trabalhar com dados não NDEF, consulte NFC avançada.

A leitura de dados NDEF de uma tag NFC é processada com o sistema de expedição de etiquetas, que analisa tags NFC descobertas, categoriza os dados de forma adequada e inicia um aplicativo interessado nos dados categorizados. Um aplicativo que queira processar a tag NFC lida pode declarar um filtro de intent e solicitar o processamento dos dados.

O sistema de expedição de etiquetas

Os dispositivos com tecnologia Android geralmente procuram tags NFC quando a tela está desbloqueada, a menos que a NFC esteja desativada no menu "Configurações" do dispositivo. Quando um dispositivo com tecnologia Android descobre uma tag NFC, o comportamento esperado é fazer com que a atividade mais apropriada processe o intent sem perguntar ao usuário qual aplicativo usar. Como os dispositivos verificam tags NFC em um alcance muito curto, é provável que, se os usuários precisarem selecionar manualmente uma atividade, eles tenham que afastar o dispositivo da tag, interrompendo a conexão. Desenvolva sua atividade para processar apenas as tags NFC relevantes para ela, evitando que o seletor de atividades apareça.

Para ajudar você com essa meta, o Android oferece um sistema especial de expedição de etiquetas que analisa as tags NFC lidas, as analisa e tenta localizar aplicativos interessados nos dados lidos. Ele faz isso desta forma:

  1. Analisa a tag NFC e descobre o tipo MIME ou um URI que identifica o payload de dados na tag.
  2. Encapsula o tipo MIME ou o URI e o payload em um intent. Essas duas primeiras etapas são descritas em Como as tags NFC são mapeadas para tipos MIME e URIs.
  3. Inicia uma atividade com base no intent. Isso é descrito em Como as tags NFC são enviadas para aplicativos.

Como etiquetas NFC são mapeadas em tipos MIME e URIs

Antes de começar a escrever seus aplicativos NFC, é importante entender os diferentes tipos de tags NFC, como o sistema de expedição de tags analisa as tags NFC e o trabalho especial que o sistema de expedição de tags faz quando detecta uma mensagem NDEF. As tags NFC vêm em uma ampla variedade de tecnologias e também podem ter dados gravados de várias maneiras diferentes. O Android tem mais compatibilidade com o padrão NDEF, que é definido pelo NFC Forum (link em inglês).

Os dados NDEF são encapsulados em uma mensagem (NdefMessage) que contém um ou mais registros (NdefRecord). Cada registro NDEF precisa ser bem formado de acordo com a especificação do tipo de registro que você quer criar. O Android também oferece suporte a outros tipos de tags que não contêm dados NDEF, que podem ser usados com as classes no pacote android.nfc.tech. Para saber mais sobre essas tecnologias, consulte o tópico NFC avançada. Para trabalhar com esses outros tipos de tags, é necessário criar sua própria pilha de protocolos para se comunicar com as tags. Por isso, recomendamos o uso do NDEF sempre que possível para facilitar o desenvolvimento e maximizar a compatibilidade com dispositivos Android.

Observação: para fazer o download das especificações completas do NDEF, acesse o site NFC Forum Specifications & Application Documents e consulte Como criar tipos comuns de registros NDEF para ver exemplos de como criar registros NDEF.

Agora que você já tem um conhecimento básico sobre tags NFC, as seções a seguir descrevem em mais detalhes como o Android lida com tags formatadas em NDEF. Quando um dispositivo Android faz a leitura de uma tag NFC com dados formatados como NDEF, ele analisa a mensagem e tenta descobrir o tipo MIME dos dados ou identificar o URI. Para fazer isso, o sistema lê o primeiro NdefRecord dentro do NdefMessage para determinar como interpretar toda a mensagem NDEF (uma mensagem NDEF pode ter vários registros NDEF). Em uma mensagem NDEF bem formada, o primeiro NdefRecord contém os seguintes campos:

Formato de nome de tipo (TNF, na sigla em inglês) de 3 bits
Indica como interpretar o campo de tipo de comprimento variável. Os valores válidos estão descritos na Tabela 1.
Tipo de comprimento variável
Descreve o tipo do registro. Se estiver usando TNF_WELL_KNOWN, use esse campo para especificar a definição de tipo de registro (RTD, na sigla em inglês). Os valores de RTD válidos são descritos na Tabela 2.
ID de comprimento variável
Um identificador exclusivo para o registro. Esse campo não é usado com frequência, mas, se você precisar identificar uma tag de forma exclusiva, poderá criar um ID para ela.
Payload de comprimento variável
O payload real que você quer ler ou gravar. Uma mensagem NDEF pode conter vários registros NDEF. Portanto, não presuma que o payload completo esteja no primeiro registro NDEF da mensagem NDEF.

O sistema de envio de tags usa os campos TNF e de tipo para tentar mapear um tipo MIME ou URI para a mensagem NDEF. Se bem-sucedido, ele encapsula essas informações dentro de um intent ACTION_NDEF_DISCOVERED com o payload real. No entanto, há casos em que o sistema de envio de tags não consegue determinar o tipo de dados com base no primeiro registro NDEF. Isso acontece quando os dados NDEF não podem ser mapeados para um tipo MIME ou URI ou quando a tag NFC não contém dados NDEF. Nesses casos, um objeto Tag que tem informações sobre as tecnologias da tag e o payload é encapsulado em uma intent ACTION_TECH_DISCOVERED.

A Tabela 1 descreve como o sistema de envio de tags mapeia os campos TNF e de tipo para tipos MIME ou URIs. Ela também descreve quais TNFs não podem ser mapeados para um tipo MIME ou URI. Nesses casos, o sistema de envio de tags volta para ACTION_TECH_DISCOVERED.

Por exemplo, se o sistema de envio de tags encontrar um registro do tipo TNF_ABSOLUTE_URI, ele vai mapear o campo de tipo de comprimento variável desse registro em um URI. O sistema de envio de tags encapsula esse URI no campo de dados de uma intent ACTION_NDEF_DISCOVERED com outras informações sobre a tag, como o payload. Por outro lado, se ele encontrar um registro do tipo TNF_UNKNOWN, ele vai criar uma intent que encapsula as tecnologias da tag.

Tabela 1. TNFs compatíveis e seus mapeamentos

Formato de nome de tipo (TNF) Mapeamento
TNF_ABSOLUTE_URI URI com base no campo de tipo.
TNF_EMPTY Volta para ACTION_TECH_DISCOVERED.
TNF_EXTERNAL_TYPE URI com base no URN no campo de tipo. O URN é codificado no campo de tipo NDEF em um formato abreviado: <domain_name>:<service_name>. O Android mapeia isso para um URI no formato: vnd.android.nfc://ext/<domain_name>:<service_name>.
TNF_MIME_MEDIA Tipo MIME com base no campo de tipo.
TNF_UNCHANGED Inválido no primeiro registro, então volta para ACTION_TECH_DISCOVERED.
TNF_UNKNOWN Volta para ACTION_TECH_DISCOVERED.
TNF_WELL_KNOWN Tipo MIME ou URI, dependendo da definição de tipo de registro (RTD, na sigla em inglês), que você define no campo de tipo. Consulte a Tabela 2 para mais informações sobre os RTDs disponíveis e os mapeamentos deles.

Tabela 2. RTDs compatíveis com TNF_WELL_KNOWN e os mapeamentos deles

Definição de tipo de registro (RTD) Mapeamento
RTD_ALTERNATIVE_CARRIER Volta para ACTION_TECH_DISCOVERED.
RTD_HANDOVER_CARRIER Volta para ACTION_TECH_DISCOVERED.
RTD_HANDOVER_REQUEST Volta para ACTION_TECH_DISCOVERED.
RTD_HANDOVER_SELECT Volta para ACTION_TECH_DISCOVERED.
RTD_SMART_POSTER URI com base na análise do payload.
RTD_TEXT Tipo MIME de text/plain.
RTD_URI URI com base no payload.

Como etiquetas NFC são expedidas para aplicativos

Quando o sistema de expedição de etiquetas termina de criar um intent que encapsula a tag NFC e as informações de identificação dela, ele o envia para um aplicativo interessado que aplica um filtro para esse intent. Se mais de um aplicativo puder processar a intent, o seletor de atividades será apresentado para que o usuário possa selecionar a atividade. O sistema de envio de tags define três intents, que são listadas em ordem de prioridade, da mais alta para a mais baixa:

  1. ACTION_NDEF_DISCOVERED: esse intent é usado para iniciar uma atividade quando uma tag que contém um payload NDEF é lida e é de um tipo reconhecido. Esse é o intent de maior prioridade, e o sistema de expedição de tags tenta iniciar uma atividade com esse intent antes de qualquer outro, sempre que possível.

    Observação: a partir do Android 16, a leitura de tags NFC que armazenam links da Web (ou seja, o esquema de URI é "http://" ou "https://") aciona a intent ACTION_VIEW em vez da intent ACTION_NDEF_DISCOVERED. A partir do Android 17, a leitura de uma tag desse tipo mostra uma notificação de "abrir link", exigindo uma interação explícita do usuário para acionar a intent ACTION_VIEW.

  2. ACTION_TECH_DISCOVERED: se nenhuma atividade for registrada para processar a intent ACTION_NDEF_DISCOVERED, o sistema de expedição de tags vai tentar iniciar um aplicativo com essa intent. Essa intent também é iniciada diretamente (sem iniciar ACTION_NDEF_DISCOVERED primeiro) se a tag lida contém dados NDEF que não podem ser mapeados para um tipo MIME ou URI ou se a tag não contém dados NDEF, mas é de uma tecnologia de tag conhecida.
  3. ACTION_TAG_DISCOVERED: essa intent será iniciada se nenhuma atividade processar as intents ACTION_NDEF_DISCOVERED ou ACTION_TECH_DISCOVERED.

O funcionamento básico do sistema de expedição de etiquetas é o seguinte:

  1. Ele tenta iniciar uma atividade com o intent que foi criado pelo sistema de expedição ao analisar a tag NFC (ACTION_NDEF_DISCOVERED ou ACTION_TECH_DISCOVERED).
  2. Se nenhuma atividade filtrar esse intent, ele tentará iniciar uma atividade com o próximo intent de prioridade mais baixa (ACTION_TECH_DISCOVERED ou ACTION_TAG_DISCOVERED) até que um aplicativo filtre o intent ou até que o sistema de expedição de tags tente todos os intents possíveis.
  3. Se nenhum aplicativo aplicar um filtro para nenhum dos intents, nada acontecerá.
Figura 1. Sistema de envio de tags

Sempre que possível, trabalhe com mensagens NDEF e a intent ACTION_NDEF_DISCOVERED, porque ela é a mais específica das três. Essa intent permite iniciar o aplicativo em um momento mais apropriado do que as outras duas, oferecendo ao usuário uma experiência melhor.

Solicitar acesso a NFC no manifesto do Android

Antes de acessar o hardware NFC de um dispositivo e processar as intents NFC corretamente, declare estes itens no arquivo AndroidManifest.xml:

  • O elemento <uses-permission> de NFC para acessar o hardware de NFC:
    <uses-permission android:name="android.permission.NFC" />
  • A partir do Android 17 (nível 37 da API), para que uma atividade receba uma intent NFC, se o app for direcionado ao SDK > Build.VERSION_CODES.BAKLAVA, ele precisará ser protegido pela permissão android.permission.DISPATCH_NFC_MESSAGE. Isso garante que apenas o serviço do sistema NFC possa enviar intents para sua atividade. Além disso, o sistema não vai enviar intents de NFC para aplicativos que estejam em um estado interrompido (por exemplo, se o aplicativo nunca tiver sido iniciado pelo usuário ou tiver sido forçado a parar).
    <activity
        android:name=".MyActivity"
        android:exported="true"
        android:permission="android.permission.DISPATCH_NFC_MESSAGE">
        ...
    </activity>
  • A versão mínima do SDK compatível com o aplicativo. O nível 9 da API só oferece suporte ao envio limitado de tags usando ACTION_TAG_DISCOVERED e só concede acesso a mensagens NDEF usando o extra EXTRA_NDEF_MESSAGES. Nenhuma outra propriedade de tag ou operação de E/S pode ser acessada. O nível 10 da API inclui suporte abrangente para leitura/gravação, bem como envio de NDEF em primeiro plano, e o nível 14 da API oferece métodos de conveniência extras para criar registros NDEF.
    <uses-sdk android:minSdkVersion="10"/>
  • O elemento uses-feature para que o aplicativo apareça no Google Play apenas para dispositivos que têm hardware NFC:
    <uses-feature android:name="android.hardware.nfc" android:required="true" />

    Se o aplicativo usa a funcionalidade de NFC, mas ela não é crucial para o aplicativo, você pode omitir o elemento uses-feature e verificar a disponibilidade de NFC no momento da execução, verificando se getDefaultAdapter() é null.

Filtro para intents NFC

O aplicativo pode aplicar um filtro para um, dois ou todos os três intents NFC no manifesto do Android para iniciar quando for lida uma tag NFC que você queira processar. No entanto, geralmente é recomendável filtrar a intent ACTION_NDEF_DISCOVERED para ter mais controle sobre quando o aplicativo é iniciado. A intent ACTION_TECH_DISCOVERED é um substituto para ACTION_NDEF_DISCOVERED quando nenhum aplicativo filtra ACTION_NDEF_DISCOVERED ou quando o payload não é NDEF. Filtrar por ACTION_TAG_DISCOVERED geralmente é uma categoria muito geral para filtrar. Muitos aplicativos filtram por ACTION_NDEF_DISCOVERED ou ACTION_TECH_DISCOVERED antes de ACTION_TAG_DISCOVERED, então seu aplicativo tem uma baixa probabilidade de ser iniciado. O ACTION_TAG_DISCOVERED só está disponível como último recurso para os aplicativos filtrarem nos casos em que nenhum outro aplicativo está instalado para processar a intent ACTION_NDEF_DISCOVERED ou ACTION_TECH_DISCOVERED.

Como as implantações de tags NFC variam e muitas vezes não estão sob seu controle, isso nem sempre é possível. Por isso, é possível substituí-lo pelos outros dois intents quando necessário. Quando você tem controle sobre os tipos de tags e dados gravados, é recomendável usar o NDEF para formatar as tags. As seções a seguir descrevem como aplicar um filtro para cada tipo de intent.

ACTION_NDEF_DISCOVERED

Para filtrar intents ACTION_NDEF_DISCOVERED, declare o filtro de intent com o tipo de dados que você quer filtrar. O exemplo a seguir filtra intents ACTION_NDEF_DISCOVERED com um tipo MIME de text/plain:

<activity
    android:name=".MyActivity"
    android:exported="true"
    android:permission="android.permission.DISPATCH_NFC_MESSAGE">
    <intent-filter>
        <action android:name="android.nfc.action.NDEF_DISCOVERED"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="text/plain" />
    </intent-filter>
</activity>

O exemplo a seguir filtra um URI no formato de https://developer.android.com/index.html.

<activity
    android:name=".MyActivity"
    android:exported="true"
    android:permission="android.permission.DISPATCH_NFC_MESSAGE">
    <intent-filter>
        <action android:name="android.nfc.action.NDEF_DISCOVERED"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:scheme="https"
                  android:host="developer.android.com"
                  android:pathPrefix="/index.html" />
    </intent-filter>
</activity>

ACTION_TECH_DISCOVERED

Se a atividade filtrar a intent ACTION_TECH_DISCOVERED, você precisará criar um arquivo de recurso XML que especifique as tecnologias compatíveis com a atividade em um conjunto tech-list. Sua atividade será considerada uma correspondência se um conjunto tech-list for um subconjunto das tecnologias compatíveis com a tag, que podem ser obtidas chamando getTechList().

Por exemplo, se a tag lida for compatível com MifareClassic, NdefFormatable e NfcA, o conjunto tech-list precisará especificar uma, duas ou as três tecnologias (e nada mais) para que a atividade seja correspondida.

O exemplo a seguir define todas as tecnologias. Remova as que não são compatíveis com sua tag NFC. Salve esse arquivo (com o nome que quiser) na pasta <project-root>/res/xml.

<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
    <tech-list>
        <tech>android.nfc.tech.IsoDep</tech>
        <tech>android.nfc.tech.NfcA</tech>
        <tech>android.nfc.tech.NfcB</tech>
        <tech>android.nfc.tech.NfcF</tech>
        <tech>android.nfc.tech.NfcV</tech>
        <tech>android.nfc.tech.Ndef</tech>
        <tech>android.nfc.tech.NdefFormatable</tech>
        <tech>android.nfc.tech.MifareClassic</tech>
        <tech>android.nfc.tech.MifareUltralight</tech>
    </tech-list>
</resources>

Também é possível especificar vários conjuntos tech-list. Cada um dos conjuntos tech-list é considerado de forma independente, e sua atividade é considerada uma correspondência se qualquer conjunto tech-list for um subconjunto das tecnologias retornadas por getTechList(). Isso fornece semânticas AND e OR para tecnologias de correspondência. O exemplo a seguir corresponde a tags que podem oferecer suporte às tecnologias NfcA e Ndef ou às tecnologias NfcB e Ndef:

<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
    <tech-list>
        <tech>android.nfc.tech.NfcA</tech>
        <tech>android.nfc.tech.Ndef</tech>
    </tech-list>
    <tech-list>
        <tech>android.nfc.tech.NfcB</tech>
        <tech>android.nfc.tech.Ndef</tech>
    </tech-list>
</resources>

No arquivo AndroidManifest.xml, especifique o arquivo de recurso que você acabou de criar no elemento <meta-data> dentro do elemento <activity>, como no exemplo a seguir:

<activity
    android:name=".MyActivity"
    android:exported="true"
    android:permission="android.permission.DISPATCH_NFC_MESSAGE">
    <intent-filter>
        <action android:name="android.nfc.action.TECH_DISCOVERED"/>
    </intent-filter>

    <meta-data android:name="android.nfc.action.TECH_DISCOVERED"
        android:resource="@xml/nfc_tech_filter" />
</activity>

Para mais informações sobre como trabalhar com tecnologias de tag e a intent ACTION_TECH_DISCOVERED, consulte Como trabalhar com tecnologias de tag compatíveis no documento NFC avançada.

ACTION_TAG_DISCOVERED

Observação: o uso de ACTION_TAG_DISCOVERED foi descontinuado no Android 17 (nível da API 37). Use ACTION_NDEF_DISCOVERED ou ACTION_TECH_DISCOVERED.

Para filtrar por ACTION_TAG_DISCOVERED, use o seguinte filtro de intent:

<activity
    android:name=".MyActivity"
    android:exported="true"
    android:permission="android.permission.DISPATCH_NFC_MESSAGE">
    <intent-filter>
        <action android:name="android.nfc.action.TAG_DISCOVERED"/>
    </intent-filter>
</activity>

ACTION_VIEW

A partir do Android 16, a leitura de tags NFC que armazenam links da Web (ou seja, o esquema de URI é "http://" ou "https://") aciona a intent ACTION_VIEW em vez da intent ACTION_NDEF_DISCOVERED. A partir do Android 17, a leitura de uma tag desse tipo mostra uma notificação de "abrir link", exigindo uma interação explícita do usuário para acionar a intent ACTION_VIEW. Para filtrar por ACTION_VIEW, consulte this. Use Android app links para abrir o app no URL.

Receber informações de intents

Se uma atividade iniciar devido a uma intent NFC, é possível obter informações sobre a tag NFC lida pela intent. Os intents podem conter os seguintes extras, dependendo da etiqueta que for lida:

Para receber esses extras, verifique se a atividade foi iniciada com um dos intents NFC para garantir que uma tag foi lida e, em seguida, receba os extras do intent. O exemplo a seguir verifica a intent ACTION_NDEF_DISCOVERED e recebe as mensagens NDEF de um extra de intent.

Kotlin

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    ...
    if (NfcAdapter.ACTION_NDEF_DISCOVERED == intent.action) {
        intent.getParcelableArrayExtra(NfcAdapter.EXTRA_NDEF_MESSAGES)?.also { rawMessages ->
            val messages: List<NdefMessage> = rawMessages.map { it as NdefMessage }
            // Process the messages array.
            ...
        }
    }
}

Java

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    ...
    if (NfcAdapter.ACTION_NDEF_DISCOVERED.equals(intent.getAction())) {
        Parcelable[] rawMessages =
            intent.getParcelableArrayExtra(NfcAdapter.EXTRA_NDEF_MESSAGES);
        if (rawMessages != null) {
            NdefMessage[] messages = new NdefMessage[rawMessages.length];
            for (int i = 0; i < rawMessages.length; i++) {
                messages[i] = (NdefMessage) rawMessages[i];
            }
            // Process the messages array.
            ...
        }
    }
}

Como alternativa, é possível receber um objeto Tag da intent, que vai conter o payload e permitir que você enumere as tecnologias da tag:

Kotlin

val tag: Tag = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG)

Java

Tag tag = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG);

Criar tipos comuns de registros NDEF

Nesta seção, descrevemos como criar tipos comuns de registros NDEF para ajudar você a gravar em tags NFC. A partir do Android 4.0 (nível 14 da API), o método createUri() está disponível para ajudar você a criar registros de URI automaticamente. No Android 4.1 (nível 16 da API) e versões mais recentes, createExternal() e createMime() estão disponíveis para ajudar você a criar registros NDEF de tipo MIME e externo. Use esses métodos auxiliares sempre que possível para evitar erros ao criar manualmente registros NDEF.

Esta seção também descreve como criar o filtro de intent correspondente para o registro. Todos esses exemplos de registro NDEF precisam estar no primeiro registro NDEF da mensagem NDEF que você está gravando em uma tag.

TNF_ABSOLUTE_URI

Observação: recomendamos usar o tipo RTD_URI em vez de TNF_ABSOLUTE_URI, porque ele é mais eficiente.

Você pode criar um registro NDEF TNF_ABSOLUTE_URI da seguinte maneira:

Kotlin

val uriRecord = ByteArray(0).let { emptyByteArray ->
    NdefRecord(
            TNF_ABSOLUTE_URI,
            "https://developer.android.com/index.html".toByteArray(Charset.forName("US-ASCII")),
            emptyByteArray,
            emptyByteArray
    )
}

Java

NdefRecord uriRecord = new NdefRecord(
    NdefRecord.TNF_ABSOLUTE_URI ,
    "https://developer.android.com/index.html".getBytes(Charset.forName("US-ASCII")),
    new byte[0], new byte[0]);

O filtro de intent do registro NDEF anterior ficaria assim:

<activity
    android:name=".MyActivity"
    android:exported="true"
    android:permission="android.permission.DISPATCH_NFC_MESSAGE">
    <intent-filter>
        <action android:name="android.nfc.action.NDEF_DISCOVERED" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:scheme="https"
            android:host="developer.android.com"
            android:pathPrefix="/index.html" />
    </intent-filter>
</activity>

TNF_MIME_MEDIA

É possível criar um registro NDEF TNF_MIME_MEDIA das seguintes maneiras:

Usando o método createMime():

Kotlin

val mimeRecord = NdefRecord.createMime(
        "application/vnd.com.example.android.beam",
        "Beam me up, Android".toByteArray(Charset.forName("US-ASCII"))
)

Java

NdefRecord mimeRecord = NdefRecord.createMime("application/vnd.com.example.android.beam",
    "Beam me up, Android".getBytes(Charset.forName("US-ASCII")));

Criando o NdefRecord manualmente:

Kotlin

val mimeRecord = Charset.forName("US-ASCII").let { usAscii ->
    NdefRecord(
            NdefRecord.TNF_MIME_MEDIA,
            "application/vnd.com.example.android.beam".toByteArray(usAscii),
            ByteArray(0),
            "Beam me up, Android!".toByteArray(usAscii)
    )
}

Java

NdefRecord mimeRecord = new NdefRecord(
    NdefRecord.TNF_MIME_MEDIA ,
    "application/vnd.com.example.android.beam".getBytes(Charset.forName("US-ASCII")),
    new byte[0], "Beam me up, Android!".getBytes(Charset.forName("US-ASCII")));

O filtro de intent do registro NDEF anterior ficaria assim:

<activity
    android:name=".MyActivity"
    android:exported="true"
    android:permission="android.permission.DISPATCH_NFC_MESSAGE">
    <intent-filter>
        <action android:name="android.nfc.action.NDEF_DISCOVERED" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="application/vnd.com.example.android.beam" />
    </intent-filter>
</activity>

TNF_WELL_KNOWN com RTD_TEXT

É possível criar um registro NDEF TNF_WELL_KNOWN da seguinte maneira:

Kotlin

fun createTextRecord(payload: String, locale: Locale, encodeInUtf8: Boolean): NdefRecord {
    val langBytes = locale.language.toByteArray(Charset.forName("US-ASCII"))
    val utfEncoding = if (encodeInUtf8) Charset.forName("UTF-8") else Charset.forName("UTF-16")
    val textBytes = payload.toByteArray(utfEncoding)
    val utfBit: Int = if (encodeInUtf8) 0 else 1 shl 7
    val status = (utfBit + langBytes.size).toChar()
    val data = ByteArray(1 + langBytes.size + textBytes.size)
    data[0] = status.toByte()
    System.arraycopy(langBytes, 0, data, 1, langBytes.size)
    System.arraycopy(textBytes, 0, data, 1 + langBytes.size, textBytes.size)
    return NdefRecord(NdefRecord.TNF_WELL_KNOWN, NdefRecord.RTD_TEXT, ByteArray(0), data)
}

Java

public NdefRecord createTextRecord(String payload, Locale locale, boolean encodeInUtf8) {
    byte[] langBytes = locale.getLanguage().getBytes(Charset.forName("US-ASCII"));
    Charset utfEncoding = encodeInUtf8 ? Charset.forName("UTF-8") : Charset.forName("UTF-16");
    byte[] textBytes = payload.getBytes(utfEncoding);
    int utfBit = encodeInUtf8 ? 0 : (1 << 7);
    char status = (char) (utfBit + langBytes.length);
    byte[] data = new byte[1 + langBytes.length + textBytes.length];
    data[0] = (byte) status;
    System.arraycopy(langBytes, 0, data, 1, langBytes.length);
    System.arraycopy(textBytes, 0, data, 1 + langBytes.length, textBytes.length);
    NdefRecord record = new NdefRecord(NdefRecord.TNF_WELL_KNOWN,
    NdefRecord.RTD_TEXT, new byte[0], data);
    return record;
}

O filtro de intent do registro NDEF anterior ficaria assim:

<activity
    android:name=".MyActivity"
    android:exported="true"
    android:permission="android.permission.DISPATCH_NFC_MESSAGE">
    <intent-filter>
        <action android:name="android.nfc.action.NDEF_DISCOVERED" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="text/plain" />
    </intent-filter>
</activity>

TNF_WELL_KNOWN com RTD_URI

É possível criar um registro NDEF TNF_WELL_KNOWN das seguintes maneiras:

Usando o método createUri(String):

Kotlin

val rtdUriRecord1 = NdefRecord.createUri("https://example.com")

Java

NdefRecord rtdUriRecord1 = NdefRecord.createUri("https://example.com");

Usando o método createUri(Uri):

Kotlin

val rtdUriRecord2 = Uri.parse("https://example.com").let { uri ->
    NdefRecord.createUri(uri)
}

Java

Uri uri = Uri.parse("https://example.com");
NdefRecord rtdUriRecord2 = NdefRecord.createUri(uri);

Criando o NdefRecord manualmente:

Kotlin

val uriField = "example.com".toByteArray(Charset.forName("US-ASCII"))
val payload = ByteArray(uriField.size + 1)                   //add 1 for the URI Prefix
payload [0] = 0x01                                           //prefixes https://www. to the URI
System.arraycopy(uriField, 0, payload, 1, uriField.size)     //appends URI to payload
val rtdUriRecord = NdefRecord(NdefRecord.TNF_WELL_KNOWN, NdefRecord.RTD_URI, ByteArray(0), payload)

Java

byte[] uriField = "example.com".getBytes(Charset.forName("US-ASCII"));
byte[] payload = new byte[uriField.length + 1];              //add 1 for the URI Prefix
payload[0] = 0x01;                                           //prefixes https://www. to the URI
System.arraycopy(uriField, 0, payload, 1, uriField.length);  //appends URI to payload
NdefRecord rtdUriRecord = new NdefRecord(
    NdefRecord.TNF_WELL_KNOWN, NdefRecord.RTD_URI, new byte[0], payload);

O filtro de intent do registro NDEF anterior ficaria assim:

<activity
    android:name=".MyActivity"
    android:exported="true"
    android:permission="android.permission.DISPATCH_NFC_MESSAGE">
    <intent-filter>
        <action android:name="android.nfc.action.NDEF_DISCOVERED" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:scheme="https"
            android:host="example.com"
            android:pathPrefix="" />
    </intent-filter>
</activity>

TNF_EXTERNAL_TYPE

É possível criar um registro NDEF TNF_EXTERNAL_TYPE das seguintes maneiras:

Usando o método createExternal():

Kotlin

var payload: ByteArray //assign to your data
val domain = "com.example" //usually your app's package name
val type = "externalType"
val extRecord = NdefRecord.createExternal(domain, type, payload)

Java

byte[] payload; //assign to your data
String domain = "com.example"; //usually your app's package name
String type = "externalType";
NdefRecord extRecord = NdefRecord.createExternal(domain, type, payload);

Criando o NdefRecord manualmente:

Kotlin

var payload: ByteArray
...
val extRecord = NdefRecord(
        NdefRecord.TNF_EXTERNAL_TYPE,
        "com.example:externalType".toByteArray(Charset.forName("US-ASCII")),
        ByteArray(0),
        payload
)

Java

byte[] payload;
...
NdefRecord extRecord = new NdefRecord(
    NdefRecord.TNF_EXTERNAL_TYPE, "com.example:externalType".getBytes(Charset.forName("US-ASCII")),
    new byte[0], payload);

O filtro de intent do registro NDEF anterior ficaria assim:

<activity
    android:name=".MyActivity"
    android:exported="true"
    android:permission="android.permission.DISPATCH_NFC_MESSAGE">
    <intent-filter>
        <action android:name="android.nfc.action.NDEF_DISCOVERED" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:scheme="vnd.android.nfc"
            android:host="ext"
            android:pathPrefix="/com.example:externalType"/>
    </intent-filter>
</activity>

Use TNF_EXTERNAL_TYPE para implantações mais genéricas de tags NFC para oferecer melhor compatibilidade para dispositivos com tecnologia Android e sem.

Observação: os URNs para TNF_EXTERNAL_TYPE têm um formato canônico de: urn:nfc:ext:example.com:externalType, mas a especificação RTD do fórum de NFC declara que a parte urn:nfc:ext: do URN precisa ser omitida do registro NDEF. Portanto, basta fornecer o domínio (example.com no exemplo) e o tipo (externalType no exemplo) separados por dois-pontos. Ao enviar TNF_EXTERNAL_TYPE, o Android converte o URN urn:nfc:ext:example.com:externalType em um URI vnd.android.nfc://ext/example.com:externalType, que é o que o filtro de intent no exemplo declara.

Registros do aplicativo para Android

Introduzido no Android 4.0 (nível 14 da API), um Android Application Record (AAR) fornece uma garantia maior de que o aplicativo será iniciado quando uma tag NFC for lida. Um AAR tem o nome do pacote de um aplicativo incorporado em um registro NDEF. É possível adicionar um AAR a qualquer registro NDEF da sua mensagem NDEF, porque o Android pesquisa toda a mensagem NDEF em busca de AARs. Se encontrar um AAR, ele vai iniciar o aplicativo com base no nome do pacote dentro do AAR. Se o aplicativo não estiver presente no dispositivo, o Google Play será iniciado para fazer o download dele.

Os AARs são úteis se você quiser impedir que outros aplicativos filtrem a mesma intent e possam processar tags específicas que você implantou. As AARs só são compatíveis no nível do aplicativo, devido à restrição de nome do pacote, e não no nível da atividade, como ocorre com a filtragem de intents. Se quiser processar um intent no nível da atividade, use os filtros de intent.

Se uma etiqueta contiver um AAR, o sistema de expedição de etiquetas fará a expedição da seguinte maneira:

  1. Ele tentará iniciar uma atividade usando um filtro de intent normalmente. Se a atividade que corresponde à intent também corresponder ao AAR, inicie a atividade.
  2. Se a atividade que filtra a intent não corresponder ao AAR, se várias atividades puderem processar a intent ou se nenhuma atividade processar a intent, inicie o aplicativo especificado pelo AAR.
  3. Se nenhum aplicativo puder ser iniciado com o AAR, acesse o Google Play para baixar o aplicativo com base no AAR.

Observação: você pode substituir os AARs e o sistema de expedição de intents pelo sistema de expedição em primeiro plano, o que permite que uma atividade em primeiro plano tenha prioridade quando uma tag NFC é descoberta. Com esse método, a atividade precisa estar em primeiro plano para substituir os AARs e o sistema de expedição de intents.

Se você ainda quiser filtrar tags lidas que não contêm um AAR, declare filtros de intent normalmente. Isso é útil se o aplicativo estiver interessado em outras tags que não contêm um AAR. Por exemplo, talvez você queira garantir que seu aplicativo processe tags reservadas que você implanta, bem como tags gerais implantadas por terceiros. Lembre-se de que os AARs são específicos para dispositivos Android 4.0 ou mais recentes. Portanto, ao implantar tags, é recomendável usar uma combinação de AARs e tipos MIME/URIs para oferecer suporte à maior variedade possível de dispositivos. Além disso, ao implantar tags NFC, pense em como você quer gravar suas tags NFC para permitir suporte para a maioria dos dispositivos (com tecnologia Android e outros). Para isso, defina um tipo MIME ou URI relativamente exclusivo para facilitar a distinção entre os aplicativos.

O Android oferece uma API simples para criar um AAR, createApplicationRecord(). Basta incorporar o AAR em qualquer lugar do NdefMessage. Não use o primeiro registro do NdefMessage, a menos que o AAR seja o único registro no NdefMessage. Isso ocorre porque o sistema Android verifica o primeiro registro de um NdefMessage para determinar o tipo MIME ou o URI da tag, que é usado para criar uma intent para os aplicativos filtrarem. O código a seguir mostra como criar um AAR:

Kotlin

val msg = NdefMessage(
        arrayOf(
                ...,
                NdefRecord.createApplicationRecord("com.example.android.beam")
        )
)

Java

NdefMessage msg = new NdefMessage(
        new NdefRecord[] {
            ...,
            NdefRecord.createApplicationRecord("com.example.android.beam")}
        );
)

Lista de permissões de apps para leitura de tags NFC

A partir do Android 16, os usuários são notificados quando um app recebe a primeira intent NFC para ler tags NFC. O usuário tem a opção de impedir que o app leia tags NFC na notificação.

Observação: a lista de permissões do app de leitura de tags NFC pode ser acessada em Settings > Apps > Special app access > Launch via NFC.

Esse mecanismo foi adicionado para resolver as preocupações levantadas pelos usuários, em que alguns apps que registraram filtros de intent para intents de tag NFC eram trazidos repetidamente para o primeiro plano quando o smartphone era colocado ao lado de uma tag NFC (cartão de crédito, outro smartphone/relógio etc.).