@apex-inc/capacitor-plugin 0.1.0

package/ApexCapacitorPlugin.podspec

@@ -0,0 +1,17 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'ApexCapacitorPlugin'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['homepage']
+  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.ios.deployment_target = '14.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.9'
+end

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Apex Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,136 @@
+# @apex-inc/capacitor-plugin
+
+Apex Capacitor plugin — iOS and Android attribution, events, deep linking, SKAN, and offline-tolerant tracking for Capacitor apps.
+
+Ships alongside `apex.js` (the web snippet) so a Capacitor app gets unified identity and events across WebView + native APIs with one dependency pattern.
+
+> **Scope.** This plugin is for Capacitor apps. Native iOS (Swift), native Android (Kotlin), React Native, and Flutter apps need their own SDKs — see https://apex.inc/docs/mobile/which-sdk.
+
+## Install
+
+```sh
+npm install @apex-inc/capacitor-plugin
+npx cap sync
+```
+
+## Initialize
+
+Call `initialize()` once at app startup, before any other plugin method.
+
+```ts
+import { Apex } from "@apex-inc/capacitor-plugin";
+
+await Apex.initialize({
+  projectKey: "prj_your_key",
+  // Optional:
+  // apiUrl: "https://api.apex.inc",
+  // sessionTimeoutMinutes: 30,
+  // offlineQueueMaxSize: 1000,
+  // testMode: false,
+  // debug: false,
+});
+```
+
+## Track events
+
+```ts
+await Apex.track({
+  type: "app_open",
+  data: { from: "push_notification" },
+});
+
+// In-app purchase — typed payload
+await Apex.track({
+  type: "in_app_purchase",
+  purchase: {
+    productId: "com.example.app.pro_monthly",
+    amount: 9.99,
+    currency: "USD",
+    transactionId: "abc123",
+  },
+});
+```
+
+Every event gets a client-generated UUIDv4 `id` automatically. Server-side idempotency means replayed events never double-count.
+
+## iOS App Tracking Transparency
+
+```ts
+// Present the ATT prompt once (no-op on Android).
+const { status } = await Apex.requestTrackingAuthorization();
+
+// Check status later without prompting.
+const { status: current } = await Apex.getTrackingStatus();
+```
+
+## Advertising identifiers
+
+```ts
+// Returns IDFA (iOS, ATT authorized), GAID (Android), or fallback.
+const { id, fallback } = await Apex.getAdvertisingId();
+if (!id && fallback === "idfv") {
+  console.log("Using IDFV fallback — user denied ATT");
+}
+```
+
+## SKAdNetwork conversion values (iOS 4.0+)
+
+```ts
+await Apex.updateConversionValue({
+  fineValue: 42,
+  coarseValue: "high",
+});
+```
+
+## Deep links
+
+```ts
+// Cold start: read the URL that opened the app (if any).
+const { url } = await Apex.getInitialDeepLink();
+
+// Warm-start / subsequent links while running:
+await Apex.addListener("deepLink", ({ url }) => {
+  handleRoute(url);
+});
+```
+
+## Sessions
+
+```ts
+const { sessionId } = await Apex.startSession();
+
+await Apex.addListener("sessionEnd", ({ sessionId, durationSeconds }) => {
+  console.log(`Session ${sessionId} ended after ${durationSeconds}s`);
+});
+```
+
+## Offline durability
+
+Events are persisted to IndexedDB (web), Core Data (iOS), or Room (Android). If the device is offline, they queue up to the configured `offlineQueueMaxSize` (default 1000). When the network returns, the plugin drains the queue in batches with exponential-backoff retry.
+
+```ts
+const { count, oldestEventAt } = await Apex.getQueueSize();
+
+// Manually trigger a flush (rarely needed — happens automatically):
+const { flushed, remaining } = await Apex.flushQueue();
+```
+
+## Test mode
+
+```ts
+// At init:
+await Apex.initialize({ projectKey: "prj_test", testMode: true });
+
+// Or toggle at runtime:
+await Apex.setTestMode({ enabled: true });
+```
+
+Test-mode events are stored separately on the server and never pollute production analytics.
+
+## Web fallback
+
+The plugin runs in a browser or PWA too — identifiers return null, ATT is a no-op, events still flow to the server via the normal offline queue. This lets you run shared code paths between web + mobile without `Capacitor.isNativePlatform()` checks everywhere.
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE). See also the project [plan document](../../plans/mobile-measurement-platform.md) for the full MMP roadmap.

package/android/build.gradle

@@ -0,0 +1,68 @@
+// Gradle build script for @apex-inc/capacitor-plugin Android module.
+// Compiled alongside a consuming Capacitor app via `npx cap sync`.
+
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.6.1'
+    installreferrerVersion = '2.2'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.2.0'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.21"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace "inc.apex.capacitor"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 34
+        versionCode 1
+        versionName "0.1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation project(':capacitor-android')
+    // Play Install Referrer API — captures click IDs (gclid, fbclid) on install
+    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"
+
+    testImplementation "junit:junit:$junitVersion"
+    testImplementation "org.jetbrains.kotlinx:kotlinx-coroutines-test:1.7.3"
+    // org.json is included in Android runtime; for local JVM unit tests we
+    // need it as a test dependency.
+    testImplementation "org.json:json:20240303"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,8 @@
+<?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" />
+</manifest>

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

@@ -0,0 +1,325 @@
+package inc.apex.capacitor
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.net.Uri
+import android.os.Build
+import android.provider.Settings
+import com.android.installreferrer.api.InstallReferrerClient
+import com.android.installreferrer.api.InstallReferrerStateListener
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+import com.google.android.gms.ads.identifier.AdvertisingIdClient
+import java.io.File
+import java.util.Locale
+import java.util.TimeZone
+import java.util.UUID
+
+/**
+ * Capacitor plugin entry point for Android. Orchestrates the pure-Kotlin
+ * logic classes (SessionManager, OfflineQueue, DeepLinkManager, InstallReferrerParser)
+ * and exposes them to the JS side via Capacitor's PluginCall bridge.
+ *
+ * Tests that don't need the Capacitor runtime live in the test/ folder and
+ * target the pure-logic classes directly. This class is verified via Android
+ * instrumentation tests on a real device or emulator.
+ */
+@CapacitorPlugin(name = "ApexCapacitorPlugin")
+class ApexCapacitorPlugin : Plugin() {
+
+    private val deepLinks = DeepLinkManager()
+    private val sessionManager by lazy {
+        NativeSessionManager(
+            onStart = { snapshot ->
+                val data = JSObject().put("sessionId", snapshot.sessionId)
+                notifyListeners("sessionStart", data)
+            },
+            onEnd = { snapshot ->
+                val data = JSObject()
+                    .put("sessionId", snapshot.sessionId)
+                    .put("durationSeconds", snapshot.durationSeconds ?: 0)
+                notifyListeners("sessionEnd", data)
+            }
+        )
+    }
+
+    private var offlineQueue: NativeOfflineQueue? = 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
+
+    override fun load() {
+        val ctx = context
+        prefs = ctx.getSharedPreferences("apex-capacitor", Context.MODE_PRIVATE)
+        visitorId = prefs?.getString("visitorId", null)
+            ?: UUID.randomUUID().toString().lowercase().also {
+                prefs?.edit()?.putString("visitorId", it)?.apply()
+            }
+
+        deepLinks.setWarmLinkHandler { url ->
+            val data = JSObject().put("url", url)
+            notifyListeners("deepLink", data)
+        }
+
+        // Capture the intent that opened the activity, if any.
+        activity.intent?.data?.toString()?.let { url ->
+            if (DeepLinkManager.isValidDeepLink(url)) {
+                deepLinks.setInitialUrl(url)
+            }
+        }
+    }
+
+    @PluginMethod
+    fun initialize(call: PluginCall) {
+        val projectKey = call.getString("projectKey")
+        if (projectKey.isNullOrEmpty()) {
+            call.reject("projectKey is required")
+            return
+        }
+        testMode = call.getBoolean("testMode", false) ?: false
+        debug = call.getBoolean("debug", false) ?: false
+        val maxSize = call.getInt("offlineQueueMaxSize") ?: 1000
+
+        val queueFile = File(context.filesDir, "apex-capacitor/events.json")
+        queueFile.parentFile?.mkdirs()
+        val storage = FileQueueStorage(queueFile)
+        offlineQueue = NativeOfflineQueue(storage, maxSize = maxSize)
+
+        // Fire-and-forget install referrer retrieval on init.
+        fetchInstallReferrer()
+
+        call.resolve()
+    }
+
+    // ── ATT ───────────────────────────────────────────────────────────
+    @PluginMethod
+    fun requestTrackingAuthorization(call: PluginCall) {
+        // Android has no equivalent of ATT — tracking is governed by the
+        // system-level Ads Personalization toggle (surfaced via AdvertisingIdClient).
+        val data = JSObject().put("status", "authorized")
+        call.resolve(data)
+    }
+
+    @PluginMethod
+    fun getTrackingStatus(call: PluginCall) {
+        val data = JSObject().put("status", "authorized")
+        call.resolve(data)
+    }
+
+    // ── Identifiers ───────────────────────────────────────────────────
+    @PluginMethod
+    fun getAdvertisingId(call: PluginCall) {
+        Thread {
+            try {
+                val info = AdvertisingIdClient.getAdvertisingIdInfo(context)
+                val data = JSObject()
+                if (info.isLimitAdTrackingEnabled || info.id.isNullOrEmpty()) {
+                    val androidId = Settings.Secure.getString(
+                        context.contentResolver,
+                        Settings.Secure.ANDROID_ID
+                    )
+                    data.put("id", androidId)
+                    data.put("fallback", "android_id")
+                } else {
+                    data.put("id", info.id)
+                    data.put("fallback", null as String?)
+                }
+                call.resolve(data)
+            } catch (e: Exception) {
+                val data = JSObject().put("id", null as String?).put("fallback", null as String?)
+                call.resolve(data)
+            }
+        }.start()
+    }
+
+    @PluginMethod
+    fun getInstallReferrer(call: PluginCall) {
+        val data = JSObject().put("referrer", lastInstallReferrer ?: JSONull())
+        call.resolve(data)
+    }
+
+    @PluginMethod
+    fun getVisitorId(call: PluginCall) {
+        call.resolve(JSObject().put("visitorId", visitorId))
+    }
+
+    @PluginMethod
+    fun setVisitorId(call: PluginCall) {
+        val id = call.getString("visitorId")
+        if (id.isNullOrEmpty()) {
+            call.reject("visitorId is required")
+            return
+        }
+        visitorId = id
+        prefs?.edit()?.putString("visitorId", id)?.apply()
+        call.resolve()
+    }
+
+    // ── SKAN (iOS-only) ───────────────────────────────────────────────
+    @PluginMethod
+    fun updateConversionValue(call: PluginCall) {
+        // No-op on Android.
+        call.resolve()
+    }
+
+    // ── Deep Links ────────────────────────────────────────────────────
+    @PluginMethod
+    fun getInitialDeepLink(call: PluginCall) {
+        val url = deepLinks.consumeInitialUrl()
+        val data = JSObject().put("url", url ?: JSONull())
+        call.resolve(data)
+    }
+
+    // ── Device Info ───────────────────────────────────────────────────
+    @PluginMethod
+    fun getDeviceInfo(call: PluginCall) {
+        val appVersion = try {
+            val pm = context.packageManager
+            val pi = pm.getPackageInfo(context.packageName, 0)
+            pi.versionName ?: "0.0.0"
+        } catch (_: Exception) {
+            "0.0.0"
+        }
+
+        val locale = Locale.getDefault()
+        val localeTag = "${locale.language}-${locale.country}"
+        val data = JSObject()
+            .put("platform", "android")
+            .put("osVersion", Build.VERSION.RELEASE)
+            .put("model", "${Build.MANUFACTURER} ${Build.MODEL}".trim())
+            .put("appVersion", appVersion)
+            .put("bundleId", context.packageName)
+            .put("timezone", TimeZone.getDefault().id)
+            .put("locale", localeTag)
+        call.resolve(data)
+    }
+
+    // ── Sessions ──────────────────────────────────────────────────────
+    @PluginMethod
+    fun startSession(call: PluginCall) {
+        val snapshot = sessionManager.forceStart()
+        call.resolve(JSObject().put("sessionId", snapshot.sessionId))
+    }
+
+    @PluginMethod
+    fun endSession(call: PluginCall) {
+        sessionManager.endSession()
+        call.resolve()
+    }
+
+    @PluginMethod
+    fun getCurrentSession(call: PluginCall) {
+        val current = sessionManager.getCurrent()
+        val data = JSObject()
+            .put("sessionId", current?.sessionId ?: JSONull())
+            .put(
+                "startedAt",
+                current?.startedAtMs?.let { java.time.Instant.ofEpochMilli(it).toString() }
+                    ?: JSONull()
+            )
+        call.resolve(data)
+    }
+
+    // ── Events / Queue ────────────────────────────────────────────────
+    @PluginMethod
+    fun track(call: PluginCall) {
+        val queue = offlineQueue
+        if (queue == null) {
+            call.reject("Plugin not initialized — call initialize() first")
+            return
+        }
+        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) }
+
+        val event = NativeQueuedEvent(
+            id = id,
+            payload = payload,
+            attempts = 0,
+            enqueuedAtMs = System.currentTimeMillis(),
+        )
+        try {
+            queue.enqueue(event)
+            call.resolve()
+        } catch (e: Exception) {
+            call.reject("Failed to enqueue event: ${e.message}")
+        }
+    }
+
+    @PluginMethod
+    fun getQueueSize(call: PluginCall) {
+        val queue = offlineQueue
+        if (queue == null) {
+            call.resolve(JSObject().put("count", 0).put("oldestEventAt", JSONull()))
+            return
+        }
+        val oldest = queue.oldestEventAtMs()
+            ?.let { java.time.Instant.ofEpochMilli(it).toString() }
+        val data = JSObject()
+            .put("count", queue.size())
+            .put("oldestEventAt", oldest ?: JSONull())
+        call.resolve(data)
+    }
+
+    @PluginMethod
+    fun flushQueue(call: PluginCall) {
+        val queue = offlineQueue
+        val data = JSObject()
+            .put("flushed", 0)
+            .put("remaining", queue?.size() ?: 0)
+        call.resolve(data)
+    }
+
+    @PluginMethod
+    fun setTestMode(call: PluginCall) {
+        testMode = call.getBoolean("enabled", false) ?: false
+        call.resolve()
+    }
+
+    // ── Internal ──────────────────────────────────────────────────────
+
+    private fun fetchInstallReferrer() {
+        val client = InstallReferrerClient.newBuilder(context).build()
+        client.startConnection(object : InstallReferrerStateListener {
+            override fun onInstallReferrerSetupFinished(responseCode: Int) {
+                try {
+                    if (responseCode == InstallReferrerClient.InstallReferrerResponse.OK) {
+                        val details = client.installReferrer
+                        lastInstallReferrer = details.installReferrer
+                    }
+                } catch (_: Exception) {
+                    // ignore
+                } finally {
+                    try {
+                        client.endConnection()
+                    } catch (_: Exception) { }
+                }
+            }
+
+            override fun onInstallReferrerServiceDisconnected() { }
+        })
+    }
+}
+
+/**
+ * File-based QueueStorage used by the plugin in production. Tests swap
+ * InMemoryQueueStorage in its place.
+ */
+private class FileQueueStorage(private val file: File) : QueueStorage {
+    override fun readAll(): String? =
+        if (file.exists()) file.readText() else null
+
+    override fun writeAll(contents: String) {
+        file.writeText(contents)
+    }
+}
+
+/** Sentinel for passing JSON null to Capacitor's JSObject helpers. */
+private object JSONull {
+    override fun toString(): String = "null"
+}

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

@@ -0,0 +1,47 @@
+package inc.apex.capacitor
+
+/**
+ * Retains the URL that opened the app (App Link or custom scheme) and
+ * forwards warm-start URLs to a registered handler. Mirrors the iOS
+ * DeepLinkManager — same shape, pure Kotlin for testability.
+ */
+class DeepLinkManager {
+    private var initialUrl: String? = null
+    private var warmHandler: ((String) -> Unit)? = null
+    private val lock = Any()
+
+    fun setInitialUrl(url: String) {
+        synchronized(lock) {
+            if (initialUrl == null) initialUrl = url
+        }
+    }
+
+    /** One-shot: returns stored URL and clears it. */
+    fun consumeInitialUrl(): String? {
+        return synchronized(lock) {
+            val url = initialUrl
+            initialUrl = null
+            url
+        }
+    }
+
+    /** Register / replace the handler that receives warm-start URLs. */
+    fun setWarmLinkHandler(handler: (String) -> Unit) {
+        synchronized(lock) { warmHandler = handler }
+    }
+
+    fun deliverWarmLink(url: String) {
+        synchronized(lock) { warmHandler?.invoke(url) }
+    }
+
+    companion object {
+        /** Is this a sensible deep link? Reject `file://` and empty schemes. */
+        fun isValidDeepLink(url: String): Boolean {
+            if (url.isBlank()) return false
+            val schemeEnd = url.indexOf(":")
+            if (schemeEnd <= 0) return false
+            val scheme = url.substring(0, schemeEnd).lowercase()
+            return scheme.isNotEmpty() && scheme != "file"
+        }
+    }
+}