@icedevml/react-native-host-card-emulation 0.6.0 → 0.6.2

package/README.md

@@ -117,7 +117,7 @@ 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/NativeHCEModule.ts](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/host-card-emulation/js/NativeHCEModule.ts).
+> 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.
 > Check it out in order to understand what methods you can call against the module and what are the expected parameters/return values.
 
 > [!NOTE]
@@ -128,7 +128,7 @@ This module provides a uniform low-level HCE API for both mobile platforms.
 1. Subscribe to the event stream. There is a single global event stream, so you can subscribe early and remain subscribed to events for the entire application's lifetime.
    ```typescript
    useEffect(() => {
-       const subscription = NativeHCEModule?.onEvent(async (event: HCEModuleEvent) => {
+       const subscription = NativeHCEModule.onEvent(async (event: HCEModuleEvent) => {
            switch (event.type) {
                /* ... implement event handlers here ... */
            }
@@ -142,28 +142,28 @@ 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:
    ```typescript
-   await NativeHCEModule?.beginSession();
+   await NativeHCEModule.beginSession();
    ```
    This will emit `sessionStarted` event right after the function call, on both iOS and Android platforms. After the session is started, you can decide to start HCE emulation right away in the event handler:
    ```typescript
-   // inside NativeHCEModule?.onEvent handler's switch
+   // inside NativeHCEModule.onEvent handler's switch
    case 'sessionStarted':
-       NativeHCEModule?.setSessionAlertMessage('Tap towards the reader');  // only for iOS, no-op in Android
-       await NativeHCEModule?.startHCE();
+       NativeHCEModule.setSessionAlertMessage('Tap towards the reader');  // only for iOS, no-op in Android
+       await NativeHCEModule.startHCE();
        break;
    ```
-   Calling `await NativeHCEModule?.startHCE()` causes:
+   Calling `await NativeHCEModule.startHCE()` causes:
    * iOS: Your smartphone will start listening for C-APDUs (Command APDUs originating from reader devices) right after that function is called, which will be additionally indicated by the operating system popping out the NFC scanning user interface prompt.
    * Android: HCE commands will be forwarded to your application from that point on. No specific user interface is displayed (you have to implement it on your own, within your app).
 3. Optionally, you can handle `readerDetected` and `readerDeselected` events to enhance user's experience.
    ```typescript
-   // inside NativeHCEModule?.onEvent handler's switch
+   // inside NativeHCEModule.onEvent handler's switch
    case 'readerDetected':
-       NativeHCEModule?.setSessionAlertMessage('Reader detected');  // only for iOS, no-op in Android
+       NativeHCEModule.setSessionAlertMessage('Reader detected');  // only for iOS, no-op in Android
        break;
 
     case 'readerDeselected':
-        NativeHCEModule?.setSessionAlertMessage('Lost reader');  // only for iOS, no-op in Android
+        NativeHCEModule.setSessionAlertMessage('Lost reader');  // only for iOS, no-op in Android
         break;
    ```
    For those events, trigger mechanisms are platform dependent:
@@ -171,16 +171,16 @@ This module provides a uniform low-level HCE API for both mobile platforms.
    * Android: The `readerDetected` event will be emitted as soon as the first matching SELECT AID command is observed. The `readerDeselected` event will be emitted if the reader is physically disconnected or a non-matching AID is selected by the reader.
 4. Receive incoming C-APDU and respond to it:
    ```typescript
-   // inside NativeHCEModule?.onEvent handler's switch
+   // inside NativeHCEModule.onEvent handler's switch
    case 'received':
-       NativeHCEModule?.setSessionAlertMessage('Keep holding the tag');  // only for iOS, no-op on Android
+       NativeHCEModule.setSessionAlertMessage('Keep holding the tag');  // only for iOS, no-op on Android
 
        // decode incoming C-APDU to bytes
        const capdu = Buffer.from(event.arg!, 'hex');
        console.log('Received C-APDU, capdu.toString('hex'));
    
        // for the demo purposes, we always want to respond with [0x0A] + status code 0x9000 (success)
-       await NativeHCEModule?.respondAPDU(null, Buffer.from([0x0A, 0x90, 0x00], "hex"));
+       await NativeHCEModule.respondAPDU(null, Buffer.from([0x0A, 0x90, 0x00]).toString("hex"));
        break;
    ```
    You don't have to respond to the APDU right away from within the event handler, but please remember that the reader might time out if you will be lingering with the response for too long.
@@ -189,16 +189,18 @@ This module provides a uniform low-level HCE API for both mobile platforms.
 
 If you need to utilize `NFCPresentmentIntentAssertion` for enhanced user experience, call:
 ```typescript
-NativeHCEModule?.acquireExclusiveNFC();
+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.
 
+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.
+
 This function will throw an exception if:
 * the presentment intent assertion was already acquired and is still active;
 * 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.
+Call `NativeHCEModule.isExclusiveNFC()` to check if exclusive NFC access is still active.
 
 ### Android: Handle HCE calls when the app is not running
 
@@ -216,7 +218,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. 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.
    ```typescript
    import { Buffer } from 'buffer/';
    import {
@@ -233,6 +235,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.
    ```typescript
+   // inside processBackgroundHCE handler's switch
    case 'readerDeselected':
        // our application was deselected or the reader field was lost
        // perform a cleanup of any resources here
@@ -240,6 +243,7 @@ for instance - your app may emulate an NDEF tag even when it's not launched on t
    ```
 4. Implement the actual APDU handler that will process the C-APDU and generate a response.
    ```typescript
+   // inside processBackgroundHCE handler's switch
    case 'received':
        // decode incoming C-APDU to bytes
        const capdu = Buffer.from(event.arg!, 'hex');
@@ -252,5 +256,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/NativeHCEModule.ts)
+* [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)

package/android/src/main/java/com/itsecrnd/rtnhceandroid/HCEService.java

@@ -20,7 +20,6 @@ import androidx.annotation.RequiresApi;
 
 import com.facebook.react.ReactApplication;
 import com.facebook.react.ReactHost;
-import com.facebook.react.ReactInstanceEventListener;
 import com.facebook.react.bridge.Arguments;
 import com.facebook.react.bridge.ReactContext;
 import com.facebook.react.bridge.UiThreadUtil;
@@ -28,12 +27,13 @@ import com.facebook.react.jstasks.HeadlessJsTaskConfig;
 import com.facebook.react.jstasks.HeadlessJsTaskContext;
 import com.facebook.react.jstasks.HeadlessJsTaskEventListener;
 
+import java.util.HashMap;
 import java.util.List;
 import java.util.Locale;
 import java.util.UUID;
 
 @RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
-public class HCEService extends HostApduService implements ReactInstanceEventListener, HCEServiceCallback {
+public class HCEService extends HostApduService implements HCEServiceCallback {
     private static final String TAG = "HCEService";
 
     private boolean isForeground;
@@ -41,6 +41,13 @@ public class HCEService extends HostApduService implements ReactInstanceEventLis
     private RTNHCEAndroidModule hceModule;
     private byte[] pendingCAPDU;
     private volatile boolean needsResponse;
+    private final HashMap<String, Integer> taskSessionIdMap;
+
+    public HCEService() {
+        super();
+
+        taskSessionIdMap = new HashMap<>();
+    }
 
     private boolean isAppOnForeground(Context context) {
         /*
@@ -67,6 +74,7 @@ public class HCEService extends HostApduService implements ReactInstanceEventLis
     @Override
     public void onBackgroundHCEInit(String handle) {
         Log.d(TAG, "HCEService:onBackgroundHCEInit");
+        Log.d(TAG, "HCEService:onBackgroundHCEInit:" + handle + ":" + backgroundSessionUUID);
 
         if (handle == null && backgroundSessionUUID != null) {
             Log.d(TAG, "HCEService:onBackgroundHCEInit foreground call to background session");
@@ -83,6 +91,35 @@ public class HCEService extends HostApduService implements ReactInstanceEventLis
         }
     }
 
+    @Override
+    public void onBackgroundHCEFinish(String handle) {
+        Log.d(TAG, "HCEService:onBackgroundHCEFinish");
+        Integer taskId = taskSessionIdMap.get(handle);
+
+        if (taskId == null) {
+            Log.d(TAG, "HCEService:onBackgroundHCEFinish unable to resolve taskId");
+            throw new IllegalArgumentException();
+        }
+
+        ReactHost reactHost = ((ReactApplication) getApplication()).getReactHost();
+
+        if (reactHost == null) {
+            Log.d(TAG, "HCEService:onBackgroundHCEFinish getReactHost() returned null");
+            throw new IllegalArgumentException();
+        }
+
+        ReactContext reactContext = reactHost.getCurrentReactContext();
+
+        if (reactContext == null) {
+            Log.d(TAG, "HCEService:onBackgroundHCEFinish getCurrentReactContext() returned null");
+            throw new IllegalArgumentException();
+        }
+
+        HeadlessJsTaskContext headlessJsTaskContext = Companion.getInstance(reactContext);
+        headlessJsTaskContext.finishTask(taskId);
+        taskSessionIdMap.remove(handle);
+    }
+
     @Override
     public void onRespondAPDU(String handle, String rapdu) {
         Log.d(TAG, "HCEService:onRespondAPDU");
@@ -110,13 +147,13 @@ public class HCEService extends HostApduService implements ReactInstanceEventLis
         String capdu = BinaryUtils.ByteArrayToHexString(command).toUpperCase(Locale.ROOT);
 
         if (isForeground) {
-            if (hceModule._isHCERunning() && !hceModule.isHCEBrokenConnection()) {
+            if (hceModule._isHCERunning() && hceModule.isHCEActiveConnection()) {
                 Log.d(TAG, "HCEService:processCommandApdu foreground sendEvent received");
                 needsResponse = true;
                 hceModule.sendEvent("received", capdu);
             } else {
                 Log.d(TAG, "HCEService:processCommandApdu foreground respond 6999");
-                return new byte[] { (byte) 0x69, (byte) 0x99 };
+                return new byte[]{(byte) 0x69, (byte) 0x99};
             }
         } else {
             if (hceModule != null && hceModule.isHCEBackgroundHandlerReady()) {
@@ -174,13 +211,29 @@ public class HCEService extends HostApduService implements ReactInstanceEventLis
         } else {
             ReactContext reactContext = reactHost.getCurrentReactContext();
             Log.d(TAG, "HCEService:onCreate background");
-            this.backgroundSessionUUID = UUID.randomUUID().toString();
+            final String useSessID = UUID.randomUUID().toString();
+            backgroundSessionUUID = useSessID;
 
             if (reactContext == null) {
-                reactHost.addReactInstanceEventListener(this);
+                reactHost.addReactInstanceEventListener(evReactContext -> {
+                    HeadlessJsTaskContext headlessJsTaskContext = Companion.getInstance(evReactContext);
+                    headlessJsTaskContext.addTaskEventListener(new HeadlessJsTaskEventListener() {
+                        @Override
+                        public void onHeadlessJsTaskStart(int i) {
+                            Log.d(TAG, "HCEService:HeadlessJsTaskEventListener:onHeadlessJsTaskStart: " + i);
+                        }
+
+                        @Override
+                        public void onHeadlessJsTaskFinish(int i) {
+                            Log.d(TAG, "HCEService:HeadlessJsTaskEventListener:onHeadlessJsTaskFinish: " + i);
+                        }
+                    });
+
+                    setupRunJSTask(evReactContext, useSessID);
+                });
                 reactHost.start();
             } else {
-                setupRunJSTask(reactContext);
+                setupRunJSTask(reactContext, useSessID);
             }
         }
     }
@@ -191,37 +244,20 @@ public class HCEService extends HostApduService implements ReactInstanceEventLis
         needsResponse = false;
 
         if (isForeground) {
-            if (this.hceModule != null && !this.hceModule.isHCEBrokenConnection()) {
+            if (this.hceModule != null && this.hceModule.isHCEActiveConnection()) {
                 this.hceModule.sendEvent("readerDeselected", "");
             }
-        } else {
-            this.hceModule.sendBackgroundEvent(backgroundSessionUUID, "readerDeselected", "");
-        }
+        } else if (backgroundSessionUUID != null) {
+            String prevBackgroundSessionUUID = backgroundSessionUUID;
+            backgroundSessionUUID = null;
 
-        if (this.hceModule != null) {
-            this.hceModule.setHCEService(null);
-        }
-    }
-
-    @Override
-    public void onReactContextInitialized(@NonNull ReactContext reactContext) {
-        HeadlessJsTaskContext headlessJsTaskContext = Companion.getInstance(reactContext);
-        headlessJsTaskContext.addTaskEventListener(new HeadlessJsTaskEventListener() {
-            @Override
-            public void onHeadlessJsTaskStart(int i) {
-                Log.d(TAG, "HCEService:HeadlessJsTaskEventListener:onHeadlessJsTaskStart: " + i);
-            }
-
-            @Override
-            public void onHeadlessJsTaskFinish(int i) {
-                Log.d(TAG, "HCEService:HeadlessJsTaskEventListener:onHeadlessJsTaskFinish: " + i);
+            if (this.hceModule != null) {
+                this.hceModule.sendBackgroundEvent(prevBackgroundSessionUUID, "readerDeselected", "");
             }
-        });
-
-        setupRunJSTask(reactContext);
+        }
     }
 
-    public void setupRunJSTask(@NonNull ReactContext reactContext) {
+    public void setupRunJSTask(final @NonNull ReactContext reactContext, final String useSessUUID) {
         hceModule = (RTNHCEAndroidModule) reactContext.getNativeModule("NativeHCEModule");
 
         if (hceModule == null) {
@@ -230,21 +266,19 @@ public class HCEService extends HostApduService implements ReactInstanceEventLis
 
         hceModule.setHCEService(this);
 
-        UiThreadUtil.runOnUiThread(new Runnable() {
-            @Override
-            public void run() {
-                Log.d(TAG, "HCEService:setupRunJSTask:runOnUiThread startTask");
-                Bundle argBundle = new Bundle();
-                argBundle.putString("handle", backgroundSessionUUID);
-                HeadlessJsTaskContext headlessJsTaskContext = Companion.getInstance(reactContext);
-                headlessJsTaskContext.startTask(
-                        new HeadlessJsTaskConfig(
-                                "handleBackgroundHCECall",
-                                Arguments.fromBundle(argBundle),
-                                15000,
-                                false // not allowed in foreground
-                        ));
-            }
+        UiThreadUtil.runOnUiThread(() -> {
+            Log.d(TAG, "HCEService:setupRunJSTask:runOnUiThread startTask");
+            Bundle argBundle = new Bundle();
+            argBundle.putString("handle", useSessUUID);
+            HeadlessJsTaskContext headlessJsTaskContext = Companion.getInstance(reactContext);
+            int taskId = headlessJsTaskContext.startTask(
+                    new HeadlessJsTaskConfig(
+                            "handleBackgroundHCECall",
+                            Arguments.fromBundle(argBundle),
+                            15000,
+                            false // not allowed in foreground
+                    ));
+            taskSessionIdMap.put(useSessUUID, taskId);
         });
     }
 

package/android/src/main/java/com/itsecrnd/rtnhceandroid/HCEServiceCallback.java

@@ -2,5 +2,6 @@ package com.itsecrnd.rtnhceandroid;
 
 public interface HCEServiceCallback {
     void onBackgroundHCEInit(String handle);
+    void onBackgroundHCEFinish(String handle);
     void onRespondAPDU(String handle, String rapdu);
 }

package/android/src/main/java/com/itsecrnd/rtnhceandroid/RTNHCEAndroidModule.java

@@ -51,19 +51,29 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
     void sendEvent(final String type, final String arg) {
         Log.d(TAG, "RTNHCEAndroidModule:sendEvent");
-        WritableMap map = Arguments.createMap();
-        map.putString("type", type);
-        map.putString("arg", arg);
-        emitOnEvent(map);
+
+        if (this.mEventEmitterCallback != null) {
+            WritableMap map = Arguments.createMap();
+            map.putString("type", type);
+            map.putString("arg", arg);
+            emitOnEvent(map);
+        } else {
+            Log.d(TAG, "RTNHCEAndroidModule:sendEvent missing event emitter, ignore");
+        }
     }
 
     void sendBackgroundEvent(final String audience, final String type, final String arg) {
         Log.d(TAG, "RTNHCEAndroidModule:sendBackgroundEvent");
-        WritableMap map = Arguments.createMap();
-        map.putString("audience", audience);
-        map.putString("type", type);
-        map.putString("arg", arg);
-        emitOnBackgroundEvent(map);
+
+        if (this.mEventEmitterCallback != null) {
+            WritableMap map = Arguments.createMap();
+            map.putString("audience", audience);
+            map.putString("type", type);
+            map.putString("arg", arg);
+            emitOnBackgroundEvent(map);
+        } else {
+            Log.d(TAG, "RTNHCEAndroidModule:sendBackgroundEvent missing event emitter, ignore");
+        }
     }
 
     boolean _isHCERunning() {
@@ -78,8 +88,8 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
         return this.hceBackgroundReady;
     }
 
-    boolean isHCEBrokenConnection() {
-        return this.hceBrokenConnection;
+    boolean isHCEActiveConnection() {
+        return !this.hceBrokenConnection;
     }
 
     void setHCEService(HCEServiceCallback serviceCallback) {
@@ -171,6 +181,19 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
         return true;
     }
 
+    @Override
+    public boolean finishBackgroundHCE(String handle) {
+        Log.d(TAG, "RTNHCEAndroidModule:finishBackgroundHCE");
+
+        try {
+            this.serviceCb.onBackgroundHCEFinish(handle);
+        } catch (IllegalStateException e) {
+            return false;
+        }
+
+        return true;
+    }
+
     @Override
     public void startHCE(Promise promise) {
         Log.d(TAG, "RTNHCEAndroidModule:startHCE");

package/js/NativeHCEModule.ts

@@ -74,8 +74,6 @@ export interface Spec extends TurboModule {
    */
   isSessionRunning(): boolean;
 
-  beginBackgroundHCE(handle: string): boolean;
-
   /**
    * iOS: Start the card emulation.
    * Android: Enable HCE service.
@@ -88,6 +86,7 @@ export interface Spec extends TurboModule {
   stopHCE(status: HCEModuleStopReason): Promise<void>;
   /**
    * Send R-APDU (hex-encoded string) as a response to the last received C-APDU event.
+   * Set handle=null when calling this function from foreground app.
    */
   respondAPDU(handle: string | null, rapdu: string): Promise<void>;
   /**
@@ -96,7 +95,30 @@ export interface Spec extends TurboModule {
    */
   isHCERunning(): Promise<boolean>;
 
+  /**
+   * Android: Report that the JS headless task is ready to handle HCE interaction in the background.
+   * NOTE: Don't call this API directly, use wrapper hceBackground.ts:createBackgroundHCE.
+   * See demo app or README.md for example wrapper usage.
+   */
+  beginBackgroundHCE(handle: string): boolean;
+
+  /**
+   * Android: Report the background HCE interaction was finished.
+   * NOTE: Don't call this API directly, use wrapper hceBackground.ts:createBackgroundHCE.
+   * See demo app or README.md for example wrapper usage.
+   */
+  finishBackgroundHCE(handle: string): boolean;
+
+  /**
+   * Event handler for foreground HCE interactions.
+   */
   readonly onEvent: CodegenTypes.EventEmitter<HCEModuleEvent>;
+
+  /**
+   * Event handler for background HCE interactions.
+   * NOTE: Don't subscribe to that handler directly, use wrapper hceBackground.ts:createBackgroundHCE.
+   * See demo app or README.md for example wrapper usage.
+   */
   readonly onBackgroundEvent: CodegenTypes.EventEmitter<HCEModuleBackgroundEvent>;
 }
 

package/js/hceBackground.ts

@@ -32,12 +32,14 @@ export const createBackgroundHCE = (handle: string) => {
             } finally {
                 if (event.type === "readerDeselected") {
                     subscription.remove();
+                    NativeHCEModule.finishBackgroundHCE(handle);
                 }
             }
         });
 
         if (!NativeHCEModule.beginBackgroundHCE(handle)) {
             subscription.remove();
+            NativeHCEModule.finishBackgroundHCE(handle);
         }
     }
 }

package/package.json

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