Added in API level 9

NfcAdapter

class NfcAdapter
kotlin.Any
   ↳ 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.

Summary

Nested classes
abstract

abstract

A callback to be invoked when another NFC device capable of NDEF push (Android Beam) is within range.

abstract

A callback to be invoked when the system successfully delivers your NdefMessage to another device.

abstract

A callback that is invoked when a tag is removed from the field.

abstract

A callback to be invoked when the system finds a tag while the foreground activity is operating in reader mode.

Constants
static String

Broadcast Action: The state of the local NFC adapter has been changed.

static String

Intent to start an activity when a tag with NDEF payload is discovered.

static String

Broadcast Action: Intent to notify if the preferred payment service changed.

static String

Intent to start an activity when a tag is discovered.

static String

Intent to start an activity when a tag is discovered and activities are registered for the specific technologies on the tag.

static String

Broadcast Action: Intent to notify an application that a transaction event has occurred on the Secure Element.

static String

Used as an int extra field in ACTION_ADAPTER_STATE_CHANGED intents to request the current power state.

static String

Mandatory byte[] extra field in ACTION_TRANSACTION_DETECTED

static String

Optional byte[] extra field in ACTION_TRANSACTION_DETECTED

static String

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.

static String

Extra containing an array of NdefMessage present on the discovered tag.

static String

Mandatory String extra field in ACTION_PREFERRED_PAYMENT_CHANGED Indicates the condition when trigger this event.

static String

Int Extra for use with enableReaderMode(android.app.Activity,android.nfc.NfcAdapter.ReaderCallback,int,android.os.Bundle).

static String

Mandatory String extra field in ACTION_TRANSACTION_DETECTED Indicates the Secure Element on which the transaction occurred.

static String

Mandatory extra containing the Tag that was discovered for the ACTION_NDEF_DISCOVERED, ACTION_TECH_DISCOVERED, and ACTION_TAG_DISCOVERED intents.

static Int

Flag for use with enableReaderMode(android.app.Activity,android.nfc.NfcAdapter.ReaderCallback,int,android.os.Bundle).

static Int

Flag for use with enableReaderMode(android.app.Activity,android.nfc.NfcAdapter.ReaderCallback,int,android.os.Bundle).

static Int

Flag for use with enableReaderMode(android.app.Activity,android.nfc.NfcAdapter.ReaderCallback,int,android.os.Bundle).

static Int

Flag for use with enableReaderMode(android.app.Activity,android.nfc.NfcAdapter.ReaderCallback,int,android.os.Bundle).

static Int

Flag for use with enableReaderMode(android.app.Activity,android.nfc.NfcAdapter.ReaderCallback,int,android.os.Bundle).

static Int

Flag for use with enableReaderMode(android.app.Activity,android.nfc.NfcAdapter.ReaderCallback,int,android.os.Bundle).

static Int

Flag for use with enableReaderMode(android.app.Activity,android.nfc.NfcAdapter.ReaderCallback,int,android.os.Bundle).

static Int

User selected another payment application as the preferred payment.

static Int

Nfc is enabled and the preferred payment aids are registered.

static Int

Current preferred payment has issued an update (registered/unregistered new aids or has been updated itself).

static Int

static Int

static Int

static Int

Public methods
Unit

Disable foreground dispatch to the given activity.

Unit

Restore the NFC adapter to normal mode of operation: supporting peer-to-peer (Android Beam), card emulation, and polling for all supported tag technologies.

Unit
enableForegroundDispatch(activity: Activity!, intent: PendingIntent!, filters: Array<IntentFilter!>!, techLists: Array<Array<String!>!>!)

Enable foreground dispatch to the given Activity.

Unit
enableReaderMode(activity: Activity!, callback: NfcAdapter.ReaderCallback!, flags: Int, extras: Bundle!)

Limit the NFC controller to reader mode while this Activity is in the foreground.

static NfcAdapter!

Helper to get the default NFC Adapter.

NfcAntennaInfo?

Returns information regarding Nfc antennas on the device such as their relative positioning on the device.

Boolean
ignore(tag: Tag!, debounceMs: Int, tagRemovedListener: NfcAdapter.OnTagRemovedListener!, handler: Handler!)

Signals that you are no longer interested in communicating with an NFC tag for as long as it remains in range.

Boolean

Return true if this NFC Adapter has any features enabled.

Boolean

Checks Secure NFC feature is enabled.

Boolean

Checks if the device supports Secure NFC functionality.

Constants

ACTION_ADAPTER_STATE_CHANGED

Added in API level 18
static val ACTION_ADAPTER_STATE_CHANGED: String

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

Value: "android.nfc.action.ADAPTER_STATE_CHANGED"

ACTION_NDEF_DISCOVERED

Added in API level 10
static val ACTION_NDEF_DISCOVERED: String

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 IntentFilters 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.

Value: "android.nfc.action.NDEF_DISCOVERED"

ACTION_PREFERRED_PAYMENT_CHANGED

Added in API level 30
static val ACTION_PREFERRED_PAYMENT_CHANGED: String

Broadcast Action: Intent to notify if the preferred payment service changed.

This intent will only be sent to the application has requested permission for android.Manifest.permission#NFC_PREFERRED_PAYMENT_INFO and if the application has the necessary access to Secure Element which witnessed the particular event.
Requires android.Manifest.permission#NFC_PREFERRED_PAYMENT_INFO

Value: "android.nfc.action.PREFERRED_PAYMENT_CHANGED"

ACTION_TAG_DISCOVERED

Added in API level 9
static val ACTION_TAG_DISCOVERED: String

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.

Value: "android.nfc.action.TAG_DISCOVERED"

ACTION_TECH_DISCOVERED

Added in API level 10
static val ACTION_TECH_DISCOVERED: String

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-lists 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.

Value: "android.nfc.action.TECH_DISCOVERED"

ACTION_TRANSACTION_DETECTED

Added in API level 28
static val ACTION_TRANSACTION_DETECTED: String

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 android.Manifest.permission#NFC_TRANSACTION_EVENT and if the application has the necessary access to Secure Element which witnessed the particular event.
Requires android.Manifest.permission#NFC_TRANSACTION_EVENT

Value: "android.nfc.action.TRANSACTION_DETECTED"

EXTRA_ADAPTER_STATE

Added in API level 18
static val EXTRA_ADAPTER_STATE: String

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,

Value: "android.nfc.extra.ADAPTER_STATE"

EXTRA_AID

Added in API level 28
static val EXTRA_AID: String

Mandatory byte[] extra field in ACTION_TRANSACTION_DETECTED

Value: "android.nfc.extra.AID"

EXTRA_DATA

Added in API level 28
static val EXTRA_DATA: String

Optional byte[] extra field in ACTION_TRANSACTION_DETECTED

Value: "android.nfc.extra.DATA"

EXTRA_ID

Added in API level 9
static val EXTRA_ID: String

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.

Value: "android.nfc.extra.ID"

EXTRA_NDEF_MESSAGES

Added in API level 9
static val EXTRA_NDEF_MESSAGES: String

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.

Value: "android.nfc.extra.NDEF_MESSAGES"

EXTRA_PREFERRED_PAYMENT_CHANGED_REASON

Added in API level 30
static val EXTRA_PREFERRED_PAYMENT_CHANGED_REASON: String

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,

Value: "android.nfc.extra.PREFERRED_PAYMENT_CHANGED_REASON"

EXTRA_READER_PRESENCE_CHECK_DELAY

Added in API level 19
static val EXTRA_READER_PRESENCE_CHECK_DELAY: String

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.

Value: "presence"

EXTRA_SECURE_ELEMENT_NAME

Added in API level 28
static val EXTRA_SECURE_ELEMENT_NAME: String

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.

Value: "android.nfc.extra.SECURE_ELEMENT_NAME"

EXTRA_TAG

Added in API level 10
static val EXTRA_TAG: String

Mandatory extra containing the Tag that was discovered for the ACTION_NDEF_DISCOVERED, ACTION_TECH_DISCOVERED, and ACTION_TAG_DISCOVERED intents.

Value: "android.nfc.extra.TAG"

FLAG_READER_NFC_A

Added in API level 19
static val FLAG_READER_NFC_A: Int

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.

Value: 1

FLAG_READER_NFC_B

Added in API level 19
static val FLAG_READER_NFC_B: Int

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.

Value: 2

FLAG_READER_NFC_BARCODE

Added in API level 19
static val FLAG_READER_NFC_BARCODE: Int

Flag for use with enableReaderMode(android.app.Activity,android.nfc.NfcAdapter.ReaderCallback,int,android.os.Bundle).

Setting this flag enables polling for NfcBarcode technology.

Value: 16

FLAG_READER_NFC_F

Added in API level 19
static val FLAG_READER_NFC_F: Int

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.

Value: 4

FLAG_READER_NFC_V

Added in API level 19
static val FLAG_READER_NFC_V: Int

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.

Value: 8

FLAG_READER_NO_PLATFORM_SOUNDS

Added in API level 19
static val FLAG_READER_NO_PLATFORM_SOUNDS: Int

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.

Value: 256

FLAG_READER_SKIP_NDEF_CHECK

Added in API level 19
static val FLAG_READER_SKIP_NDEF_CHECK: Int

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.

Value: 128

PREFERRED_PAYMENT_CHANGED

Added in API level 30
static val PREFERRED_PAYMENT_CHANGED: Int

User selected another payment application as the preferred payment.

Value: 2

PREFERRED_PAYMENT_LOADED

Added in API level 30
static val PREFERRED_PAYMENT_LOADED: Int

Nfc is enabled and the preferred payment aids are registered.

Value: 1

PREFERRED_PAYMENT_UPDATED

Added in API level 30
static val PREFERRED_PAYMENT_UPDATED: Int

Current preferred payment has issued an update (registered/unregistered new aids or has been updated itself).

Value: 3

STATE_OFF

Added in API level 18
static val STATE_OFF: Int
Value: 1

STATE_ON

Added in API level 18
static val STATE_ON: Int
Value: 3

STATE_TURNING_OFF

Added in API level 18
static val STATE_TURNING_OFF: Int
Value: 4

STATE_TURNING_ON

Added in API level 18
static val STATE_TURNING_ON: Int
Value: 2

Public methods

disableForegroundDispatch

Added in API level 10
fun disableForegroundDispatch(activity: Activity!): Unit

Disable foreground dispatch to the given activity.

After calling enableForegroundDispatch, an activity must call this method before its Activity#onPause callback completes.

This method must be called from the main thread.

Requires the android.Manifest.permission#NFC permission.

Parameters
activity Activity!: the Activity to disable dispatch to
Exceptions
java.lang.IllegalStateException if the Activity has already been paused
java.lang.UnsupportedOperationException if FEATURE_NFC is unavailable.

disableReaderMode

Added in API level 19
fun disableReaderMode(activity: Activity!): Unit

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
Exceptions
java.lang.UnsupportedOperationException if FEATURE_NFC is unavailable.

enableForegroundDispatch

Added in API level 10
fun enableForegroundDispatch(
    activity: Activity!,
    intent: PendingIntent!,
    filters: Array<IntentFilter!>!,
    techLists: Array<Array<String!>!>!
): Unit

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 before the completion of their Activity#onPause callback to disable foreground dispatch after it has been enabled.

Requires the android.Manifest.permission#NFC permission.

Parameters
activity Activity!: the Activity to dispatch to
intent PendingIntent!: the PendingIntent to start for the dispatch
filters Array<IntentFilter!>!: the IntentFilters to override dispatching for, or null to always dispatch
techLists Array<Array<String!>!>!: the tech lists used to perform matching for dispatching of the NfcAdapter#ACTION_TECH_DISCOVERED intent
Exceptions
java.lang.IllegalStateException if the Activity is not currently in the foreground
java.lang.UnsupportedOperationException if FEATURE_NFC is unavailable.

enableReaderMode

Added in API level 19
fun enableReaderMode(
    activity: Activity!,
    callback: NfcAdapter.ReaderCallback!,
    flags: Int,
    extras: Bundle!
): Unit

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.
Exceptions
java.lang.UnsupportedOperationException if FEATURE_NFC is unavailable.

getDefaultAdapter

Added in API level 10
static fun getDefaultAdapter(context: Context!): NfcAdapter!

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
Return
NfcAdapter! the default NFC adapter, or null if no NFC adapter exists

getNfcAntennaInfo

Added in API level 34
fun getNfcAntennaInfo(): NfcAntennaInfo?

Returns information regarding Nfc antennas on the device such as their relative positioning on the device.

Return
NfcAntennaInfo? Information on the nfc antenna(s) on the device. This value may be null.
Exceptions
java.lang.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

Added in API level 24
fun ignore(
    tag: Tag!,
    debounceMs: Int,
    tagRemovedListener: NfcAdapter.OnTagRemovedListener!,
    handler: Handler!
): Boolean

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.
Return
Boolean false if the tag couldn't be found (or has already gone out of range), true otherwise

isEnabled

Added in API level 9
fun isEnabled(): Boolean

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))
Return
Boolean true if this NFC Adapter has any features enabled

isSecureNfcEnabled

Added in API level 29
fun isSecureNfcEnabled(): Boolean

Checks Secure NFC feature is enabled.

Return
Boolean True if Secure NFC is enabled, false otherwise
Exceptions
java.lang.UnsupportedOperationException if device doesn't support Secure NFC functionality. isSecureNfcSupported

isSecureNfcSupported

Added in API level 29
fun isSecureNfcSupported(): Boolean

Checks if the device supports Secure NFC functionality.

Return
Boolean True if device supports Secure NFC, false otherwise
Exceptions
java.lang.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