NfcAdapter
public
final
class
NfcAdapter
extends Object
java.lang.Object | |
↳ | android.nfc.NfcAdapter |
Represents the local NFC adapter.
Use the helper getDefaultAdapter(android.content.Context)
to get the default NFC
adapter for this Android device.
Developer Guides
For more information about using NFC, read the Near Field Communication developer guide.
To perform basic file sharing between devices, read Sharing Files with NFC.
Summary
Nested classes | |
---|---|
interface |
NfcAdapter.CreateBeamUrisCallback
This interface was deprecated in API level 29. this feature is removed. File sharing can work using other technology like Bluetooth. |
interface |
NfcAdapter.CreateNdefMessageCallback
This interface was deprecated in API level 29. this feature is removed. File sharing can work using other technology like Bluetooth. |
interface |
NfcAdapter.OnNdefPushCompleteCallback
This interface was deprecated in API level 29. this feature is removed. File sharing can work using other technology like Bluetooth. |
interface |
NfcAdapter.OnTagRemovedListener
A callback that is invoked when a tag is removed from the field. |
interface |
NfcAdapter.ReaderCallback
A callback to be invoked when the system finds a tag while the foreground activity is operating in reader mode. |
Public methods | |
---|---|
void
|
disableForegroundDispatch(Activity activity)
Disable foreground dispatch to the given activity. |
void
|
disableReaderMode(Activity activity)
Restore the NFC adapter to normal mode of operation: supporting peer-to-peer (Android Beam), card emulation, and polling for all supported tag technologies. |
void
|
enableForegroundDispatch(Activity activity, PendingIntent intent, IntentFilter[] filters, String[][] techLists)
Enable foreground dispatch to the given Activity. |
void
|
enableReaderMode(Activity activity, NfcAdapter.ReaderCallback callback, int flags, Bundle extras)
Limit the NFC controller to reader mode while this Activity is in the foreground. |
static
NfcAdapter
|
getDefaultAdapter(Context context)
Helper to get the default NFC Adapter. |
NfcAntennaInfo
|
getNfcAntennaInfo()
Returns information regarding Nfc antennas on the device such as their relative positioning on the device. |
boolean
|
ignore(Tag tag, int debounceMs, NfcAdapter.OnTagRemovedListener tagRemovedListener, Handler handler)
Signals that you are no longer interested in communicating with an NFC tag for as long as it remains in range. |
boolean
|
isEnabled()
Return true if this NFC Adapter has any features enabled. |
boolean
|
isSecureNfcEnabled()
Checks Secure NFC feature is enabled. |
boolean
|
isSecureNfcSupported()
Checks if the device supports Secure NFC functionality. |
Inherited methods | |
---|---|
Constants
ACTION_ADAPTER_STATE_CHANGED
public static final String ACTION_ADAPTER_STATE_CHANGED
Broadcast Action: The state of the local NFC adapter has been changed.
For example, NFC has been turned on or off.
Always contains the extra field EXTRA_ADAPTER_STATE
Constant Value: "android.nfc.action.ADAPTER_STATE_CHANGED"
ACTION_NDEF_DISCOVERED
public static final String ACTION_NDEF_DISCOVERED
Intent to start an activity when a tag with NDEF payload is discovered.
The system inspects the first NdefRecord
in the first NdefMessage
and
looks for a URI, SmartPoster, or MIME record. If a URI or SmartPoster record is found the
intent will contain the URI in its data field. If a MIME record is found the intent will
contain the MIME type in its type field. This allows activities to register
IntentFilter
s targeting specific content on tags. Activities should register the
most specific intent filters possible to avoid the activity chooser dialog, which can
disrupt the interaction with the tag as the user interacts with the screen.
If the tag has an NDEF payload this intent is started before
ACTION_TECH_DISCOVERED
. If any activities respond to this intent neither
ACTION_TECH_DISCOVERED
or ACTION_TAG_DISCOVERED
will be started.
The MIME type or data URI of this intent are normalized before dispatch - so that MIME, URI scheme and URI host are always lower-case.
Constant Value: "android.nfc.action.NDEF_DISCOVERED"
ACTION_PREFERRED_PAYMENT_CHANGED
public static final String ACTION_PREFERRED_PAYMENT_CHANGED
Broadcast Action: Intent to notify if the preferred payment service changed.
This intent will only be sent to the application has requested permission for
Manifest.permission.NFC_PREFERRED_PAYMENT_INFO
and if the application
has the necessary access to Secure Element which witnessed the particular event.
Requires Manifest.permission.NFC_PREFERRED_PAYMENT_INFO
Constant Value: "android.nfc.action.PREFERRED_PAYMENT_CHANGED"
ACTION_TAG_DISCOVERED
public static final String ACTION_TAG_DISCOVERED
Intent to start an activity when a tag is discovered.
This intent will not be started when a tag is discovered if any activities respond to
ACTION_NDEF_DISCOVERED
or ACTION_TECH_DISCOVERED
for the current tag.
Constant Value: "android.nfc.action.TAG_DISCOVERED"
ACTION_TECH_DISCOVERED
public static final String ACTION_TECH_DISCOVERED
Intent to start an activity when a tag is discovered and activities are registered for the specific technologies on the tag.
To receive this intent an activity must include an intent filter
for this action and specify the desired tech types in a
manifest meta-data
entry. Here is an example manfiest entry:
<activity android:name=".nfc.TechFilter" android:label="NFC/TechFilter"> <!-- Add a technology filter --> <intent-filter> <action android:name="android.nfc.action.TECH_DISCOVERED" /> </intent-filter> <meta-data android:name="android.nfc.action.TECH_DISCOVERED" android:resource="@xml/filter_nfc" /> </activity>
The meta-data XML file should contain one or more tech-list
entries
each consisting or one or more tech
entries. The tech
entries refer
to the qualified class name implementing the technology, for example "android.nfc.tech.NfcA".
A tag matches if any of the
tech-list
sets is a subset of Tag.getTechList()
. Each
of the tech-list
s is considered independently and the
activity is considered a match is any single tech-list
matches the tag that was
discovered. This provides AND and OR semantics for filtering desired techs. Here is an
example that will match any tag using NfcF
or any tag using NfcA
,
MifareClassic
, and Ndef
:
<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2"> <!-- capture anything using NfcF --> <tech-list> <tech>android.nfc.tech.NfcF</tech> </tech-list> <!-- OR --> <!-- capture all MIFARE Classics with NDEF payloads --> <tech-list> <tech>android.nfc.tech.NfcA</tech> <tech>android.nfc.tech.MifareClassic</tech> <tech>android.nfc.tech.Ndef</tech> </tech-list> </resources>
This intent is started after ACTION_NDEF_DISCOVERED
and before
ACTION_TAG_DISCOVERED
. If any activities respond to ACTION_NDEF_DISCOVERED
this intent will not be started. If any activities respond to this intent
ACTION_TAG_DISCOVERED
will not be started.
Constant Value: "android.nfc.action.TECH_DISCOVERED"
ACTION_TRANSACTION_DETECTED
public static final String ACTION_TRANSACTION_DETECTED
Broadcast Action: Intent to notify an application that a transaction event has occurred on the Secure Element.
This intent will only be sent if the application has requested permission for
Manifest.permission.NFC_TRANSACTION_EVENT
and if the application has the
necessary access to Secure Element which witnessed the particular event.
Requires Manifest.permission.NFC_TRANSACTION_EVENT
Constant Value: "android.nfc.action.TRANSACTION_DETECTED"
EXTRA_ADAPTER_STATE
public static final String EXTRA_ADAPTER_STATE
Used as an int extra field in ACTION_ADAPTER_STATE_CHANGED
intents to request the current power state. Possible values are:
STATE_OFF
,
STATE_TURNING_ON
,
STATE_ON
,
STATE_TURNING_OFF
,
Constant Value: "android.nfc.extra.ADAPTER_STATE"
EXTRA_AID
public static final String EXTRA_AID
Mandatory byte[] extra field in ACTION_TRANSACTION_DETECTED
Constant Value: "android.nfc.extra.AID"
EXTRA_DATA
public static final String EXTRA_DATA
Optional byte[] extra field in ACTION_TRANSACTION_DETECTED
Constant Value: "android.nfc.extra.DATA"
EXTRA_ID
public static final String EXTRA_ID
Optional extra containing a byte array containing the ID of the discovered tag for
the ACTION_NDEF_DISCOVERED
, ACTION_TECH_DISCOVERED
, and
ACTION_TAG_DISCOVERED
intents.
Constant Value: "android.nfc.extra.ID"
EXTRA_NDEF_MESSAGES
public static final String EXTRA_NDEF_MESSAGES
Extra containing an array of NdefMessage
present on the discovered tag.
This extra is mandatory for ACTION_NDEF_DISCOVERED
intents,
and optional for ACTION_TECH_DISCOVERED
, and
ACTION_TAG_DISCOVERED
intents.
When this extra is present there will always be at least one
NdefMessage
element. Most NDEF tags have only one NDEF message,
but we use an array for future compatibility.
Constant Value: "android.nfc.extra.NDEF_MESSAGES"
EXTRA_PREFERRED_PAYMENT_CHANGED_REASON
public static final String EXTRA_PREFERRED_PAYMENT_CHANGED_REASON
Mandatory String extra field in ACTION_PREFERRED_PAYMENT_CHANGED
Indicates the condition when trigger this event. Possible values are:
PREFERRED_PAYMENT_LOADED
,
PREFERRED_PAYMENT_CHANGED
,
PREFERRED_PAYMENT_UPDATED
,
Constant Value: "android.nfc.extra.PREFERRED_PAYMENT_CHANGED_REASON"
EXTRA_READER_PRESENCE_CHECK_DELAY
public static final String EXTRA_READER_PRESENCE_CHECK_DELAY
Int Extra for use with enableReaderMode(android.app.Activity, android.nfc.NfcAdapter.ReaderCallback, int, android.os.Bundle)
.
Setting this integer extra allows the calling application to specify the delay that the platform will use for performing presence checks on any discovered tag.
Constant Value: "presence"
EXTRA_SECURE_ELEMENT_NAME
public static final String EXTRA_SECURE_ELEMENT_NAME
Mandatory String extra field in ACTION_TRANSACTION_DETECTED
Indicates the Secure Element on which the transaction occurred.
eSE1...eSEn for Embedded Secure Elements, SIM1...SIMn for UICC, etc.
Constant Value: "android.nfc.extra.SECURE_ELEMENT_NAME"
EXTRA_TAG
public static final String EXTRA_TAG
Mandatory extra containing the Tag
that was discovered for the
ACTION_NDEF_DISCOVERED
, ACTION_TECH_DISCOVERED
, and
ACTION_TAG_DISCOVERED
intents.
Constant Value: "android.nfc.extra.TAG"
FLAG_READER_NFC_A
public static final int FLAG_READER_NFC_A
Flag for use with enableReaderMode(android.app.Activity, android.nfc.NfcAdapter.ReaderCallback, int, android.os.Bundle)
.
Setting this flag enables polling for Nfc-A technology.
Constant Value: 1 (0x00000001)
FLAG_READER_NFC_B
public static final int FLAG_READER_NFC_B
Flag for use with enableReaderMode(android.app.Activity, android.nfc.NfcAdapter.ReaderCallback, int, android.os.Bundle)
.
Setting this flag enables polling for Nfc-B technology.
Constant Value: 2 (0x00000002)
FLAG_READER_NFC_BARCODE
public static final int FLAG_READER_NFC_BARCODE
Flag for use with enableReaderMode(android.app.Activity, android.nfc.NfcAdapter.ReaderCallback, int, android.os.Bundle)
.
Setting this flag enables polling for NfcBarcode technology.
Constant Value: 16 (0x00000010)
FLAG_READER_NFC_F
public static final int FLAG_READER_NFC_F
Flag for use with enableReaderMode(android.app.Activity, android.nfc.NfcAdapter.ReaderCallback, int, android.os.Bundle)
.
Setting this flag enables polling for Nfc-F technology.
Constant Value: 4 (0x00000004)
FLAG_READER_NFC_V
public static final int FLAG_READER_NFC_V
Flag for use with enableReaderMode(android.app.Activity, android.nfc.NfcAdapter.ReaderCallback, int, android.os.Bundle)
.
Setting this flag enables polling for Nfc-V (ISO15693) technology.
Constant Value: 8 (0x00000008)
FLAG_READER_NO_PLATFORM_SOUNDS
public static final int FLAG_READER_NO_PLATFORM_SOUNDS
Flag for use with enableReaderMode(android.app.Activity, android.nfc.NfcAdapter.ReaderCallback, int, android.os.Bundle)
.
Setting this flag allows the caller to prevent the platform from playing sounds when it discovers a tag.
Constant Value: 256 (0x00000100)
FLAG_READER_SKIP_NDEF_CHECK
public static final int FLAG_READER_SKIP_NDEF_CHECK
Flag for use with enableReaderMode(android.app.Activity, android.nfc.NfcAdapter.ReaderCallback, int, android.os.Bundle)
.
Setting this flag allows the caller to prevent the platform from performing an NDEF check on the tags it finds.
Constant Value: 128 (0x00000080)
PREFERRED_PAYMENT_CHANGED
public static final int PREFERRED_PAYMENT_CHANGED
User selected another payment application as the preferred payment.
Constant Value: 2 (0x00000002)
PREFERRED_PAYMENT_LOADED
public static final int PREFERRED_PAYMENT_LOADED
Nfc is enabled and the preferred payment aids are registered.
Constant Value: 1 (0x00000001)
PREFERRED_PAYMENT_UPDATED
public static final int PREFERRED_PAYMENT_UPDATED
Current preferred payment has issued an update (registered/unregistered new aids or has been updated itself).
Constant Value: 3 (0x00000003)
STATE_TURNING_OFF
public static final int STATE_TURNING_OFF
Constant Value: 4 (0x00000004)
STATE_TURNING_ON
public static final int STATE_TURNING_ON
Constant Value: 2 (0x00000002)
Public methods
disableForegroundDispatch
public void disableForegroundDispatch (Activity activity)
Disable foreground dispatch to the given activity.
After calling enableForegroundDispatch(Activity, PendingIntent, IntentFilter, String)
, an activity
must call this method before its Activity#onPause
callback
completes.
This method must be called from the main thread.
Requires the Manifest.permission.NFC
permission.
Parameters | |
---|---|
activity |
Activity : the Activity to disable dispatch to |
Throws | |
---|---|
IllegalStateException |
if the Activity has already been paused |
UnsupportedOperationException |
if FEATURE_NFC is unavailable. |
disableReaderMode
public void disableReaderMode (Activity activity)
Restore the NFC adapter to normal mode of operation: supporting peer-to-peer (Android Beam), card emulation, and polling for all supported tag technologies.
Parameters | |
---|---|
activity |
Activity : the Activity that currently has reader mode enabled |
Throws | |
---|---|
UnsupportedOperationException |
if FEATURE_NFC is unavailable. |
enableForegroundDispatch
public void enableForegroundDispatch (Activity activity, PendingIntent intent, IntentFilter[] filters, String[][] techLists)
Enable foreground dispatch to the given Activity.
This will give priority to the foreground activity when
dispatching a discovered Tag
to an application.
If any IntentFilters are provided to this method they are used to match dispatch Intents
for both the NfcAdapter#ACTION_NDEF_DISCOVERED
and
NfcAdapter#ACTION_TAG_DISCOVERED
. Since NfcAdapter#ACTION_TECH_DISCOVERED
relies on meta data outside of the IntentFilter matching for that dispatch Intent is handled
by passing in the tech lists separately. Each first level entry in the tech list represents
an array of technologies that must all be present to match. If any of the first level sets
match then the dispatch is routed through the given PendingIntent. In other words, the second
level is ANDed together and the first level entries are ORed together.
If you pass null
for both the filters
and techLists
parameters
that acts a wild card and will cause the foreground activity to receive all tags via the
NfcAdapter#ACTION_TAG_DISCOVERED
intent.
This method must be called from the main thread, and only when the activity is in the
foreground (resumed). Also, activities must call disableForegroundDispatch(Activity)
before
the completion of their Activity#onPause
callback to disable foreground dispatch
after it has been enabled.
Requires the Manifest.permission.NFC
permission.
Parameters | |
---|---|
activity |
Activity : the Activity to dispatch to |
intent |
PendingIntent : the PendingIntent to start for the dispatch |
filters |
IntentFilter : the IntentFilters to override dispatching for, or null to always dispatch |
techLists |
String : the tech lists used to perform matching for dispatching of the
NfcAdapter#ACTION_TECH_DISCOVERED intent |
Throws | |
---|---|
IllegalStateException |
if the Activity is not currently in the foreground |
UnsupportedOperationException |
if FEATURE_NFC is unavailable. |
enableReaderMode
public void enableReaderMode (Activity activity, NfcAdapter.ReaderCallback callback, int flags, Bundle extras)
Limit the NFC controller to reader mode while this Activity is in the foreground.
In this mode the NFC controller will only act as an NFC tag reader/writer, thus disabling any peer-to-peer (Android Beam) and card-emulation modes of the NFC adapter on this device.
Use FLAG_READER_SKIP_NDEF_CHECK
to prevent the platform from
performing any NDEF checks in reader mode. Note that this will prevent the
Ndef
tag technology from being enumerated on the tag, and that
NDEF-based tag dispatch will not be functional.
For interacting with tags that are emulated on another Android device
using Android's host-based card-emulation, the recommended flags are
FLAG_READER_NFC_A
and FLAG_READER_SKIP_NDEF_CHECK
.
Parameters | |
---|---|
activity |
Activity : the Activity that requests the adapter to be in reader mode |
callback |
NfcAdapter.ReaderCallback : the callback to be called when a tag is discovered |
flags |
int : Flags indicating poll technologies and other optional parameters |
extras |
Bundle : Additional extras for configuring reader mode. |
Throws | |
---|---|
UnsupportedOperationException |
if FEATURE_NFC is unavailable. |
getDefaultAdapter
public static NfcAdapter getDefaultAdapter (Context context)
Helper to get the default NFC Adapter.
Most Android devices will only have one NFC Adapter (NFC Controller).
This helper is the equivalent of:
NfcManager manager = (NfcManager) context.getSystemService(Context.NFC_SERVICE); NfcAdapter adapter = manager.getDefaultAdapter();
Parameters | |
---|---|
context |
Context : the calling application's context |
Returns | |
---|---|
NfcAdapter |
the default NFC adapter, or null if no NFC adapter exists |
getNfcAntennaInfo
public NfcAntennaInfo getNfcAntennaInfo ()
Returns information regarding Nfc antennas on the device such as their relative positioning on the device.
Returns | |
---|---|
NfcAntennaInfo |
Information on the nfc antenna(s) on the device.
This value may be null . |
Throws | |
---|---|
UnsupportedOperationException |
if FEATURE_NFC, FEATURE_NFC_HOST_CARD_EMULATION, FEATURE_NFC_HOST_CARD_EMULATION_NFCF, FEATURE_NFC_OFF_HOST_CARD_EMULATION_UICC and FEATURE_NFC_OFF_HOST_CARD_EMULATION_ESE are unavailable |
ignore
public boolean ignore (Tag tag, int debounceMs, NfcAdapter.OnTagRemovedListener tagRemovedListener, Handler handler)
Signals that you are no longer interested in communicating with an NFC tag
for as long as it remains in range.
All future attempted communication to this tag will fail with IOException
.
The NFC controller will be put in a low-power polling mode, allowing the device
to save power in cases where it's "attached" to a tag all the time (e.g. a tag in
car dock).
Additionally the debounceMs parameter allows you to specify for how long the tag needs
to have gone out of range, before it will be dispatched again.
Note: the NFC controller typically polls at a pretty slow interval (100 - 500 ms).
This means that if the tag repeatedly goes in and out of range (for example, in
case of a flaky connection), and the controller happens to poll every time the
tag is out of range, it *will* re-dispatch the tag after debounceMs, despite the tag
having been "in range" during the interval.
Note 2: if a tag with another UID is detected after this API is called, its effect
will be cancelled; if this tag shows up before the amount of time specified in
debounceMs, it will be dispatched again.
Note 3: some tags have a random UID, in which case this API won't work reliably.
Parameters | |
---|---|
tag |
Tag : the Tag to ignore. |
debounceMs |
int : minimum amount of time the tag needs to be out of range before being
dispatched again. |
tagRemovedListener |
NfcAdapter.OnTagRemovedListener : listener to be called when the tag is removed from the field.
Note that this will only be called if the tag has been out of range
for at least debounceMs, or if another tag came into range before
debounceMs. May be null in case you don't want a callback. |
handler |
Handler : the Handler that will be used for delivering
the callback. if the handler is null, then the thread used for delivering
the callback is unspecified. |
Returns | |
---|---|
boolean |
false if the tag couldn't be found (or has already gone out of range), true otherwise |
isEnabled
public boolean isEnabled ()
Return true if this NFC Adapter has any features enabled.
If this method returns false, the NFC hardware is guaranteed not to generate or respond to any NFC communication over its NFC radio.
Applications can use this to check if NFC is enabled. Applications can request Settings UI allowing the user to toggle NFC using:
startActivity(new Intent(Settings.ACTION_NFC_SETTINGS))
Returns | |
---|---|
boolean |
true if this NFC Adapter has any features enabled |
See also:
isSecureNfcEnabled
public boolean isSecureNfcEnabled ()
Checks Secure NFC feature is enabled.
Returns | |
---|---|
boolean |
True if Secure NFC is enabled, false otherwise |
Throws | |
---|---|
UnsupportedOperationException |
if FEATURE_NFC, FEATURE_NFC_HOST_CARD_EMULATION, FEATURE_NFC_HOST_CARD_EMULATION_NFCF, FEATURE_NFC_OFF_HOST_CARD_EMULATION_UICC and FEATURE_NFC_OFF_HOST_CARD_EMULATION_ESE are unavailable |
UnsupportedOperationException |
if device doesn't support
Secure NFC functionality. isSecureNfcSupported() |
isSecureNfcSupported
public boolean isSecureNfcSupported ()
Checks if the device supports Secure NFC functionality.
Returns | |
---|---|
boolean |
True if device supports Secure NFC, false otherwise |
Throws | |
---|---|
UnsupportedOperationException |
if FEATURE_NFC, FEATURE_NFC_HOST_CARD_EMULATION, FEATURE_NFC_HOST_CARD_EMULATION_NFCF, FEATURE_NFC_OFF_HOST_CARD_EMULATION_UICC and FEATURE_NFC_OFF_HOST_CARD_EMULATION_ESE are unavailable |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2023-06-07 UTC.