react-native-hce
v0.3.0TypeScript
React Native HCE
0/weekUpdated 6 months agoMITUnpacked: 146.2 KB
Published by Mateusz Falkowski
npm install react-native-hce
react-native-hce
Adds Host card emulation (HCE) capabilities to React Native
---
!Tag
Host Card Emulation is the technology in Android Devices, that let the device act as a host in the NFC communication. This technology can be used, e.g. to simulate the passive smart cards or NFC tags.
This package allows the `react-native application to use the adventages of this technology.
For now, the only out-of-the-box solution provided by this package is:
- NFC Type 4 tag emulation _(Text and URI record types supported)_
anyways, the module's architecture is ready to engage also the new, other usages.
Architectural overview
Core part of the library (on the native side) is a Service which implements HostApduService Android interface.
The key difference between usual Android services and HostApduService is the initializer entity.HostApduService is initiated by OS - when phone taps the NFC reader. Thus, the Service (and - in the big
picture - the entire library) has been prepared to the case, when the React
Activity is in the background or even not available at the time in time of card data transfer.
Because of this special behavior of HostApduService, we have chosen
the _"declarativeness over interactivity"_ approach in the architecture design.
To make the transactions stable and reliable, library stores the state
on the Native side (in Android, the data are stored in SharedPreferences). The application can specify
the available data in advance, to store it to native memory right away and
pass it efficiently to the Service, if needed. Also, the Service can pass the data to a storage
without considering the presence of JS thread. React app can grab the saved data later on.
Of course, all of this synchronization operations are handled in the React part of the library,
so the end user can control the entire HCE session with convenient abstraction - the HCEService class.
The library also provides the convenient wrapper that binds the HCEService with React application lifecycle using the
"Contexts" feature of React.js.
Important notes
- Currenlty supported only on the Android platform, as there is no official support for HCE in Apple platform.
- Required minimum SDK version is API 21
- Be careful __when using this library for transmission of any sensitive data__. This library does not provide
any built-it cryptographic layer, the data are transmitted in plain form. Ensure that You know, what You are doing and take care about any needed ensafements on Your own.
Installation
`sh`
npm install react-native-hce --save
or
`sh`
yarn add react-native-hce
...up to Your preferences and project configuration. Autolinking will take care about the rest.
Post-installation steps
After the installation, following changes must be made inside the :
$3
Create new file aid_list.xml in directory. Create the directory, if it does not exist yet.
- Put the following content to the file:
`xml`
android:requireDeviceUnlock="false">
$3
Open the app's manifest ():
- Add permission to use NFC in the application, and add the declaration of usage the HCE feature:
`xml
...
`
- HCE emulation on the Android platform works as a service. react-native-hce module communicating with this service, so that's why we need to place the reference in AndroidManifest.
`xml
android:label="@string/app_name"
android:icon="@mipmap/ic_launcher"
android:roundIcon="@mipmap/ic_launcher_round"
android:allowBackup="false"
android:theme="@style/AppTheme">
android:exported="true"
android:enabled="false"
android:permission="android.permission.BIND_NFC_SERVICE" >
android:resource="@xml/aid_list" />
`
That's it.
Usage
$3
You can find the generated documentation on the project's website.
$3
You can try out the example react-native app, which presents the usage of this package in practice. The instructions regarding starting up the example application are provided in Contribution guide.
$3
Inspired by underwindfall's NFC Type 4 tag communication handling used in NFCAndroid.
Note! If You want to use this feature, make sure that You added the proper aid to Your aid_list.xml. Otherwise, the app will not handle any signal of NFC reader related with NFC Tags v4.
This is how to enable the NFC Tag emulation:
`js
import { HCESession, NFCTagType4NDEFContentType, NFCTagType4 } from 'react-native-hce';
let session;
const startSession = async () => {
const tag = new NFCTagType4({
type: NFCTagType4NDEFContentType.Text,
content: "Hello world",
writable: false
});
session = await HCESession.getInstance();
session.setApplication(tag);
await session.setEnabled(true);
}
startSession();
`
stops this way:
`js
const stopSession = async () => {
await session.setEnabled(false);
}
stopSimulation();
`
It is possible to listen for events during the emulation:
`js
const listen = async () => {
const removeListener = session.on(HCESession.Events.HCE_STATE_READ, () => {
ToastAndroid.show("The tag has been read! Thank You.", ToastAndroid.LONG);
});
// to remove the listener:
removeListener();
}
listen();
``
Example application shows also the usage of writable tag feature.
$3
This project is opened for Your ideas. You can contribute to the library and add the other functionalities, if You eager.
Troubleshooting
- Ensure, that there is no AID conflict with other HCE-enabled apps. Try to disable all HCE-enabled apps except the Your one. You can do this in Android Settings. See more details...
- If You experience the issues when trying to start up the example application, ensure, that You follow the steps described in contribution guide.
Development roadmap
- support for more types of NDEF Messages
- support for writable NFC Tags
- support for development of custom applications
Contributing
This project has been bootstrapped with Bob.
See the contributing guide to learn how to contribute to the repository and the development workflow.
License
MIT