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

package/README.md

@@ -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 insignt about the library's API.
 
 ### Quick start guide
 
@@ -200,7 +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;
 
-Call `NativeHCEModule.isExclusiveNFC()` to check if exclusive NFC access is still active.
+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
+NativeHCEModule.releaseExclusiveNFC();
+```
+
+> [!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
 
@@ -256,5 +278,5 @@ for instance - your app may emulate an NDEF tag even when it's not launched on t
 
 ### 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/android/src/main/java/com/itsecrnd/rtnhceandroid/RTNHCEAndroidModule.java

@@ -119,6 +119,12 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
         promise.reject("err_platform_unsupported", "acquireExclusiveNFC() is not supported on Android.");
     }
 
+    @Override
+    public void releaseExclusiveNFC() {
+        Log.d(TAG, "RTNHCEAndroidModule:releaseExclusiveNFC");
+        // unsupported on Android, no-op
+    }
+
     @Override
     public boolean isExclusiveNFC() {
         Log.d(TAG, "RTNHCEAndroidModule:isExclusiveNFC");

package/ios/RTNHCEModuleIOS.mm

@@ -50,6 +50,12 @@
     }
 }
 
+- (void)releaseExclusiveNFC {
+    if (@available(iOS 17.4, *)) {
+        [hcemoduleios releaseExclusiveNFC];
+    }
+}
+
 - (nonnull NSNumber *)isExclusiveNFC {
     if (@available(iOS 17.4, *)) {
         return [hcemoduleios isExclusiveNFC] ? @1 : @0;
@@ -90,6 +96,10 @@
     return @0;
 }
 
+- (nonnull NSNumber *)finishBackgroundHCE:(nonnull NSString *)handle {
+    return @0;
+}
+
 - (void)startHCE:(nonnull RCTPromiseResolveBlock)resolve reject:(nonnull RCTPromiseRejectBlock)reject {
     if (@available(iOS 17.4, *)) {
         return [hcemoduleios startHCEWithResolve:resolve reject:reject];

package/ios/RTNHCEModuleIOSImpl.swift

@@ -38,7 +38,7 @@ extension Data {
         reject("err_nfc_reader_not_available", "Preflight check failed: NFCReaderSession.readingAvailable is false", nil)
         return
       }
-        
+
       guard CardSession.isSupported else {
         reject("err_card_session_unsupported", "Preflight check failed: CardSession.isSupported is false", nil)
         return
@@ -67,6 +67,10 @@ extension Data {
     }
   }
 
+  @objc public func releaseExclusiveNFC() {
+    self.presentmentIntent = nil
+  }
+
   @objc public func isExclusiveNFC() -> Bool {
     return self.presentmentIntent != nil && self.presentmentIntent!.isValid
   }
@@ -166,7 +170,7 @@ extension Data {
         reject("err_illegal_state", "The provided handle is invalid.", nil)
         return
       }
-        
+
       guard let capdu = self.receivedCardAPDU else {
         reject("err_no_apdu_received", "There is no received APDU to respond to.", nil)
         return

package/js/NativeHCEModule.ts

@@ -47,6 +47,11 @@ export interface Spec extends TurboModule {
    * Android: Not supported (throws an exception).
    */
   acquireExclusiveNFC(): Promise<void>;
+  /**
+   * iOS: Release NFCPresentmentIntentAssertion object.
+   * Android: Not supported (no-op).
+   */
+  releaseExclusiveNFC(): void;
   /**
    * iOS: Whether the NFCPresentmentIntentAssertion is acquired and still valid.
    * Android: Always false.

package/package.json

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