@icedevml/react-native-host-card-emulation 0.7.1 → 0.8.0

package/README.md

@@ -3,7 +3,7 @@
 Host Card Emulation Module for React Native on iOS and Android platforms.
 
 > [!NOTE]
-> Pull requests are welcome! Please [report an issue](https://github.com/icedevml/react-native-host-card-emulation/issues) if you are running into any difficulties.
+> Pull requests are welcome! Please [report an issue](https://github.com/icedevml/react-native-host-card-emulation/issues) if you encounter any difficulties.
 
 > [!IMPORTANT]  
 > As per Apple's policy, **Host Card Emulation feature is only available for users based in the European
@@ -121,7 +121,7 @@ This module provides a uniform low-level HCE API for both mobile platforms.
 > Check it out in order to understand what methods you can call against the module and what are the expected parameters/return values.
 
 > [!NOTE]
-> See [Source Code for Demo Application: NDEF NFC Type 4 Tag Emulator (for iOS/Android)](https://github.com/icedevml/react-native-host-card-emulation/tree/master/packages/demo-ndef-app) example for more insignt about the library's API.
+> See [Source Code for Demo Application: NDEF NFC Type 4 Tag Emulator (for iOS/Android)](https://github.com/icedevml/react-native-host-card-emulation/tree/master/packages/demo-ndef-app) example for more insights about the library's API.
 
 ### Quick start guide
 
@@ -140,7 +140,7 @@ This module provides a uniform low-level HCE API for both mobile platforms.
        }
    }, []);
    ```
-2. When user indicates that he/she wants to perform the HCE action, call the following function from the button's onClick routine:
+2. When the user indicates that he/she wants to perform the HCE action, call the following function from the button's onClick routine:
    ```typescript
    await NativeHCEModule.beginSession();
    ```
@@ -163,8 +163,8 @@ This module provides a uniform low-level HCE API for both mobile platforms.
        break;
 
     case 'readerDeselected':
-        NativeHCEModule.setSessionAlertMessage('Lost reader');  // only for iOS, no-op in Android
-        break;
+       NativeHCEModule.setSessionAlertMessage('Lost reader');  // only for iOS, no-op in Android
+       break;
    ```
    For those events, trigger mechanisms are platform dependent:
    * iOS: The `readerDetected` event will be emitted as soon as the NFC reader's field presence is observed. The `readerDeselected` event will be emitted if the reader is physically disconnected or a non-matching AID is selected by the reader.
@@ -191,7 +191,7 @@ If you need to utilize `NFCPresentmentIntentAssertion` for enhanced user experie
 ```typescript
 await NativeHCEModule.acquireExclusiveNFC();
 ```
-This function will acquire an exclusive NFC access for 15 seconds. On system services or other applications will be able to interfere with NFC during that period. For example, the NFC background tag reading will be disabled so it would not generate any distracting notifications.
+This function will acquire an exclusive NFC access for 15 seconds. No system services or other applications will be able to interfere with NFC during that period. For example, the NFC background tag reading will be disabled so it would not generate any distracting notifications.
 
 While both session and exclusive NFC access are active, you will receive `readerDetected` events even when the HCE emulation is not started at the time (without any explicit UI being displayed by the system). You can then make a call to `startHCE` to initiate the interaction automatically, without needing the user to click anything beforehand.
 
@@ -240,7 +240,7 @@ for instance - your app may emulate an NDEF tag even when it's not launched on t
       }
    });
    ```
-2. Register onBackgroundEvent listener in your `runBackground()` function and call to `await NativeHCEModule.initBackgroundHCE()` at the very end, after the event listener is fully set up.
+2. Implement your background HCE handler by passing an event callback to `processBackgroundHCE()`:
    ```typescript
    import { Buffer } from 'buffer/';
    import {
@@ -248,6 +248,8 @@ for instance - your app may emulate an NDEF tag even when it's not launched on t
    } from '@icedevml/react-native-host-card-emulation/js/hceBackground';
 
    export default async function runBackgroundHCETask(processBackgroundHCE: ProcessBackgroundHCEFunc) {
+      // ... initialize any state keeping variables here ...
+
       processBackgroundHCE(async (event, respondAPDU) => {
          switch (event.type) {
             /* ... background HCE event handler here ... */
@@ -255,7 +257,7 @@ for instance - your app may emulate an NDEF tag even when it's not launched on t
       });
    }
    ```
-3. Cleanup your event listener in `readerDeselected` -- this is obligatory because lack of proper cleanup will result in bugs and unexpected behavior.
+3. Whenever you receive `readerDeselected` event, cleanup any side effects (deallocate resources, reset the state back to initial) -- this is obligatory because lack of proper cleanup will result in bugs and unexpected behavior.
    ```typescript
    // inside processBackgroundHCE handler's switch
    case 'readerDeselected':
@@ -276,6 +278,14 @@ for instance - your app may emulate an NDEF tag even when it's not launched on t
        break;
    ```
 
+> [!WARNING]
+> Please note that under some circumstances you might find that your `runBackgroundHCETask()` is running in a few instances concurrently.
+> An example of such situation could be when you receive a C-APDU and the reader rapidly restarts the NFC field and reselects your application
+> before you manage to respond to the original command. Thus, you should not use any global variables to track the state of your app.
+>
+> The library automatically identifies stale (deselected) background tasks. For such stale tasks, any subsequent calls to `await respondAPDU()`
+> will throw an error to prevent communication glitches.
+
 ### More resources
 
 * [Module's API specification](https://github.com/icedevml/react-native-host-card-emulation/tree/master/packages/host-card-emulation/js)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icedevml/react-native-host-card-emulation",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Host Card Emulation (HCE) React Native Turbo Module for iOS and Android platforms.",
   "react-native": "js/index",
   "source": "js/index",