From 87aad0876d5781edc387b6a45e17fb0b21d03b84 Mon Sep 17 00:00:00 2001 From: javix64 Date: Wed, 15 Mar 2023 16:52:29 +0100 Subject: [PATCH 1/2] [DOC] Update README.md --- README.md | 324 ++++++++++++++++---------------------- FAQ.md => docs/FAQ.md | 0 docs/README.md | 17 ++ docs/examples.md | 68 ++++++++ docs/expoGo.md | 48 ++++++ docs/oldMethod.md | 39 +++++ setup.md => docs/setup.md | 21 +++ 7 files changed, 330 insertions(+), 187 deletions(-) rename FAQ.md => docs/FAQ.md (100%) create mode 100644 docs/README.md create mode 100644 docs/examples.md create mode 100644 docs/expoGo.md create mode 100644 docs/oldMethod.md rename setup.md => docs/setup.md (71%) diff --git a/README.md b/README.md index e4b06d0..9ac3d50 100644 --- a/README.md +++ b/README.md @@ -10,29 +10,92 @@ Contributions are welcome! Made with ❤️ by [whitedogg13](https://github.com/whitedogg13) and [revteltech](https://github.com/revtel) -## Install -### javascript part +## Table of Contents + +1. [Installation](#installation) +2. [Getting Started](#gettingstarted) +3. [Setup](#setup) +4. [Documentation](#docs) +5. [Nfc compatibility](#nfccompatibility) +6. [Usage Concept](#usageconcept) +7. [API](#api) +8. [App demo](#appdemo) +9. [Learn](#learn) + +## Installation + + ```shell npm i --save react-native-nfc-manager ``` - -### native part +### iOS This library use native-modules, so you will need to do `pod install` for iOS: ```shell cd ios && pod install && cd .. ``` +### Android -For Android, it should be properly auto-linked, so you don't need to do anything. +It should be properly auto-linked, so you don't need to do anything. ## Setup -Please see [here](setup.md) + + +### iOS + +1. In [apple developer site](https://developer.apple.com/), enable capability for NFC + +![enable capability](./images/enable-capability.png "enable capability") + +2. in Xcode, add `NFCReaderUsageDescription` into your `info.plist`, for example: + +``` +NFCReaderUsageDescription +We need to use NFC +``` + +More info on Apple's [doc](https://developer.apple.com/documentation/bundleresources/information_property_list/nfcreaderusagedescription?language=objc) + +Additionally, if writing ISO7816 tags add application identifiers (aid) into your `info.plist` as needed like this. +``` +com.apple.developer.nfc.readersession.iso7816.select-identifiers + + D2760000850100 + D2760000850101 + +``` + +More info on Apple's [doc](https://developer.apple.com/documentation/corenfc/nfciso7816tag) + +An incomplete list of aid's can be found here. [Application identifier](https://www.eftlab.com/knowledge-base/211-emv-aid-rid-pix/) + +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") + +If this is the first time you toggle the capabilities, the Xcode will generate a `.entitlement` file for you: + +![xcode-add-entitlement](./images/xcode-entitlement.png "xcode entitlement") -### **Android 12** +4. in Xcode, review the generated entitlement. It should look like this: + +![edit entitlement](./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) + +### Android + +Simple add `uses-permission` into your `AndroidManifest.xml`: + +```xml + +``` + +#### **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: @@ -51,31 +114,12 @@ The reason for this is because Android puts new limitation on [PendingIntent](ht > The original issue is [here](https://github.com/revtel/react-native-nfc-manager/issues/469) -BTW, if you don't care about **Android 12** for now, you can use **`v3.11.0`** as a short term solution. +If you don't care about **Android 12** for now, you can use **`v3.11.0`** as a short term solution. -### **[Demo App] NfcOpenReWriter** -We have a full featured NFC utility app using this library available for download. +## Getting Started - -react-native-nfc-rewriter - - -
- - -react-native-nfc-rewriter - - -It also open sourced in this repo: [React Native NFC ReWriter App](https://github.com/revtel/react-native-nfc-rewriter) - -## Learn - -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) - -## Usage + 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: @@ -123,203 +167,109 @@ const styles = StyleSheet.create({ export default App; ``` -Pleaes notice when running above codes, iOS and Android has different behaviors: -- iOS will pop up a system scanning UI -- Android provides **NO** system scanning UI -Regarding the system scannning UI, both platforms should be able to scan your NFC tags succesfully and print out its content. +## DOCUMENTATION -### Old Style (registerTagEvent) To Scan NFC Tags + -There's an alterntaive style to scan NFC tags through `NfcManager.registerTagEvent`, like this: +Check the full documentation that contains setup,examples, faq and more [here](docs/readme.md) -```javascript -import NfcManager, {NfcTech} from 'react-native-nfc-manager'; -// The following function resolves to a NFC Tag object using old event listener approach. -// You can call it like this: -// `const nfcTag = await listenToNfcEventOnce()` - -function listenToNfcEventOnce() { - const cleanUp = () => { - NfcManager.setEventListener(NfcEvents.DiscoverTag, null); - NfcManager.setEventListener(NfcEvents.SessionClosed, null); - }; - - return new Promise((resolve) => { - let tagFound = null; - - NfcManager.setEventListener(NfcEvents.DiscoverTag, (tag) => { - tagFound = tag; - resolve(tagFound); - NfcManager.unregisterTagEvent(); - }); - - NfcManager.setEventListener(NfcEvents.SessionClosed, () => { - cleanUp(); - if (!tagFound) { - resolve(); - } - }); - - NfcManager.registerTagEvent(); - }); -} -``` - -As you can see, the above approach is more verbose and hard-to-read, so we recommend using `NfcManager.requestTechnology` instead of `NfcManager.registerTagEvent` in your application. - -## Advanced Usage Concept - -In higher level, there're 4 steps to use this library: +## Nfc Compatibility -1. request your particular NFC technologies through `NfcManager.requestTechnology`, for example: + - - `Ndef` - - `NfcA` - - `NfcB` (Android-only) - - `NfcF` (Android-only) - - `NfcV` (Android-only) - - `IsoDep` - - `MifareClassic` (Android-only) - - `MifareUltralight` (Android-only) - - `MifareIOS` (ios-only) - - `Iso15693IOS` (ios-only) - - `FelicaIOS` (ios-only) +|NFC Technologies | Android | iOS | +|--- |--- |--- | +| `Ndef` | ✅ | ✅ | +| `NfcA` | ✅ | ✅ | +| `IsoDep` | ✅ | ✅ | +| `NfcB` | ✅ | ❌ | +| `NfcF` | ✅ | ❌ | +| `NfcV` | ✅ | ❌ | +| `MifareClassic` | ✅ | ❌ | +| `MifareUltralight`| ✅ | ❌ | +| `MifareIOS` | ❌ | ✅ | +| `Iso15693IOS` | ❌ | ✅ | +| `FelicaIOS` | ❌ | ✅ | -2. select the proper NFC technology handler, which is implemented as getter in main `NfcManager` object, for example: +## Usage concept - - `ndefHandler` (for `Ndef` tech) - - `nfcAHandler` (for `NfcA` tech) - - `isoDepHandler` (for `IsoDep` tech) - - `iso15693HandlerIOS` (for `Iso15693IOS` tech) - - `mifareClassicHandlerAndroid` (for `mifareClassic` tech) - - `mifareUltralightHandlerAndroid` (for `mifareUltralight` tech) - - ... and so on + -3. call specific methods on the NFC technology handler (for example `NfcManager.ndefHandler.writeNdefMessage`). To view all available methods for some tech handler, check out the [API List](index.d.ts) +In higher level, there're 4 steps to use this library: -4. clean up your tech registration through `NfcManager.cancelTechnology` +0. (Recommended but not necessary) Before all next steps, use `NfcManager.start()` to start listen a tag. -## Advanced Usage Example: NDEF-Writing -For example, here's an example to write NDEF: +1. Request your particular NFC technologies through `NfcManager.requestTechnology`. Let's request `Ndef` techonogy. ```javascript -import NfcManager, {NfcTech, Ndef} from 'react-native-nfc-manager'; - -async function writeNdef({type, value}) { - let result = false; +NfcManager.requestTechnology(NfcTech.Ndef); +``` - try { - // STEP 1 - await NfcManager.requestTechnology(NfcTech.Ndef); +2. Select the proper NFC technology handler, which is implemented as getter in main `NfcManager` object. - const bytes = Ndef.encodeMessage([Ndef.textRecord('Hello NFC')]); +```javascript +NfcManager.ndefHandler +``` - if (bytes) { - await NfcManager.ndefHandler // STEP 2 - .writeNdefMessage(bytes); // STEP 3 - result = true; - } - } catch (ex) { - console.warn(ex); - } finally { - // STEP 4 - NfcManager.cancelTechnologyRequest(); - } +3. Call specific methods on the NFC technology handler. - return result; -} +```javascript +NfcManager.ndefHandler.getNdefMessage() ``` -## Advanced Usage Example: Mifare Ultralight - -Here's another example to read a Mifare Ultralight tag: +4. Clean up your tech registration through: ```javascript -async function readMifare() { - let mifarePages = []; - - try { - // STEP 1 - let reqMifare = await NfcManager.requestTechnology( - NfcTech.MifareUltralight, - ); - - const readLength = 60; - const mifarePagesRead = await Promise.all( - [...Array(readLength).keys()].map(async (_, i) => { - const pages = await NfcManager.mifareUltralightHandlerAndroid // STEP 2 - .mifareUltralightReadPages(i * 4); // STEP 3 - mifarePages.push(pages); - }), - ); - } catch (ex) { - console.warn(ex); - } finally { - // STEP 4 - NfcManager.cancelTechnologyRequest(); - } - - return mifarePages; -} +NfcManager.cancelTechnologyRequest() ``` -To see more examples, please see [React Native NFC ReWriter App](https://github.com/revtel/react-native-nfc-rewriter) ## API -Please see [here](index.d.ts) + -## FAQ +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. -Please see [here](FAQ.md) +|NFC Technologies | Handlers | +|--- |--- | +| `Ndef` | `NdefHandler` | +| `NfcA` | `NfcAHandler` | +| `IsoDep` | `IsoDepHandler` | +| `NfcB` | - | +| `NfcF` | - | +| `NfcV` | `NfcVHandler` | +| `MifareClassic` | `MifareClassicHandlerAndroid` | +| `MifareUltralight`| `MifareUltralightHandlerAndroid` | +| `MifareIOS` | - | +| `Iso15693IOS` | `Iso15693HandlerIOS` | +| `FelicaIOS` | - | -## Expo -> This package cannot be used in the "Expo Go" app because [it requires custom native code](https://docs.expo.io/workflow/customizing/). +## App Demo - NfcOpenReWriter -After installing this npm package, add the [config plugin](https://docs.expo.io/guides/config-plugins/) to the [`plugins`](https://docs.expo.io/versions/latest/config/app/#plugins) array of your `app.json` or `app.config.js`: + -```json -{ - "expo": { - "plugins": ["react-native-nfc-manager"] - } -} -``` +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) -Next, rebuild your app as described in the ["Adding custom native code"](https://docs.expo.io/workflow/customizing/) guide. + +react-native-nfc-rewriter + -> Notice: This Config Plugin will ensure the minimum Android SDK version is 31. +
-#### Props + +react-native-nfc-rewriter + -The plugin provides props for extra customization. Every time you change the props or plugins, you'll need to rebuild (and `prebuild`) the native app. If no extra properties are added, defaults will be used. +## Learn -- `nfcPermission` (_string | false_): Sets the iOS `NFCReaderUsageDescription` permission message to the `Info.plist`. Setting `false` will skip adding the permission. Defaults to `Allow $(PRODUCT_NAME) to interact with nearby NFC devices` (Info.plist). -- `selectIdentifiers` (_string[]_): Sets the iOS [`com.apple.developer.nfc.readersession.iso7816.select-identifiers`](https://developer.apple.com/documentation/bundleresources/information_property_list/select-identifiers) to a list of supported application IDs (Info.plist). -- `systemCodes` (_string[]_): Sets the iOS [`com.apple.developer.nfc.readersession.felica.systemcodes`](https://developer.apple.com/documentation/bundleresources/information_property_list/systemcodes) to a user provided list of FeliCa™ system codes that the app supports (Info.plist). Each system code must be a discrete value. The wild card value (`0xFF`) isn't allowed. -- `includeNdefEntitlement` (true | false): When explicitly set to false, removes the NDEF entitlement as a workaround to [asset validation invalid entitlement bug](https://stackoverflow.com/questions/58131299/xcode-testflight-validate-error-itms-90778-ndef-is-disallowed). + -#### Example +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) -```json -{ - "expo": { - "plugins": [ - [ - "react-native-nfc-manager", - { - "nfcPermission": "Custom permission message", - "selectIdentifiers": ["A0000002471001"], - "systemCodes": ["8008"], - "includeNdefEntitlement": false, - } - ] - ] - } -} -``` diff --git a/FAQ.md b/docs/FAQ.md similarity index 100% rename from FAQ.md rename to docs/FAQ.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..80de92c --- /dev/null +++ b/docs/README.md @@ -0,0 +1,17 @@ +# Documentation + +## Table of Contents + +1. [Setup](#setup) +2. [Documentation](#docs) +3. [Nfc compatibility](#nfcCompatibility) +4. [Usage Concept](#usageConcept) +5. [API](#api) +6. [App demo](#appDemo) +7. [Learn](#learn) + +## Setup + + + + diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..51f5fc7 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,68 @@ + +## Advanced Usage Example: NDEF-Writing + +For example, here's an example to write NDEF: + +```javascript +import NfcManager, {NfcTech, Ndef} from 'react-native-nfc-manager'; + +async function writeNdef({type, value}) { + let result = false; + + try { + // STEP 1 + await NfcManager.requestTechnology(NfcTech.Ndef); + + const bytes = Ndef.encodeMessage([Ndef.textRecord('Hello NFC')]); + + if (bytes) { + await NfcManager.ndefHandler // STEP 2 + .writeNdefMessage(bytes); // STEP 3 + result = true; + } + } catch (ex) { + console.warn(ex); + } finally { + // STEP 4 + NfcManager.cancelTechnologyRequest(); + } + + return result; +} +``` + +## Advanced Usage Example: Mifare Ultralight + +Here's another example to read a Mifare Ultralight tag: + +```javascript +async function readMifare() { + let mifarePages = []; + + try { + // STEP 1 + let reqMifare = await NfcManager.requestTechnology( + NfcTech.MifareUltralight, + ); + + const readLength = 60; + const mifarePagesRead = await Promise.all( + [...Array(readLength).keys()].map(async (_, i) => { + const pages = await NfcManager.mifareUltralightHandlerAndroid // STEP 2 + .mifareUltralightReadPages(i * 4); // STEP 3 + mifarePages.push(pages); + }), + ); + } catch (ex) { + console.warn(ex); + } finally { + // STEP 4 + NfcManager.cancelTechnologyRequest(); + } + + return mifarePages; +} +``` + +To see more examples, please see [React Native NFC ReWriter App](https://github.com/revtel/react-native-nfc-rewriter) + diff --git a/docs/expoGo.md b/docs/expoGo.md new file mode 100644 index 0000000..211c7a7 --- /dev/null +++ b/docs/expoGo.md @@ -0,0 +1,48 @@ + + +## Expo + +> This package cannot be used in the "Expo Go" app because [it requires custom native code](https://docs.expo.io/workflow/customizing/). + +After installing this npm package, add the [config plugin](https://docs.expo.io/guides/config-plugins/) to the [`plugins`](https://docs.expo.io/versions/latest/config/app/#plugins) array of your `app.json` or `app.config.js`: + +```json +{ + "expo": { + "plugins": ["react-native-nfc-manager"] + } +} +``` + +Next, rebuild your app as described in the ["Adding custom native code"](https://docs.expo.io/workflow/customizing/) guide. + +> Notice: This Config Plugin will ensure the minimum Android SDK version is 31. + +#### Props + +The plugin provides props for extra customization. Every time you change the props or plugins, you'll need to rebuild (and `prebuild`) the native app. If no extra properties are added, defaults will be used. + +- `nfcPermission` (_string | false_): Sets the iOS `NFCReaderUsageDescription` permission message to the `Info.plist`. Setting `false` will skip adding the permission. Defaults to `Allow $(PRODUCT_NAME) to interact with nearby NFC devices` (Info.plist). +- `selectIdentifiers` (_string[]_): Sets the iOS [`com.apple.developer.nfc.readersession.iso7816.select-identifiers`](https://developer.apple.com/documentation/bundleresources/information_property_list/select-identifiers) to a list of supported application IDs (Info.plist). +- `systemCodes` (_string[]_): Sets the iOS [`com.apple.developer.nfc.readersession.felica.systemcodes`](https://developer.apple.com/documentation/bundleresources/information_property_list/systemcodes) to a user provided list of FeliCa™ system codes that the app supports (Info.plist). Each system code must be a discrete value. The wild card value (`0xFF`) isn't allowed. +- `includeNdefEntitlement` (true | false): When explicitly set to false, removes the NDEF entitlement as a workaround to [asset validation invalid entitlement bug](https://stackoverflow.com/questions/58131299/xcode-testflight-validate-error-itms-90778-ndef-is-disallowed). + +#### Example + +```json +{ + "expo": { + "plugins": [ + [ + "react-native-nfc-manager", + { + "nfcPermission": "Custom permission message", + "selectIdentifiers": ["A0000002471001"], + "systemCodes": ["8008"], + "includeNdefEntitlement": false, + } + ] + ] + } +} +``` diff --git a/docs/oldMethod.md b/docs/oldMethod.md new file mode 100644 index 0000000..b380b77 --- /dev/null +++ b/docs/oldMethod.md @@ -0,0 +1,39 @@ +### Old Style (registerTagEvent) To Scan NFC Tags + +There's an alterntaive style to scan NFC tags through `NfcManager.registerTagEvent`, like this: + +```javascript +import NfcManager, {NfcTech} from 'react-native-nfc-manager'; + +// The following function resolves to a NFC Tag object using old event listener approach. +// You can call it like this: +// `const nfcTag = await listenToNfcEventOnce()` + +function listenToNfcEventOnce() { + const cleanUp = () => { + NfcManager.setEventListener(NfcEvents.DiscoverTag, null); + NfcManager.setEventListener(NfcEvents.SessionClosed, null); + }; + + return new Promise((resolve) => { + let tagFound = null; + + NfcManager.setEventListener(NfcEvents.DiscoverTag, (tag) => { + tagFound = tag; + resolve(tagFound); + NfcManager.unregisterTagEvent(); + }); + + NfcManager.setEventListener(NfcEvents.SessionClosed, () => { + cleanUp(); + if (!tagFound) { + resolve(); + } + }); + + NfcManager.registerTagEvent(); + }); +} +``` + +As you can see, the above approach is more verbose and hard-to-read, so we recommend using `NfcManager.requestTechnology` instead of `NfcManager.registerTagEvent` in your application. \ No newline at end of file diff --git a/setup.md b/docs/setup.md similarity index 71% rename from setup.md rename to docs/setup.md index ff5c5a4..91d7a8c 100644 --- a/setup.md +++ b/docs/setup.md @@ -47,3 +47,24 @@ Simple add `uses-permission` into your `AndroidManifest.xml`: ```xml ``` + +### **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. From 41a9ab2919760b36dae8d55685d9d241d23ff45d Mon Sep 17 00:00:00 2001 From: javix64 Date: Wed, 15 Mar 2023 17:05:16 +0100 Subject: [PATCH 2/2] [DOC] Remove unnecesary folder docs --- docs/FAQ.md | 28 ------------------- docs/README.md | 17 ------------ docs/examples.md | 68 --------------------------------------------- docs/expoGo.md | 48 -------------------------------- docs/oldMethod.md | 39 -------------------------- docs/setup.md | 70 ----------------------------------------------- 6 files changed, 270 deletions(-) delete mode 100644 docs/FAQ.md delete mode 100644 docs/README.md delete mode 100644 docs/examples.md delete mode 100644 docs/expoGo.md delete mode 100644 docs/oldMethod.md delete mode 100644 docs/setup.md diff --git a/docs/FAQ.md b/docs/FAQ.md deleted file mode 100644 index d0ffde9..0000000 --- a/docs/FAQ.md +++ /dev/null @@ -1,28 +0,0 @@ -# FAQ - -## [iOS] cannot write NDEF into NFC tags - -iOS won't allow writing NDEF into un-formatted tags, so you should first format your tags. For type 2 tags (most NTAG2xx), you can use an app like NFC Tools or NXP Tag Writer to do perform formatting. - -> It's possible to implement the NDEF formatting ourself through this library, here's an [example](https://github.com/revtel/react-native-nfc-rewriter/tree/naive-ndef-format). However, it's actually an naive approach, since we don't handle the case if the tag is already formatted and we provide no extra lock / memory information before NDEF TLV, so use this code snippet with cautions. - -## [iOS] cannot read NDEF from NFC tags - -The same as above, please check if the tag is properly formatted, and contain at least 1 NdefMessage -* This NdefMessage can contain only one NdefRecord as [TNF_EMPTY](https://developer.android.com/reference/android/nfc/NdefRecord#TNF_EMPTY) - -## [iOS] cannot read / write Mifare Classic - -Indeed, currently MifareClassic isn't supported by Core NFC in our tests. It is also not listed in Core NFC's [NFCMiFareFamily](https://developer.apple.com/documentation/corenfc/nfcmifarefamily?language=objc) - -## [Android] My NFC tag cannot launch my app - -Note on getLaunchTagEvent: keep in mind that you can only create intent-filters for the very first NDEF record on an NFC tag! If your intent-filter doesn't match the FIRST record your app will launch but it won't get the tag data. Check out for details: -https://stackoverflow.com/questions/25504418/get-nfc-tag-with-ndef-android-application-record-aar/25510642 - -Also you should add -```xml -android:launchMode="singleTask" -``` -to your manifest to prevent launching your app as another task when it is already running. - diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 80de92c..0000000 --- a/docs/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# Documentation - -## Table of Contents - -1. [Setup](#setup) -2. [Documentation](#docs) -3. [Nfc compatibility](#nfcCompatibility) -4. [Usage Concept](#usageConcept) -5. [API](#api) -6. [App demo](#appDemo) -7. [Learn](#learn) - -## Setup - - - - diff --git a/docs/examples.md b/docs/examples.md deleted file mode 100644 index 51f5fc7..0000000 --- a/docs/examples.md +++ /dev/null @@ -1,68 +0,0 @@ - -## Advanced Usage Example: NDEF-Writing - -For example, here's an example to write NDEF: - -```javascript -import NfcManager, {NfcTech, Ndef} from 'react-native-nfc-manager'; - -async function writeNdef({type, value}) { - let result = false; - - try { - // STEP 1 - await NfcManager.requestTechnology(NfcTech.Ndef); - - const bytes = Ndef.encodeMessage([Ndef.textRecord('Hello NFC')]); - - if (bytes) { - await NfcManager.ndefHandler // STEP 2 - .writeNdefMessage(bytes); // STEP 3 - result = true; - } - } catch (ex) { - console.warn(ex); - } finally { - // STEP 4 - NfcManager.cancelTechnologyRequest(); - } - - return result; -} -``` - -## Advanced Usage Example: Mifare Ultralight - -Here's another example to read a Mifare Ultralight tag: - -```javascript -async function readMifare() { - let mifarePages = []; - - try { - // STEP 1 - let reqMifare = await NfcManager.requestTechnology( - NfcTech.MifareUltralight, - ); - - const readLength = 60; - const mifarePagesRead = await Promise.all( - [...Array(readLength).keys()].map(async (_, i) => { - const pages = await NfcManager.mifareUltralightHandlerAndroid // STEP 2 - .mifareUltralightReadPages(i * 4); // STEP 3 - mifarePages.push(pages); - }), - ); - } catch (ex) { - console.warn(ex); - } finally { - // STEP 4 - NfcManager.cancelTechnologyRequest(); - } - - return mifarePages; -} -``` - -To see more examples, please see [React Native NFC ReWriter App](https://github.com/revtel/react-native-nfc-rewriter) - diff --git a/docs/expoGo.md b/docs/expoGo.md deleted file mode 100644 index 211c7a7..0000000 --- a/docs/expoGo.md +++ /dev/null @@ -1,48 +0,0 @@ - - -## Expo - -> This package cannot be used in the "Expo Go" app because [it requires custom native code](https://docs.expo.io/workflow/customizing/). - -After installing this npm package, add the [config plugin](https://docs.expo.io/guides/config-plugins/) to the [`plugins`](https://docs.expo.io/versions/latest/config/app/#plugins) array of your `app.json` or `app.config.js`: - -```json -{ - "expo": { - "plugins": ["react-native-nfc-manager"] - } -} -``` - -Next, rebuild your app as described in the ["Adding custom native code"](https://docs.expo.io/workflow/customizing/) guide. - -> Notice: This Config Plugin will ensure the minimum Android SDK version is 31. - -#### Props - -The plugin provides props for extra customization. Every time you change the props or plugins, you'll need to rebuild (and `prebuild`) the native app. If no extra properties are added, defaults will be used. - -- `nfcPermission` (_string | false_): Sets the iOS `NFCReaderUsageDescription` permission message to the `Info.plist`. Setting `false` will skip adding the permission. Defaults to `Allow $(PRODUCT_NAME) to interact with nearby NFC devices` (Info.plist). -- `selectIdentifiers` (_string[]_): Sets the iOS [`com.apple.developer.nfc.readersession.iso7816.select-identifiers`](https://developer.apple.com/documentation/bundleresources/information_property_list/select-identifiers) to a list of supported application IDs (Info.plist). -- `systemCodes` (_string[]_): Sets the iOS [`com.apple.developer.nfc.readersession.felica.systemcodes`](https://developer.apple.com/documentation/bundleresources/information_property_list/systemcodes) to a user provided list of FeliCa™ system codes that the app supports (Info.plist). Each system code must be a discrete value. The wild card value (`0xFF`) isn't allowed. -- `includeNdefEntitlement` (true | false): When explicitly set to false, removes the NDEF entitlement as a workaround to [asset validation invalid entitlement bug](https://stackoverflow.com/questions/58131299/xcode-testflight-validate-error-itms-90778-ndef-is-disallowed). - -#### Example - -```json -{ - "expo": { - "plugins": [ - [ - "react-native-nfc-manager", - { - "nfcPermission": "Custom permission message", - "selectIdentifiers": ["A0000002471001"], - "systemCodes": ["8008"], - "includeNdefEntitlement": false, - } - ] - ] - } -} -``` diff --git a/docs/oldMethod.md b/docs/oldMethod.md deleted file mode 100644 index b380b77..0000000 --- a/docs/oldMethod.md +++ /dev/null @@ -1,39 +0,0 @@ -### Old Style (registerTagEvent) To Scan NFC Tags - -There's an alterntaive style to scan NFC tags through `NfcManager.registerTagEvent`, like this: - -```javascript -import NfcManager, {NfcTech} from 'react-native-nfc-manager'; - -// The following function resolves to a NFC Tag object using old event listener approach. -// You can call it like this: -// `const nfcTag = await listenToNfcEventOnce()` - -function listenToNfcEventOnce() { - const cleanUp = () => { - NfcManager.setEventListener(NfcEvents.DiscoverTag, null); - NfcManager.setEventListener(NfcEvents.SessionClosed, null); - }; - - return new Promise((resolve) => { - let tagFound = null; - - NfcManager.setEventListener(NfcEvents.DiscoverTag, (tag) => { - tagFound = tag; - resolve(tagFound); - NfcManager.unregisterTagEvent(); - }); - - NfcManager.setEventListener(NfcEvents.SessionClosed, () => { - cleanUp(); - if (!tagFound) { - resolve(); - } - }); - - NfcManager.registerTagEvent(); - }); -} -``` - -As you can see, the above approach is more verbose and hard-to-read, so we recommend using `NfcManager.requestTechnology` instead of `NfcManager.registerTagEvent` in your application. \ No newline at end of file diff --git a/docs/setup.md b/docs/setup.md deleted file mode 100644 index 91d7a8c..0000000 --- a/docs/setup.md +++ /dev/null @@ -1,70 +0,0 @@ -## iOS - -1. In [apple developer site](https://developer.apple.com/), enable capability for NFC - -![enable capability](./images/enable-capability.png "enable capability") - -2. in Xcode, add `NFCReaderUsageDescription` into your `info.plist`, for example: - -``` -NFCReaderUsageDescription -We need to use NFC -``` - -More info on Apple's [doc](https://developer.apple.com/documentation/bundleresources/information_property_list/nfcreaderusagedescription?language=objc) - -Additionally, if writing ISO7816 tags add application identifiers (aid) into your `info.plist` as needed like this. -``` -com.apple.developer.nfc.readersession.iso7816.select-identifiers - - D2760000850100 - D2760000850101 - -``` - -More info on Apple's [doc](https://developer.apple.com/documentation/corenfc/nfciso7816tag) - -An incomplete list of aid's can be found here. [Application identifier](https://www.eftlab.com/knowledge-base/211-emv-aid-rid-pix/) - -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") - -If this is the first time you toggle the capabilities, the Xcode will generate a `.entitlement` file for you: - -![xcode-add-entitlement](./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") - -More info on Apple's [doc](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_nfc_readersession_formats?language=objc) - -## Android - -Simple add `uses-permission` into your `AndroidManifest.xml`: - -```xml - -``` - -### **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.