W tym dokumencie opisujemy podstawowe zadania związane z NFC, które można wykonywać na Androidzie. Wyjaśnia, jak wysyłać i odbierać dane NFC w formie wiadomości NDEF, oraz opisuje interfejsy API platformy Androida, które obsługują te funkcje. Bardziej zaawansowane tematy, w tym omówienie pracy z danymi innymi niż NDEF, znajdziesz w artykule Zaawansowane NFC.
Odczytywanie danych NDEF z tagu NFC jest obsługiwane przez system wysyłania tagów, który analizuje wykryte tagi NFC, odpowiednio kategoryzuje dane i uruchamia aplikację, która jest zainteresowana skategoryzowanymi danymi. Aplikacja, która chce obsługiwać zeskanowany tag NFC, może zadeklarować filtr intencji i poprosić o obsługę danych.
system wysyłania tagów,
Urządzenia z Androidem zwykle szukają tagów NFC, gdy ekran jest odblokowany, chyba że komunikacja NFC jest wyłączona w menu Ustawienia urządzenia. Gdy urządzenie z Androidem wykryje tag NFC, najlepiej, aby najbardziej odpowiednia aktywność obsłużyła intencję bez pytania użytkownika, której aplikacji użyć. Urządzenia skanują tagi NFC z bardzo bliskiej odległości, więc jeśli użytkownik będzie musiał ręcznie wybrać aktywność, prawdopodobnie odsunie urządzenie od tagu i przerwie połączenie. Aby zapobiec wyświetlaniu selektora aktywności, należy tak opracować aktywność, aby obsługiwała tylko te tagi NFC, które są dla niej istotne.
Aby Ci w tym pomóc, Android udostępnia specjalny system wysyłania tagów, który analizuje zeskanowane tagi NFC, przetwarza je i próbuje znaleźć aplikacje, które mogą być zainteresowane zeskanowanymi danymi. W tym celu:
- analizowanie tagu NFC i określanie typu MIME lub identyfikatora URI, który identyfikuje ładunek danych w tagu;
- umieszczenie typu MIME lub identyfikatora URI oraz ładunku w intencji; Te 2 pierwsze kroki są opisane w sekcji Jak tagi NFC są mapowane na typy MIME i identyfikatory URI.
- Rozpoczyna aktywność na podstawie intencji. Zostało to opisane w artykule How NFC Tags are Dispatched to Applications (Jak tagi NFC są wysyłane do aplikacji).
Jak tagi NFC są mapowane na typy MIME i identyfikatory URI
Zanim zaczniesz pisać aplikacje NFC, musisz poznać różne rodzaje tagów NFC, dowiedzieć się, jak system wysyłania tagów analizuje tagi NFC i jakie specjalne zadania wykonuje, gdy wykryje wiadomość NDEF. Tagi NFC są dostępne w wielu różnych technologiach, a dane można na nich zapisywać na wiele różnych sposobów. Android zapewnia najlepszą obsługę standardu NDEF, który jest zdefiniowany przez NFC Forum.
Dane NDEF są umieszczane w wiadomości (NdefMessage), która zawiera co najmniej 1 rekord (NdefRecord). Każdy rekord NDEF musi być poprawnie sformatowany zgodnie ze specyfikacją typu rekordu, który chcesz utworzyć. Android obsługuje też inne typy tagów, które nie zawierają danych NDEF. Możesz z nimi pracować, używając klas w pakiecie android.nfc.tech. Więcej informacji o tych technologiach znajdziesz w temacie Zaawansowane NFC. Praca z innymi typami tagów wymaga napisania własnego stosu protokołów do komunikacji z tagami, dlatego zalecamy używanie NDEF, gdy jest to możliwe, aby ułatwić programowanie i zapewnić maksymalną obsługę urządzeń z Androidem.
Uwaga: aby pobrać pełne specyfikacje NDEF, wejdź na stronę NFC Forum Specifications & Application Documents i zapoznaj się z artykułem Creating common types of NDEF records, w którym znajdziesz przykłady tworzenia rekordów NDEF.
Teraz, gdy masz już pewną wiedzę na temat tagów NFC, w sekcjach poniżej znajdziesz bardziej szczegółowe informacje o tym, jak Android obsługuje tagi w formacie NDEF. Gdy urządzenie z Androidem skanuje tag NFC zawierający dane w formacie NDEF, analizuje wiadomość i próbuje określić typ MIME danych lub identyfikujący je identyfikator URI. W tym celu system odczytuje pierwszy element NdefRecord w NdefMessage, aby określić, jak interpretować całą wiadomość NDEF (wiadomość NDEF może zawierać wiele rekordów NDEF). W prawidłowo sformatowanym komunikacie NDEF pierwszy NdefRecord zawiera te pola:
- 3-bitowy TNF (Type Name Format)
- Wskazuje, jak interpretować pole typu o zmiennej długości. Prawidłowe wartości opisano w tabeli 1.
- Typ zmiennej długości
- Opisuje typ rekordu. Jeśli używasz
TNF_WELL_KNOWN, użyj tego pola, aby określić definicję typu rekordu (RTD). Prawidłowe wartości RTD są opisane w tabeli 2. - Identyfikator o zmiennej długości
- Unikalny identyfikator rekordu. To pole nie jest często używane, ale jeśli musisz jednoznacznie zidentyfikować tag, możesz utworzyć dla niego identyfikator.
- Ładunek o zmiennej długości
- Rzeczywisty ładunek danych, który chcesz odczytać lub zapisać. Komunikat NDEF może zawierać wiele rekordów NDEF, więc nie zakładaj, że cały ładunek znajduje się w pierwszym rekordzie NDEF komunikatu NDEF.
System wysyłania tagów używa pól TNF i typu, aby spróbować zmapować typ MIME lub identyfikator URI na wiadomość NDEF. Jeśli się powiedzie, informacje te zostaną umieszczone w intencji ACTION_NDEF_DISCOVERED wraz z rzeczywistym ładunkiem. Zdarzają się jednak przypadki, gdy system wysyłania tagów nie może określić typu danych na podstawie pierwszego rekordu NDEF. Dzieje się tak, gdy danych NDEF nie można zmapować na typ MIME lub identyfikator URI albo gdy tag NFC nie zawiera danych NDEF. W takich przypadkach obiekt Tag, który zawiera informacje o technologiach tagu i ładunku, jest umieszczany w intencji ACTION_TECH_DISCOVERED.
Tabela 1 opisuje, jak system wysyłania tagów mapuje pola TNF i typu na typy MIME lub identyfikatory URI. Opisuje też, których formatów TNF nie można zmapować na typ MIME ani identyfikator URI.
W takich przypadkach system wysyłania tagów powraca do ACTION_TECH_DISCOVERED.
Jeśli na przykład system wysyłania tagów napotka rekord typu TNF_ABSOLUTE_URI, mapuje pole typu o zmiennej długości tego rekordu na identyfikator URI. System wysyłania tagów umieszcza ten identyfikator URI w polu danych intencji ACTION_NDEF_DISCOVERED wraz z innymi informacjami o tagu, takimi jak ładunek. Jeśli jednak napotka rekord typu TNF_UNKNOWN, utworzy intencję, która zawiera technologie tagu.
Tabela 1. Obsługiwane typy TNF i ich mapowania
| Type Name Format (TNF) | Mapowanie |
|---|---|
TNF_ABSOLUTE_URI |
Identyfikator URI oparty na polu typu. |
TNF_EMPTY |
W przypadku braku danych używana jest wartość ACTION_TECH_DISCOVERED. |
TNF_EXTERNAL_TYPE |
Identyfikator URI oparty na identyfikatorze URN w polu typu. Identyfikator URN jest zakodowany w polu typu NDEF w skróconej formie: <domain_name>:<service_name>.
Android mapuje to na identyfikator URI w formacie: vnd.android.nfc://ext/<domain_name>:<service_name>. |
TNF_MIME_MEDIA |
Typ MIME na podstawie pola typu. |
TNF_UNCHANGED |
Nieprawidłowa wartość w pierwszym rekordzie, więc przyjmuje wartość ACTION_TECH_DISCOVERED. |
TNF_UNKNOWN |
W przypadku braku danych używana jest wartość ACTION_TECH_DISCOVERED. |
TNF_WELL_KNOWN |
Typ MIME lub identyfikator URI w zależności od definicji typu rekordu (RTD), którą ustawiasz w polu typu. Więcej informacji o dostępnych RTD i ich mapowaniach znajdziesz w Tabeli 2. |
Tabela 2. Obsługiwane typy RTD dla TNF_WELL_KNOWN i ich mapowania
| Definicja typu rekordu (RTD) | Mapowanie |
|---|---|
RTD_ALTERNATIVE_CARRIER |
W przypadku braku danych używana jest wartość ACTION_TECH_DISCOVERED. |
RTD_HANDOVER_CARRIER |
W przypadku braku danych używana jest wartość ACTION_TECH_DISCOVERED. |
RTD_HANDOVER_REQUEST |
W przypadku braku danych używana jest wartość ACTION_TECH_DISCOVERED. |
RTD_HANDOVER_SELECT |
W przypadku braku danych używana jest wartość ACTION_TECH_DISCOVERED. |
RTD_SMART_POSTER |
Identyfikator URI oparty na analizie ładunku. |
RTD_TEXT |
Typ MIME: text/plain. |
RTD_URI |
Identyfikator URI oparty na ładunku. |
Jak tagi NFC są wysyłane do aplikacji
Gdy system wysyłania tagów zakończy tworzenie intencji, która zawiera tag NFC i informacje umożliwiające identyfikację, wysyła intencję do zainteresowanej aplikacji, która ją filtruje. Jeśli intencję może obsłużyć więcej niż 1 aplikacja, wyświetli się selektor aktywności, aby użytkownik mógł wybrać aktywność. System wysyłania tagów definiuje 3 intencje, które są wymienione w kolejności od najwyższego do najniższego priorytetu:
-
ACTION_NDEF_DISCOVERED: ta intencja służy do uruchamiania aktywności, gdy zostanie zeskanowany tag zawierający ładunek NDEF i jest on rozpoznanego typu. Jest to intencja o najwyższym priorytecie, a system wysyłania tagów próbuje uruchomić aktywność z tą intencją przed innymi intencjami, gdy tylko jest to możliwe.Uwaga: od Androida 16 skanowanie tagów NFC, które przechowują linki internetowe (czyli schemat URI to „http://” lub „https://”), wywołuje intencję
ACTION_VIEWzamiast intencjiACTION_NDEF_DISCOVERED. Począwszy od Androida 17, zeskanowanie takiego tagu powoduje wyświetlenie powiadomienia „Otwórz link”, które wymaga wyraźnej interakcji użytkownika, aby wywołać intencjęACTION_VIEW. ACTION_TECH_DISCOVERED: jeśli nie ma zarejestrowanych aktywności do obsługi intencjiACTION_NDEF_DISCOVERED, system wysyłania tagów próbuje uruchomić aplikację z tą intencją. Ta intencja jest też uruchamiana bezpośrednio (bez wcześniejszego uruchamianiaACTION_NDEF_DISCOVERED), jeśli skanowany tag zawiera dane NDEF, których nie można zmapować na typ MIME lub identyfikator URI, lub jeśli tag nie zawiera danych NDEF, ale jest zgodny ze znaną technologią tagów.ACTION_TAG_DISCOVERED: ta intencja jest uruchamiana, jeśli żadne aktywności nie obsługują intencjiACTION_NDEF_DISCOVEREDaniACTION_TECH_DISCOVERED.
Podstawowy sposób działania systemu wysyłania tagów jest następujący:
- Spróbuj rozpocząć aktywność z intencją utworzoną przez system wysyłania tagów podczas analizowania tagu NFC (
ACTION_NDEF_DISCOVEREDlubACTION_TECH_DISCOVERED). - Jeśli żadna aktywność nie filtruje tej intencji, spróbuj uruchomić aktywność z następną intencją o niższym priorytecie (
ACTION_TECH_DISCOVEREDlubACTION_TAG_DISCOVERED), dopóki aplikacja nie przefiltruje intencji lub system wysyłania tagów nie wypróbuje wszystkich możliwych intencji. - Jeśli żadna aplikacja nie filtruje żadnej intencji, nie rób nic.
Jeśli to możliwe, pracuj z wiadomościami NDEF i intencją ACTION_NDEF_DISCOVERED, ponieważ jest ona najbardziej szczegółowa z tych 3 opcji. Ta intencja pozwala uruchomić aplikację w bardziej odpowiednim momencie niż pozostałe 2 intencje, co zapewnia użytkownikom lepsze wrażenia.
Poproś o dostęp do NFC w pliku manifestu Androida
Zanim uzyskasz dostęp do sprzętu NFC urządzenia i będziesz prawidłowo obsługiwać intencje NFC, zadeklaruj te elementy w pliku AndroidManifest.xml:
- Element NFC
<uses-permission>umożliwiający dostęp do sprzętu NFC:<uses-permission android:name="android.permission.NFC" />
- Od Androida 17 (interfejs API na poziomie 37), aby aktywność mogła wysłać intencję NFC, jeśli aplikacja jest kierowana na pakiet SDK >
Build.VERSION_CODES.BAKLAVA, musi być chroniona uprawnieniemandroid.permission.DISPATCH_NFC_MESSAGE. Dzięki temu tylko usługa systemowa NFC może wysyłać intencje do Twojej aktywności. Dodatkowo system nie będzie wysyłać intencji NFC do aplikacji, które są w stanie zatrzymania (np. jeśli aplikacja nigdy nie została uruchomiona przez użytkownika lub została wymuszenie zatrzymana).<activity android:name=".MyActivity" android:exported="true" android:permission="android.permission.DISPATCH_NFC_MESSAGE"> ... </activity>
- Minimalna wersja pakietu SDK, którą może obsługiwać Twoja aplikacja. Interfejs API na poziomie 9 obsługuje tylko ograniczone wysyłanie tagów za pomocą
ACTION_TAG_DISCOVEREDi zapewnia dostęp do wiadomości NDEF tylko za pomocą dodatkuEXTRA_NDEF_MESSAGES. Żadne inne właściwości tagu ani operacje wejścia/wyjścia nie są dostępne. Poziom interfejsu API 10 obejmuje kompleksową obsługę odczytu i zapisu oraz przesyłanie NDEF na pierwszym planie, a poziom interfejsu API 14 zapewnia dodatkowe wygodne metody tworzenia rekordów NDEF.<uses-sdk android:minSdkVersion="10"/> - Element
uses-feature, dzięki któremu aplikacja będzie widoczna w Google Play tylko na urządzeniach z modułem NFC:<uses-feature android:name="android.hardware.nfc" android:required="true" />
Jeśli aplikacja korzysta z funkcji NFC, ale nie jest ona dla niej kluczowa, możesz pominąć element
uses-featurei sprawdzić dostępność NFC w czasie działania, sprawdzając, czygetDefaultAdapter()ma wartośćnull.
Filtrowanie intencji NFC
Aby uruchomić aplikację, gdy zostanie zeskanowany tag NFC, który chcesz obsłużyć, aplikacja może filtrować 1, 2 lub wszystkie 3 intencje NFC w pliku manifestu Androida. Zwykle jednak najlepiej jest filtrować intencję ACTION_NDEF_DISCOVERED, aby mieć największą kontrolę nad tym, kiedy aplikacja się uruchamia. Intencja ACTION_TECH_DISCOVERED jest zastępcza dla ACTION_NDEF_DISCOVERED, gdy żadna aplikacja nie filtruje ACTION_NDEF_DISCOVERED lub gdy ładunek nie jest NDEF. Filtrowanie według ACTION_TAG_DISCOVERED jest zwykle zbyt ogólne. Wiele aplikacji będzie filtrować pod kątem ACTION_NDEF_DISCOVERED lub ACTION_TECH_DISCOVERED przed ACTION_TAG_DISCOVERED, więc istnieje małe prawdopodobieństwo, że Twoja aplikacja się uruchomi. ACTION_TAG_DISCOVERED jest dostępna tylko w ostateczności dla aplikacji, które mają filtrować w przypadkach, gdy nie są zainstalowane żadne inne aplikacje do obsługi intencji ACTION_NDEF_DISCOVERED lub ACTION_TECH_DISCOVERED.
Ponieważ wdrożenia tagów NFC różnią się i często nie masz nad nimi kontroli, nie zawsze jest to możliwe. Dlatego w razie potrzeby możesz użyć 2 pozostałych intencji. Jeśli masz kontrolę nad typami tagów i zapisywanych danych, zalecamy używanie formatu NDEF do formatowania tagów. W sekcjach poniżej opisujemy, jak filtrować dane według poszczególnych typów intencji.
ACTION_NDEF_DISCOVERED
Aby filtrować intencje ACTION_NDEF_DISCOVERED, zadeklaruj filtr intencji wraz z typem danych, które chcesz filtrować. W tym przykładzie odfiltrowywane są intencje ACTION_NDEF_DISCOVERED z typem MIME 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>
W tym przykładzie filtrowany jest identyfikator URI w formacie 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
Jeśli aktywność filtruje intencję ACTION_TECH_DISCOVERED,
musisz utworzyć plik zasobów XML, który określa technologie obsługiwane przez aktywność
w zbiorze tech-list. Twoja aktywność jest uznawana za dopasowanie, jeśli zbiór tech-list jest podzbiorem technologii obsługiwanych przez tag, który można uzyskać, wywołując getTechList().
Jeśli na przykład skanowany tag obsługuje MifareClassic, NdefFormatable i NfcA, zbiór tech-list musi określać wszystkie 3, 2 lub 1 z tych technologii (i żadnej innej), aby aktywność została dopasowana.
Poniższy przykład definiuje wszystkie technologie. Musisz usunąć te, które nie są obsługiwane przez tag NFC. Zapisz ten plik (możesz go nazwać, jak chcesz) w folderze <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>
Możesz też określić wiele zestawów tech-list. Każdy z zestawów tech-list jest rozpatrywany niezależnie, a Twoja aktywność jest uznawana za dopasowanie, jeśli dowolny pojedynczy zestaw tech-list jest podzbiorem technologii zwracanych przez getTechList(). Zapewnia to semantykę AND i OR dla technologii dopasowywania. Ten przykład pasuje do tagów, które obsługują technologie NfcA i Ndef lub NfcB i 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>
W pliku AndroidManifest.xml określ utworzony plik zasobów w elemencie <meta-data> wewnątrz elementu <activity>, jak w tym przykładzie:
<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>
Więcej informacji o korzystaniu z technologii tagów i intencji ACTION_TECH_DISCOVERED znajdziesz w sekcji Working with Supported Tag Technologies (Praca z obsługiwanymi technologiami tagów) w dokumencie Advanced NFC (Zaawansowane NFC).
ACTION_TAG_DISCOVERED
Uwaga: od Androida 17 (poziom interfejsu API 37) metoda ACTION_TAG_DISCOVERED jest wycofana. Użyj w zamian zasady ACTION_NDEF_DISCOVERED lub ACTION_TECH_DISCOVERED.
Aby filtrować według ACTION_TAG_DISCOVERED, użyj tego filtra intencji:
<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
Począwszy od Androida 16 skanowanie tagów NFC, które przechowują linki internetowe (czyli schemat URI to „http://” lub „https://”), wywołuje intencję ACTION_VIEW zamiast intencji ACTION_NDEF_DISCOVERED. Począwszy od Androida 17, zeskanowanie takiego tagu powoduje wyświetlenie powiadomienia „Otwórz link”, które wymaga wyraźnej interakcji użytkownika, aby wywołać intencję ACTION_VIEW. Aby filtrować według ACTION_VIEW, zapoznaj się z this. Użyj Android app links, aby otworzyć aplikację dla adresu URL.
Uzyskiwanie informacji z intencji
Jeśli aktywność rozpoczyna się z powodu intencji NFC, możesz uzyskać informacje o zeskanowanym tagu NFC z intencji. Intencje mogą zawierać te dodatkowe informacje w zależności od zeskanowanego tagu:
EXTRA_TAG(wymagany): obiektTagreprezentujący zeskanowany tag.EXTRA_NDEF_MESSAGES(opcjonalnie): tablica wiadomości NDEF przeanalizowanych z tagu. Ten dodatek jest obowiązkowy w przypadku intencjiACTION_NDEF_DISCOVERED.EXTRA_ID(opcjonalnie): identyfikator tagu niskiego poziomu.
Aby uzyskać te dodatkowe informacje, sprawdź, czy aktywność została uruchomiona z jedną z intencji NFC, aby upewnić się, że tag został zeskanowany, a następnie pobierz dodatkowe informacje z intencji. Ten przykładowy kod sprawdza intencję ACTION_NDEF_DISCOVERED i pobiera wiadomości NDEF z dodatku intencji.
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. ... } } }
Możesz też uzyskać obiekt Tag z intencji, który będzie zawierać ładunek i umożliwi wyliczenie technologii tagu:
Kotlin
val tag: Tag = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG)
Java
Tag tag = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG);
Tworzenie typowych rodzajów rekordów NDEF
W tej sekcji opisano, jak tworzyć typowe rodzaje rekordów NDEF, aby ułatwić zapisywanie na tagach NFC. Od Androida 4.0 (interfejs API na poziomie 14) dostępna jest metoda createUri(), która pomaga automatycznie tworzyć rekordy URI. Od Androida 4.1 (API na poziomie 16) dostępne są metody createExternal() i createMime(), które ułatwiają tworzenie rekordów NDEF typu MIME i typu zewnętrznego. W miarę możliwości używaj tych metod pomocniczych, aby uniknąć błędów podczas ręcznego tworzenia rekordów NDEF.
W tej sekcji opisano też, jak utworzyć odpowiedni filtr intencji dla rekordu. Wszystkie te przykłady rekordów NDEF powinny znajdować się w pierwszym rekordzie NDEF wiadomości NDEF, którą zapisujesz w tagu.
TNF_ABSOLUTE_URI
Uwaga: zalecamy używanie typu RTD_URI zamiast TNF_ABSOLUTE_URI, ponieważ jest on bardziej wydajny.
Rekord NDEF TNF_ABSOLUTE_URI możesz utworzyć w ten sposób:
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]);
Filtr intencji dla poprzedniego rekordu NDEF wyglądałby tak:
<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
Rekord NDEF TNF_MIME_MEDIA możesz utworzyć na te sposoby:
Używanie metody 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")));
Ręczne tworzenie NdefRecord:
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")));
Filtr intencji dla poprzedniego rekordu NDEF wyglądałby tak:
<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 z RTD_TEXT
Rekord NDEF TNF_WELL_KNOWN możesz utworzyć w ten sposób:
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; }
Filtr intencji dla poprzedniego rekordu NDEF wyglądałby tak:
<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 z RTD_URI
Rekord NDEF TNF_WELL_KNOWN możesz utworzyć na te sposoby:
Używanie metody createUri(String):
Kotlin
val rtdUriRecord1 = NdefRecord.createUri("https://example.com")
Java
NdefRecord rtdUriRecord1 = NdefRecord.createUri("https://example.com");
Używanie metody 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);
Ręczne tworzenie NdefRecord:
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);
Filtr intencji dla poprzedniego rekordu NDEF wyglądałby tak:
<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
Rekord NDEF TNF_EXTERNAL_TYPE możesz utworzyć na te sposoby:
Używanie metody 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);
Ręczne tworzenie NdefRecord:
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);
Filtr intencji dla poprzedniego rekordu NDEF wyglądałby tak:
<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>
Używaj TNF_EXTERNAL_TYPE w przypadku bardziej ogólnych wdrożeń tagów NFC, aby lepiej obsługiwać zarówno urządzenia z Androidem, jak i urządzenia bez Androida.
Uwaga: nazwy URN dla TNF_EXTERNAL_TYPE mają format kanoniczny: urn:nfc:ext:example.com:externalType, ale specyfikacja NFC Forum RTD deklaruje, że część urn:nfc:ext: nazwy URN musi zostać pominięta w rekordzie NDEF. Wystarczy więc podać domenę (w przykładzie: example.com) i typ (w przykładzie: externalType) rozdzielone dwukropkiem.
Podczas wysyłania TNF_EXTERNAL_TYPE Android konwertuje identyfikator URN urn:nfc:ext:example.com:externalType
na identyfikator URI vnd.android.nfc://ext/example.com:externalType, który jest zadeklarowany w przykładowym filtrze intencji.
Rekordy aplikacji na Androida
Wprowadzony w Androidzie 4.0 (API na poziomie 14) rekord aplikacji na Androida (AAR) daje większą pewność, że aplikacja zostanie uruchomiona po zeskanowaniu tagu NFC. AAR zawiera nazwę pakietu aplikacji umieszczoną w rekordzie NDEF. Możesz dodać AAR do dowolnego rekordu NDEF w wiadomości NDEF, ponieważ Android wyszukuje AAR w całej wiadomości NDEF. Jeśli znajdzie rekord AAR, uruchamia aplikację na podstawie nazwy pakietu w rekordzie AAR. Jeśli aplikacja nie jest zainstalowana na urządzeniu, uruchamia się Google Play, aby ją pobrać.
Reguły AAR są przydatne, jeśli chcesz uniemożliwić innym aplikacjom filtrowanie pod kątem tej samej intencji i potencjalne obsługiwanie określonych tagów, które zostały przez Ciebie wdrożone. Ze względu na ograniczenie dotyczące nazwy pakietu linki aplikacji na Androida są obsługiwane tylko na poziomie aplikacji, a nie na poziomie Activity, jak w przypadku filtru intencji. Jeśli chcesz obsługiwać intencję na poziomie aktywności, użyj filtrów intencji.
Jeśli tag zawiera AAR, system wysyłania tagów wysyła go w następujący sposób:
- Spróbuj uruchomić aktywność, używając filtra intencji w normalny sposób. Jeśli aktywność, która pasuje do intencji, pasuje też do AAR, uruchom aktywność.
- Jeśli aktywność, która filtruje intencję, nie pasuje do AAR, jeśli wiele aktywności może obsłużyć intencję lub jeśli żadna aktywność nie obsługuje intencji, uruchom aplikację określoną przez AAR.
- Jeśli nie można uruchomić żadnej aplikacji za pomocą AAR, przejdź do Google Play, aby pobrać aplikację na podstawie AAR.
Uwaga: możesz zastąpić AAR i system wysyłania intencji systemem wysyłania na pierwszym planie, który umożliwia nadanie priorytetu aktywności na pierwszym planie po wykryciu tagu NFC. W przypadku tej metody aktywność musi być na pierwszym planie, aby zastąpić AAR i system wysyłania intencji.
Jeśli nadal chcesz filtrować zeskanowane tagi, które nie zawierają AAR, możesz zadeklarować filtry intencji w normalny sposób. Jest to przydatne, jeśli aplikacja jest zainteresowana innymi tagami, które nie zawierają AAR. Możesz na przykład chcieć mieć pewność, że Twoja aplikacja obsługuje zarówno zastrzeżone tagi, które wdrażasz, jak i ogólne tagi wdrażane przez osoby trzecie. Pamiętaj, że rekordy AAR są przeznaczone dla urządzeń z Androidem 4.0 lub nowszym, więc podczas wdrażania tagów najlepiej używać kombinacji rekordów AAR i typów MIME lub identyfikatorów URI, aby zapewnić obsługę jak największej liczby urządzeń. Dodatkowo podczas wdrażania tagów NFC zastanów się, jak chcesz je zapisać, aby zapewnić obsługę jak największej liczby urządzeń (z Androidem i innych). Możesz to zrobić, definiując względnie unikalny typ MIME lub identyfikator URI, aby ułatwić aplikacjom rozróżnianie.
Android udostępnia prosty interfejs API do tworzenia AAR:
createApplicationRecord(). Wystarczy, że umieścisz kod AAR w dowolnym miejscu w pliku NdefMessage. Nie chcesz używać pierwszego rekordu NdefMessage, chyba że rekord AAR jest jedynym rekordem w NdefMessage. Dzieje się tak, ponieważ system Android sprawdza pierwszy rekord NdefMessage, aby określić typ MIME lub identyfikator URI tagu, który jest używany do tworzenia intencji do filtrowania przez aplikacje. Poniższy kod pokazuje, jak utworzyć 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 dozwolonych aplikacji do skanowania tagów NFC
Od Androida 16 użytkownicy są powiadamiani, gdy aplikacja otrzyma pierwszą intencję NFC do skanowania tagów NFC. W powiadomieniu użytkownik może wybrać opcję, która uniemożliwi aplikacji dalsze skanowanie tagów NFC.
- Aplikacje mogą sprawdzać, czy użytkownik zezwolił im na skanowanie tagów NFC, za pomocą metody
NfcAdapter.isTagIntentAllowed(). - Aplikacje mogą poprosić użytkownika o ponowne zezwolenie na skanowanie tagów NFC, wysyłając intencję
ACTION_CHANGE_TAG_INTENT_PREFERENCE.
Uwaga: lista dozwolonych aplikacji do skanowania tagów NFC jest dostępna w sekcji Settings > Apps > Special app access > Launch via NFC.