@icedevml/react-native-host-card-emulation 0.7.0 → 0.7.2

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
@@ -117,11 +117,11 @@ Afterwards, follow the subsections below for each platform that you need to supp
 This module provides a uniform low-level HCE API for both mobile platforms.
 
 > [!NOTE]
-> Raw native module's API specification is available in [packages/host-card-emulation/js](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/host-card-emulation/js) subdirectory.
+> Raw native module's API specification is available in [packages/host-card-emulation/js](https://github.com/icedevml/react-native-host-card-emulation/tree/master/packages/host-card-emulation/js) subdirectory.
 > 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 [Demo App's Code (Example Library Usage)](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/demo-ndef-app/App.tsx) 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.
 
@@ -200,12 +200,29 @@ This function will throw an exception if:
 * you are in the cooldown period where you are not allowed to acquire the presentment intent assertion (cooldown is 15 seconds after the previous assertion had expired);
 * the feature is not supported or the device is not eligible for whatever reason;
 
+You can check if you are holding an exclusive NFC access by calling:
+```typescript
+NativeHCEModule.isExclusiveNFC()
+```
+
 Whenever you don't need the exclusive NFC access anymore, call the following function to release the `NFCPresentmentIntentAssertion` object:
 ```typescript
-await NativeHCEModule.releaseExclusiveNFC();
+NativeHCEModule.releaseExclusiveNFC();
 ```
 
-Call `NativeHCEModule.isExclusiveNFC()` to check if exclusive NFC access is still active.
+> [!TIP]
+> Your exclusive NFC access might time out after exceeding certain allowance period imposed by iOS. Thus, you should periodically poll
+> the `NativeHCEModule.isExclusiveNFC()` value to see if it's still granted. You might decide to navigate into a different UI view
+> once your assertion has timed out, or indicate that in some different way.
+
+> [!TIP]
+> Use the React's [AppState](https://reactnative.dev/docs/appstate) listener to see when your app goes out to background.
+> In such event, call `NativeHCEModule.releaseExclusiveNFC()` to explicitly release the exclusive NFC assertion.
+>
+> You must do so in order to avoid running into ambigous states, since the operating system is not going to enforce your
+> exclusive NFC access anyway, as your app has gone to background.
+> 
+> You can attempt to acquire the exclusive access assertion again once your app has gone back to foreground (active state).
 
 ### Android: Handle HCE calls when the app is not running
 
@@ -223,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 {
@@ -231,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 ... */
@@ -238,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':
@@ -259,7 +278,15 @@ 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/blob/master/packages/host-card-emulation/js)
-* [Demo App's Code (Example Library Usage)](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/demo-ndef-app/App.tsx)
+* [Module's API specification](https://github.com/icedevml/react-native-host-card-emulation/tree/master/packages/host-card-emulation/js)
+* [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)

package/package.json

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