In diesem Dokument werden die grundlegenden NFC-Aufgaben beschrieben, die Sie in Android ausführen. Es wird erläutert, wie NFC-Daten in Form von NDEF-Nachrichten gesendet und empfangen werden, und die Android-Framework-APIs, die diese Funktionen unterstützen, werden beschrieben. Weitere Informationen zu fortgeschrittenen Themen, einschließlich der Arbeit mit Nicht-NDEF-Daten, findest du unter Erweiterte NFC-Funktionen.
Das Lesen von NDEF-Daten von einem NFC-Tag wird mit dem Tag-Versandsystem durchgeführt. Dieses analysiert erkannte NFC-Tags, kategorisiert die Daten entsprechend und startet eine Anwendung, die an den kategorisierten Daten interessiert ist. Eine Anwendung, die das gescannte NFC-Tag verarbeiten möchte, kann einen Intent-Filter deklarieren und die Verarbeitung der Daten anfordern.
Das Tag-Versandsystem
Android-Geräte suchen normalerweise nach NFC-Tags, wenn das Display entsperrt ist, es sei denn, NFC ist im Menü „Einstellungen“ des Geräts deaktiviert. Wenn ein Android-Gerät ein NFC-Tag erkennt, sollte die am besten geeignete Aktivität den Intent verarbeiten, ohne den Nutzer zu fragen, welche Anwendung verwendet werden soll. Da Geräte NFC-Tags aus sehr kurzer Entfernung scannen, ist es wahrscheinlich, dass Nutzer das Gerät vom Tag wegbewegen und die Verbindung unterbrechen müssen, wenn sie eine Aktivität manuell auswählen müssen. Du solltest deine Aktivität so entwickeln, dass sie nur die NFC-Tags verarbeitet, die für deine Aktivität relevant sind, damit die Aktivitätsauswahl nicht angezeigt wird.
Android bietet ein spezielles Tag-Dispatch-System, das gescannte NFC-Tags analysiert, parst und versucht, Anwendungen zu finden, die an den gescannten Daten interessiert sind. Das funktioniert so:
- Das NFC-Tag parsen und den MIME-Typ oder einen URI ermitteln, der die Datennutzlast im Tag identifiziert.
- Kapseln des MIME-Typs oder URI und der Nutzlast in einen Intent. Diese ersten beiden Schritte werden unter NFC-Tags MIME-Typen und URIs zuordnen beschrieben.
- Startet eine Aktivität basierend auf dem Intent. Dies wird unter NFC-Tags an Anwendungen senden beschrieben.
Zuordnung von NFC-Tags zu MIME-Typen und URIs
Bevor du mit dem Schreiben deiner NFC-Anwendungen beginnst, solltest du dich mit den verschiedenen Arten von NFC-Tags, dem Parsen von NFC-Tags durch das Tag-Dispatch-System und den speziellen Aufgaben des Tag-Dispatch-Systems beim Erkennen einer NDEF-Nachricht vertraut machen. NFC-Tags sind in einer Vielzahl von Technologien verfügbar und können auch auf viele verschiedene Arten mit Daten beschrieben werden. Android bietet die beste Unterstützung für den NDEF-Standard, der vom NFC Forum definiert wird.
NDEF-Daten sind in einer Nachricht (NdefMessage) gekapselt, die einen oder mehrere Einträge (NdefRecord) enthält. Jeder NDEF-Eintrag muss gemäß der Spezifikation des Typs des Eintrags, den Sie erstellen möchten, wohlgeformt sein. Android unterstützt auch andere Arten von Tags, die keine NDEF-Daten enthalten. Diese können Sie mit den Klassen im Paket android.nfc.tech verwenden. Weitere Informationen zu diesen Technologien findest du im Thema Erweitertes NFC. Wenn du mit diesen anderen Arten von Tags arbeitest, musst du einen eigenen Protokollstack schreiben, um mit den Tags zu kommunizieren. Wir empfehlen daher, nach Möglichkeit NDEF zu verwenden, um die Entwicklung zu vereinfachen und die maximale Unterstützung für Android-Geräte zu gewährleisten.
Hinweis: Wenn du die vollständigen NDEF-Spezifikationen herunterladen möchtest, rufe die Website NFC Forum Specifications & Application Documents auf. Unter Creating common types of NDEF records findest du Beispiele für die Erstellung von NDEF-Einträgen.
Nachdem du nun einige Hintergrundinformationen zu NFC-Tags hast, wird in den folgenden Abschnitten genauer beschrieben, wie Android mit NDEF-formatierten Tags umgeht. Wenn ein Android-Gerät ein NFC-Tag mit NDEF-formatierten Daten scannt, parst es die Nachricht und versucht, den MIME-Typ oder die identifizierende URI der Daten zu ermitteln. Dazu liest das System den ersten NdefRecord in der NdefMessage, um zu bestimmen, wie die gesamte NDEF-Nachricht interpretiert werden soll. Eine NDEF-Nachricht kann mehrere NDEF-Einträge enthalten. In einer wohlgeformten NDEF-Nachricht enthält der erste NdefRecord die folgenden Felder:
- 3-Bit-TNF (Type Name Format)
- Gibt an, wie das Feld für den Typ mit variabler Länge interpretiert werden soll. Gültige Werte werden in Tabelle 1 beschrieben.
- Typ mit variabler Länge
- Beschreibt den Typ des Datensatzes. Wenn Sie
TNF_WELL_KNOWNverwenden, geben Sie in diesem Feld die Record Type Definition (RTD) an. Gültige RTD-Werte werden in Tabelle 2 beschrieben. - ID mit variabler Länge
- Eine eindeutige Kennung für den Eintrag. Dieses Feld wird nicht oft verwendet. Wenn Sie ein Tag jedoch eindeutig identifizieren müssen, können Sie eine ID dafür erstellen.
- Nutzlast mit variabler Länge
- Die tatsächliche Datennutzlast, die Sie lesen oder schreiben möchten. Eine NDEF-Nachricht kann mehrere NDEF-Einträge enthalten. Gehe also nicht davon aus, dass sich die vollständige Nutzlast im ersten NDEF-Eintrag der NDEF-Nachricht befindet.
Das Tag-Versandsystem verwendet die Felder „TNF“ und „Typ“, um der NDEF-Nachricht einen MIME-Typ oder URI zuzuordnen. Wenn der Vorgang erfolgreich ist, werden diese Informationen zusammen mit der eigentlichen Nutzlast in einem ACTION_NDEF_DISCOVERED-Intent gekapselt. Es gibt jedoch Fälle, in denen das Tag-Versandsystem den Datentyp nicht anhand des ersten NDEF-Eintrags bestimmen kann. Das passiert, wenn die NDEF-Daten keinem MIME-Typ oder URI zugeordnet werden können oder wenn das NFC-Tag keine NDEF-Daten enthält. In solchen Fällen wird stattdessen ein Tag-Objekt mit Informationen zu den Technologien des Tags und der Nutzlast in einem ACTION_TECH_DISCOVERED-Intent gekapselt.
In Tabelle 1 wird beschrieben, wie das Tag-Dispatch-System TNF- und Typfelder MIME-Typen oder URIs zuordnet. Außerdem wird beschrieben, welche TNFs keinem MIME-Typ oder keiner URI zugeordnet werden können.
In diesen Fällen greift das Tag-Versandsystem auf ACTION_TECH_DISCOVERED zurück.
Wenn das Tag-Dispatch-System beispielsweise auf einen Eintrag vom Typ TNF_ABSOLUTE_URI stößt, wird das Feld mit variabler Länge dieses Eintrags einem URI zugeordnet. Das Tag-Versandsystem kapselt diesen URI zusammen mit anderen Informationen zum Tag, z. B. der Nutzlast, im Datenfeld eines ACTION_NDEF_DISCOVERED-Intents. Wenn es dagegen auf einen Eintrag vom Typ TNF_UNKNOWN stößt, erstellt es stattdessen einen Intent, der die Technologien des Tags kapselt.
Tabelle 1. Unterstützte TNFs und ihre Zuordnungen
| Type Name Format (TNF) | Zuordnung |
|---|---|
TNF_ABSOLUTE_URI |
URI basierend auf dem Typfeld. |
TNF_EMPTY |
Ein Fallback auf ACTION_TECH_DISCOVERED erfolgt. |
TNF_EXTERNAL_TYPE |
URI basierend auf dem URN im Feld „type“. Der URN wird in verkürzter Form in das NDEF-Typfeld codiert: <domain_name>:<service_name>.
Android ordnet dies einem URI im folgenden Format zu:
vnd.android.nfc://ext/<domain_name>:<service_name>. |
TNF_MIME_MEDIA |
MIME-Typ basierend auf dem Typfeld. |
TNF_UNCHANGED |
Ungültig im ersten Eintrag, daher wird auf ACTION_TECH_DISCOVERED zurückgegriffen. |
TNF_UNKNOWN |
Ein Fallback auf ACTION_TECH_DISCOVERED erfolgt. |
TNF_WELL_KNOWN |
MIME-Typ oder URI, je nach Record Type Definition (RTD), die Sie im Feld „Typ“ festlegen. Weitere Informationen zu den verfügbaren RTDs und ihren Zuordnungen finden Sie in Tabelle 2. |
Tabelle 2. Unterstützte RTDs für TNF_WELL_KNOWN und ihre Zuordnungen
| Record Type Definition (RTD) | Zuordnung |
|---|---|
RTD_ALTERNATIVE_CARRIER |
Ein Fallback auf ACTION_TECH_DISCOVERED erfolgt. |
RTD_HANDOVER_CARRIER |
Ein Fallback auf ACTION_TECH_DISCOVERED erfolgt. |
RTD_HANDOVER_REQUEST |
Ein Fallback auf ACTION_TECH_DISCOVERED erfolgt. |
RTD_HANDOVER_SELECT |
Ein Fallback auf ACTION_TECH_DISCOVERED erfolgt. |
RTD_SMART_POSTER |
URI basierend auf dem Parsen der Nutzlast. |
RTD_TEXT |
MIME-Typ von text/plain. |
RTD_URI |
URI basierend auf der Nutzlast. |
Wie NFC-Tags an Anwendungen gesendet werden
Wenn das Tag-Versandsystem einen Intent erstellt hat, der das NFC-Tag und die zugehörigen Identifikationsinformationen enthält, wird der Intent an eine interessierte Anwendung gesendet, die nach dem Intent filtert. Wenn mehr als eine Anwendung den Intent verarbeiten kann, wird die Aktivitätsauswahl angezeigt, damit der Nutzer die Aktivität auswählen kann. Das Tag-Dispatch-System definiert drei Intents, die in der Reihenfolge von der höchsten zur niedrigsten Priorität aufgeführt sind:
-
ACTION_NDEF_DISCOVERED: Dieser Intent wird verwendet, um eine Aktivität zu starten, wenn ein Tag mit einer NDEF-Nutzlast gescannt wird und einen erkannten Typ hat. Dies ist der Intent mit der höchsten Priorität. Das Tag-Versandsystem versucht, wenn möglich, vor allen anderen Intents eine Aktivität mit diesem Intent zu starten.Hinweis: Ab Android 16 wird beim Scannen von NFC-Tags, die Weblinks speichern (d. h. das URI-Schema ist „http://“ oder „https://“), der Intent
ACTION_VIEWanstelle des IntentsACTION_NDEF_DISCOVEREDausgelöst. Ab Android 17 wird beim Scannen eines solchen Tags eine Benachrichtigung zum Öffnen des Links angezeigt. Der Nutzer muss dann explizit mit dem Tag interagieren, um denACTION_VIEW-Intent auszulösen. ACTION_TECH_DISCOVERED: Wenn keine Aktivitäten für die Verarbeitung des IntentsACTION_NDEF_DISCOVEREDregistriert sind, versucht das Tag-Versandsystem, eine Anwendung mit diesem Intent zu starten. Dieser Intent wird auch direkt gestartet (ohne zuerstACTION_NDEF_DISCOVEREDzu starten), wenn das gescannte Tag NDEF-Daten enthält, die keinem MIME-Typ oder URI zugeordnet werden können, oder wenn das Tag keine NDEF-Daten enthält, aber eine bekannte Tag-Technologie verwendet.ACTION_TAG_DISCOVERED: Dieser Intent wird gestartet, wenn keine Aktivitäten die IntentsACTION_NDEF_DISCOVEREDoderACTION_TECH_DISCOVEREDverarbeiten.
Das Tag-Dispatch-System funktioniert im Wesentlichen so:
- Versuchen Sie, eine Aktivität mit dem Intent zu starten, der vom Tag-Versandsystem beim Parsen des NFC-Tags (entweder
ACTION_NDEF_DISCOVEREDoderACTION_TECH_DISCOVERED) erstellt wurde. - Wenn keine Aktivitäten für diesen Intent filtern, wird versucht, eine Aktivität mit dem Intent mit der nächstniedrigeren Priorität (entweder
ACTION_TECH_DISCOVEREDoderACTION_TAG_DISCOVERED) zu starten, bis eine Anwendung für den Intent filtert oder bis das Tag-Dispatch-System alle möglichen Intents ausprobiert hat. - Wenn keine Anwendungen nach einem der Intents filtern, wird nichts unternommen.
Arbeite nach Möglichkeit mit NDEF-Nachrichten und dem Intent ACTION_NDEF_DISCOVERED, da dieser der spezifischste der drei Intents ist. Mit diesem Intent kannst du deine Anwendung zu einem geeigneteren Zeitpunkt als mit den anderen beiden Intents starten, was die Nutzerfreundlichkeit verbessert.
NFC-Zugriff im Android-Manifest anfordern
Bevor du auf die NFC-Hardware eines Geräts zugreifen und NFC-Intents richtig verarbeiten kannst, musst du diese Elemente in deiner AndroidManifest.xml-Datei deklarieren:
- Das NFC-Element
<uses-permission>für den Zugriff auf die NFC-Hardware:<uses-permission android:name="android.permission.NFC" />
- Ab Android 17 (API-Level 37) muss eine Aktivität, die einen NFC-Intent erhalten soll, durch die Berechtigung
android.permission.DISPATCH_NFC_MESSAGEgeschützt sein, wenn die App auf SDK >Build.VERSION_CODES.BAKLAVAausgerichtet ist. Dadurch wird sichergestellt, dass nur der NFC-Systemdienst Intents an deine Aktivität senden kann. Außerdem werden keine NFC-Intents an Anwendungen gesendet, die sich im Status „Beendet“ befinden, z.B. wenn die Anwendung noch nie vom Nutzer gestartet oder zwangsweise beendet wurde.<activity android:name=".MyActivity" android:exported="true" android:permission="android.permission.DISPATCH_NFC_MESSAGE"> ... </activity>
- Die SDK-Mindestversion, die Ihre Anwendung unterstützen kann. API-Level 9 unterstützt nur die eingeschränkte Tag-Weiterleitung mit
ACTION_TAG_DISCOVEREDund ermöglicht den Zugriff auf NDEF-Nachrichten nur über das ExtraEXTRA_NDEF_MESSAGES. Auf andere Tag-Attribute oder E/A-Vorgänge kann nicht zugegriffen werden. API-Level 10 bietet umfassende Unterstützung für Lese- und Schreibvorgänge sowie für das NDEF-Pushing im Vordergrund. API-Level 14 bietet zusätzliche praktische Methoden zum Erstellen von NDEF-Datensätzen.<uses-sdk android:minSdkVersion="10"/> - Das Element
uses-feature, damit deine App bei Google Play nur für Geräte mit NFC-Hardware angezeigt wird:<uses-feature android:name="android.hardware.nfc" android:required="true" />
Wenn deine App NFC-Funktionen verwendet, diese aber nicht entscheidend für deine App sind, kannst du das Element
uses-featureweglassen und die NFC-Verfügbarkeit zur Laufzeit prüfen, indem du prüfst, obgetDefaultAdapter()den Wertnullhat.
Nach NFC-Intents filtern
Wenn Sie Ihre Anwendung starten möchten, wenn ein NFC-Tag gescannt wird, das Sie verarbeiten möchten, kann Ihre Anwendung nach einem, zwei oder allen drei NFC-Intents im Android-Manifest filtern. In der Regel sollten Sie jedoch nach dem Intent ACTION_NDEF_DISCOVERED filtern, um die beste Kontrolle darüber zu haben, wann Ihre Anwendung gestartet wird. Der Intent ACTION_TECH_DISCOVERED ist ein Fallback für ACTION_NDEF_DISCOVERED, wenn keine Anwendungen nach ACTION_NDEF_DISCOVERED filtern oder wenn die Nutzlast nicht NDEF ist. Das Filtern nach ACTION_TAG_DISCOVERED ist in der Regel eine zu allgemeine Kategorie, um danach zu filtern. Viele Anwendungen filtern vor ACTION_TAG_DISCOVERED nach ACTION_NDEF_DISCOVERED oder ACTION_TECH_DISCOVERED, sodass die Wahrscheinlichkeit, dass Ihre Anwendung gestartet wird, gering ist. ACTION_TAG_DISCOVERED ist nur als letzte Möglichkeit für Anwendungen verfügbar, nach denen gefiltert werden kann, wenn keine anderen Anwendungen installiert sind, um den Intent ACTION_NDEF_DISCOVERED oder ACTION_TECH_DISCOVERED zu verarbeiten.
Da NFC-Tag-Bereitstellungen variieren und oft nicht unter deiner Kontrolle sind, ist dies nicht immer möglich. Deshalb kannst du bei Bedarf auf die anderen beiden Intents zurückgreifen. Wenn du die Kontrolle über die Arten von Tags und Daten hast, die geschrieben werden, solltest du deine Tags mit NDEF formatieren. In den folgenden Abschnitten wird beschrieben, wie Sie nach den einzelnen Intent-Typen filtern.
ACTION_NDEF_DISCOVERED
Wenn du nach ACTION_NDEF_DISCOVERED-Intents filtern möchtest, deklariere den Intent-Filter zusammen mit dem Datentyp, nach dem du filtern möchtest. Im folgenden Beispiel wird nach ACTION_NDEF_DISCOVERED-Intents mit dem MIME-Typ text/plain gefiltert:
<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>
Im folgenden Beispiel wird nach einem URI im Format https://developer.android.com/index.html gefiltert.
<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
Wenn Ihre Aktivität nach dem Intent ACTION_TECH_DISCOVERED filtert, müssen Sie eine XML-Ressourcendatei erstellen, in der die von Ihrer Aktivität unterstützten Technologien in einem tech-list-Satz angegeben sind. Ihre Aktivität gilt als Übereinstimmung, wenn eine tech-list-Gruppe eine Teilmenge der Technologien ist, die vom Tag unterstützt werden. Diese können Sie durch Aufrufen von getTechList() abrufen.
Wenn das gescannte Tag beispielsweise MifareClassic, NdefFormatable und NfcA unterstützt, muss dein tech-list-Satz alle drei, zwei oder eine der Technologien (und nichts anderes) angeben, damit deine Aktivität abgeglichen wird.
Im folgenden Beispiel werden alle Technologien definiert. Sie müssen die entfernen, die von Ihrem NFC-Tag nicht unterstützt werden. Speichern Sie diese Datei (Sie können sie beliebig benennen) im Ordner <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>
Sie können auch mehrere tech-list-Sätze angeben. Jeder der tech-list-Sätze wird unabhängig voneinander betrachtet. Ihre Aktivität wird als Übereinstimmung gewertet, wenn ein einzelner tech-list-Satz eine Teilmenge der von getTechList() zurückgegebenen Technologien ist. Dies bietet AND- und OR-Semantik für übereinstimmende Technologien. Im folgenden Beispiel werden Tags abgeglichen, die die NfcA- und Ndef-Technologien oder die NfcB- und Ndef-Technologien unterstützen können:
<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>
Geben Sie in der Datei AndroidManifest.xml die Ressourcendatei an, die Sie gerade im Element <meta-data> innerhalb des Elements <activity> erstellt haben, wie im folgenden Beispiel:
<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>
Weitere Informationen zum Arbeiten mit Tag-Technologien und dem Intent ACTION_TECH_DISCOVERED findest du im Dokument „Advanced NFC“ unter Working with Supported Tag Technologies.
ACTION_TAG_DISCOVERED
Hinweis: ACTION_TAG_DISCOVERED wird ab Android 17 (API-Level 37) eingestellt. Verwenden Sie stattdessen ACTION_NDEF_DISCOVERED oder ACTION_TECH_DISCOVERED.
Verwenden Sie den folgenden Intent-Filter, um nach ACTION_TAG_DISCOVERED zu filtern:
<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
Ab Android 16 wird beim Scannen von NFC-Tags, die Weblinks speichern (d. h. das URI-Schema ist „http://“ oder „https://“), der Intent ACTION_VIEW anstelle des Intents ACTION_NDEF_DISCOVERED ausgelöst. Ab Android 17 wird beim Scannen eines solchen Tags die Benachrichtigung „Link öffnen“ angezeigt. Der Intent ACTION_VIEW wird erst nach einer expliziten Nutzerinteraktion ausgelöst. Informationen zum Filtern nach ACTION_VIEW finden Sie unter this. Verwenden Sie Android app links, um Ihre App für die URL zu öffnen.
Informationen aus Intents abrufen
Wenn eine Aktivität aufgrund eines NFC-Intents gestartet wird, kannst du Informationen zum gescannten NFC-Tag aus dem Intent abrufen. Intents können je nach gescanntem Tag die folgenden Extras enthalten:
EXTRA_TAG(erforderlich): EinTag-Objekt, das das gescannte Tag darstellt.EXTRA_NDEF_MESSAGES(optional): Ein Array von NDEF-Nachrichten, die aus dem Tag geparst wurden. Dieses Extra ist fürACTION_NDEF_DISCOVERED-Intents obligatorisch.EXTRA_ID(optional): Die Low-Level-ID des Tags.
Prüfe, ob deine Aktivität mit einem der NFC-Intents gestartet wurde, um sicherzustellen, dass ein Tag gescannt wurde. Rufe dann die Extras aus dem Intent ab. Im folgenden Beispiel wird der Intent ACTION_NDEF_DISCOVERED geprüft und die NDEF-Nachrichten werden aus einem Intent-Extra abgerufen.
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. ... } } }
Alternativ können Sie ein Tag-Objekt aus dem Intent abrufen, das die Nutzlast enthält und es Ihnen ermöglicht, die Technologien des Tags aufzulisten:
Kotlin
val tag: Tag = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG)
Java
Tag tag = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG);
Gängige Typen von NDEF-Einträgen erstellen
In diesem Abschnitt wird beschrieben, wie Sie gängige Typen von NDEF-Einträgen erstellen, um Ihnen beim Schreiben auf NFC-Tags zu helfen. Ab Android 4.0 (API-Level 14) ist die Methode createUri() verfügbar, mit der du URI-Einträge automatisch erstellen kannst. Ab Android 4.1 (API-Level 16) sind createExternal() und createMime() verfügbar, mit denen du NDEF-Einträge für MIME- und externe Typen erstellen kannst. Verwende diese Hilfsmethoden nach Möglichkeit, um Fehler beim manuellen Erstellen von NDEF-Datensätzen zu vermeiden.
In diesem Abschnitt wird auch beschrieben, wie Sie den entsprechenden Intent-Filter für den Eintrag erstellen. Alle diese NDEF-Eintragsbeispiele sollten sich im ersten NDEF-Eintrag der NDEF-Nachricht befinden, die Sie in ein Tag schreiben.
TNF_ABSOLUTE_URI
Hinweis: Wir empfehlen, den Typ RTD_URI anstelle von TNF_ABSOLUTE_URI zu verwenden, da er effizienter ist.
So erstellen Sie einen TNF_ABSOLUTE_URI-NDEF-Eintrag:
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]);
Der Intent-Filter für den vorherigen NDEF-Eintrag würde so aussehen:
<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
Du hast folgende Möglichkeiten, einen TNF_MIME_MEDIA-NDEF-Eintrag zu erstellen:
Verwenden Sie die Methode 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")));
NdefRecord manuell erstellen:
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")));
Der Intent-Filter für den vorherigen NDEF-Eintrag würde so aussehen:
<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 mit RTD_TEXT
So erstellen Sie einen TNF_WELL_KNOWN-NDEF-Eintrag:
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; }
Der Intent-Filter für den vorherigen NDEF-Eintrag würde so aussehen:
<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 mit RTD_URI
Du hast folgende Möglichkeiten, einen TNF_WELL_KNOWN-NDEF-Eintrag zu erstellen:
Verwenden Sie die Methode createUri(String):
Kotlin
val rtdUriRecord1 = NdefRecord.createUri("https://example.com")
Java
NdefRecord rtdUriRecord1 = NdefRecord.createUri("https://example.com");
Verwenden Sie die Methode 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);
NdefRecord manuell erstellen:
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);
Der Intent-Filter für den vorherigen NDEF-Eintrag würde so aussehen:
<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
So erstellen Sie einen TNF_EXTERNAL_TYPE-NDEF-Eintrag:
Verwenden Sie die Methode 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);
NdefRecord manuell erstellen:
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);
Der Intent-Filter für den vorherigen NDEF-Eintrag würde so aussehen:
<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>
Verwenden Sie TNF_EXTERNAL_TYPE für allgemeinere NFC-Tag-Bereitstellungen, um sowohl Android- als auch Nicht-Android-Geräte besser zu unterstützen.
Hinweis: URNs für TNF_EXTERNAL_TYPE haben das kanonische Format urn:nfc:ext:example.com:externalType. In der RTD-Spezifikation des NFC-Forums wird jedoch festgelegt, dass der urn:nfc:ext:-Teil der URN im NDEF-Eintrag weggelassen werden muss. Sie müssen also nur die Domain (example.com im Beispiel) und den Typ (externalType im Beispiel) angeben, getrennt durch einen Doppelpunkt.
Beim Senden von TNF_EXTERNAL_TYPE konvertiert Android den urn:nfc:ext:example.com:externalType
-URN in einen vnd.android.nfc://ext/example.com:externalType-URI, der im Intent-Filter im Beispiel deklariert ist.
Android-App-Einträge
Ein Android Application Record (AAR) wurde in Android 4.0 (API-Level 14) eingeführt und bietet eine höhere Sicherheit, dass Ihre App gestartet wird, wenn ein NFC-Tag gescannt wird. Ein AAR enthält den Paketnamen einer Anwendung, die in einen NDEF-Eintrag eingebettet ist. Sie können jedem NDEF-Eintrag Ihrer NDEF-Nachricht einen AAR hinzufügen, da Android die gesamte NDEF-Nachricht nach AARs durchsucht. Wenn ein AAR gefunden wird, wird die Anwendung basierend auf dem Paketnamen im AAR gestartet. Wenn die App nicht auf dem Gerät vorhanden ist, wird Google Play gestartet, um die App herunterzuladen.
AARs sind nützlich, wenn Sie verhindern möchten, dass andere Anwendungen nach demselben Intent filtern und möglicherweise bestimmte von Ihnen bereitgestellte Tags verarbeiten. AARs werden aufgrund der Einschränkung des Paketnamens nur auf Anwendungsebene unterstützt und nicht auf Aktivitätsebene wie bei der Intent-Filterung. Wenn du einen Intent auf Aktivitätsebene verarbeiten möchtest, verwende Intent-Filter.
Wenn ein Tag einen AAR enthält, wird das Tag vom Tag-Versandsystem so versendet:
- Versuche, eine Aktivität wie gewohnt mit einem Intent-Filter zu starten. Wenn die Aktivität, die dem Intent entspricht, auch dem AAR entspricht, starten Sie die Aktivität.
- Wenn die Aktivität, die nach dem Intent filtert, nicht mit dem AAR übereinstimmt, wenn mehrere Aktivitäten den Intent verarbeiten können oder wenn keine Aktivität den Intent verarbeitet, wird die vom AAR angegebene Anwendung gestartet.
- Wenn keine Anwendung mit dem AAR gestartet werden kann, rufen Sie Google Play auf, um die Anwendung basierend auf dem AAR herunterzuladen.
Hinweis: Du kannst AARs und das Intent-Dispatch-System mit dem Vordergrund-Dispatch-System überschreiben. Dadurch hat eine Vordergrundaktivität Priorität, wenn ein NFC-Tag erkannt wird. Bei dieser Methode muss die Aktivität im Vordergrund sein, um AARs und das Intent-Dispatch-System zu überschreiben.
Wenn du trotzdem nach gescannten Tags filtern möchtest, die keinen AAR enthalten, kannst du Intent-Filter wie gewohnt deklarieren. Das ist nützlich, wenn deine Anwendung an anderen Tags interessiert ist, die keinen AAR enthalten. Beispielsweise möchten Sie vielleicht sicherstellen, dass Ihre Anwendung sowohl proprietäre Tags, die Sie bereitstellen, als auch allgemeine Tags, die von Drittanbietern bereitgestellt werden, verarbeitet. Beachten Sie, dass AARs nur für Geräte mit Android 4.0 oder höher gelten. Wenn Sie Tags bereitstellen, sollten Sie daher wahrscheinlich eine Kombination aus AARs und MIME-Typen/URIs verwenden, um möglichst viele Geräte zu unterstützen. Wenn du NFC-Tags bereitstellst, solltest du dir außerdem überlegen, wie du deine NFC-Tags schreiben möchtest, um die Unterstützung für die meisten Geräte (Android-Geräte und andere Geräte) zu ermöglichen. Dazu können Sie einen relativ eindeutigen MIME-Typ oder URI definieren, damit Anwendungen die Daten leichter unterscheiden können.
Android bietet eine einfache API zum Erstellen eines AAR, createApplicationRecord(). Sie müssen die AAR-Datei nur an einer beliebigen Stelle in NdefMessage einbetten. Sie sollten nicht den ersten Eintrag Ihrer NdefMessage verwenden, es sei denn, der AAR ist der einzige Eintrag in der NdefMessage. Das liegt daran, dass das Android-System den ersten Datensatz eines NdefMessage prüft, um den MIME-Typ oder URI des Tags zu ermitteln, der zum Erstellen eines Intents für Anwendungen zum Filtern verwendet wird. Der folgende Code zeigt, wie Sie eine AAR erstellen:
Kotlin
val msg = NdefMessage( arrayOf( ..., NdefRecord.createApplicationRecord("com.example.android.beam") ) )
Java
NdefMessage msg = new NdefMessage( new NdefRecord[] { ..., NdefRecord.createApplicationRecord("com.example.android.beam")} ); )
App-Zulassungsliste für das Scannen von NFC-Tags
Ab Android 16 werden Nutzer benachrichtigt, wenn eine App ihren ersten NFC-Intent zum Scannen von NFC-Tags erhält. Der Nutzer hat die Möglichkeit, der App in der Benachrichtigung zu verbieten, weiterhin nach NFC-Tags zu suchen.
- Apps können mit
NfcAdapter.isTagIntentAllowed()prüfen, ob der Nutzer der App erlaubt hat, NFC-Tags zu scannen. - Apps können den Nutzer auffordern, das Scannen von NFC-Tags wieder zuzulassen, indem sie den Intent
ACTION_CHANGE_TAG_INTENT_PREFERENCEsenden.
Hinweis: Die Zulassungsliste für Apps zum Scannen von NFC-Tags finden Sie unter Settings > Apps > Special app access > Launch via NFC.