react-native-nfc-manager
Bring NFC feature to React Native. Inspired by phonegap-nfc and react-native-ble-manager
Contributions are welcome!
Made with ❤️ by whitedogg13 and revteltech
Install
javascript part
npm i --save react-native-nfc-manager
native part
This library use native-modules, so you will need to do pod install
for iOS:
cd ios && pod install && cd ..
For Android, it should be properly auto-linked, so you don't need to do anything.
Setup
Please see here
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 which says Starting with Build.VERSION_CODES.S, it will be required to explicitly specify the mutability of PendingIntents
The original issue is here
BTW, 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.
It also open sourced in this repo: React Native NFC ReWriter App
Learn
We have published a React Native NFC course with newline.co, check it out!
- Free course (1 hour) about basic NFC setup and concept here
- Full course (3 hours) for more (NDEF, Deep Linking, NTAG password protection, signature with UID) here
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:
import React from 'react';
import {View, Text, TouchableOpacity, StyleSheet} from 'react-native';
import NfcManager, {NfcTech} from 'react-native-nfc-manager';
NfcManager.start();
function App() {
async function readNdef() {
try {
await NfcManager.requestTechnology(NfcTech.Ndef);
const tag = await NfcManager.getTag();
console.warn('Tag found', tag);
} catch (ex) {
console.warn('Oops!', ex);
} finally {
NfcManager.cancelTechnologyRequest();
}
}
return (
<View style={styles.wrapper}>
<TouchableOpacity onPress={readNdef}>
<Text>Scan a Tag</Text>
</TouchableOpacity>
</View>
);
}
const styles = StyleSheet.create({
wrapper: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
},
});
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.
Old Style (registerTagEvent) To Scan NFC Tags
There's an alterntaive style to scan NFC tags through NfcManager.registerTagEvent
, like this:
import NfcManager, {NfcTech} from 'react-native-nfc-manager';
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:
-
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)
-
select the proper NFC technology handler, which is implemented as getter in main NfcManager
object, for example:
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
-
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
-
clean up your tech registration through NfcManager.cancelTechnology
Advanced Usage Example: NDEF-Writing
For example, here's an example to write NDEF:
import NfcManager, {NfcTech, Ndef} from 'react-native-nfc-manager';
async function writeNdef({type, value}) {
let result = false;
try {
await NfcManager.requestTechnology(NfcTech.Ndef);
const bytes = Ndef.encodeMessage([Ndef.textRecord('Hello NFC')]);
if (bytes) {
await NfcManager.ndefHandler
.writeNdefMessage(bytes);
result = true;
}
} catch (ex) {
console.warn(ex);
} finally {
NfcManager.cancelTechnologyRequest();
}
return result;
}
Advanced Usage Example: Mifare Ultralight
Here's another example to read a Mifare Ultralight tag:
async function readMifare() {
let mifarePages = [];
try {
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
.mifareUltralightReadPages(i * 4);
mifarePages.push(pages);
}),
);
} catch (ex) {
console.warn(ex);
} finally {
NfcManager.cancelTechnologyRequest();
}
return mifarePages;
}
To see more examples, please see React Native NFC ReWriter App
API
Please see here
FAQ
Please see here
Expo
This package cannot be used in the "Expo Go" app because it requires custom native code.
After installing this npm package, add the config plugin to the plugins
array of your app.json
or app.config.js
:
{
"expo": {
"plugins": ["react-native-nfc-manager"]
}
}
Next, rebuild your app as described in the "Adding custom native code" 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
to a list of supported application IDs (Info.plist).systemCodes
(string[]): Sets the iOS com.apple.developer.nfc.readersession.felica.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.
Example
{
"expo": {
"plugins": [
[
"react-native-nfc-manager",
{
"nfcPermission": "Custom permission message",
"selectIdentifiers": ["A0000002471001"],
"systemCodes": ["8008"]
}
]
]
}
}