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

package/README.md

@@ -1,12 +1,17 @@
-# Package: React Native HCE Module
+# React Native Package: @icedevml/react-native-host-card-emulation
 
 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.
+
 > [!IMPORTANT]  
 > As per Apple's policy, **Host Card Emulation feature is only available for users based in the European
 > Economic Area (EEA)** with an iPhone running iOS 17.4 or later. Applications require a special HCE entitlement
 > in order to use this feature, which is managed by Apple. Read more in the official support article:
 > "[HCE-based contactless NFC transactions for apps in the European Economic Area (EEA)](https://developer.apple.com/support/hce-transactions-in-apps/)".
+>
+> However, you can still use this package without any limitations if you only want to cover for Android implementation.
 
 ## Prerequisites
 This package was designed for React Native [New Architecture](https://reactnative.dev/architecture/landing-page) only.
@@ -64,9 +69,8 @@ Afterwards, follow the subsections below for each platform that you need to supp
       ...
 
    +  <uses-permission android:name="android.permission.NFC" />
+   +  <!-- set required="true" if your app would be entirely useless on devices without HCE support -->
    +  <uses-feature android:name="android.hardware.nfc.hce" android:required="false" />
-   +  <permission android:name="com.itsecrnd.rtnhceandroid.HCE_BROADCAST" android:protectionLevel="signature" />
-   +  <uses-permission android:name="com.itsecrnd.rtnhceandroid.HCE_BROADCAST"/>
 
       ...
 
@@ -77,7 +81,7 @@ Afterwards, follow the subsections below for each platform that you need to supp
         ...
    
    +    <service
-   +      android:name="com.itsecrnd.rtnhceandroid.service.HCEService"
+   +      android:name="com.itsecrnd.rtnhceandroid.HCEService"
    +      android:exported="true"
    +      android:enabled="true"
    +      android:permission="android.permission.BIND_NFC_SERVICE">
@@ -113,18 +117,18 @@ 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/native-hce-module/js/NativeHCEModule.ts](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/native-hce-module/js/NativeHCEModule.ts).
+> 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).
 > 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-hce-module-app/App.tsx) example for more insignt about the library's API.
+> 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.
 
 ### Quick start guide
 
 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 removeListener = NativeHCEModule?.onEvent(async (event: HCEModuleEvent) => {
+       const subscription = NativeHCEModule?.onEvent(async (event: HCEModuleEvent) => {
            switch (event.type) {
                /* ... implement event handlers here ... */
            }
@@ -132,7 +136,7 @@ This module provides a uniform low-level HCE API for both mobile platforms.
 
        // cleanup the event listener when the effect is unmounted
        return () => {
-           removeListener();
+           subscription.remove();
        }
    }, []);
    ```
@@ -163,7 +167,7 @@ This module provides a uniform low-level HCE API for both mobile platforms.
         break;
    ```
    For those events, trigger mechanisms are platform dependent:
-   * iOS: The `readerDetected` event will be emitted as soon as the NFC tag 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.
+   * 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.
    * 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
@@ -176,12 +180,13 @@ This module provides a uniform low-level HCE API for both mobile platforms.
        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(Buffer.from([0x0A, 0x90, 0x00], "hex"));
+       await NativeHCEModule?.respondAPDU(null, Buffer.from([0x0A, 0x90, 0x00], "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.
 
 ### iOS: Acquiring exclusive NFC access
+
 If you need to utilize `NFCPresentmentIntentAssertion` for enhanced user experience, call:
 ```typescript
 NativeHCEModule?.acquireExclusiveNFC();
@@ -195,7 +200,57 @@ This function will throw an exception if:
 
 Call `NativeHCEModule?.isExclusiveNFC()` to check if exclusive NFC access is still active.
 
+### Android: Handle HCE calls when the app is not running
+
+Exclusively on Android platform it is possible to handle Host Card Emulation even when the app is not running in foreground.
+In such case, no user interface will be available, the handler will run in headless mode. This is still extremely useful in certain cases,
+for instance - your app may emulate an NDEF tag even when it's not launched on the foreground.
+
+1. Register `handleBackgroundHCECall` headless task in your app's `index.js`:
+   ```typescript
+   import { createBackgroundHCE } from '@icedevml/react-native-host-card-emulation/js/hceBackground';
+
+   AppRegistry.registerHeadlessTask('handleBackgroundHCECall', () => {
+      return async (taskData) => {
+         return await runBackgroundHCETask(createBackgroundHCE(taskData.handle));
+      }
+   });
+   ```
+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 {
+     ProcessBackgroundHCEFunc,
+   } from '@icedevml/react-native-host-card-emulation/js/hceBackground';
+
+   export default async function runBackgroundHCETask(processBackgroundHCE: ProcessBackgroundHCEFunc) {
+      processBackgroundHCE(async (event, respondAPDU) => {
+         switch (event.type) {
+            /* ... background HCE event handler here ... */
+         }
+      });
+   }
+   ```
+3. Cleanup your event listener in `readerDeselected` -- this is obligatory because lack of proper cleanup will result in bugs and unexpected behavior.
+   ```typescript
+   case 'readerDeselected':
+       // our application was deselected or the reader field was lost
+       // perform a cleanup of any resources here
+       break;
+   ```
+4. Implement the actual APDU handler that will process the C-APDU and generate a response.
+   ```typescript
+   case 'received':
+       // 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 respondAPDU(Buffer.from([0x0A, 0x90, 0x00]).toString("hex"));
+       break;
+   ```
+
 ### More resources
 
-* [Module's API specification](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/native-hce-module/js/NativeHCEModule.ts)
-* [Demo App's Code (Example Library Usage)](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/demo-hce-module-app/App.tsx)
+* [Module's API specification](https://github.com/icedevml/react-native-host-card-emulation/blob/master/packages/host-card-emulation/js/NativeHCEModule.ts)
+* [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/{util/BinaryUtils.java → BinaryUtils.java}

@@ -20,7 +20,7 @@
  *
  */
 
-package com.itsecrnd.rtnhceandroid.util;
+package com.itsecrnd.rtnhceandroid;
 
 public class BinaryUtils {
     /**

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

@@ -0,0 +1,257 @@
+/*
+ * Some of the code inspired by:
+ * https://github.com/appidea/react-native-hce
+ * https://github.com/transistorsoft/react-native-background-fetch
+ */
+
+package com.itsecrnd.rtnhceandroid;
+
+import static com.facebook.react.jstasks.HeadlessJsTaskContext.Companion;
+
+import android.app.ActivityManager;
+import android.content.Context;
+import android.nfc.cardemulation.HostApduService;
+import android.os.Build;
+import android.os.Bundle;
+import android.util.Log;
+
+import androidx.annotation.NonNull;
+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;
+import com.facebook.react.jstasks.HeadlessJsTaskConfig;
+import com.facebook.react.jstasks.HeadlessJsTaskContext;
+import com.facebook.react.jstasks.HeadlessJsTaskEventListener;
+
+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 {
+    private static final String TAG = "HCEService";
+
+    private boolean isForeground;
+    private String backgroundSessionUUID;
+    private RTNHCEAndroidModule hceModule;
+    private byte[] pendingCAPDU;
+    private volatile boolean needsResponse;
+
+    private boolean isAppOnForeground(Context context) {
+        /*
+         We need to check if app is in foreground otherwise the app will crash.
+         https://stackoverflow.com/questions/8489993/check-android-application-is-in-foreground-or-not
+         */
+        ActivityManager activityManager = (ActivityManager) context.getSystemService(Context.ACTIVITY_SERVICE);
+        List<ActivityManager.RunningAppProcessInfo> appProcesses =
+                activityManager.getRunningAppProcesses();
+        if (appProcesses == null) {
+            return false;
+        }
+        final String packageName = context.getPackageName();
+        for (ActivityManager.RunningAppProcessInfo appProcess : appProcesses) {
+            if (appProcess.importance ==
+                    ActivityManager.RunningAppProcessInfo.IMPORTANCE_FOREGROUND &&
+                    appProcess.processName.equals(packageName)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    @Override
+    public void onBackgroundHCEInit(String handle) {
+        Log.d(TAG, "HCEService:onBackgroundHCEInit");
+
+        if (handle == null && backgroundSessionUUID != null) {
+            Log.d(TAG, "HCEService:onBackgroundHCEInit foreground call to background session");
+            throw new IllegalStateException();
+        } else if (handle != null && !handle.equals(backgroundSessionUUID)) {
+            Log.d(TAG, "HCEService:onBackgroundHCEInit mismatched background session handle");
+            throw new IllegalStateException();
+        }
+
+        if (pendingCAPDU != null) {
+            Log.d(TAG, "HCEService:onBackgroundHCEInit send pendingCAPDU");
+            hceModule.sendBackgroundEvent(backgroundSessionUUID, "received", BinaryUtils.ByteArrayToHexString(pendingCAPDU));
+            pendingCAPDU = null;
+        }
+    }
+
+    @Override
+    public void onRespondAPDU(String handle, String rapdu) {
+        Log.d(TAG, "HCEService:onRespondAPDU");
+
+        if (handle == null && backgroundSessionUUID != null) {
+            Log.d(TAG, "HCEService:onRespondAPDU foreground call to background session");
+            throw new IllegalStateException();
+        } else if (handle != null && !handle.equals(backgroundSessionUUID)) {
+            Log.d(TAG, "HCEService:onRespondAPDU mismatched background session handle");
+            throw new IllegalStateException();
+        }
+
+        if (!needsResponse) {
+            Log.d(TAG, "HCEService:onRespondAPDU not waiting for a response");
+            throw new IllegalStateException();
+        }
+
+        needsResponse = false;
+        sendResponseApdu(BinaryUtils.HexStringToByteArray(rapdu));
+    }
+
+    @Override
+    public byte[] processCommandApdu(byte[] command, Bundle extras) {
+        Log.d(TAG, "HCEService:processCommandApdu");
+        String capdu = BinaryUtils.ByteArrayToHexString(command).toUpperCase(Locale.ROOT);
+
+        if (isForeground) {
+            if (hceModule._isHCERunning() && !hceModule.isHCEBrokenConnection()) {
+                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 };
+            }
+        } else {
+            if (hceModule != null && hceModule.isHCEBackgroundHandlerReady()) {
+                Log.d(TAG, "HCEService:processCommandApdu background sendBackgroundEvent received");
+                needsResponse = true;
+                hceModule.sendBackgroundEvent(backgroundSessionUUID, "received", capdu);
+            } else {
+                Log.d(TAG, "HCEService:processCommandApdu background pendingCAPDU");
+                needsResponse = true;
+                pendingCAPDU = command;
+            }
+        }
+
+        return null;
+    }
+
+    @Override
+    public void onCreate() {
+        Log.d(TAG, "HCEService:onCreate");
+
+        ReactHost reactHost = ((ReactApplication) getApplication()).getReactHost();
+
+        if (reactHost == null) {
+            throw new RuntimeException("BUG! getReactHost() returned null.");
+        }
+
+        isForeground = isAppOnForeground(getApplicationContext());
+        pendingCAPDU = null;
+        hceModule = null;
+        needsResponse = false;
+
+        if (isForeground) {
+            Log.d(TAG, "HCEService:onCreate foreground");
+            this.backgroundSessionUUID = null;
+
+            ReactContext reactContext = reactHost.getCurrentReactContext();
+
+            if (reactContext == null) {
+                throw new RuntimeException("BUG! getCurrentReactContext() returned null in foreground.");
+            }
+
+            this.hceModule = ((RTNHCEAndroidModule) reactContext.getNativeModule("NativeHCEModule"));
+
+            if (this.hceModule == null) {
+                throw new RuntimeException("BUG! getNativeModule() returned null in foreground.");
+            }
+
+            this.hceModule.setHCEService(this);
+
+            if (this.hceModule._isHCERunning()) {
+                this.hceModule.sendEvent("readerDetected", "");
+            } else {
+                this.hceModule.setHCEBrokenConnection();
+            }
+        } else {
+            ReactContext reactContext = reactHost.getCurrentReactContext();
+            Log.d(TAG, "HCEService:onCreate background");
+            this.backgroundSessionUUID = UUID.randomUUID().toString();
+
+            if (reactContext == null) {
+                reactHost.addReactInstanceEventListener(this);
+                reactHost.start();
+            } else {
+                setupRunJSTask(reactContext);
+            }
+        }
+    }
+
+    @Override
+    public void onDeactivated(int reason) {
+        Log.d(TAG, "HCEService:onDeactivated: " + reason);
+        needsResponse = false;
+
+        if (isForeground) {
+            if (this.hceModule != null && !this.hceModule.isHCEBrokenConnection()) {
+                this.hceModule.sendEvent("readerDeselected", "");
+            }
+        } else {
+            this.hceModule.sendBackgroundEvent(backgroundSessionUUID, "readerDeselected", "");
+        }
+
+        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);
+            }
+        });
+
+        setupRunJSTask(reactContext);
+    }
+
+    public void setupRunJSTask(@NonNull ReactContext reactContext) {
+        hceModule = (RTNHCEAndroidModule) reactContext.getNativeModule("NativeHCEModule");
+
+        if (hceModule == null) {
+            throw new RuntimeException("BUG! getNativeModule() returned null in background.");
+        }
+
+        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
+                        ));
+            }
+        });
+    }
+
+    @Override
+    public void onDestroy() {
+        super.onDestroy();
+
+        Log.d(TAG, "HCEService:onDestroy");
+    }
+}

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

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

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

@@ -1,16 +1,5 @@
 package com.itsecrnd.rtnhceandroid;
 
-import static android.content.Context.RECEIVER_EXPORTED;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_READER_DETECT;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_READER_LOST;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_RECEIVE_C_APDU;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_SEND_R_APDU;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.PERMISSION_HCE_BROADCAST;
-
-import android.content.BroadcastReceiver;
-import android.content.Context;
-import android.content.Intent;
-import android.content.IntentFilter;
 import android.content.pm.PackageManager;
 import android.os.Build;
 import android.util.Log;
@@ -29,102 +18,82 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
     private volatile boolean sessionRunning;
     private volatile boolean hceRunning;
-    private volatile boolean hceBreakConnection;
     private volatile boolean hceDeselected;
+    private volatile boolean hceBrokenConnection;
 
-    private void sendEvent(final String type, final String arg) {
-        WritableMap map = Arguments.createMap();
-        map.putString("type", type);
-        map.putString("arg", arg);
-        emitOnEvent(map);
-    }
+    private volatile boolean hceBackgroundReady;
 
-    @RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
-    private final BroadcastReceiver receiver = new BroadcastReceiver() {
-        @Override
-        public void onReceive(Context context, Intent intent) {
-            try {
-                String action = intent.getAction();
-
-                if (action == null) {
-                    Log.w(TAG, "Received intent with null action in module receiver.");
-                    return;
-                }
-
-                if (action.equals(ACTION_RECEIVE_C_APDU)) {
-                    String capdu = intent.getStringExtra("capdu");
-
-                    if (!hceBreakConnection && hceRunning) {
-                        sendEvent("received", capdu);
-                    } else {
-                        // HCE is already disabled or was just disabled while the HCEService was running
-                        // don't forward C-APDUs to the application and just respond 6999 to everything
-                        Intent rintent = new Intent(ACTION_SEND_R_APDU);
-                        rintent.setPackage(getReactApplicationContext().getPackageName());
-                        rintent.putExtra("rapdu", "6999");
-                        getReactApplicationContext().getApplicationContext().sendBroadcast(rintent, PERMISSION_HCE_BROADCAST);
-                    }
-                } else if (action.equals(ACTION_READER_DETECT)) {
-                    if (hceRunning) {
-                        hceDeselected = false;
-                        sendEvent("readerDetected", "");
-                    }
-                } else if (action.equals(ACTION_READER_LOST)) {
-                    if (hceRunning && !hceBreakConnection && !hceDeselected) {
-                        // only if we haven't send a fake disconnect event already
-                        hceDeselected = true;
-                        sendEvent("readerDeselected", "");
-                    }
-
-                    hceBreakConnection = false;
-                } else {
-                    Log.w(TAG, "Received unknown action intent in module receiver: " + action);
-                }
-            } catch (Exception e) {
-                Log.e(TAG, "Failed to handle broadcast in RTNHCEAndroidModule.", e);
-            }
-        }
-    };
+    private HCEServiceCallback serviceCb;
 
     RTNHCEAndroidModule(ReactApplicationContext context) {
         super(context);
 
+        this.serviceCb = null;
+
         this.sessionRunning = false;
         this.hceRunning = false;
-        this.hceBreakConnection = false;
         this.hceDeselected = true;
-
-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
-            IntentFilter filter = new IntentFilter();
-            filter.addAction(ACTION_RECEIVE_C_APDU);
-            filter.addAction(ACTION_READER_DETECT);
-            filter.addAction(ACTION_READER_LOST);
-
-            getReactApplicationContext().getApplicationContext().registerReceiver(
-                    receiver,
-                    filter,
-                    PERMISSION_HCE_BROADCAST,
-                    null,
-                    RECEIVER_EXPORTED
-            );
-        }
+        this.hceBrokenConnection = false;
+        this.hceBackgroundReady = false;
     }
 
     @Override
     public void invalidate() {
-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
-            getReactApplicationContext().getApplicationContext().unregisterReceiver(receiver);
-        }
+        Log.d(TAG, "RTNHCEAndroidModule:invalidate");
     }
 
     @Override
     @NonNull
     public String getName() {
+        Log.d(TAG, "RTNHCEAndroidModule:getName");
         return RTNHCEAndroidModule.NAME;
     }
 
+    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);
+    }
+
+    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);
+    }
+
+    boolean _isHCERunning() {
+        return this.hceRunning;
+    }
+
+    void setHCEBrokenConnection() {
+        this.hceBrokenConnection = true;
+    }
+
+    boolean isHCEBackgroundHandlerReady() {
+        return this.hceBackgroundReady;
+    }
+
+    boolean isHCEBrokenConnection() {
+        return this.hceBrokenConnection;
+    }
+
+    void setHCEService(HCEServiceCallback serviceCallback) {
+        Log.d(TAG, "RTNHCEAndroidModule:setHCEService");
+
+        this.serviceCb = serviceCallback;
+        this.hceDeselected = true;
+        this.hceBackgroundReady = false;
+        this.hceBrokenConnection = false;
+    }
+
     @Override
     public boolean isPlatformSupported() {
+        Log.d(TAG, "RTNHCEAndroidModule:isPlatformSupported");
         if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
             return false;
         }
@@ -136,17 +105,21 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
     @Override
     public void acquireExclusiveNFC(Promise promise) {
+        Log.d(TAG, "RTNHCEAndroidModule:acquireExclusiveNFC");
         promise.reject("err_platform_unsupported", "acquireExclusiveNFC() is not supported on Android.");
     }
 
     @Override
     public boolean isExclusiveNFC() {
+        Log.d(TAG, "RTNHCEAndroidModule:isExclusiveNFC");
         // unsupported on Android, always false
         return false;
     }
 
     @Override
     public void beginSession(Promise promise) {
+        Log.d(TAG, "RTNHCEAndroidModule:beginSession");
+
         if (!isPlatformSupported()) {
             promise.reject("err_platform_unsupported", "Unsupported Android version or missing NFC/HCE feature.");
             return;
@@ -163,24 +136,44 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
     @Override
     public void setSessionAlertMessage(String message) {
+        Log.d(TAG, "RTNHCEAndroidModule:setSessionAlertMessage");
         // unsupported on Android, no-op
     }
 
     @Override
     public void invalidateSession() {
+        Log.d(TAG, "RTNHCEAndroidModule:invalidateSession");
         if (this.sessionRunning) {
+            this.hceRunning = false;
             this.sessionRunning = false;
+            this.hceBrokenConnection = true;
             sendEvent("sessionInvalidated", "userInvalidated");
         }
     }
 
     @Override
     public boolean isSessionRunning() {
+        Log.d(TAG, "RTNHCEAndroidModule:isSessionRunning");
         return this.sessionRunning;
     }
 
+    @Override
+    public boolean beginBackgroundHCE(String handle) {
+        Log.d(TAG, "RTNHCEAndroidModule:beginBackgroundHCE");
+
+        try {
+            this.serviceCb.onBackgroundHCEInit(handle);
+        } catch (IllegalStateException e) {
+            return false;
+        }
+
+        this.hceBackgroundReady = true;
+        return true;
+    }
+
     @Override
     public void startHCE(Promise promise) {
+        Log.d(TAG, "RTNHCEAndroidModule:startHCE");
         if (!this.sessionRunning) {
             promise.reject("err_no_session", "No session is active.");
             return;
@@ -192,11 +185,13 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
         }
 
         this.hceRunning = true;
+        this.hceBrokenConnection = false;
         promise.resolve(null);
     }
 
     @Override
     public void stopHCE(String status, Promise promise) {
+        Log.d(TAG, "RTNHCEAndroidModule:stopHCE");
         if (!this.sessionRunning) {
             promise.reject("err_no_session", "No session is active.");
             return;
@@ -207,7 +202,7 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
             if (!this.hceDeselected) {
                 this.hceDeselected = true;
-                this.hceBreakConnection = true;
+                this.hceBrokenConnection = true;
                 sendEvent("readerDeselected", "");
             }
         }
@@ -217,25 +212,34 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
     @RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
     @Override
-    public void respondAPDU(String rapdu, Promise promise) {
-        if (!this.sessionRunning) {
-            promise.reject("err_no_session", "No session is active.");
-            return;
-        } else if (!this.hceRunning) {
-            promise.reject("err_no_hce", "HCE is not running.");
-            return;
+    public void respondAPDU(String handle, String rapdu, Promise promise) {
+        Log.d(TAG, "RTNHCEAndroidModule:respondAPDU");
+
+        if (!this.hceBackgroundReady) {
+            if (!this.sessionRunning) {
+                promise.reject("err_no_session", "No session is active.");
+                return;
+            } else if (!this.hceRunning) {
+                promise.reject("err_no_hce", "HCE is not running.");
+                return;
+            }
         }
 
-        Intent intent = new Intent(ACTION_SEND_R_APDU);
-        intent.setPackage(getReactApplicationContext().getPackageName());
-        intent.putExtra("rapdu", rapdu);
-        getReactApplicationContext().getApplicationContext().sendBroadcast(intent, PERMISSION_HCE_BROADCAST);
+        Log.d(TAG, "respondAPDU(): Send to service");
+
+        try {
+            serviceCb.onRespondAPDU(handle, rapdu);
+        } catch (IllegalStateException e) {
+            promise.reject("err_illegal_state", "There is no C-APDU to respond to at the time or the provided handle is invalid.");
+            return;
+        }
 
         promise.resolve(null);
     }
 
     @Override
     public void isHCERunning(Promise promise) {
+        Log.d(TAG, "RTNHCEAndroidModule:isHCERunning");
         promise.resolve(this.hceRunning);
     }
 }

package/ios/RTNHCEModuleIOS.mm

@@ -86,6 +86,10 @@
     }
 }
 
+- (nonnull NSNumber *)beginBackgroundHCE:(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];
@@ -102,9 +106,9 @@
     }
 }
 
-- (void)respondAPDU:(nonnull NSString *)rapdu resolve:(nonnull RCTPromiseResolveBlock)resolve reject:(nonnull RCTPromiseRejectBlock)reject {
+- (void)respondAPDU:(NSString * _Nullable)handle rapdu:(nonnull NSString *)rapdu resolve:(nonnull RCTPromiseResolveBlock)resolve reject:(nonnull RCTPromiseRejectBlock)reject {
     if (@available(iOS 17.4, *)) {
-        return [hcemoduleios respondAPDUWithRapdu:rapdu resolve:resolve reject:reject];
+        return [hcemoduleios respondAPDUWithHandle:handle rapdu:rapdu resolve:resolve reject:reject];
     } else {
         reject(@"err_platform_unsupported", @"This iOS version does not support HCE.", nil);
     }

package/ios/RTNHCEModuleIOSImpl.swift

@@ -145,8 +145,13 @@ extension Data {
     }
   }
 
-  @objc public func respondAPDU(rapdu: NSString, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+  @objc public func respondAPDU(handle: NSString?, rapdu: NSString, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
     Task.init {
+      guard handle == nil else {
+        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

@@ -1,7 +1,8 @@
 import type {TurboModule, CodegenTypes} from 'react-native';
 import {TurboModuleRegistry} from 'react-native';
 
-export type HCEModuleEventType = 'sessionStarted'
+export type HCEModuleEventType =
+    'sessionStarted'
     | 'sessionInvalidated'
     /**
      * iOS: Whether the reader field was detected.
@@ -19,11 +20,21 @@ export type HCEModuleEventType = 'sessionStarted'
     | 'received';
 export type HCEModuleStopReason = 'success' | 'failure';
 
+export type HCEModuleBackgroundEventType =
+    'readerDeselected'
+    | 'received';
+
 export type HCEModuleEvent = {
   type: HCEModuleEventType
   arg: string | null,
 }
 
+export type HCEModuleBackgroundEvent = {
+  type: HCEModuleBackgroundEventType
+  arg: string | null,
+  audience: string,
+}
+
 export interface Spec extends TurboModule {
   /**
    * Checks if a given smartphone supports required HCE features.
@@ -63,6 +74,8 @@ export interface Spec extends TurboModule {
    */
   isSessionRunning(): boolean;
 
+  beginBackgroundHCE(handle: string): boolean;
+
   /**
    * iOS: Start the card emulation.
    * Android: Enable HCE service.
@@ -76,7 +89,7 @@ export interface Spec extends TurboModule {
   /**
    * Send R-APDU (hex-encoded string) as a response to the last received C-APDU event.
    */
-  respondAPDU(rapdu: string): Promise<void>;
+  respondAPDU(handle: string | null, rapdu: string): Promise<void>;
   /**
    * iOS: Checks if the card emulation is running.
    * Android: Checks if the HCE service is enabled.
@@ -84,6 +97,7 @@ export interface Spec extends TurboModule {
   isHCERunning(): Promise<boolean>;
 
   readonly onEvent: CodegenTypes.EventEmitter<HCEModuleEvent>;
+  readonly onBackgroundEvent: CodegenTypes.EventEmitter<HCEModuleBackgroundEvent>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>(

package/js/hceBackground.ts

@@ -0,0 +1,43 @@
+import NativeHCEModule, {HCEModuleBackgroundEvent} from "./NativeHCEModule";
+
+export interface BackgroundEventHandler {
+    (
+        event: HCEModuleBackgroundEvent,
+        respondAPDU: (rapdu: string) => Promise<void>,
+    ): Promise<void>
+}
+
+export interface ProcessBackgroundHCEFunc {
+    (
+        handler: BackgroundEventHandler
+    ): void
+}
+
+export const createBackgroundHCE = (handle: string) => {
+    const respondAPDU = (rapdu: string) => {
+        return NativeHCEModule.respondAPDU(handle, rapdu);
+    }
+
+    return (handler: BackgroundEventHandler) => {
+        const subscription = NativeHCEModule.onBackgroundEvent(async (event) => {
+            if (event.audience !== handle) {
+                // ignore
+                return;
+            }
+
+            try {
+                await handler(event, respondAPDU);
+            } catch (e) {
+                throw e;
+            } finally {
+                if (event.type === "readerDeselected") {
+                    subscription.remove();
+                }
+            }
+        });
+
+        if (!NativeHCEModule.beginBackgroundHCE(handle)) {
+            subscription.remove();
+        }
+    }
+}

package/package.json

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

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

@@ -1,11 +0,0 @@
-package com.itsecrnd.rtnhceandroid;
-
-public class IntentKeys {
-    public static final String PERMISSION_HCE_BROADCAST = "com.itsecrnd.rtnhceandroid.HCE_BROADCAST";
-    public static final String ACTION_RECEIVE_C_APDU = "com.itsecrnd.rtnhceandroid.ACTION_RECEIVE_C_APDU";
-    public static final String ACTION_SEND_R_APDU = "com.itsecrnd.rtnhceandroid.ACTION_SEND_R_APDU";
-    public static final String ACTION_READER_DETECT = "com.itsecrnd.rtnhceandroid.ACTION_READER_DETECT";
-    public static final String ACTION_READER_LOST = "com.itsecrnd.rtnhceandroid.ACTION_READER_LOST";
-    public static final String KEY_CAPDU = "capdu";
-    public static final String KEY_RAPDU = "rapdu";
-}

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

@@ -1,90 +0,0 @@
-package com.itsecrnd.rtnhceandroid.service;
-
-import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_READER_DETECT;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_READER_LOST;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_RECEIVE_C_APDU;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.ACTION_SEND_R_APDU;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.KEY_CAPDU;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.KEY_RAPDU;
-import static com.itsecrnd.rtnhceandroid.IntentKeys.PERMISSION_HCE_BROADCAST;
-
-import android.content.BroadcastReceiver;
-import android.content.Context;
-import android.content.Intent;
-import android.content.IntentFilter;
-import android.nfc.cardemulation.HostApduService;
-import android.os.Build;
-import android.os.Bundle;
-import android.util.Log;
-
-import androidx.annotation.RequiresApi;
-
-import com.itsecrnd.rtnhceandroid.util.BinaryUtils;
-
-import java.util.Locale;
-
-@RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
-public class HCEService extends HostApduService {
-    private static final String TAG = "HCEService";
-
-    private final BroadcastReceiver receiver = new BroadcastReceiver() {
-        @Override
-        public void onReceive(Context context, Intent intent) {
-            try {
-                String action = intent.getAction();
-
-                if (action != null && action.equals(ACTION_SEND_R_APDU)) {
-                    String rapdu = intent.getStringExtra(KEY_RAPDU);
-
-                    if (rapdu == null) {
-                        throw new RuntimeException("Bug! ACTION_SEND_RAPDU intent KEY_RAPDU is null.");
-                    }
-
-                    byte[] dec = BinaryUtils.HexStringToByteArray(rapdu.toUpperCase(Locale.ROOT));
-                    sendResponseApdu(dec);
-                } else {
-                    Log.w(TAG, "Received unknown action: " + action);
-                }
-            } catch (Exception e) {
-                Log.e(TAG, "Failed to handle broadcast in HCEService.", e);
-            }
-        }
-    };
-
-    @Override
-    public byte[] processCommandApdu(byte[] command, Bundle extras) {
-        String capdu = BinaryUtils.ByteArrayToHexString(command).toUpperCase(Locale.ROOT);
-
-        Intent intent = new Intent(ACTION_RECEIVE_C_APDU);
-        intent.setPackage(getApplicationContext().getPackageName());
-        intent.putExtra(KEY_CAPDU, capdu);
-        getApplicationContext().sendBroadcast(intent, PERMISSION_HCE_BROADCAST);
-
-        return null;
-    }
-
-    @Override
-    public void onCreate() {
-        Log.d(TAG, "HCEService onCreate");
-
-        IntentFilter filter = new IntentFilter();
-        filter.addAction(ACTION_SEND_R_APDU);
-        getApplicationContext().registerReceiver(
-                receiver, filter, PERMISSION_HCE_BROADCAST, null, RECEIVER_EXPORTED);
-
-        Intent intent = new Intent(ACTION_READER_DETECT);
-        intent.setPackage(getApplicationContext().getPackageName());
-        getApplicationContext().sendBroadcast(intent, PERMISSION_HCE_BROADCAST);
-    }
-
-    @Override
-    public void onDeactivated(int reason) {
-        Log.d(TAG, "HCEService onDeactivated: " + reason);
-
-        getApplicationContext().unregisterReceiver(receiver);
-
-        Intent intent = new Intent(ACTION_READER_LOST);
-        intent.setPackage(getApplicationContext().getPackageName());
-        getApplicationContext().sendBroadcast(intent, PERMISSION_HCE_BROADCAST);
-    }
-}