Merge pull request #2 from visibait/feat/antenna-location

feat: Report NFC antenna location and Secure NFC status

Author: visibait

CHANGELOG.md

@@ -1,5 +1,34 @@
 # react-native-nfc-kit
 
+## 2.1.0
+
+### Minor Changes
+
+- d1a3d89: Report where the device's NFC antenna is, and whether Secure NFC is on.
+
+  `nfc.getAntennaInfo()` answers with the device's dimensions in millimetres and the
+  position of each NFC antenna within them, which is what turns "hold the card here"
+  into a hint drawn in the right place instead of in the middle of the screen. Android
+  14 and later, through `NfcAdapter.getNfcAntennaInfo`. It resolves `null` — never
+  rejects — on iOS, on the web, below Android 14, and on the many Android 14 devices
+  whose manufacturer left the numbers empty, so a screen laying out a hint needs no
+  try/catch and still has to keep its generic fallback.
+
+  `nfc.isSecureNfcEnabled()` reports Android's Secure NFC setting, which restricts NFC
+  to an unlocked screen and is the usual explanation for a background or launch tag
+  that silently does nothing on one device and works on another. Android 10 and later;
+  `false` where the setting does not exist. It is a call rather than a capability
+  because the user can change it while the app is running.
+
+  Both are reflected in `nfc.capabilities` as `antennaInfo` and `secureNfc`, and there
+  is a new page in the docs covering the coordinate system, foldables, and why `null`
+  is a normal answer.
+
+  **This bumps the native contract to version 6, so a development build has to be
+  rebuilt.** Updating the JavaScript alone leaves the installed binary reporting
+  version 5, and every call will fail with `contractMismatch` until
+  `npx expo run:android`, `npx expo run:ios` or an EAS build has run again.
+
 ## 2.0.0
 
 ### Major Changes

README.md

@@ -127,6 +127,8 @@ runtime, and the types tell you before that.
 | Card emulation (HCE)         | entitlement, EEA only |   ✅    |      —       |
 | Observe mode, polling frames |           —           | API 35+ |      —       |
 | Apple Wallet passes (VAS)    |      entitlement      |    —    |      —       |
+| Antenna location             |           —           | API 34+ |      —       |
+| Secure NFC status            |           —           | API 29+ |      —       |
 
 <br>
 

android/src/main/java/com/nfckit/NfcKitModule.kt

@@ -30,7 +30,7 @@ import java.util.concurrent.ConcurrentHashMap
 import java.util.concurrent.atomic.AtomicInteger
 
 /** Bumped together with `CONTRACT_VERSION` in `src/native/contract.ts`. */
-private const val CONTRACT_VERSION = 5
+private const val CONTRACT_VERSION = 6
 
 private const val EVENT_TAG_DISCOVERED = "onTagDiscovered"
 private const val EVENT_BACKGROUND_TAG = "onBackgroundTag"
@@ -44,6 +44,12 @@ private const val EVENT_POLLING_FRAMES = "onPollingFrames"
 /** The API level that added observe mode and polling loop frames. */
 private const val OBSERVE_MODE_SDK = 35
 
+/** The API level that added `NfcAdapter.getNfcAntennaInfo`. */
+private const val ANTENNA_INFO_SDK = 34
+
+/** The API level that added the secure NFC setting. */
+private const val SECURE_NFC_SDK = 29
+
 /** Mirrors `NativePollingLoopFilter`. */
 class PollingLoopFilterOptions : Record {
   @Field val pattern: String = ""
@@ -177,6 +183,13 @@ class NfcKitModule : Module() {
         // Apple Wallet passes are an Apple protocol read through CoreNFC's own VAS
         // session. There is no Android equivalent to expose.
         "vas" to false,
+        // Asked of the device rather than inferred from the API level: the
+        // manufacturer has to have filled the numbers in, and plenty of API 34
+        // devices answer null.
+        "antennaInfo" to (antennaInfoPayload() != null),
+        // Hardware-dependent as well as version-dependent, so the adapter is the
+        // one to ask.
+        "secureNfc" to isSecureNfcSupported(),
       )
     }
 
@@ -202,6 +215,12 @@ class NfcKitModule : Module() {
       activity.startActivity(Intent(Settings.ACTION_NFC_SETTINGS))
     }
 
+    AsyncFunction("getAntennaInfo") { antennaInfoPayload() }
+
+    AsyncFunction("isSecureNfcEnabled") {
+      Build.VERSION.SDK_INT >= SECURE_NFC_SDK && nfcAdapter()?.isSecureNfcEnabled == true
+    }
+
     /* -- Session lifecycle ----------------------------------------------- */
 
     AsyncFunction("startSession") { sessionId: String, options: SessionOptions ->
@@ -550,6 +569,38 @@ class NfcKitModule : Module() {
   private fun isObserveModeSupported(): Boolean =
     Build.VERSION.SDK_INT >= OBSERVE_MODE_SDK && nfcAdapter()?.isObserveModeSupported == true
 
+  private fun isSecureNfcSupported(): Boolean =
+    Build.VERSION.SDK_INT >= SECURE_NFC_SDK && nfcAdapter()?.isSecureNfcSupported == true
+
+  /**
+   * This device's antenna layout, in the shape `NativeNfcAntennaInfo` describes,
+   * or null.
+   *
+   * Null covers three situations deliberately: below API 34 the call does not
+   * exist, there may be no adapter at all, and a manufacturer on API 34 may
+   * simply not have filled the numbers in. None of them is an error, and a caller
+   * that handles the third one has already handled the other two.
+   *
+   * The platform type never appears in a signature here, only inside the guarded
+   * branch, so nothing in this class references an API 34 class on a device that
+   * does not have one.
+   */
+  private fun antennaInfoPayload(): Map<String, Any?>? {
+    if (Build.VERSION.SDK_INT < ANTENNA_INFO_SDK) {
+      return null
+    }
+    val info = nfcAdapter()?.nfcAntennaInfo ?: return null
+
+    return mapOf(
+      "deviceWidth" to info.deviceWidth,
+      "deviceHeight" to info.deviceHeight,
+      "deviceFoldable" to info.isDeviceFoldable,
+      "antennas" to info.availableNfcAntennas.map { antenna ->
+        mapOf("locationX" to antenna.locationX, "locationY" to antenna.locationY)
+      },
+    )
+  }
+
   /**
    * Asks the platform to route taps to this app's service while it is in front.
    *

docs/antenna-location.mdx

@@ -0,0 +1,118 @@
+---
+title: 'Where the antenna is, and what the settings allow'
+sidebarTitle: 'Antenna and secure NFC'
+description: 'Two things only the device can answer: where its NFC antenna physically sits, and whether NFC is restricted to an unlocked screen.'
+---
+
+Both of these describe the hardware in the user's hand rather than anything your app
+does with it. They exist because the two most common complaints about an NFC screen —
+"it never reads" and "nothing happens on the lock screen" — usually have nothing to do
+with the tag.
+
+## Where to tell the user to tap
+
+Android 14 added an API that reports where the NFC antenna physically sits on the
+device. It is the difference between a card illustration in the middle of the screen
+and one over the antenna.
+
+```ts
+import { nfc } from 'react-native-nfc-kit';
+
+const info = await nfc.getAntennaInfo();
+
+if (info !== null) {
+  const [antenna] = info.antennas;
+  // Millimetres from the bottom-left corner of the device.
+  console.log(antenna.locationX, antenna.locationY);
+}
+```
+
+<Info>
+  The coordinates are millimetres from the **bottom-left corner of the device** — the corner of the
+  hardware, bezels included. They are not screen coordinates and not pixels, so they mean nothing on
+  their own. That is why `deviceWidth` and `deviceHeight` come back in the same object: it is the
+  ratio of the two that becomes a position you can lay out against.
+</Info>
+
+```ts
+import { nfc } from 'react-native-nfc-kit';
+
+const info = await nfc.getAntennaInfo();
+const antenna = info?.antennas[0];
+
+const hint =
+  info === null || antenna === undefined
+    ? null
+    : {
+        left: `${(antenna.locationX / info.deviceWidth) * 100}%`,
+        // Measured up from the bottom, which is the opposite of a CSS `top`.
+        bottom: `${(antenna.locationY / info.deviceHeight) * 100}%`,
+      };
+```
+
+A phone can report more than one antenna, and `antennas` is ordered as the platform
+gives it, with no promise about which is the "main" one. Most devices report exactly
+one.
+
+### When it is null
+
+`null` is a normal answer, not a failure, and it covers four different situations on
+purpose:
+
+| Situation                              | Why                                                         |
+| -------------------------------------- | ----------------------------------------------------------- |
+| iOS                                    | CoreNFC never reports antenna geometry, at any iOS version. |
+| Web                                    | A page is handed records, never anything about the radio.   |
+| Android 13 and earlier                 | The API arrived in Android 14 (API 34).                     |
+| Android 14 where the OEM left it empty | Common. The numbers are the manufacturer's to fill in.      |
+
+The last row is the one worth designing around: it means the `null` branch is not "the
+iOS branch" by another name, and a device on the right Android version can still
+decline to answer. Keep the generic illustration as the fallback.
+
+Because of that, `getAntennaInfo()` resolves `null` rather than rejecting — a screen
+laying out a hint needs no `try`/`catch`. If you want the answer without the round
+trip, `nfc.capabilities?.antennaInfo` is the same fact as a boolean.
+
+<Note>
+  On a foldable, `deviceFoldable` is `true` and every number describes the device **unfolded**. A
+  folded phone needs its own arithmetic before any of this reaches a layout, and the platform gives
+  you nothing to do it with — so on a foldable, showing the generic hint is usually the better
+  answer.
+</Note>
+
+## Secure NFC
+
+Android 10 added a setting called **Secure NFC**: when it is on, the device reads tags
+only while the screen is unlocked. It is off by default on most devices and on by
+default on a few, and a user can turn it on without connecting it to anything.
+
+```ts
+import { nfc } from 'react-native-nfc-kit';
+
+if (await nfc.isSecureNfcEnabled()) {
+  // A tap on the lock screen will do nothing at all. Say so, rather than
+  // letting the scan sit there looking broken.
+}
+```
+
+This is a call rather than a capability because the user can change it from the
+settings while your app is running. Whether the device has the setting at all is
+`nfc.capabilities?.secureNfc`, which is `false` below Android 10, on iOS and on the
+web — and `isSecureNfcEnabled()` is `false` there too.
+
+It matters most for [background and launch tags](/setup/background-reading): a tap
+against a locked phone is exactly what that feature is for, and Secure NFC is the
+reason it silently does nothing on some devices. A reading session started from a
+screen the user is looking at is unaffected, because the screen is unlocked by
+definition.
+
+## What each platform reports
+
+|                        |   iOS   |                   Android                   | Web (Chrome) |
+| ---------------------- | :-----: | :-----------------------------------------: | :----------: |
+| `getAntennaInfo()`     | `null`  | API 34+, and only when the OEM filled it in |    `null`    |
+| `isSecureNfcEnabled()` | `false` |                   API 29+                   |   `false`    |
+
+Neither call needs a permission, an entitlement, or anything in the manifest. Both are
+safe to call on every platform on startup.

docs/device-matrix.mdx

@@ -139,6 +139,22 @@ Procedure:
 A soak result is worth reporting whether it holds or not — it is the one piece of
 evidence CI cannot produce.
 
+## Device information, Android only
+
+The two rows that need no tag at all. They describe the device, so a wrong answer is
+visible the moment you look at the phone.
+
+| #   | Claim                                             | Setup                                     | Passed when                                                                                                      | Status |
+| --- | ------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------ |
+| 46  | The antenna location is reported, and plausible   | API 34+ device                            | `nfc.getAntennaInfo()` gives dimensions within a few mm of the real phone, and a location that falls inside them | ⬜     |
+| 47  | Secure NFC is reported as the system setting says | API 29+ device, setting toggled both ways | `nfc.isSecureNfcEnabled()` follows the setting without restarting the app                                        | ⬜     |
+
+<Note>
+  A `null` from row 46 on an API 34 device is a **pass**, not a failure: filling those numbers in is
+  the manufacturer's choice and many have not. What would be a failure is a throw, or numbers that
+  do not match the hardware in your hand. Worth reporting either way, with the exact model.
+</Note>
+
 ## The rows most worth covering
 
 Not every row is equally informative. If you are only going to run some:
@@ -153,6 +169,9 @@ Not every row is equally informative. If you are only going to run some:
   inference it has not been able to check. If it turns out to be wrong, the fix is a
   one-line default and the docs already say it is provisional.
 - **Row 45 on both platforms.**
+- **Row 46 on any Android 14 phone.** It costs one call and no tag, and how many
+  devices actually fill the numbers in is not something the documentation anywhere
+  answers.
 
 Rows 39 and 40 need an entitlement Apple grants case by case, and rows 30 to 33 need a
 terminal, so those stay thin until somebody who has one reports back. They are

docs/docs.json

@@ -64,7 +64,7 @@
           {
             "group": "Reference",
             "icon": "list",
-            "pages": ["errors", "device-matrix"]
+            "pages": ["errors", "device-matrix", "antenna-location"]
           },
           {
             "group": "Coming from elsewhere",

docs/index.mdx

@@ -95,6 +95,8 @@ runtime, and the types tell you before that.
 | Card emulation (HCE)         | entitlement, EEA only |   ✅    |      —       |
 | Observe mode, polling frames |           —           | API 35+ |      —       |
 | Apple Wallet passes (VAS)    |      entitlement      |    —    |      —       |
+| Antenna location             |           —           | API 34+ |      —       |
+| Secure NFC status            |           —           | API 29+ |      —       |
 
 <Warning>
   **NFC needs a development build.** It is native code, so Expo Go cannot load it. `npx expo

example/App.tsx

@@ -15,6 +15,7 @@ import {
   isTextRecord,
   nfc,
   toHex,
+  type NfcAntennaInfo,
   type NfcAvailability,
   type Tag,
 } from 'react-native-nfc-kit';
@@ -31,6 +32,8 @@ export default function App() {
   const [status, setStatus] = useState('Idle');
   const [result, setResult] = useState<ScanResult | null>(null);
   const [busy, setBusy] = useState(false);
+  const [antenna, setAntenna] = useState<NfcAntennaInfo | null>(null);
+  const [secureNfc, setSecureNfc] = useState<boolean | null>(null);
 
   useEffect(() => {
     void nfc.getAvailability().then(setAvailability);
@@ -39,6 +42,13 @@ export default function App() {
     return () => subscription.remove();
   }, []);
 
+  useEffect(() => {
+    // Hardware facts, so they are read once. Both answer on every platform
+    // rather than throwing, which is why neither needs a catch.
+    void nfc.getAntennaInfo().then(setAntenna);
+    void nfc.isSecureNfcEnabled().then(setSecureNfc);
+  }, []);
+
   /** Reads whatever is on the tag, and reports it. */
   const read = useCallback(async () => {
     setBusy(true);
@@ -141,6 +151,8 @@ export default function App() {
             label="Observe mode"
             value={String(availability?.capabilities?.observeMode ?? '…')}
           />
+          <Row label="Antenna" value={describeAntenna(antenna)} />
+          <Row label="Secure NFC" value={secureNfc === null ? '…' : String(secureNfc)} />
         </Section>
 
         <View style={styles.buttons}>
@@ -180,6 +192,25 @@ function describe(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+/**
+ * The antenna layout as one line.
+ *
+ * Null is the common answer even on Android 14 -- the numbers are the
+ * manufacturer's to fill in -- so it says which of the two it is rather than
+ * leaving a blank that reads like a bug.
+ */
+function describeAntenna(info: NfcAntennaInfo | null): string {
+  if (info === null) {
+    return 'not reported by this device';
+  }
+
+  const positions = info.antennas
+    .map((antenna) => `${antenna.locationX}, ${antenna.locationY}`)
+    .join(' · ');
+
+  return `${positions || 'none listed'} mm of ${info.deviceWidth}×${info.deviceHeight} mm`;
+}
+
 function Section({ title, children }: { title: string; children: React.ReactNode }) {
   return (
     <View style={styles.section}>