refactor(android): replace IntercomMessagingService with static IntercomFcmHelper (#7)

* feat(android): add native push notification handling for Intercom

Add IntercomMessagingService (FirebaseMessagingService with priority 100)
that handles Intercom pushes natively via handlePush(), ensuring
notifications display correctly when the app is backgrounded. Non-Intercom
messages are forwarded to @capacitor/push-notifications via reflection.

Add IntercomInitProvider (ContentProvider) that reads Intercom keys from
capacitor.config.json and initializes the SDK at app startup, before any
Activity launches. This prevents crashes when tapping a notification on
cold start (IntercomRootActivity requires Intercom to be initialized).

Users just need to add their keys to capacitor.config.json:

  "plugins": {
    "CapgoIntercom": {
      "androidApiKey": "android_sdk-...",
      "androidAppId": "your-app-id"
    }
  }

* fix: address PR review comments on IntercomInitProvider and manifest

- Return true from IntercomInitProvider.onCreate() per ContentProvider contract
- Use ByteArrayOutputStream loop instead of unreliable is.available()/is.read()
- Use try-with-resources for proper InputStream cleanup
- Use fully-qualified class names in AndroidManifest.xml

* refactor(android): replace IntercomMessagingService with static IntercomFcmHelper

Android only allows one FirebaseMessagingService, so the plugin should not
register its own service — it conflicts with other FCM-dependent plugins
(e.g. @capacitor/push-notifications, Pushwoosh, OneSignal).

Instead, provide a static helper class (IntercomFcmHelper) that app developers
call from their own FirebaseMessagingService, following the same pattern as
Pushwoosh's PushwooshFcmHelper.

Changes:
- Delete IntercomMessagingService and its manifest registration
- Add IntercomFcmHelper with isIntercomPush(), onMessageReceived(), onNewToken()
- Change firebase-messaging dependency to compileOnly (app provides it)

* docs: add Android push notification setup guide for IntercomFcmHelper

Document how to create a custom FirebaseMessagingService that routes
Intercom pushes via IntercomFcmHelper while remaining compatible with
other Firebase plugins.

Author: WcaleNieWolny

README.md

@@ -69,6 +69,53 @@ The Intercom iOS SDK (`~> 19.0`) is included automatically via CocoaPods or Swif
 
 The Intercom Android SDK (`17.4.2`) is included automatically via Gradle.
 
+#### Push Notifications
+
+Since Android only allows **one** `FirebaseMessagingService`, this plugin does **not** register its own. Instead it provides `IntercomFcmHelper` — a static helper you call from your app's service.
+
+1. Create your own `FirebaseMessagingService` in your app (e.g. `app/src/main/java/.../MyFirebaseMessagingService.java`):
+
+```java
+package com.your.app;
+
+import com.google.firebase.messaging.FirebaseMessagingService;
+import com.google.firebase.messaging.RemoteMessage;
+import app.capgo.capacitor.intercom.IntercomFcmHelper;
+
+public class MyFirebaseMessagingService extends FirebaseMessagingService {
+
+    @Override
+    public void onMessageReceived(RemoteMessage remoteMessage) {
+        if (IntercomFcmHelper.isIntercomPush(remoteMessage)) {
+            IntercomFcmHelper.onMessageReceived(this, remoteMessage);
+        } else {
+            // Handle other push SDKs (e.g. @capacitor/push-notifications)
+            // or your own notification logic here
+        }
+    }
+
+    @Override
+    public void onNewToken(String token) {
+        IntercomFcmHelper.onNewToken(this, token);
+        // Forward token to other SDKs if needed
+    }
+}
+```
+
+2. Register it in your app's `AndroidManifest.xml`:
+
+```xml
+<service
+    android:name=".MyFirebaseMessagingService"
+    android:exported="false">
+    <intent-filter>
+        <action android:name="com.google.firebase.MESSAGING_EVENT" />
+    </intent-filter>
+</service>
+```
+
+This approach is compatible with any other Firebase plugin — you control the routing.
+
 ## API
 
 <docgen-index>

android/build.gradle

@@ -55,6 +55,7 @@ dependencies {
     annotationProcessor project(':capacitor-android')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
     implementation "io.intercom.android:intercom-sdk:$intercomSdkVersion"
+    compileOnly "com.google.firebase:firebase-messaging:24.1.1"
     testImplementation "junit:junit:$junitVersion"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"

android/src/main/AndroidManifest.xml

@@ -1,2 +1,9 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application>
+        <provider
+            android:name="app.capgo.capacitor.intercom.IntercomInitProvider"
+            android:authorities="${applicationId}.intercom-init"
+            android:exported="false"
+            android:initOrder="100" />
+    </application>
 </manifest>

android/src/main/java/app/capgo/capacitor/intercom/IntercomFcmHelper.java

@@ -0,0 +1,72 @@
+package app.capgo.capacitor.intercom;
+
+import android.app.Application;
+import android.util.Log;
+import androidx.annotation.NonNull;
+import com.google.firebase.messaging.RemoteMessage;
+import io.intercom.android.sdk.push.IntercomPushClient;
+import java.util.Map;
+
+/**
+ * Static helper for routing Firebase Cloud Messaging events to Intercom.
+ *
+ * <p>Since Android allows only one {@code FirebaseMessagingService}, your app must
+ * create its own service and call these methods to forward Intercom pushes.
+ *
+ * <h3>Usage</h3>
+ * <pre>{@code
+ * public class MyFirebaseMessagingService extends FirebaseMessagingService {
+ *
+ *     @Override
+ *     public void onMessageReceived(RemoteMessage remoteMessage) {
+ *         if (IntercomFcmHelper.isIntercomPush(remoteMessage)) {
+ *             IntercomFcmHelper.onMessageReceived(this, remoteMessage);
+ *         } else {
+ *             // handle your own / other SDK pushes
+ *         }
+ *     }
+ *
+ *     @Override
+ *     public void onNewToken(String token) {
+ *         IntercomFcmHelper.onNewToken(this, token);
+ *         // also forward token to other SDKs if needed
+ *     }
+ * }
+ * }</pre>
+ */
+public final class IntercomFcmHelper {
+
+    private static final String TAG = "IntercomFcmHelper";
+    private static final IntercomPushClient pushClient = new IntercomPushClient();
+
+    private IntercomFcmHelper() {}
+
+    /**
+     * Returns {@code true} if this message was sent by Intercom.
+     */
+    public static boolean isIntercomPush(@NonNull RemoteMessage remoteMessage) {
+        return pushClient.isIntercomPush(remoteMessage.getData());
+    }
+
+    /**
+     * Passes an Intercom push message to the SDK for display.
+     * Call this only when {@link #isIntercomPush} returns {@code true}.
+     */
+    public static void onMessageReceived(@NonNull android.content.Context context, @NonNull RemoteMessage remoteMessage) {
+        Map<String, String> data = remoteMessage.getData();
+        if (pushClient.isIntercomPush(data)) {
+            Log.d(TAG, "Handling Intercom push");
+            Application app = (Application) context.getApplicationContext();
+            pushClient.handlePush(app, data);
+        }
+    }
+
+    /**
+     * Forwards a new FCM token to Intercom so the device can receive pushes.
+     */
+    public static void onNewToken(@NonNull android.content.Context context, @NonNull String token) {
+        Log.d(TAG, "Forwarding FCM token to Intercom");
+        Application app = (Application) context.getApplicationContext();
+        pushClient.sendTokenToIntercom(app, token);
+    }
+}

android/src/main/java/app/capgo/capacitor/intercom/IntercomInitProvider.java

@@ -0,0 +1,80 @@
+package app.capgo.capacitor.intercom;
+
+import android.app.Application;
+import android.content.ContentProvider;
+import android.content.ContentValues;
+import android.content.Context;
+import android.database.Cursor;
+import android.net.Uri;
+import android.util.Log;
+import io.intercom.android.sdk.Intercom;
+import java.io.ByteArrayOutputStream;
+import java.io.InputStream;
+import org.json.JSONObject;
+
+/**
+ * Auto-initializes Intercom at app startup by reading keys from capacitor.config.json.
+ *
+ * ContentProviders run before Application.onCreate(), which means Intercom is ready
+ * before any Activity launches — including IntercomRootActivity when the user taps
+ * a push notification on a cold start.
+ *
+ * Users just need to add their keys to capacitor.config.json:
+ *
+ *   "plugins": {
+ *     "CapgoIntercom": {
+ *       "androidApiKey": "android_sdk-...",
+ *       "androidAppId": "your-app-id"
+ *     }
+ *   }
+ */
+public class IntercomInitProvider extends ContentProvider {
+
+    private static final String TAG = "IntercomInitProvider";
+
+    @Override
+    public boolean onCreate() {
+        Context context = getContext();
+        if (context == null) return false;
+
+        try (InputStream is = context.getAssets().open("capacitor.config.json")) {
+            ByteArrayOutputStream result = new ByteArrayOutputStream();
+            byte[] buf = new byte[4096];
+            int len;
+            while ((len = is.read(buf)) != -1) {
+                result.write(buf, 0, len);
+            }
+
+            JSONObject config = new JSONObject(result.toString("UTF-8"));
+            JSONObject plugins = config.optJSONObject("plugins");
+            if (plugins == null) return true;
+
+            JSONObject intercomConfig = plugins.optJSONObject("CapgoIntercom");
+            if (intercomConfig == null) return true;
+
+            String apiKey = intercomConfig.optString("androidApiKey", "");
+            String appId = intercomConfig.optString("androidAppId", "");
+
+            if (!apiKey.isEmpty() && !appId.isEmpty()) {
+                Application app = (Application) context.getApplicationContext();
+                Intercom.initialize(app, apiKey, appId);
+                Log.d(TAG, "Intercom initialized from capacitor.config.json");
+            }
+        } catch (Exception e) {
+            Log.w(TAG, "Could not auto-initialize Intercom: " + e.getMessage());
+        }
+
+        return true;
+    }
+
+    @Override
+    public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder) { return null; }
+    @Override
+    public String getType(Uri uri) { return null; }
+    @Override
+    public Uri insert(Uri uri, ContentValues values) { return null; }
+    @Override
+    public int delete(Uri uri, String selection, String[] selectionArgs) { return 0; }
+    @Override
+    public int update(Uri uri, ContentValues values, String selection, String[] selectionArgs) { return 0; }
+}