@apex-inc/capacitor-plugin 2.5.0 → 2.6.0

package/ApexIncCapacitorPlugin.podspec

@@ -11,6 +11,7 @@ Pod::Spec.new do |s|
   s.author = package['author']
   s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
   s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.resource_bundles = { 'ApexIncCapacitorPluginPrivacy' => ['ios/Sources/PrivacyInfo.xcprivacy'] }
   s.ios.deployment_target = '13.0'
   s.dependency 'Capacitor'
   s.swift_version = '5.9'

package/README.md

@@ -25,10 +25,12 @@ import { Apex } from "@apex-inc/capacitor-plugin";
 await Apex.initialize({
   workspaceKey: "prj_your_key",
   // Optional:
-  // apiKey: "apex_sk_…",       // see "API keys" below — unlocks verified identity stitching
+  // apiKey: "apex_pk_…", // app key only; see "API keys" below
   // apiUrl: "https://app.apex.inc",
   // autoTrackScreenViews: true, // default — screen_view auto-fires from SPA navigation
   // autoConversionValues: true, // default — Apex drives SKAdNetwork values from Set up Apex (iOS)
+  // autoTrackInstall: true, // default — app_install once, on the first launch of a fresh install
+  // metaAppId: "1234567890", // Android: credits installs from Meta ads (see "Meta install referrer")
   // sessionTimeoutMinutes: 30,
   // offlineQueueMaxSize: 1000,
   // testMode: false,
@@ -36,7 +38,17 @@ await Apex.initialize({
 });
 ```
 
-`app_open` auto-fires on `initialize()`. `screen_view` auto-fires from
+On iOS and Android the plugin sends `app_install` itself, once, on the
+first launch of a fresh install, carrying what Apex needs to credit the
+ad behind it. Someone who had your app before you added Apex is not sent
+as an install. If your app already tracks `app_install`, keep it or
+remove it: only the first one per install is sent.
+
+Track `app_open` yourself on launch and when the app returns to the
+foreground; on iOS and Android the plugin does not send it for you. (In a
+browser preview, the web version sends one `app_open` per page load.)
+
+`screen_view` auto-fires from
 the webview's History API (pushState / replaceState / back-forward /
 hashchange — covers Ionic, React Router, Vue Router, and plain SPA
 routing, on device and in browser preview). Screen names default to the
@@ -46,15 +58,30 @@ into your router instead.
 
 ### API keys
 
-`identify()` and server-trusted flows work best with a workspace SDK key
-(`apex_sk_…`). Mint one in the Apex dashboard under **Settings →
-Workspace → AI agents & API keys**, and pass it as `apiKey` in
-`initialize()`. Without a key, identity stitches from untrusted contexts
-may be quarantined (held un-verified) rather than applied — events still
-flow, but traits and journey triggers wait until a verified stitch.
-Treat the value like a publishable key: assume it can be extracted from
-the app bundle; Apex rate-limits per key + per visitor to keep leaked
-keys low-yield.
+Use an app key (`apex_pk_…`). Make one under Settings, Organization, API
+keys with the **App key** preset. It is safe to ship: it gives your app its
+own rate limit and lets a sign-up add a new person, but it never changes a
+person already in Apex, never counts revenue, and never sends anything to
+your ad platforms.
+
+Do not put a server key (`apex_sk_…`) or a personal key (`apex_uk_…`) in
+your app. Anyone can unpack an app and read the key, and either one lets
+them send purchases Apex counts as revenue and passes to your ad
+platforms. Send purchases from your server with a server key and the
+[Server Events API](https://app.apex.inc/docs/api/server-events), or
+connect the App Store or Google Play.
+
+### Signed sign-ins
+
+To attach a sign-in to someone already in Apex, have your server sign the
+email with your workspace's sign-in secret and pass the result as
+`userHash`:
+
+```ts
+await Apex.identify({ email, userHash }); // userHash comes from your backend
+```
+
+See [Signed sign-ins](https://app.apex.inc/docs/identity/signed-sign-ins).
 
 ## Track events
 
@@ -154,6 +181,27 @@ const { status: current } = await Apex.getTrackingStatus();
 
 ## Advertising identifiers
 
+Every event carries the phone's details under `mobile` (app id, app
+version, OS version, model, language, time zone, and on iOS the tracking
+answer). Apex passes them to the ad networks you connect, so they can
+credit installs and purchases to their ads. The advertising id rides
+along only with permission:
+
+- **iOS**: the IDFA, only after the person allowed tracking in the ATT
+  prompt. Read on every event, so a change in Settings applies at once.
+- **Android**: the GAID, only when the person has not limited ad tracking
+  or deleted the id. Looked up at `initialize()` and again when the app
+  opens.
+
+The plugin ships an Apple privacy manifest that declares the advertising
+id, app activity and purchases as used for tracking, since Apex sends
+installs and purchases to the ad networks you connect. Xcode merges it into your app's privacy report;
+your App Store privacy label should say the same.
+
+The IDFV and Android ID fallbacks below are never put on events. If your
+app asks for consent with `requireConsent`, nothing is sent at all until
+`setConsent({ granted: true })`.
+
 ```ts
 // Returns IDFA (iOS, ATT authorized), GAID (Android), or fallback.
 const { id, fallback } = await Apex.getAdvertisingId();
@@ -162,6 +210,24 @@ if (!id && fallback === "idfv") {
 }
 ```
 
+## Meta install referrer (Android)
+
+The Facebook, Instagram and Facebook Lite apps remember the Meta ad a
+person tapped or saw before installing yours. Pass your Meta app id and
+the install carries that ad to Apex:
+
+```ts
+await Apex.initialize({ workspaceKey: "prj_your_key", metaAppId: "1234567890" });
+```
+
+Skip `metaAppId` if your app already has the Facebook SDK's
+`com.facebook.sdk.ApplicationId` manifest entry; the plugin reads it.
+The ad stays encrypted on the phone. Apex opens it with your install
+referrer key: in Meta for Developers, open your app's Basic settings,
+find "Install Referrer Decryption Key" under Android, and paste it in
+Apex under the Meta connection. Needs Facebook 428, Instagram 296 or
+Facebook Lite 411 or newer on the phone.
+
 ## SKAdNetwork conversion values (iOS 4.0+)
 
 You do not have to write this code. In the Apex dashboard, **Set up Apex →

package/android/src/main/AndroidManifest.xml

@@ -36,5 +36,10 @@
         <package android:name="com.google.android.feedback" />
         <package android:name="com.amazon.venezia" />
         <package android:name="com.sec.android.app.samsungapps" />
+        <!-- Meta Install Referrer: Android 11+ hides these apps' content
+             providers unless the app declares it looks for them. -->
+        <package android:name="com.facebook.katana" />
+        <package android:name="com.instagram.android" />
+        <package android:name="com.facebook.lite" />
     </queries>
 </manifest>

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

@@ -52,6 +52,9 @@ class ApexCapacitorPlugin : Plugin() {
 
     private var offlineQueue: NativeOfflineQueue? = null
     private var batchSender: NativeBatchSender? = null
+    private val flushHandler = Handler(Looper.getMainLooper())
+    private var flushTimer: Runnable? = null
+    private var pendingTrackFlush: Runnable? = null
     private var prefs: SharedPreferences? = null
     private var visitorId: String = ""
     private var testMode: Boolean = false
@@ -64,9 +67,19 @@ class ApexCapacitorPlugin : Plugin() {
     // rather than returning null because the Play service hasn't
     // connected yet. Calls that arrive before the fetch completes are
     // parked and flushed by the listener.
-    private var installReferrerResolved: Boolean = false
+    @Volatile private var installReferrerResolved: Boolean = false
     private var installReferrerClickSeconds: Long = 0
     private val pendingReferrerCalls = mutableListOf<PluginCall>()
+    private val referrerLatch = java.util.concurrent.CountDownLatch(1)
+
+    // The install is sent once per install, by the plugin or the app, never both.
+    private var autoTrackInstall: Boolean = true
+    private val installLock = Any()
+
+    // Meta Install Referrer. Read once per launch, on the install event.
+    private var metaAppId: String? = null
+    @Volatile private var metaReferrerRead: Boolean = false
+    @Volatile private var metaReferrer: MetaInstallReferrer.Found? = 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
@@ -82,6 +95,27 @@ class ApexCapacitorPlugin : Plugin() {
     // Phase 4a — consent gate. Defaults granted; set false by
     // initialize({ requireConsent: true }) until setConsent({ granted:true }).
     private var consentGranted: Boolean = true
+
+    // The GAID, looked up off the main thread (Play services blocks) and
+    // refreshed on `app_open`, since the person can limit ad tracking or
+    // delete the id in Settings at any time.
+    @Volatile private var gaid: String? = null
+    @Volatile private var gaidResolved: Boolean = false
+    private val device by lazy {
+        val locale = Locale.getDefault()
+        MobileContext.Device(
+            bundleId = context.packageName,
+            appVersion = try {
+                context.packageManager.getPackageInfo(context.packageName, 0).versionName ?: "0.0.0"
+            } catch (_: Exception) {
+                "0.0.0"
+            },
+            osVersion = Build.VERSION.RELEASE,
+            deviceModel = "${Build.MANUFACTURER} ${Build.MODEL}".trim(),
+            timezone = TimeZone.getDefault().id,
+            locale = "${locale.language}-${locale.country}",
+        )
+    }
     // Phase 3 — per-launch dedup so each (experiment, variant) exposure fires
     // once. Concurrent set: getVariant resolves on background threads.
     private val firedExposures = java.util.concurrent.ConcurrentHashMap.newKeySet<String>()
@@ -153,6 +187,8 @@ class ApexCapacitorPlugin : Plugin() {
         apiKey = if (rawKey.isNullOrEmpty()) null else rawKey
         // Phase 4a — consent gate.
         consentGranted = !(call.getBoolean("requireConsent", false) ?: false)
+        metaAppId = MetaInstallReferrer.normalizeAppId(call.getString("metaAppId")) ?: manifestMetaAppId()
+        autoTrackInstall = call.getBoolean("autoTrackInstall", true) ?: true
         val maxSize = call.getInt("offlineQueueMaxSize") ?: 1000
 
         val queueFile = File(context.filesDir, "apex-capacitor/events.json")
@@ -170,6 +206,8 @@ class ApexCapacitorPlugin : Plugin() {
             apiKey = apiKey,
             debug = debug,
         )
+        scheduleFlushTimer()
+        kickFlush("initialize")
 
         // MMP-061 — release channel detection. Unlike iOS, Play doesn't
         // surface internal/closed/open tracks at the device level
@@ -205,10 +243,80 @@ class ApexCapacitorPlugin : Plugin() {
 
         // Fire-and-forget install referrer retrieval on init.
         fetchInstallReferrer()
+        Thread { resolveGaid() }.start()
+        // Off this thread: the install waits up to REFERRER_WAIT_MS for Play.
+        Thread { sendInstallIfFirstLaunch() }.start()
 
         call.resolve()
     }
 
+    /** First install time and this version's install time, from the package manager. */
+    private fun installTimes(): Pair<Long?, Long?> = try {
+        val info = context.packageManager.getPackageInfo(context.packageName, 0)
+        Pair(info.firstInstallTime, info.lastUpdateTime)
+    } catch (_: Exception) {
+        Pair(null, null)
+    }
+
+    /**
+     * Send `app_install` on the first launch of a fresh install. Marks the
+     * install as handled for someone who had the app before Apex, so the
+     * update that adds Apex reports no one as new.
+     */
+    private fun sendInstallIfFirstLaunch() {
+        if (!autoTrackInstall || !consentGranted || offlineQueue == null) return
+        val (installed, versionInstalled) = installTimes()
+        val decision = synchronized(installLock) {
+            val sent = prefs?.getBoolean(FirstLaunchInstall.PREF_KEY, false) == true
+            val d = FirstLaunchInstall.decide(sent, installed, versionInstalled, System.currentTimeMillis())
+            if (d != FirstLaunchInstall.Decision.ALREADY_SENT) {
+                prefs?.edit()?.putBoolean(FirstLaunchInstall.PREF_KEY, true)?.apply()
+            }
+            d
+        }
+        if (debug) println("[apex-capacitor] first-launch install: $decision")
+        if (decision != FirstLaunchInstall.Decision.SEND) return
+        try {
+            enqueuePayload(
+                UUID.randomUUID().toString().lowercase(),
+                mutableMapOf<String, Any?>("type" to "app_install", "data" to JSONObject().put("source", "apex_first_launch")),
+            )
+        } catch (e: Exception) {
+            if (debug) println("[apex-capacitor] first-launch install not queued: ${e.message}")
+        }
+    }
+
+    /** True the first time an install is claimed; the app's own `app_install` after that is dropped. */
+    private fun claimInstall(): Boolean = synchronized(installLock) {
+        if (prefs?.getBoolean(FirstLaunchInstall.PREF_KEY, false) == true) {
+            false
+        } else {
+            prefs?.edit()?.putBoolean(FirstLaunchInstall.PREF_KEY, true)?.apply()
+            true
+        }
+    }
+
+    private fun resolveGaid() {
+        if (Looper.myLooper() == Looper.getMainLooper()) return
+        gaid = try {
+            val info = AdvertisingIdClient.getAdvertisingIdInfo(context)
+            MobileContext.advertisingId(info.id, info.isLimitAdTrackingEnabled)
+        } catch (_: Exception) {
+            null
+        }
+        gaidResolved = true
+    }
+
+    /** The first event of a launch (often the install) waits for the lookup rather than going without. */
+    private fun currentGaid(): String? {
+        if (!gaidResolved) resolveGaid()
+        return gaid
+    }
+
+    private fun stampDevice(slot: MutableMap<String, Any?>) {
+        MobileContext.fill(slot, device, currentGaid())
+    }
+
     // ── Push notifications (FCM) ──────────────────────────────────────
     @PluginMethod
     fun registerForPushNotifications(call: PluginCall) {
@@ -468,6 +576,10 @@ class ApexCapacitorPlugin : Plugin() {
         if (traits != null) {
             payload.put("metadata", traits)
         }
+        val userHash = call.getString("userHash")
+        if (!userHash.isNullOrEmpty()) {
+            payload.put("userHash", userHash)
+        }
 
         Thread {
             try {
@@ -798,15 +910,12 @@ class ApexCapacitorPlugin : Plugin() {
             "surface" to "mobile",
             "app_version" to appVersion,
         )
-        if (testMode) payload["testMode"] = true
-        payload["platform"] = "android"
-        payload["timestamp"] = java.time.Instant.now().toString()
-        payload["visitorId"] = visitorId
+        TrackStamps.apply(payload, visitorId, testMode, java.time.Instant.now().toString())
         payload["clientType"] = "native-android"
         payload["mobile"] = mutableMapOf<String, Any?>(
             "releaseChannel" to releaseChannel,
             "releaseChannelSource" to releaseChannelSource,
-        )
+        ).also { stampDevice(it) }
         val event = NativeQueuedEvent(
             id = UUID.randomUUID().toString().lowercase(),
             payload = payload,
@@ -815,7 +924,7 @@ class ApexCapacitorPlugin : Plugin() {
         )
         try {
             queue.enqueue(event)
-            batchSender?.flush(queue) { _, _ -> }
+            kickFlush("track")
         } catch (e: Exception) {
             if (debug) println("[apex-capacitor] exposure enqueue failed: ${e.message}")
         }
@@ -896,8 +1005,7 @@ class ApexCapacitorPlugin : Plugin() {
     // ── Events / Queue ────────────────────────────────────────────────
     @PluginMethod
     fun track(call: PluginCall) {
-        val queue = offlineQueue
-        if (queue == null) {
+        if (offlineQueue == null) {
             call.reject("Plugin not initialized — call initialize() first")
             return
         }
@@ -910,6 +1018,23 @@ class ApexCapacitorPlugin : Plugin() {
         val id = call.getString("id") ?: UUID.randomUUID().toString().lowercase()
         val payload = mutableMapOf<String, Any?>()
         call.data.keys().forEach { key -> payload[key] = call.data.opt(key) }
+        if (payload["type"] == "app_install" && !claimInstall()) {
+            if (debug) println("[apex-capacitor] app_install already sent for this install; dropping")
+            call.resolve()
+            return
+        }
+        try {
+            enqueuePayload(id, payload)
+            call.resolve()
+        } catch (e: Exception) {
+            call.reject("Failed to enqueue event: ${e.message}")
+        }
+    }
+
+    /** Stamp and queue an event. Shared by `track()` and the plugin's own install. */
+    private fun enqueuePayload(id: String, payload: MutableMap<String, Any?>) {
+        val queue = offlineQueue ?: throw IllegalStateException("Plugin not initialized")
+        TrackStamps.apply(payload, visitorId, testMode, java.time.Instant.now().toString())
 
         // MMP-061 — stamp release channel under event.mobile so the
         // server's TrackingEvent shape lands the field in the right
@@ -927,7 +1052,10 @@ class ApexCapacitorPlugin : Plugin() {
         }
         mobileSlot["releaseChannel"] = releaseChannel
         mobileSlot["releaseChannelSource"] = releaseChannelSource
+        stampDevice(mobileSlot)
+        if (payload["type"] == "app_install") stampInstallReferrers(mobileSlot)
         payload["mobile"] = mobileSlot
+        if (payload["type"] == "app_open") Thread { resolveGaid() }.start()
 
         // MMP-081 — runtime context. Native Android plugin always
         // stamps `native-android`; we don't overwrite a value the
@@ -944,12 +1072,8 @@ class ApexCapacitorPlugin : Plugin() {
             attempts = 0,
             enqueuedAtMs = System.currentTimeMillis(),
         )
-        try {
-            queue.enqueue(event)
-            call.resolve()
-        } catch (e: Exception) {
-            call.reject("Failed to enqueue event: ${e.message}")
-        }
+        queue.enqueue(event)
+        kickFlush("track")
     }
 
     @PluginMethod
@@ -1001,11 +1125,8 @@ class ApexCapacitorPlugin : Plugin() {
         consentGranted = granted
         if (granted) {
             // Resume: flush anything captured before this point.
-            val queue = offlineQueue
-            val sender = batchSender
-            if (queue != null && sender != null) {
-                sender.flush(queue) { _, _ -> }
-            }
+            kickFlush("consent")
+            Thread { sendInstallIfFirstLaunch() }.start()
         } else {
             // Revoke: drop anything queued but not yet sent.
             try {
@@ -1023,6 +1144,54 @@ class ApexCapacitorPlugin : Plugin() {
 
     // ── Internal ──────────────────────────────────────────────────────
 
+    override fun handleOnResume() {
+        super.handleOnResume()
+        kickFlush("foreground")
+    }
+
+    override fun handleOnDestroy() {
+        flushTimer?.let { flushHandler.removeCallbacks(it) }
+        pendingTrackFlush?.let { flushHandler.removeCallbacks(it) }
+        super.handleOnDestroy()
+    }
+
+    /** Sends the queue every 30s so bursts and background captures leave the device. */
+    private fun scheduleFlushTimer() {
+        flushTimer?.let { flushHandler.removeCallbacks(it) }
+        val tick = object : Runnable {
+            override fun run() {
+                kickFlush("timer")
+                flushHandler.postDelayed(this, FLUSH_INTERVAL_MS)
+            }
+        }
+        flushTimer = tick
+        flushHandler.postDelayed(tick, FLUSH_INTERVAL_MS)
+    }
+
+    /**
+     * Fire-and-forget send. Track-triggered sends wait 250ms so a burst of
+     * taps goes as one batch. The sender only runs one drain at a time.
+     */
+    private fun kickFlush(reason: String) {
+        val queue = offlineQueue ?: return
+        val sender = batchSender ?: return
+        val run = Runnable {
+            if (debug) println("[apex-capacitor] flush kicked ($reason)")
+            sender.flush(queue) { flushed, remaining ->
+                if (debug && (flushed > 0 || remaining > 0)) {
+                    println("[apex-capacitor] flush done — sent $flushed, remaining $remaining")
+                }
+            }
+        }
+        if (reason == "track") {
+            pendingTrackFlush?.let { flushHandler.removeCallbacks(it) }
+            pendingTrackFlush = run
+            flushHandler.postDelayed(run, TRACK_FLUSH_DEBOUNCE_MS)
+        } else {
+            run.run()
+        }
+    }
+
     private fun fetchInstallReferrer() {
         val client = InstallReferrerClient.newBuilder(context).build()
         client.startConnection(object : InstallReferrerStateListener {
@@ -1056,8 +1225,71 @@ class ApexCapacitorPlugin : Plugin() {
         })
     }
 
+    /**
+     * The install event carries Play's referrer and Meta's, so Apex can
+     * credit the ad. Waits briefly for Play when it hasn't answered yet,
+     * off the main thread only.
+     */
+    private fun stampInstallReferrers(slot: MutableMap<String, Any?>) {
+        if (!installReferrerResolved && Looper.myLooper() != Looper.getMainLooper()) {
+            try {
+                referrerLatch.await(REFERRER_WAIT_MS, java.util.concurrent.TimeUnit.MILLISECONDS)
+            } catch (_: InterruptedException) { }
+        }
+        MetaInstallReferrer.stampInstall(slot, lastInstallReferrer, installReferrerClickSeconds, readMetaReferrer())
+    }
+
+    /** The Meta app id from the Facebook SDK's manifest entry, when the app has one. */
+    @Suppress("DEPRECATION")
+    private fun manifestMetaAppId(): String? = try {
+        val info = context.packageManager.getApplicationInfo(
+            context.packageName,
+            android.content.pm.PackageManager.GET_META_DATA,
+        )
+        MetaInstallReferrer.normalizeAppId(info.metaData?.get("com.facebook.sdk.ApplicationId")?.toString())
+    } catch (_: Exception) {
+        null
+    }
+
+    /** Ask the Facebook, Instagram and Facebook Lite apps for the Meta ad behind this install. */
+    private fun readMetaReferrer(): MetaInstallReferrer.Found? {
+        if (metaReferrerRead) return metaReferrer
+        val appId = metaAppId
+        if (appId == null) {
+            metaReferrerRead = true
+            return null
+        }
+        val found = mutableListOf<MetaInstallReferrer.Found>()
+        for ((authority, app) in MetaInstallReferrer.PROVIDERS) {
+            try {
+                if (context.packageManager.resolveContentProvider(authority, 0) == null) continue
+                val uri = Uri.parse("content://$authority/$appId")
+                context.contentResolver.query(uri, MetaInstallReferrer.COLUMNS, null, null, null)?.use { c ->
+                    if (!c.moveToFirst()) return@use
+                    val refIdx = c.getColumnIndex("install_referrer")
+                    if (refIdx < 0 || c.isNull(refIdx)) return@use
+                    val ctIdx = c.getColumnIndex("is_ct")
+                    val tsIdx = c.getColumnIndex("actual_timestamp")
+                    found += MetaInstallReferrer.Found(
+                        referrer = c.getString(refIdx),
+                        isClickThrough = if (ctIdx >= 0 && !c.isNull(ctIdx)) c.getInt(ctIdx) == 1 else null,
+                        timestampSeconds = if (tsIdx >= 0 && !c.isNull(tsIdx)) c.getLong(tsIdx) else null,
+                        app = app,
+                    )
+                }
+            } catch (e: Exception) {
+                if (debug) println("[apex-capacitor] Meta referrer from $app failed: ${e.message}")
+            }
+        }
+        metaReferrer = MetaInstallReferrer.latest(found)
+        metaReferrerRead = true
+        if (debug) println("[apex-capacitor] Meta install referrer ${if (metaReferrer != null) "found (${metaReferrer?.app})" else "not found"}")
+        return metaReferrer
+    }
+
     private fun flushPendingReferrerCalls() {
         installReferrerResolved = true
+        referrerLatch.countDown()
         val waiting = synchronized(pendingReferrerCalls) {
             val copy = pendingReferrerCalls.toList()
             pendingReferrerCalls.clear()
@@ -1090,6 +1322,9 @@ class ApexCapacitorPlugin : Plugin() {
          */
         private const val REFERRER_WAIT_MS = 2500L
 
+        private const val FLUSH_INTERVAL_MS = 30_000L
+        private const val TRACK_FLUSH_DEBOUNCE_MS = 250L
+
         /**
          * Register a (possibly refreshed) FCM token with Apex from the
          * messaging service. Reads the persisted workspaceKey / apiBaseUrl

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

@@ -0,0 +1,28 @@
+package inc.apex.capacitor
+
+/**
+ * Whether this launch should send `app_install`. The plugin sends it once
+ * per install so every app counts installs the same way; the app's own
+ * `app_install` is dropped once one has gone.
+ *
+ * Someone who had the app before Apex was added is not a new install: the
+ * update that brings Apex must not report every existing user to the ad
+ * networks as one. A fresh install is one made in the last 7 days, or one
+ * never updated since (the version installed is the one running).
+ */
+internal object FirstLaunchInstall {
+    const val PREF_KEY = "installSent"
+    const val FRESH_WINDOW_MS: Long = 7L * 24 * 3600 * 1000
+    private const val SAME_VERSION_TOLERANCE_MS: Long = 5L * 60 * 1000
+
+    enum class Decision { SEND, ALREADY_SENT, EXISTING_USER }
+
+    fun decide(alreadySent: Boolean, installedMs: Long?, versionInstalledMs: Long?, nowMs: Long): Decision {
+        if (alreadySent) return Decision.ALREADY_SENT
+        if (installedMs == null || installedMs <= 0) return Decision.SEND
+        if (versionInstalledMs != null && kotlin.math.abs(versionInstalledMs - installedMs) <= SAME_VERSION_TOLERANCE_MS) {
+            return Decision.SEND
+        }
+        return if (nowMs - installedMs <= FRESH_WINDOW_MS) Decision.SEND else Decision.EXISTING_USER
+    }
+}

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

@@ -0,0 +1,75 @@
+package inc.apex.capacitor
+
+/**
+ * Meta Install Referrer: the Facebook, Instagram and Facebook Lite apps
+ * keep the Meta ad a person tapped or saw before installing, and hand it to
+ * the app that was installed. Play's referrer only carries a tap that led
+ * straight to the install; this also carries views and earlier taps.
+ *
+ * The campaign inside is encrypted with the app owner's key. The plugin
+ * never decrypts it; it goes to Apex on the `app_install` event and Apex
+ * opens it with the key the shop saved in the Meta connection.
+ *
+ * Pure logic here (no Android imports) so it runs under plain JUnit. The
+ * ContentResolver query lives in the plugin.
+ */
+internal object MetaInstallReferrer {
+
+    /** Content provider authority → the app name Apex records. */
+    val PROVIDERS: List<Pair<String, String>> = listOf(
+        "com.facebook.katana.provider.InstallReferrerProvider" to "facebook",
+        "com.instagram.contentprovider.InstallReferrerProvider" to "instagram",
+        "com.facebook.lite.provider.InstallReferrerProvider" to "facebook_lite",
+    )
+
+    val COLUMNS: Array<String> = arrayOf("install_referrer", "is_ct", "actual_timestamp")
+
+    data class Found(
+        val referrer: String,
+        /** Null when the Meta app didn't say tap or view. */
+        val isClickThrough: Boolean?,
+        /** When the tap or view happened, in seconds. */
+        val timestampSeconds: Long?,
+        val app: String,
+    )
+
+    /**
+     * The Meta app id as the provider path wants it: digits only. Accepts
+     * the Facebook SDK's `fb1234…` form as well as the plain id.
+     */
+    fun normalizeAppId(raw: String?): String? {
+        val trimmed = raw?.trim()?.removePrefix("fb") ?: return null
+        return if (trimmed.isNotEmpty() && trimmed.all { it.isDigit() }) trimmed else null
+    }
+
+    /** The most recent touch wins when more than one Meta app answered. */
+    fun latest(found: List<Found>): Found? =
+        found.filter { it.referrer.isNotBlank() }.maxByOrNull { it.timestampSeconds ?: 0L }
+
+    /** What goes under `event.mobile.metaInstallReferrer`. */
+    fun toSlot(found: Found): Map<String, Any?> {
+        val slot = mutableMapOf<String, Any?>("referrer" to found.referrer, "app" to found.app)
+        found.isClickThrough?.let { slot["isClickThrough"] = it }
+        found.timestampSeconds?.let { if (it > 0) slot["timestamp"] = it }
+        return slot
+    }
+
+    /**
+     * Stamp the install's referrers on an `app_install` event, keeping
+     * anything the app already set.
+     */
+    fun stampInstall(
+        slot: MutableMap<String, Any?>,
+        playReferrer: String?,
+        playClickSeconds: Long,
+        meta: Found?,
+    ) {
+        if (slot["installReferrer"] == null && !playReferrer.isNullOrBlank()) {
+            slot["installReferrer"] = playReferrer
+            if (playClickSeconds > 0) slot["installReferrerClickTimestamp"] = playClickSeconds
+        }
+        if (slot["metaInstallReferrer"] == null && meta != null) {
+            slot["metaInstallReferrer"] = toSlot(meta)
+        }
+    }
+}