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:
- Analisa a tag NFC e descobre o tipo MIME ou um URI que identifica o payload de dados na tag.
- 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.
- 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:
-
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_VIEWem vez da intentACTION_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 intentACTION_VIEW. ACTION_TECH_DISCOVERED: se nenhuma atividade for registrada para processar a intentACTION_NDEF_DISCOVERED, o sistema de expedição de tags vai tentar iniciar um aplicativo com essa intent. Essa intent também é iniciada diretamente (sem iniciarACTION_NDEF_DISCOVEREDprimeiro) 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.ACTION_TAG_DISCOVERED: essa intent será iniciada se nenhuma atividade processar as intentsACTION_NDEF_DISCOVEREDouACTION_TECH_DISCOVERED.
O funcionamento básico do sistema de expedição de etiquetas é o seguinte:
- Ele tenta iniciar uma atividade com o intent que foi criado pelo sistema de expedição ao analisar a tag NFC (
ACTION_NDEF_DISCOVEREDouACTION_TECH_DISCOVERED). - Se nenhuma atividade filtrar esse intent, ele tentará iniciar uma atividade com o próximo intent de prioridade mais baixa (
ACTION_TECH_DISCOVEREDouACTION_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. - Se nenhum aplicativo aplicar um filtro para nenhum dos intents, nada acontecerá.
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ãoandroid.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_DISCOVEREDe só concede acesso a mensagens NDEF usando o extraEXTRA_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-featurepara 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-featuree verificar a disponibilidade de NFC no momento da execução, verificando segetDefaultAdapter()é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:
EXTRA_TAG(obrigatório): um objetoTagque representa a tag lida.EXTRA_NDEF_MESSAGES(opcional): uma matriz de mensagens NDEF analisadas da tag. Esse extra é obrigatório em intentsACTION_NDEF_DISCOVERED.EXTRA_ID(opcional): o ID de nível inferior da etiqueta.
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:
- 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.
- 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.
- 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.
- Os apps podem verificar se
o usuário permitiu que eles leiam tags NFC usando
NfcAdapter.isTagIntentAllowed(). - Os apps podem pedir que o usuário permita a leitura de tags NFC novamente enviando a intent
ACTION_CHANGE_TAG_INTENT_PREFERENCE.
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.