{"id":27224872,"url":"https://github.com/appidea/react-native-hce","last_synced_at":"2025-04-10T10:35:12.788Z","repository":{"id":54446004,"uuid":"298279041","full_name":"appidea/react-native-hce","owner":"appidea","description":"Emulate smart cards inside React-Native application.","archived":false,"fork":false,"pushed_at":"2024-02-08T01:13:15.000Z","size":1273,"stargazers_count":83,"open_issues_count":11,"forks_count":27,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-21T06:18:38.919Z","etag":null,"topics":["hce","nfc","react","react-native"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/appidea.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-24T12:56:03.000Z","updated_at":"2025-03-20T13:44:06.000Z","dependencies_parsed_at":"2024-06-18T22:48:57.242Z","dependency_job_id":"f2340f6f-207c-4a01-a75b-acdaa0d79ddb","html_url":"https://github.com/appidea/react-native-hce","commit_stats":{"total_commits":45,"total_committers":4,"mean_commits":11.25,"dds":0.06666666666666665,"last_synced_commit":"f1d0e9d140d3d916d347b04d808d2bcc2b72de17"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appidea%2Freact-native-hce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appidea%2Freact-native-hce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appidea%2Freact-native-hce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appidea%2Freact-native-hce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appidea","download_url":"https://codeload.github.com/appidea/react-native-hce/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248199247,"owners_count":21063641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hce","nfc","react","react-native"],"created_at":"2025-04-10T10:35:11.892Z","updated_at":"2025-04-10T10:35:12.767Z","avatar_url":"https://github.com/appidea.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://react-native-hce.appidea.pl/logo.png\" alt=\"React Native HCE\"\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003ereact-native-hce\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003ci\u003e\n    Adds Host card emulation (HCE) capabilities to React Native\n  \u003c/i\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://react-native-hce.appidea.pl\" target=\"_blank\"\u003ereact-native-hce.appidea.pl\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n![Tag](https://img.shields.io/github/v/tag/appidea/react-native-hce)\n[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/appidea/react-native-hce/graphs/commit-activity)\n[![Last commit](https://img.shields.io/github/last-commit/appidea/react-native-hce)](https://github.com/appidea/react-native-hce/graphs/commit-activity)\n\n**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.\nThis package allows the ``react-native`` application to use the adventages of this technology.\n\nFor now, the only out-of-the-box solution provided by this package is:\n\n- NFC Type 4 tag emulation _(Text and URI record types supported)_\n\nanyways, the module's architecture is ready to engage also the new, other usages.\n\n## Architectural overview\n\nCore part of the library (on the native side) is a Service which implements [``HostApduService``](https://developer.android.com/reference/android/nfc/cardemulation/HostApduService) Android interface.\nThe key difference between usual Android services and ``HostApduService`` is the initializer entity.\n``HostApduService`` is initiated by OS - when phone taps the NFC reader. Thus, the Service (and - in the big\npicture - the entire library) has been prepared to the case, when the React\nActivity is in the background or even not available at the time in time of card data transfer.\n\nBecause of this special behavior of ``HostApduService``, we have chosen\nthe _\"declarativeness over interactivity\"_ approach in the architecture design.\nTo make the transactions stable and reliable, library stores the state\non the Native side (in Android, the data are stored in ``SharedPreferences``). The application can specify\nthe available data in advance, to store it to native memory right away and\npass it efficiently to the Service, if needed. Also, the Service can pass the data to a storage\nwithout considering the presence of JS thread. React app can grab the saved data later on.\n\nOf course, all of this synchronization operations are handled in the React part of the library,\nso the end user can control the entire HCE session with convenient abstraction - the ``HCEService`` class.\nThe library also provides the convenient wrapper that binds the HCEService with React application lifecycle using the\n\"Contexts\" feature of React.js.\n\n\n## Important notes\n\n- Currenlty supported **only on the Android platform**, as there is no official support for HCE in Apple platform.\n- Required minimum SDK version is **API 21**\n- Be careful __when using this library for transmission of any sensitive data__. This library does not provide\nany 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.\n\n## Installation\n\n```sh\nnpm install react-native-hce --save\n```\n\nor\n\n```sh\nyarn add react-native-hce\n```\n\n...up to Your preferences and project configuration. Autolinking will take care about the rest.\n\n\n## Post-installation steps\n\nAfter the installation, following changes must be made inside the  ``\u003cprojectRoot\u003e/android``:\n\n### aid_list.xml\n\nCreate new file `aid_list.xml` in `\u003cprojectRoot\u003e/android/app/src/main/res/xml` directory. Create the directory, if it does not exist yet.\n\n- Put the following content to the file:\n\n```xml\n\u003chost-apdu-service xmlns:android=\"http://schemas.android.com/apk/res/android\"\n                   android:description=\"@string/app_name\"\n                   android:requireDeviceUnlock=\"false\"\u003e\n  \u003caid-group android:category=\"other\"\n             android:description=\"@string/app_name\"\u003e\n    \u003c!-- Create a separate \u003caid-filer /\u003e node for each NFC application ID, that You intent to emulate/host. --\u003e\n    \u003c!-- For the NFC Type 4 tag emulation, let's put \"D2760000850101\" --\u003e\n    \u003caid-filter android:name=\"D2760000850101\" /\u003e\n  \u003c/aid-group\u003e\n\u003c/host-apdu-service\u003e\n```\n\n### AndroidManifest.xml\n\nOpen the app's manifest (``\u003cprojectRoot\u003e/android/app/src/main/AndroidManifest.xml``):\n\n- Add permission to use NFC in the application, and add the declaration of usage the HCE feature:\n\n```xml\n\u003cmanifest xmlns:android=\"http://schemas.android.com/apk/res/android\"\n  package=\"com.example.reactnativehce\"\u003e\n\n    \u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n\n    \u003c!-- add the following two nodes: --\u003e\n    \u003cuses-permission android:name=\"android.permission.NFC\" /\u003e\n    \u003cuses-feature android:name=\"android.hardware.nfc.hce\" android:required=\"true\" /\u003e\n    ...\n\n\u003c/manifest\u003e\n```\n\n- 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.\n\n```xml\n\u003capplication\n      android:name=\".MainApplication\"\n      android:label=\"@string/app_name\"\n      android:icon=\"@mipmap/ic_launcher\"\n      android:roundIcon=\"@mipmap/ic_launcher_round\"\n      android:allowBackup=\"false\"\n      android:theme=\"@style/AppTheme\"\u003e\n\n    \u003c!-- ... --\u003e\n\n    \u003c!-- Add the following block: --\u003e\n    \u003cservice\n        android:name=\"com.reactnativehce.services.CardService\"\n        android:exported=\"true\"\n        android:enabled=\"false\"\n        android:permission=\"android.permission.BIND_NFC_SERVICE\" \u003e\n        \u003cintent-filter\u003e\n          \u003caction android:name=\"android.nfc.cardemulation.action.HOST_APDU_SERVICE\" /\u003e\n          \u003ccategory android:name=\"android.intent.category.DEFAULT\"/\u003e\n        \u003c/intent-filter\u003e\n\n        \u003cmeta-data\n          android:name=\"android.nfc.cardemulation.host_apdu_service\"\n          android:resource=\"@xml/aid_list\" /\u003e\n    \u003c/service\u003e\n    \u003c!-- ... --\u003e\n\u003c/application\u003e\n```\n\nThat's it.\n\n## Usage\n\n### API documentation\n\nYou can find the generated documentation on the [project's website](https://react-native-hce.appidea.pl).\n\n### Example application\n\nYou can try out the [example react-native app](example), which presents the usage of this package in practice. The instructions regarding starting up the example application are provided in [Contribution guide](CONTRIBUTING.md).\n\n### NFC Type 4 tag emulation feature\n\nInspired by [underwindfall's](https://github.com/underwindfall) NFC Type 4 tag communication handling used in [NFCAndroid](https://github.com/underwindfall/NFCAndroid).\n\n**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.**\n\nThis is how to enable the NFC Tag emulation:\n\n```js\nimport { HCESession, NFCTagType4NDEFContentType, NFCTagType4 } from 'react-native-hce';\n\nlet session;\n\nconst startSession = async () =\u003e {\n  const tag = new NFCTagType4({\n    type: NFCTagType4NDEFContentType.Text,\n    content: \"Hello world\",\n    writable: false\n  });\n\n  session = await HCESession.getInstance();\n  session.setApplication(tag);\n  await session.setEnabled(true);\n}\n\nstartSession();\n```\n\nstops this way:\n\n```js\nconst stopSession = async () =\u003e {\n  await session.setEnabled(false);\n}\n\nstopSimulation();\n```\n\nIt is possible to listen for events during the emulation:\n\n```js\nconst listen = async () =\u003e {\n  const removeListener = session.on(HCESession.Events.HCE_STATE_READ, () =\u003e {\n    ToastAndroid.show(\"The tag has been read! Thank You.\", ToastAndroid.LONG);\n  });\n\n  // to remove the listener:\n  removeListener();\n}\n\nlisten();\n```\n\nExample application shows also the usage of writable tag feature.\n\n### Other features\n\nThis project is opened for Your ideas. You can contribute to the library and add the other functionalities, if You eager.\n\n## Troubleshooting\n\n- 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...](https://github.com/appidea/react-native-hce/issues/2#issuecomment-1221538916)\n- If You experience the issues when trying to start up the example application, ensure, that You follow the steps described in [contribution guide](CONTRIBUTING.md).\n\n## Development roadmap\n\n- support for more types of NDEF Messages\n- support for writable NFC Tags\n- support for development of custom applications\n\n## Contributing\n\nThis project has been bootstrapped with [Bob](https://github.com/react-native-community/bob.git).\n\nSee the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappidea%2Freact-native-hce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappidea%2Freact-native-hce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappidea%2Freact-native-hce/lists"}