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

package/README.md

@@ -64,9 +64,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 +76,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">
@@ -124,7 +123,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 removeListener = NativeHCEModule?.onEvent(async (event: HCEModuleEvent) => {
+       const subscription = NativeHCEModule?.onEvent(async (event: HCEModuleEvent) => {
            switch (event.type) {
                /* ... implement event handlers here ... */
            }
@@ -132,7 +131,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 +162,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
@@ -182,6 +181,7 @@ This module provides a uniform low-level HCE API for both mobile platforms.
    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,6 +195,51 @@ 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
+   AppRegistry.registerHeadlessTask('handleBackgroundHCECall', () => {
+      return async () => {
+         return await runBackground();
+      }
+   });
+   ```
+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
+   async function runBackground() {
+      let subscription = NativeHCEModule?.onBackgroundEvent(async (event: HCEModuleBackgroundEvent) => {
+         switch (event.type) {
+            /* ... background HCE event handler here ... */
+         }
+      });
+   
+      await NativeHCEModule?.initBackgroundHCE();
+   }
+   ```
+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':
+       // cleanup, remove the event listener
+       subscription.remove();
+       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 NativeHCEModule?.respondAPDU(Buffer.from([0x0A, 0x90, 0x00], "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)

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,235 @@
+/*
+ * 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;
+
+@RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
+public class HCEService extends HostApduService implements ReactInstanceEventListener, HCEServiceCallback {
+    private static final String TAG = "HCEService";
+
+    private boolean isForeground;
+    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() {
+        Log.d(TAG, "HCEService:onBackgroundHCEInit");
+
+        if (pendingCAPDU != null) {
+            Log.d(TAG, "HCEService:onBackgroundHCEInit send pendingCAPDU");
+            hceModule.sendBackgroundEvent("received", BinaryUtils.ByteArrayToHexString(pendingCAPDU));
+            pendingCAPDU = null;
+        }
+    }
+
+    @Override
+    public void onRespondAPDU(String rapdu) {
+        Log.d(TAG, "HCEService:onRespondAPDU");
+
+        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("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");
+
+            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");
+
+            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("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");
+                HeadlessJsTaskContext headlessJsTaskContext = Companion.getInstance(reactContext);
+                headlessJsTaskContext.startTask(
+                        new HeadlessJsTaskConfig(
+                                "handleBackgroundHCECall",
+                                Arguments.fromBundle(new Bundle()),
+                                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();
+    void onRespondAPDU(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,81 @@ 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 type, final String arg) {
+        Log.d(TAG, "RTNHCEAndroidModule:sendBackgroundEvent");
+        WritableMap map = Arguments.createMap();
+        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 +104,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 +135,41 @@ 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 void initBackgroundHCE(Promise promise) {
+        Log.d(TAG, "RTNHCEAndroidModule:initBackgroundHCE");
+
+        this.hceBackgroundReady = true;
+
+        promise.resolve(null);
+
+        this.serviceCb.onBackgroundHCEInit();
+    }
+
     @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 +181,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 +198,7 @@ public class RTNHCEAndroidModule extends NativeHCEModuleSpec {
 
             if (!this.hceDeselected) {
                 this.hceDeselected = true;
-                this.hceBreakConnection = true;
+                this.hceBrokenConnection = true;
                 sendEvent("readerDeselected", "");
             }
         }
@@ -218,24 +209,33 @@ 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;
+        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(rapdu);
+        } catch (IllegalStateException e) {
+            promise.reject("err_no_capdu", "There is no C-APDU to respond to at the time.");
+            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 @@
     }
 }
 
+- (void)initBackgroundHCE:(nonnull RCTPromiseResolveBlock)resolve reject:(nonnull RCTPromiseRejectBlock)reject {
+    reject(@"err_platform_unsupported", @"Background HCE is not supported on iOS.", nil);
+}
+
 - (void)startHCE:(nonnull RCTPromiseResolveBlock)resolve reject:(nonnull RCTPromiseRejectBlock)reject {
     if (@available(iOS 17.4, *)) {
         return [hcemoduleios startHCEWithResolve:resolve reject:reject];

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,20 @@ 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,
+}
+
 export interface Spec extends TurboModule {
   /**
    * Checks if a given smartphone supports required HCE features.
@@ -63,6 +73,8 @@ export interface Spec extends TurboModule {
    */
   isSessionRunning(): boolean;
 
+  initBackgroundHCE(): Promise<void>;
+
   /**
    * iOS: Start the card emulation.
    * Android: Enable HCE service.
@@ -84,6 +96,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icedevml/react-native-host-card-emulation",
-  "version": "0.4.1",
+  "version": "0.5.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);
-    }
-}