react-native-nfc-manager 4.0.0-beta.1 → 4.0.0-beta.11

package/README.md

@@ -1,8 +1,8 @@
 # react-native-nfc-manager
 
 [![npm version](https://img.shields.io/npm/v/react-native-nfc-manager.svg?style=flat)](https://www.npmjs.com/package/react-native-nfc-manager)
-[![build](https://api.travis-ci.org/whitedogg13/react-native-nfc-manager.svg?branch=master)](https://travis-ci.org/whitedogg13/react-native-nfc-manager)
-[![issues](https://img.shields.io/github/issues/whitedogg13/react-native-nfc-manager.svg?style=flat)](https://github.com/whitedogg13/react-native-nfc-manager/issues)
+[![CI](https://github.com/revtel/react-native-nfc-manager/actions/workflows/ci.yml/badge.svg?branch=v4)](https://github.com/revtel/react-native-nfc-manager/actions/workflows/ci.yml)
+[![issues](https://img.shields.io/github/issues/revtel/react-native-nfc-manager.svg?style=flat)](https://github.com/revtel/react-native-nfc-manager/issues)
 
 Bring NFC feature to React Native. Inspired by [phonegap-nfc](https://github.com/chariotsolutions/phonegap-nfc) and [react-native-ble-manager](https://github.com/innoveit/react-native-ble-manager)
 
@@ -12,25 +12,87 @@ Made with ❤️ by [whitedogg13](https://github.com/whitedogg13) and [revteltec
 
 > Special thanks to [javix64](https://github.com/javix64) for restructuring the documentation!
 
+## Version Notes
+
+- `v3` only supports legacy architecture (`v3.x.y`).
+- `v4` targets the New Architecture and remains beta (`v4.0.0-beta.x`). Its support floor is React Native 0.76 with the New Architecture enabled; React Native 0.82 and newer are New Architecture only.
+
+## Support Policy
+
+- See [Support Policy](https://github.com/revtel/react-native-nfc-manager/blob/v4/docs/SUPPORT_POLICY.md) for official React Native version window, architecture targets, and verification matrix.
+- Maintainers should follow [Release Validation](https://github.com/revtel/react-native-nfc-manager/blob/v4/docs/RELEASING.md) for Codegen, compiler, simulator, and physical-device evidence gates.
+
 ## Table of Contents
 
 1. [Installation](#installation)
-2. [Getting Started](#gettingstarted)
-3. [Setup](#setup)
+2. [Expo Development Builds](#expo-development-builds)
+3. [Getting Started](#gettingstarted)
+4. [Setup](#setup)
 4. [Documentation](#docs)
 5. [Nfc compatibility](#nfccompatibility)
 6. [Usage Concept](#usageconcept)
 7. [API](#api)
 8. [App demo](#appdemo)
 9. [Learn](#learn)
+10. [Development Example](#development-example)
 
 ## Installation
 
 <a name="installation"></a>
 
 ```shell
-npm i --save react-native-nfc-manager
+npm install react-native-nfc-manager@beta
+```
+
+This branch documents v4, which is still a prerelease. `@beta` selects the published v4 beta; pin its exact version in your application for reproducible installs. Changes on this branch may be newer than the published beta. An unqualified install currently selects v3 via npm `latest`. Legacy Architecture applications should use `npm install react-native-nfc-manager@3`.
+
+See the [v3 → v4 migration guide](https://github.com/revtel/react-native-nfc-manager/blob/v4/docs/MIGRATING_V3_TO_V4.md) before upgrading.
+
+### Expo Development Builds
+
+`react-native-nfc-manager` contains native code, so it does **not** work in Expo Go. Use an [Expo Development Build](https://docs.expo.dev/develop/development-builds/introduction/) generated locally or by EAS.
+
+Install the package and add its config plugin to `app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "react-native-nfc-manager",
+        {
+          "nfcPermission": "Allow this app to scan nearby NFC tags",
+          "includeNdefEntitlement": true,
+          "selectIdentifiers": ["A0000002471001"],
+          "systemCodes": ["8008"]
+        }
+      ]
+    ]
+  }
+}
+```
+
+- `nfcPermission` sets the iOS `NFCReaderUsageDescription` and enables the Android NFC permission. Omit it to use the default description.
+- `nfcPermission: false` is an advanced opt-out: it omits the iOS usage description and blocks the Android permission contributed by the library manifest. NFC cannot be used until the application supplies equivalent native configuration itself.
+- `includeNdefEntitlement` defaults to `true`; set it to `false` to generate only the iOS `TAG` reader-session format.
+- `selectIdentifiers` supplies iOS ISO 7816 application identifiers.
+- `systemCodes` supplies iOS FeliCa system codes.
+
+Generate and build the native application after adding or changing the plugin:
+
+```shell
+npx expo prebuild
+npx expo run:ios
+# or
+npx expo run:android
 ```
+
+An EAS Development Build is also a valid deployment path, but a new native build is still required after native dependency or plugin configuration changes. The config plugin generates project files; Apple provisioning must still permit the NFC capability for the selected App ID.
+
+Repository maintainers can prepare a packed-package [Expo NFC device smoke app](https://github.com/revtel/react-native-nfc-manager/blob/v4/example-expo/README.md) with `npm run prepare:expo:smoke`. Its build checks do not replace physical-device NFC scans.
+
+See the [2026-09-29 Expo physical-device smoke record](https://github.com/revtel/react-native-nfc-manager/blob/v4/docs/EXPO_SMOKE_2026-09-29.md) for tested iPhone/Android flows and remaining validation gaps. The Android smoke app provides a cancellable scan prompt through tag I/O and cleanup.
+
 ### iOS
 
 This library use native-modules, so you will need to do `pod install` for iOS:
@@ -38,6 +100,9 @@ This library use native-modules, so you will need to do `pod install` for iOS:
 ```shell
 cd ios && pod install && cd ..
 ```
+
+Minimum Swift language version for iOS native sources is **Swift 5.7**.
+
 ### Android
 
 It should be properly auto-linked, so you don't need to do anything.
@@ -50,7 +115,7 @@ It should be properly auto-linked, so you don't need to do anything.
 
 1. In [apple developer site](https://developer.apple.com/), enable capability for NFC
 
-![enable capability](./images/enable-capability.png "enable capability")
+![enable capability](https://raw.githubusercontent.com/revtel/react-native-nfc-manager/v4/images/enable-capability.png "enable capability")
 
 2. in Xcode, add `NFCReaderUsageDescription` into your `info.plist`, for example:
 
@@ -92,15 +157,15 @@ An incomplete list of aid's can be found here. [Application identifier](https://
 
 3. in Xcode's `Signing & Capabilities` tab, make sure `Near Field Communication Tag Reading` capability had been added, like this:
 
-![xcode-add-capability](./images/xcode-capability.png "xcode capability")
+![xcode-add-capability](https://raw.githubusercontent.com/revtel/react-native-nfc-manager/v4/images/xcode-capability.png "xcode capability")
 
 If this is the first time you toggle the capabilities, the Xcode will generate a `<your-project>.entitlement` file for you:
 
-![xcode-add-entitlement](./images/xcode-entitlement.png "xcode entitlement")
+![xcode-add-entitlement](https://raw.githubusercontent.com/revtel/react-native-nfc-manager/v4/images/xcode-entitlement.png "xcode entitlement")
 
 4. in Xcode, review the generated entitlement. It should look like this:
 
-![edit entitlement](./images/edit-entitlement.png "edit entitlement")
+![edit entitlement](https://raw.githubusercontent.com/revtel/react-native-nfc-manager/v4/images/edit-entitlement.png "edit entitlement")
 
 More info on Apple's [doc](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_nfc_readersession_formats?language=objc)
 
@@ -112,27 +177,7 @@ Simple add `uses-permission` into your `AndroidManifest.xml`:
  <uses-permission android:name="android.permission.NFC" />
 ```
 
-#### **Support Android 12**
-
-We start to support Android 12 from `v3.11.1`, and you will need to update `compileSdkVersion` to `31`, otherwise the build will fail:
-
-```
-buildscript {
-    ext {
-        ...
-        compileSdkVersion = 31
-        ...
-    }
-    ...
-}
-```
-
-The reason for this is because Android puts new limitation on [PendingIntent](https://developer.android.com/reference/android/app/PendingIntent#FLAG_MUTABLE) which says `Starting with Build.VERSION_CODES.S, it will be required to explicitly specify the mutability of PendingIntents`
-
-> The original issue is [here](https://github.com/revtel/react-native-nfc-manager/issues/469)
-
-If you don't care about **Android 12** for now, you can use **`v3.11.0`** as a short term solution.
-
+Use the Android SDK, build tools, NDK, and Java versions required by your React Native version. Do not lower `compileSdkVersion` to an old v3 example value. The development example uses React Native 0.84 with the New Architecture enabled; its toolchain is documented in [example/README.md](https://github.com/revtel/react-native-nfc-manager/blob/v4/example/README.md).
 
 ## Getting Started
 
@@ -141,32 +186,47 @@ If you don't care about **Android 12** for now, you can use **`v3.11.0`** as a s
 The simplest (and most common) use case for this library is to read `NFC` tags containing `NDEF`, which can be achieved via the following codes:
 
 ```javascript
-import React from 'react';
+import React, {useRef, useState} from 'react';
 import {View, Text, TouchableOpacity, StyleSheet} from 'react-native';
 import NfcManager, {NfcTech} from 'react-native-nfc-manager';
 
-// Pre-step, call this before any NFC operations
-NfcManager.start();
-
 function App() {
+  const scanning = useRef(false);
+  const [busy, setBusy] = useState(false);
+
   async function readNdef() {
+    // A ref also blocks rapid taps before React renders the disabled button.
+    if (scanning.current) return;
+    scanning.current = true;
+    setBusy(true);
+    let requestAttempted = false;
     try {
-      // register for the NFC tag with NDEF in it
+      await NfcManager.start();
+      requestAttempted = true;
       await NfcManager.requestTechnology(NfcTech.Ndef);
-      // the resolved tag object will contain `ndefMessage` property
       const tag = await NfcManager.getTag();
-      console.warn('Tag found', tag);
+      console.warn('NDEF records', tag?.ndefMessage ?? []);
     } catch (ex) {
-      console.warn('Oops!', ex);
+      // Includes initialization, request, cancellation and tag-I/O failures.
+      console.warn('NFC scan ended', ex);
     } finally {
-      // stop the nfc scanning
-      NfcManager.cancelTechnologyRequest();
+      try {
+        if (requestAttempted) {
+          // Await cleanup before permitting a subsequent scan.
+          await NfcManager.cancelTechnologyRequest();
+        }
+      } catch (cleanupError) {
+        console.warn('NFC cleanup failed', cleanupError);
+      } finally {
+        scanning.current = false;
+        setBusy(false);
+      }
     }
   }
 
   return (
     <View style={styles.wrapper}>
-      <TouchableOpacity onPress={readNdef}>
+      <TouchableOpacity onPress={readNdef} disabled={busy}>
         <Text>Scan a Tag</Text>
       </TouchableOpacity>
     </View>
@@ -190,7 +250,29 @@ export default App;
 
 <a name="docs"></a>
 
-Check the full documentation that contains `examples`, `faq` and other topics like `Expo` in our [Wiki](https://github.com/revtel/react-native-nfc-manager/wiki)
+Check the full documentation that contains `examples`, `faq`, and other topics in our [Wiki](https://github.com/revtel/react-native-nfc-manager/wiki). The Expo instructions above are the current v4 integration contract.
+
+## Development Example
+
+<a name="development-example"></a>
+
+For local library development and physical-device NFC testing, use the React Native 0.84 New Architecture example app in [`example/`](https://github.com/revtel/react-native-nfc-manager/tree/v4/example). See [example/README.md](https://github.com/revtel/react-native-nfc-manager/blob/v4/example/README.md).
+
+The example Jest suite mocks the native module and verifies application interactions only. It does not verify NFC hardware. Android and iOS compiler builds and physical-device checks are separate release gates.
+
+### Build (TypeScript)
+
+This project now uses a TypeScript build flow and emits distributable JavaScript to `dist/`:
+
+```shell
+npm run build
+```
+
+For package publishing, `prepack` runs the build automatically.
+
+### Routine CI
+
+CI on pull requests and `v4` pushes uses Node.js 22 for build, lint, public type checking, root and example mocked tests, package contents, and the RN 0.76.9 / 0.77.3 / 0.84.0 packed Codegen matrix. Separate Android and iOS jobs compile the RN 0.84 New Architecture example when relevant files change; documentation-only changes skip them. Manual CI runs force both builds for release candidates. These are compiler checks, not NFC hardware tests. Packed support-floor and Expo consumer builds remain additional release gates; see [Release Validation](https://github.com/revtel/react-native-nfc-manager/blob/v4/docs/RELEASING.md).
 
 ## Nfc Compatibility
 
@@ -210,19 +292,21 @@ Check the full documentation that contains `examples`, `faq` and other topics li
 | `Iso15693IOS`     | ❌      | ✅   |
 | `FelicaIOS`       | ❌      | ✅   |
 
+This table describes the intended platform API availability. It is not a record of the devices, OS versions, or tag technologies verified for a particular release; see the [Support Policy](https://github.com/revtel/react-native-nfc-manager/blob/v4/docs/SUPPORT_POLICY.md) for evidence labels and limitations.
+
 ## Usage concept
 
 <a name="usageconcept"></a>
 
 In higher level, there're 4 steps to use this library:
 
-0. (Recommended but not necessary) Before all next steps, use `NfcManager.start()` to start listen a tag.
+0. Await `NfcManager.start()` to initialize the native module before requesting a technology. Initialization alone does not start a tag scan.
 
 
 1. Request your particular NFC technologies through `NfcManager.requestTechnology`. Let's request `Ndef` techonogy.
 
 ```javascript
-NfcManager.requestTechnology(NfcTech.Ndef);
+await NfcManager.requestTechnology(NfcTech.Ndef);
 ```
 
 2. Select the proper NFC technology handler, which is implemented as getter in main `NfcManager` object.
@@ -234,13 +318,13 @@ NfcManager.ndefHandler
 3. Call specific methods on the NFC technology handler.
 
 ```javascript
-NfcManager.ndefHandler.getNdefMessage()
+await NfcManager.ndefHandler.getNdefMessage();
 ```
 
 4. Clean up your tech registration through:
 
 ```javascript
-NfcManager.cancelTechnologyRequest()
+await NfcManager.cancelTechnologyRequest();
 ```
 
 
@@ -248,6 +332,20 @@ NfcManager.cancelTechnologyRequest()
 
 <a name="api"></a>
 
+### Android cached tag metadata
+
+Android tag results from discovery and `getTag()` may include these optional, discovery-time fields when the tag supports the corresponding technology:
+
+| Technology | Fields |
+| --- | --- |
+| NFC-A | `atqa: number[]`, `sak: number` |
+| NFC-V | `dsfid: number`, `responseFlags: number` |
+| ISO-DEP | `historicalBytes: number[]`, `hiLayerResponse: number[]` |
+
+Byte values are unsigned (0–255). An unsupported or unavailable field is omitted; check for its presence before using it. These values come from Android's cached tag discovery data and do not trigger another NFC command. The new NFC-A and NFC-V fields and `hiLayerResponse` are Android-only; `historicalBytes` can also be reported by iOS ISO 7816 tags. Compiler and mock tests do not establish physical-device behavior, so verify each technology with suitable hardware before relying on it in a release.
+
+The [2026-09-29 device record](https://github.com/revtel/react-native-nfc-manager/blob/v4/docs/V4_RELEASE_VALIDATION_2026-09-29.md) observed NFC-A `atqa: [68, 0]` and `sak: 0` on Samsung SM-N975U1 / Android 12 with NTAG215. NFC-V and ISO-DEP metadata were not verified on hardware in that session.
+
 The following table shows the handler for each technology, so if you need to use a technology, go to [index.d.ts](index.d.ts) and search for it.
 
 |NFC Technologies   | Handlers |
@@ -272,13 +370,13 @@ The following table shows the handler for each technology, so if you need to use
 We have a full featured NFC utility app using this library available for download. The source code is here: [**React Native NFC ReWriter App**](https://github.com/revtel/react-native-nfc-rewriter)
 
 <a href='https://apps.apple.com/tw/app/nfc-rewriter/id1551243964' target='_blank'>
-<img alt="react-native-nfc-rewriter" src="./images/Apple-App-Store-Icon.png" width="250">
+<img alt="react-native-nfc-rewriter" src="https://raw.githubusercontent.com/revtel/react-native-nfc-manager/v4/images/Apple-App-Store-Icon.png" width="250">
 </a>
 
 </br>
 
 <a href='https://play.google.com/store/apps/details?id=com.washow.nfcopenrewriter' target='_blank'>
-<img alt="react-native-nfc-rewriter" src="./images/google-play-icon.jpeg" width="250">
+<img alt="react-native-nfc-rewriter" src="https://raw.githubusercontent.com/revtel/react-native-nfc-manager/v4/images/google-play-icon.jpeg" width="250">
 </a>
 
 ## Learn
@@ -288,4 +386,3 @@ We have a full featured NFC utility app using this library available for downloa
 We have published a React Native NFC course with [newline.co](https://www.newline.co/), check it out!
 - Free course (1 hour) about basic NFC setup and concept [here](https://www.youtube.com/watch?v=rAS-DvNUFck)
 - Full course (3 hours) for more (NDEF, Deep Linking, NTAG password protection, signature with UID) [here](https://www.newline.co/courses/newline-guide-to-nfcs-with-react-native)
-