@apex-inc/capacitor-plugin 0.3.9 → 2.2.0

package/README.md

@@ -23,9 +23,9 @@ Call `initialize()` once at app startup, before any other plugin method.
 import { Apex } from "@apex-inc/capacitor-plugin";
 
 await Apex.initialize({
-  projectKey: "prj_your_key",
+  workspaceKey: "prj_your_key",
   // Optional:
-  // apiUrl: "https://api.apex.inc",
+  // apiUrl: "https://app.apex.inc",
   // sessionTimeoutMinutes: 30,
   // offlineQueueMaxSize: 1000,
   // testMode: false,
@@ -117,7 +117,7 @@ extension AppDelegate {
 Then enable the **Push Notifications** capability in Xcode (Signing &
 Capabilities → + → Push Notifications). Sandbox builds (Xcode-built
 installs to a real device) hit Apple's sandbox APNs endpoint —
-configure that environment in your Apex project settings.
+configure that environment in your Apex workspace settings.
 
 ## iOS App Tracking Transparency
 
@@ -185,7 +185,7 @@ const { flushed, remaining } = await Apex.flushQueue();
 
 ```ts
 // At init:
-await Apex.initialize({ projectKey: "prj_test", testMode: true });
+await Apex.initialize({ workspaceKey: "prj_test", testMode: true });
 
 // Or toggle at runtime:
 await Apex.setTestMode({ enabled: true });
@@ -199,4 +199,4 @@ The plugin runs in a browser or PWA too — identifiers return null, ATT is a no
 
 ## License
 
-Apache-2.0 — see [LICENSE](./LICENSE). See also the project [plan document](../../plans/mobile-measurement-platform.md) for the full MMP roadmap.
+Apache-2.0 — see [LICENSE](./LICENSE). See also the workspace [plan document](../../plans/mobile-measurement-platform.md) for the full MMP roadmap.

package/android/build.gradle

@@ -57,8 +57,10 @@ dependencies {
     implementation "com.android.installreferrer:installreferrer:$installreferrerVersion"
     // Play Services Ads for GAID
     implementation "com.google.android.gms:play-services-ads-identifier:18.0.1"
-    // Firebase Messaging for FCM push tokens (used in Phase 5f uninstall tracking)
-    compileOnly "com.google.firebase:firebase-messaging:23.4.0"
+    // Firebase Messaging for FCM push tokens + alert notifications.
+    // `implementation` (not compileOnly) so the messaging service +
+    // token APIs are available at runtime for Android push.
+    implementation "com.google.firebase:firebase-messaging:23.4.0"
 
     testImplementation "junit:junit:$junitVersion"
     testImplementation "org.jetbrains.kotlinx:kotlinx-coroutines-test:1.7.3"

package/android/src/main/AndroidManifest.xml

@@ -1,8 +1,40 @@
-<?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
-    <!-- Access Google Advertising ID (GAID) on API 24+. -->
     <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
-    <!-- Network required for batch-sender event delivery. -->
     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <!-- Android 13+ runtime permission for posting notifications (FCM alerts). -->
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <!-- FCM messaging service: receives the device token (onNewToken) and
+         alert messages (onMessageReceived). Merged into the host app's
+         manifest by the Android build. -->
+    <application>
+        <service
+            android:name="inc.apex.capacitor.ApexFirebaseMessagingService"
+            android:exported="false">
+            <intent-filter>
+                <action android:name="com.google.firebase.MESSAGING_EVENT" />
+            </intent-filter>
+        </service>
+    </application>
+
+    <!--
+        MMP-061 — release channel detection. On Android 11+ (API 30),
+        `PackageManager.getInstallerPackageName(pkg)` returns null unless
+        the calling package declares a <queries> element listing the
+        installers it cares about. Without this, half of the Play
+        Store + sideloaded device base would read as "unknown" / "sideloaded".
+
+        We use `PackageManager.getInstallSourceInfo()` on API 30+ (no
+        <queries> needed for the caller's OWN package). The query block
+        below explicitly lists Play + AOSP installer packages so the
+        legacy `getInstallerPackageName` fallback on API 29 and below
+        also resolves correctly.
+    -->
+    <queries>
+        <package android:name="com.android.vending" />
+        <package android:name="com.google.android.feedback" />
+        <package android:name="com.amazon.venezia" />
+        <package android:name="com.sec.android.app.samsungapps" />
+    </queries>
 </manifest>

package/android/src/main/java/inc/apex/capacitor/ApexCapacitorPlugin.kt

@@ -13,6 +13,7 @@ import com.getcapacitor.PluginCall
 import com.getcapacitor.PluginMethod
 import com.getcapacitor.annotation.CapacitorPlugin
 import com.google.android.gms.ads.identifier.AdvertisingIdClient
+import com.google.firebase.messaging.FirebaseMessaging
 import java.io.File
 import java.util.Locale
 import java.util.TimeZone
@@ -47,11 +48,23 @@ class ApexCapacitorPlugin : Plugin() {
     }
 
     private var offlineQueue: NativeOfflineQueue? = null
+    private var batchSender: NativeBatchSender? = null
     private var prefs: SharedPreferences? = null
     private var visitorId: String = ""
     private var testMode: Boolean = false
     private var debug: Boolean = false
     private var lastInstallReferrer: String? = null
+    // Phase 2-SDK — workspace-bound SDK key forwarded as
+    // `x-apex-api-key` on every event POST + on `identify()`.
+    private var apiKey: String? = null
+    private var apiBaseUrl: String = "https://app.apex.inc"
+    private var workspaceKey: String = ""
+
+    // MMP-061 — cached release channel + source. Detected once per
+    // launch in `initialize()` from installer-package source +
+    // `BuildConfig.DEBUG` + optional JS override.
+    private var releaseChannel: String = "unknown"
+    private var releaseChannelSource: String = "auto"
 
     override fun load() {
         val ctx = context
@@ -72,17 +85,50 @@ class ApexCapacitorPlugin : Plugin() {
                 deepLinks.setInitialUrl(url)
             }
         }
+
+        // Register as the active plugin so the FCM messaging service can
+        // forward token refreshes + taps to JS listeners.
+        activePlugin = this
+
+        // If the app was launched by tapping an FCM notification, the
+        // launcher intent carries the apex push data as extras — forward
+        // it as `pushClicked` so the app can report engagement + route.
+        activity.intent?.extras?.let { extras ->
+            if (extras.getString("apex_messageId") != null ||
+                extras.getString("apex_apexToken") != null ||
+                extras.getString("apex_url") != null
+            ) {
+                emitPushClicked(
+                    url = extras.getString("apex_url"),
+                    messageId = extras.getString("apex_messageId"),
+                    apexToken = extras.getString("apex_apexToken"),
+                )
+            }
+        }
+    }
+
+    /** Forward a push tap to JS listeners (`pushClicked`). */
+    private fun emitPushClicked(url: String?, messageId: String?, apexToken: String?) {
+        val data = JSObject()
+        if (url != null) data.put("url", url)
+        if (messageId != null) data.put("messageId", messageId)
+        if (apexToken != null) data.put("apexToken", apexToken)
+        notifyListeners("pushClicked", JSObject().put("data", data))
     }
 
     @PluginMethod
     fun initialize(call: PluginCall) {
-        val projectKey = call.getString("projectKey")
-        if (projectKey.isNullOrEmpty()) {
-            call.reject("projectKey is required")
+        val pk = call.getString("workspaceKey")
+        if (pk.isNullOrEmpty()) {
+            call.reject("workspaceKey is required")
             return
         }
+        workspaceKey = pk
         testMode = call.getBoolean("testMode", false) ?: false
         debug = call.getBoolean("debug", false) ?: false
+        apiBaseUrl = call.getString("apiUrl") ?: "https://app.apex.inc"
+        val rawKey = call.getString("apiKey")
+        apiKey = if (rawKey.isNullOrEmpty()) null else rawKey
         val maxSize = call.getInt("offlineQueueMaxSize") ?: 1000
 
         val queueFile = File(context.filesDir, "apex-capacitor/events.json")
@@ -90,12 +136,200 @@ class ApexCapacitorPlugin : Plugin() {
         val storage = FileQueueStorage(queueFile)
         offlineQueue = NativeOfflineQueue(storage, maxSize = maxSize)
 
+        // MMP-215 — drain the queue. Without this, every event captured
+        // while the webview was unmounted is stranded in apex-capacitor/
+        // events.json forever.
+        batchSender = NativeBatchSender(
+            apiBaseUrl = apiBaseUrl,
+            workspaceKey = workspaceKey,
+            platformHeader = "android",
+            apiKey = apiKey,
+            debug = debug,
+        )
+
+        // MMP-061 — release channel detection. Unlike iOS, Play doesn't
+        // surface internal/closed/open tracks at the device level
+        // (`com.android.vending` is the installer for every Play install).
+        // So an explicit override here is the canonical Android path
+        // for tagging closed-test builds until Play Console API
+        // reconciliation lands (MMP-069). Wire `Apex.initialize({
+        // releaseChannel: BuildConfig.RELEASE_CHANNEL })` from your
+        // Gradle build flavors and the channel reflects the flavor.
+        val override = call.getString("releaseChannel")
+        if (!override.isNullOrEmpty() && isValidReleaseChannel(override)) {
+            releaseChannel = override
+            releaseChannelSource = "override"
+            if (debug) {
+                println("[apex-capacitor] releaseChannel override = $override")
+            }
+        } else {
+            releaseChannel = detectReleaseChannel()
+            releaseChannelSource = "auto"
+            if (debug) {
+                println("[apex-capacitor] releaseChannel detected = $releaseChannel")
+            }
+        }
+
+        // Persist the bits the FCM messaging service needs to register a
+        // refreshed token on its own (it runs in a separate process
+        // context without access to the plugin's in-memory fields).
+        prefs?.edit()
+            ?.putString("workspaceKey", workspaceKey)
+            ?.putString("apiBaseUrl", apiBaseUrl)
+            ?.putString("apiKey", apiKey)
+            ?.apply()
+
         // Fire-and-forget install referrer retrieval on init.
         fetchInstallReferrer()
 
         call.resolve()
     }
 
+    // ── Push notifications (FCM) ──────────────────────────────────────
+    @PluginMethod
+    fun registerForPushNotifications(call: PluginCall) {
+        try {
+            FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
+                if (!task.isSuccessful) {
+                    call.resolve(
+                        JSObject().put("permission", "denied").put("token", null as String?),
+                    )
+                    return@addOnCompleteListener
+                }
+                val token = task.result
+                if (token.isNullOrEmpty()) {
+                    call.resolve(
+                        JSObject().put("permission", "denied").put("token", null as String?),
+                    )
+                    return@addOnCompleteListener
+                }
+                // Auto-register with Apex (same contract as iOS) so the
+                // dashboard sees the device immediately.
+                registerFcmToken(token)
+                notifyListeners(
+                    "pushTokenReceived",
+                    JSObject().put("token", token).put("platform", "android"),
+                )
+                call.resolve(
+                    JSObject().put("permission", "granted").put("token", token),
+                )
+            }
+        } catch (e: Exception) {
+            call.reject("FCM registration failed: ${e.message ?: "unknown"}")
+        }
+    }
+
+    /**
+     * POST the FCM token to Apex's `/api/mobile/push-token` (same route
+     * the iOS plugin auto-registers against). Best-effort + background.
+     */
+    private fun registerFcmToken(token: String) {
+        val pk = workspaceKey
+        if (pk.isEmpty()) return
+        val appVersion = try {
+            context.packageManager.getPackageInfo(context.packageName, 0).versionName
+        } catch (_: Exception) {
+            null
+        }
+        val payload = JSObject()
+            .put("workspaceKey", pk)
+            .put("visitorId", visitorId)
+            .put("platform", "android")
+            .put("token", token)
+            .put("bundleId", context.packageName)
+            .put("appVersion", appVersion ?: "")
+        Thread {
+            try {
+                val url = java.net.URL("${apiBaseUrl.trimEnd('/')}/api/mobile/push-token")
+                val conn = url.openConnection() as java.net.HttpURLConnection
+                conn.requestMethod = "POST"
+                conn.doOutput = true
+                conn.setRequestProperty("Content-Type", "application/json")
+                apiKey?.let { conn.setRequestProperty("x-apex-api-key", it) }
+                conn.connectTimeout = 10000
+                conn.readTimeout = 15000
+                conn.outputStream.use { it.write(payload.toString().toByteArray(Charsets.UTF_8)) }
+                conn.responseCode
+                conn.disconnect()
+            } catch (e: Exception) {
+                if (debug) println("[apex-capacitor] FCM token register failed: ${e.message}")
+            }
+        }.start()
+    }
+
+    /**
+     * MMP-061 — detect the build's `releaseChannel` from the installer
+     * package source + `BuildConfig.DEBUG`.
+     *
+     * Detection waterfall:
+     *   1. `BuildConfig.DEBUG=true` → `xcode-debug` (Gradle debug).
+     *      Returned before installer-source so debug builds installed
+     *      via Play Internal still report as `xcode-debug` for the
+     *      developer's own machine.
+     *   2. **API 30+** uses `PackageManager.getInstallSourceInfo()` —
+     *      doesn't require a `<queries>` declaration for the caller's
+     *      own package, so it works regardless of manifest.
+     *   3. **API 29 and below** uses the deprecated
+     *      `getInstallerPackageName()`. Works on every API level but
+     *      requires the `<queries>` block we added in the manifest so
+     *      the result isn't silently null on API 30+.
+     *
+     * Mapping (post-API-version split):
+     *   - `com.android.vending` (Play Store)              → `play-production`
+     *   - `com.google.android.feedback` (legacy Play)     → `play-production`
+     *   - any other non-null installer (Amazon, Samsung)  → `sideloaded`
+     *   - `null` (sideloaded APK, adb install, unknown)   → `sideloaded`
+     */
+    private fun detectReleaseChannel(): String {
+        // Step 1 — Gradle DEBUG build.
+        try {
+            val buildConfigClass = Class.forName("${context.packageName}.BuildConfig")
+            val isDebug = buildConfigClass.getField("DEBUG").getBoolean(null)
+            if (isDebug) return "xcode-debug"
+        } catch (_: Throwable) {
+            // BuildConfig might not be reachable in some test environments.
+            // Fall through to installer-source detection.
+        }
+
+        // Step 2 / 3 — installer source.
+        val installer: String? = try {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                val info = context.packageManager.getInstallSourceInfo(context.packageName)
+                info.installingPackageName
+            } else {
+                @Suppress("DEPRECATION")
+                context.packageManager.getInstallerPackageName(context.packageName)
+            }
+        } catch (_: Exception) {
+            null
+        }
+
+        return when (installer) {
+            "com.android.vending" -> "play-production"
+            "com.google.android.feedback" -> "play-production"
+            null -> "sideloaded"
+            else -> "sideloaded"
+        }
+    }
+
+    /**
+     * Validate a JS-supplied `releaseChannel` override. Anything we don't
+     * recognise gets ignored (we fall back to auto-detection). Mirrors
+     * the type union in `packages/capacitor/src/definitions.ts`.
+     */
+    private fun isValidReleaseChannel(channel: String): Boolean {
+        return when (channel) {
+            "xcode-debug",
+            "testflight",
+            "app-store",
+            "play-internal",
+            "play-production",
+            "sideloaded",
+            "unknown" -> true
+            else -> false
+        }
+    }
+
     // ── ATT ───────────────────────────────────────────────────────────
     @PluginMethod
     fun requestTrackingAuthorization(call: PluginCall) {
@@ -160,6 +394,67 @@ class ApexCapacitorPlugin : Plugin() {
         call.resolve()
     }
 
+    // ── Identity (Phase 2-SDK) ────────────────────────────────────────
+    //
+    // POSTs to `${apiBaseUrl}/api/identity/stitch` with the current
+    // visitor id + supplied email + optional userId/traits. The server
+    // resolves the email to an Apex Contact, stamps verifiedAt = now,
+    // and runs the verified-mode downstream pipeline (affiliate
+    // stamping, scoring, journey dispatch).
+    //
+    // We use a background thread (`Thread {}`) rather than coroutines
+    // to keep the plugin's dependency footprint minimal — adding
+    // kotlinx.coroutines here would bloat every consumer's APK by ~1MB.
+    @PluginMethod
+    fun identify(call: PluginCall) {
+        val email = call.getString("email")?.trim()
+        if (email.isNullOrEmpty()) {
+            call.reject("email is required")
+            return
+        }
+        val userId = call.getString("userId")
+        val traits = call.getObject("traits")
+
+        val payload = JSObject()
+            .put("visitorId", visitorId)
+            .put("email", email)
+            .put("workspaceKey", workspaceKey)
+            .put("timestamp", java.time.Instant.now().toString())
+        if (!userId.isNullOrEmpty()) {
+            payload.put("userId", userId)
+        }
+        if (traits != null) {
+            payload.put("metadata", traits)
+        }
+
+        Thread {
+            try {
+                val url = java.net.URL("${apiBaseUrl.trimEnd('/')}/api/identity/stitch")
+                val conn = url.openConnection() as java.net.HttpURLConnection
+                conn.requestMethod = "POST"
+                conn.doOutput = true
+                conn.setRequestProperty("Content-Type", "application/json")
+                conn.setRequestProperty("x-apex-source", "sdk")
+                conn.setRequestProperty("x-apex-workspace", workspaceKey)
+                apiKey?.let { conn.setRequestProperty("x-apex-api-key", it) }
+                conn.connectTimeout = 10000
+                conn.readTimeout = 15000
+                conn.outputStream.use { os ->
+                    os.write(payload.toString().toByteArray(Charsets.UTF_8))
+                }
+                val code = conn.responseCode
+                conn.disconnect()
+                if (code in 200..299) {
+                    call.resolve()
+                } else {
+                    call.reject("identify: server rejected (HTTP $code)")
+                }
+            } catch (e: Exception) {
+                call.reject("identify network error: ${e.message ?: "unknown"}")
+            }
+        }.start()
+    }
+
     // ── SKAN (iOS-only) ───────────────────────────────────────────────
     @PluginMethod
     fun updateConversionValue(call: PluginCall) {
@@ -196,6 +491,10 @@ class ApexCapacitorPlugin : Plugin() {
             .put("bundleId", context.packageName)
             .put("timezone", TimeZone.getDefault().id)
             .put("locale", localeTag)
+            // MMP-061 — surface release channel for sample apps and
+            // developer-facing UIs.
+            .put("releaseChannel", releaseChannel)
+            .put("releaseChannelSource", releaseChannelSource)
         call.resolve(data)
     }
 
@@ -237,6 +536,33 @@ class ApexCapacitorPlugin : Plugin() {
         val payload = mutableMapOf<String, Any?>()
         call.data.keys().forEach { key -> payload[key] = call.data.opt(key) }
 
+        // MMP-061 — stamp release channel under event.mobile so the
+        // server's TrackingEvent shape lands the field in the right
+        // slot. On Android, installer source doesn't change post-install
+        // (a sideload-then-Play-upgrade still reports `sideloaded`), so
+        // unlike iOS we don't re-detect on `app_open`.
+        val mobileSlot: MutableMap<String, Any?> = when (val existing = payload["mobile"]) {
+            is JSObject -> {
+                val map = mutableMapOf<String, Any?>()
+                existing.keys().forEach { k -> map[k] = existing.opt(k) }
+                map
+            }
+            is Map<*, *> -> existing.entries.associate { (k, v) -> (k as String) to v }.toMutableMap()
+            else -> mutableMapOf()
+        }
+        mobileSlot["releaseChannel"] = releaseChannel
+        mobileSlot["releaseChannelSource"] = releaseChannelSource
+        payload["mobile"] = mobileSlot
+
+        // MMP-081 — runtime context. Native Android plugin always
+        // stamps `native-android`; we don't overwrite a value the
+        // caller already set (preserves test fixtures and unusual
+        // workflows). Stamped at enqueue time so it travels with the
+        // event whichever sender drains the queue.
+        if (payload["clientType"] == null) {
+            payload["clientType"] = "native-android"
+        }
+
         val event = NativeQueuedEvent(
             id = id,
             payload = payload,
@@ -269,10 +595,22 @@ class ApexCapacitorPlugin : Plugin() {
     @PluginMethod
     fun flushQueue(call: PluginCall) {
         val queue = offlineQueue
-        val data = JSObject()
-            .put("flushed", 0)
-            .put("remaining", queue?.size() ?: 0)
-        call.resolve(data)
+        val sender = batchSender
+        if (queue == null || sender == null) {
+            // Plugin not initialized — preserve the prior no-op shape so
+            // callers don't have to special-case this branch.
+            val data = JSObject()
+                .put("flushed", 0)
+                .put("remaining", 0)
+            call.resolve(data)
+            return
+        }
+        sender.flush(queue) { flushed, remaining ->
+            val data = JSObject()
+                .put("flushed", flushed)
+                .put("remaining", remaining)
+            call.resolve(data)
+        }
     }
 
     @PluginMethod
@@ -304,6 +642,65 @@ class ApexCapacitorPlugin : Plugin() {
             override fun onInstallReferrerServiceDisconnected() { }
         })
     }
+
+    companion object {
+        /**
+         * Weak-ish reference to the live plugin so the FCM messaging
+         * service (a separate Android component) can forward a refreshed
+         * token / a tap to JS listeners when the webview is alive.
+         */
+        @Volatile
+        var activePlugin: ApexCapacitorPlugin? = null
+
+        /**
+         * Register a (possibly refreshed) FCM token with Apex from the
+         * messaging service. Reads the persisted workspaceKey / apiBaseUrl
+         * / apiKey / visitorId from SharedPreferences so it works even
+         * when no plugin instance is alive (background token refresh).
+         */
+        fun registerTokenFromService(appContext: Context, token: String) {
+            val prefs = appContext.getSharedPreferences(
+                "apex-capacitor",
+                Context.MODE_PRIVATE,
+            )
+            val workspaceKey = prefs.getString("workspaceKey", null) ?: return
+            val apiBaseUrl = prefs.getString("apiBaseUrl", null) ?: "https://app.apex.inc"
+            val apiKey = prefs.getString("apiKey", null)
+            val visitorId = prefs.getString("visitorId", null) ?: return
+
+            val payload = JSObject()
+                .put("workspaceKey", workspaceKey)
+                .put("visitorId", visitorId)
+                .put("platform", "android")
+                .put("token", token)
+                .put("bundleId", appContext.packageName)
+            Thread {
+                try {
+                    val url = java.net.URL("${apiBaseUrl.trimEnd('/')}/api/mobile/push-token")
+                    val conn = url.openConnection() as java.net.HttpURLConnection
+                    conn.requestMethod = "POST"
+                    conn.doOutput = true
+                    conn.setRequestProperty("Content-Type", "application/json")
+                    apiKey?.let { conn.setRequestProperty("x-apex-api-key", it) }
+                    conn.connectTimeout = 10000
+                    conn.readTimeout = 15000
+                    conn.outputStream.use {
+                        it.write(payload.toString().toByteArray(Charsets.UTF_8))
+                    }
+                    conn.responseCode
+                    conn.disconnect()
+                } catch (_: Exception) {
+                    // best-effort
+                }
+            }.start()
+
+            // If the plugin is alive, surface the refreshed token to JS.
+            activePlugin?.notifyListeners(
+                "pushTokenReceived",
+                JSObject().put("token", token).put("platform", "android"),
+            )
+        }
+    }
 }
 
 /**