@apex-inc/capacitor-plugin 2.4.1 → 2.5.0

package/README.md

@@ -4,7 +4,7 @@ Apex Capacitor plugin — iOS and Android attribution, events, deep linking, SKA
 
 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.
+> **Scope.** This plugin is for Capacitor apps. Native iOS (Swift), native Android (Kotlin), React Native, and Flutter apps need their own SDKs — see https://app.apex.inc/docs/mobile/which-sdk.
 
 > **Try it in 5 minutes.** The [sample app](https://github.com/apex-incorporated/capacitor-sample-app) is a three-screen Capacitor + React app that exercises every API in this plugin. `git clone`, `npm install`, `npm run dev`, watch events land in your Apex dashboard.
 
@@ -28,6 +28,7 @@ await Apex.initialize({
   // apiKey: "apex_sk_…",       // see "API keys" below — unlocks verified identity stitching
   // 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)
   // sessionTimeoutMinutes: 30,
   // offlineQueueMaxSize: 1000,
   // testMode: false,
@@ -163,25 +164,61 @@ if (!id && fallback === "idfv") {
 
 ## SKAdNetwork conversion values (iOS 4.0+)
 
+You do not have to write this code. In the Apex dashboard, **Set up Apex →
+Mobile → Say what Apple's numbers mean** asks one question (which event
+means an install was worth it) and turns it into the full table of what
+Apple's 0–63 values mean for your app. With `autoConversionValues` on
+(the default on iOS), the plugin:
+
+- fetches that table on `initialize()`, caches it for a day, and
+  revalidates by ETag;
+- calls `SKAdNetwork.updatePostbackConversionValue` whenever `track()`
+  sees an event in the table, in the postback window the install is in;
+- only ever moves the value up within a window, and stops after day 35
+  when Apple stops listening.
+
+With `debug: true` every decision is logged as
+`[apex-capacitor] skan updatePostbackConversionValue(32, high) for purchase in window 1`.
+
+Read the table the plugin is acting on:
+
+```ts
+const { schema, mobileAppId, fetchedAt } = await Apex.getConversionValueSchema();
+```
+
+If you would rather run your own ladder, call `updateConversionValue`
+yourself. The first manual call turns automatic values off for that
+install — manual always wins — or pass `autoConversionValues: false` at
+`initialize()`.
+
 ```ts
 await Apex.updateConversionValue({
   fineValue: 42,
   coarseValue: "high",
+  lockWindow: false, // true asks Apple to send this window's postback now
 });
 ```
 
+Android has no SKAdNetwork; both calls are no-ops there.
+
 ## Deep links
 
 ```ts
 // Cold start: read the URL that opened the app (if any).
-const { url } = await Apex.getInitialDeepLink();
+const { url, deepLinkHint } = await Apex.getInitialDeepLink();
 
 // Warm-start / subsequent links while running:
-await Apex.addListener("deepLink", ({ url }) => {
-  handleRoute(url);
+await Apex.addListener("deepLink", ({ url, deepLinkHint }) => {
+  handleRoute(url, deepLinkHint);
 });
 ```
 
+`deepLinkHint` is the value the merchant set on the Apex Link (`apex_dl` on the
+URL), handed over already parsed. It's null when the link didn't carry one. Use
+it when your in-app routes don't look like your web routes — the link can say
+`checkout` and your router can honor that without parsing a web path it doesn't
+recognize. Apex never interprets the value.
+
 ## Sessions
 
 ```ts

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

@@ -4,6 +4,8 @@ import android.content.Context
 import android.content.SharedPreferences
 import android.net.Uri
 import android.os.Build
+import android.os.Handler
+import android.os.Looper
 import android.provider.Settings
 import com.android.installreferrer.api.InstallReferrerClient
 import com.android.installreferrer.api.InstallReferrerStateListener
@@ -55,6 +57,16 @@ class ApexCapacitorPlugin : Plugin() {
     private var testMode: Boolean = false
     private var debug: Boolean = false
     private var lastInstallReferrer: String? = null
+
+    // Deferred deep linking. The Play referrer is the ONLY thing that
+    // survives the browser-tap → store → first-launch gap on Android, so
+    // `getInstallReferrer` has to be able to answer during first launch
+    // 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
+    private var installReferrerClickSeconds: Long = 0
+    private val pendingReferrerCalls = mutableListOf<PluginCall>()
     // Phase 2-SDK — workspace-bound SDK key forwarded as
     // `x-apex-api-key` on every event POST + on `identify()`.
     private var apiKey: String? = null
@@ -83,7 +95,9 @@ class ApexCapacitorPlugin : Plugin() {
             }
 
         deepLinks.setWarmLinkHandler { url ->
-            val data = JSObject().put("url", url)
+            val data = JSObject()
+                .put("url", url)
+                .put("deepLinkHint", DeepLinkManager.apexHint(url) ?: JSONObject.NULL)
             notifyListeners("deepLink", data)
         }
 
@@ -383,8 +397,20 @@ class ApexCapacitorPlugin : Plugin() {
 
     @PluginMethod
     fun getInstallReferrer(call: PluginCall) {
-        val data = JSObject().put("referrer", lastInstallReferrer ?: JSONObject.NULL)
-        call.resolve(data)
+        if (installReferrerResolved) {
+            resolveInstallReferrer(call)
+            return
+        }
+        // Park the call until the Play service answers. Bounded, because
+        // first launch is the most latency-sensitive moment in the app's
+        // life and a wedged Play service must never hold up a screen.
+        synchronized(pendingReferrerCalls) { pendingReferrerCalls.add(call) }
+        Handler(Looper.getMainLooper()).postDelayed({
+            val stillPending = synchronized(pendingReferrerCalls) {
+                pendingReferrerCalls.remove(call)
+            }
+            if (stillPending) resolveInstallReferrer(call)
+        }, REFERRER_WAIT_MS)
     }
 
     @PluginMethod
@@ -709,6 +735,7 @@ class ApexCapacitorPlugin : Plugin() {
                 conn.setRequestProperty("x-apex-source", "sdk")
                 conn.setRequestProperty("x-apex-visitor-id", visitorId)
                 conn.setRequestProperty("x-apex-workspace", workspaceKey)
+                conn.setRequestProperty("x-apex-release-channel", releaseChannel)
                 apiKey?.let { conn.setRequestProperty("x-apex-api-key", it) }
                 conn.connectTimeout = 10000
                 conn.readTimeout = 15000
@@ -755,12 +782,21 @@ class ApexCapacitorPlugin : Plugin() {
      */
     private fun enqueueExposure(experimentId: String, variant: String) {
         val queue = offlineQueue ?: return
+        // App version that saw the variant — the mobile equivalent of the web
+        // build id. Enables version-adoption curves + version-gating during a
+        // staged rollout (Phase 5, 2026-07-20).
+        val appVersion = try {
+            context.packageManager.getPackageInfo(context.packageName, 0).versionName ?: "0.0.0"
+        } catch (_: Exception) {
+            "0.0.0"
+        }
         val payload = mutableMapOf<String, Any?>()
         payload["type"] = "experiment_exposure"
         payload["data"] = mapOf(
             "experiment_id" to experimentId,
             "variant_key" to variant,
             "surface" to "mobile",
+            "app_version" to appVersion,
         )
         if (testMode) payload["testMode"] = true
         payload["platform"] = "android"
@@ -796,7 +832,10 @@ class ApexCapacitorPlugin : Plugin() {
     @PluginMethod
     fun getInitialDeepLink(call: PluginCall) {
         val url = deepLinks.consumeInitialUrl()
-        val data = JSObject().put("url", url ?: JSONObject.NULL)
+        val hint = url?.let { DeepLinkManager.apexHint(it) }
+        val data = JSObject()
+            .put("url", url ?: JSONObject.NULL)
+            .put("deepLinkHint", hint ?: JSONObject.NULL)
         call.resolve(data)
     }
 
@@ -992,6 +1031,11 @@ class ApexCapacitorPlugin : Plugin() {
                     if (responseCode == InstallReferrerClient.InstallReferrerResponse.OK) {
                         val details = client.installReferrer
                         lastInstallReferrer = details.installReferrer
+                        // The tap's own timestamp, not the install's. A
+                        // deferred link is only worth honouring while the
+                        // user still remembers tapping it, so JS ages the
+                        // referrer out against this.
+                        installReferrerClickSeconds = details.referrerClickTimestampSeconds
                     }
                 } catch (_: Exception) {
                     // ignore
@@ -999,13 +1043,36 @@ class ApexCapacitorPlugin : Plugin() {
                     try {
                         client.endConnection()
                     } catch (_: Exception) { }
+                    flushPendingReferrerCalls()
                 }
             }
 
-            override fun onInstallReferrerServiceDisconnected() { }
+            // A disconnect before the first response means Play will not
+            // answer this launch. Resolve the waiters with what we have
+            // (nothing) rather than leaving them to time out one by one.
+            override fun onInstallReferrerServiceDisconnected() {
+                flushPendingReferrerCalls()
+            }
         })
     }
 
+    private fun flushPendingReferrerCalls() {
+        installReferrerResolved = true
+        val waiting = synchronized(pendingReferrerCalls) {
+            val copy = pendingReferrerCalls.toList()
+            pendingReferrerCalls.clear()
+            copy
+        }
+        for (call in waiting) resolveInstallReferrer(call)
+    }
+
+    private fun resolveInstallReferrer(call: PluginCall) {
+        val data = JSObject()
+            .put("referrer", lastInstallReferrer ?: JSONObject.NULL)
+            .put("clickTimestamp", installReferrerClickSeconds)
+        call.resolve(data)
+    }
+
     companion object {
         /**
          * Weak-ish reference to the live plugin so the FCM messaging
@@ -1015,6 +1082,14 @@ class ApexCapacitorPlugin : Plugin() {
         @Volatile
         var activePlugin: ApexCapacitorPlugin? = null
 
+        /**
+         * How long `getInstallReferrer` will wait for Play before
+         * answering with what it has. Google's own samples see the
+         * connection settle in well under a second; past that the user is
+         * staring at a held-back first screen for a nice-to-have.
+         */
+        private const val REFERRER_WAIT_MS = 2500L
+
         /**
          * 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/ApexEvents.kt

@@ -47,6 +47,10 @@ object ApexEvents {
 
     // ─── Identity ───────────────────────────────────────────────────────
     const val USER_SIGNED_UP = "user_signed_up"
+    const val WAITLIST_JOINED = "waitlist_joined"
+    const val USER_INVITED = "user_invited"
+    const val USER_INVITE_ACCEPTED = "user_invite_accepted"
+    const val PASSWORD_RESET_REQUESTED = "password_reset_requested"
     const val USER_SIGNED_IN = "user_signed_in"
     const val USER_SIGNED_OUT = "user_signed_out"
     const val USER_IDENTIFIED = "user_identified"
@@ -73,6 +77,7 @@ object ApexEvents {
     const val CONTENT_VIEW = "content_view"
     const val FORM_SUBMIT = "form_submit"
     const val CLICK = "click"
+    const val UI_ACTION = "ui_action"
     const val ENGAGEMENT = "engagement"
     const val HEARTBEAT = "heartbeat"
     const val RAGE_CLICK = "rage_click"
@@ -147,11 +152,13 @@ object ApexEvents {
     const val USAGE_MILESTONE_REACHED = "usage_milestone_reached"
     const val USER_CHURNED = "user_churned"
     const val USER_REACTIVATED = "user_reactivated"
+    const val TRIAL_EXPIRING = "trial_expiring"
     const val TRIAL_EXPIRED = "trial_expired"
     const val INVOICE_PAID = "invoice_paid"
     const val SUBSCRIPTION_RENEWED = "subscription_renewed"
 
     // Engagement suite (User Lifecycle)
+    const val REPORT_READY = "report_ready"
     const val REPORT_VIEWED = "report_viewed"
     const val CONTENT_VIEWED = "content_viewed"
     const val TASK_COMPLETED = "task_completed"
@@ -168,13 +175,13 @@ object ApexEvents {
     const val CLIENT_REPORT_VIEWED = "client_report_viewed"
 
     /** Apex Spec semver this SDK implements. */
-    const val SPEC_VERSION = "1.3.0"
+    const val SPEC_VERSION = "1.5.0"
 
     /** Complete list of every canonical event name. */
     val ALL: List<String> = listOf(
         ADD_TO_CART, REMOVE_FROM_CART, PRODUCT_VIEW, ADD_TO_WISHLIST, CHECKOUT_STARTED,
         IN_APP_PURCHASE, PURCHASE_REFUNDED, SUBSCRIPTION_EVENT, SUBSCRIPTION_UPGRADED, SUBSCRIPTION_DOWNGRADED,
-        USER_SIGNED_UP, USER_SIGNED_IN, USER_SIGNED_OUT, USER_IDENTIFIED,
+        USER_SIGNED_UP, WAITLIST_JOINED, USER_INVITED, USER_INVITE_ACCEPTED, PASSWORD_RESET_REQUESTED, USER_SIGNED_IN, USER_SIGNED_OUT, USER_IDENTIFIED,
         APP_INSTALL, APP_OPEN, APP_BACKGROUND, APP_UNINSTALL, APP_REINSTALL,
         SESSION_START, SESSION_END,
         PAGE_VIEW, PAGEVIEW, SCREEN_VIEW, SEARCH, SHARE, CONTENT_VIEW, FORM_SUBMIT,
@@ -193,8 +200,8 @@ object ApexEvents {
         SELLER_VIEWED, ITEM_SAVED, INQUIRY_STARTED, MATCH_CREATED, TRANSACTION_CANCELED, DISPUTE_OPENED, REVIEW_SUBMITTED,
         CLIENT_ONBOARDED, CAMPAIGN_MILESTONE_REACHED, CONTRACT_RENEWAL_APPROACHING, NEW_CAPABILITY_LAUNCHED,
         LOYALTY_MILESTONE_REACHED, USAGE_MILESTONE_REACHED, USER_CHURNED, USER_REACTIVATED,
-        TRIAL_EXPIRED, INVOICE_PAID, SUBSCRIPTION_RENEWED,
-        REPORT_VIEWED, CONTENT_VIEWED, TASK_COMPLETED, API_REQUEST_COMPLETED, PROJECT_CREATED,
+        TRIAL_EXPIRING, TRIAL_EXPIRED, INVOICE_PAID, SUBSCRIPTION_RENEWED,
+        REPORT_READY, REPORT_VIEWED, CONTENT_VIEWED, TASK_COMPLETED, API_REQUEST_COMPLETED, PROJECT_CREATED,
         LISTING_VIEWED, MESSAGE_SENT, OFFER_SUBMITTED, TRANSACTION_COMPLETED, TASK_UPDATED,
         ASSET_UPLOADED, COMMENT_ADDED, TIME_LOGGED, CLIENT_REPORT_VIEWED,
     )

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

@@ -35,6 +35,33 @@ class DeepLinkManager {
     }
 
     companion object {
+        /**
+         * The `apex_dl` value an Apex Link carried, or null when it had none.
+         *
+         * Apex appends this on mobile clicks as a pass-through hint the merchant
+         * set on the link. Surfaced already-parsed so the app doesn't have to
+         * pick apart a query string; never interpreted here. Hand-parsed rather
+         * than via `Uri.parse` so this class stays pure Kotlin and testable off
+         * an Android device.
+         */
+        fun apexHint(url: String): String? {
+            val query = url.substringAfter('?', "").substringBefore('#')
+            if (query.isEmpty()) return null
+            for (pair in query.split('&')) {
+                val key = pair.substringBefore('=')
+                if (key != "apex_dl") continue
+                val raw = pair.substringAfter('=', "")
+                if (raw.isEmpty()) return null
+                val decoded = try {
+                    java.net.URLDecoder.decode(raw, "UTF-8")
+                } catch (_: Exception) {
+                    raw
+                }
+                return decoded.ifEmpty { null }
+            }
+            return null
+        }
+
         /** Is this a sensible deep link? Reject `file://` and empty schemes. */
         fun isValidDeepLink(url: String): Boolean {
             if (url.isBlank()) return false

package/dist/deferred-link.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Deferred deep-link resolution.
+ *
+ * The problem this solves: a user taps a link in Safari or Chrome, does
+ * not have your app, installs it from the store, and opens it. The tap
+ * and the launch share no cookie and no storage, so by default your app
+ * has no idea the user was headed for a specific screen and drops them
+ * on your home screen. The tap that cost you money lands nowhere.
+ *
+ * Apex matches the launch back to the tap server-side and hands you the
+ * destination. Call it once, early, and route on the result:
+ *
+ * ```ts
+ * const link = await Apex.getDeferredDeepLink();
+ * if (link) router.navigateByUrl(link.deepLinkHint ?? new URL(link.url).pathname);
+ * ```
+ *
+ * Two properties worth knowing before you build on it:
+ *
+ *   - **One-shot.** The match key is coarse (network + OS), so a link can
+ *     only be claimed once. Call this on first launch and persist what
+ *     you get; a second call returns null.
+ *   - **Best-effort.** Matching is probabilistic and returns null more
+ *     often than it returns a link — no network address, a VPN between
+ *     tap and install, or a slow install all produce a miss. Treat a
+ *     link as a bonus that improves the first run, never as a
+ *     precondition for it.
+ *
+ * Implemented in TypeScript rather than in the native bridges because it
+ * is one HTTPS call with no platform APIs involved, and the webview can
+ * make it identically on iOS, Android, and in browser preview.
+ */
+export interface DeferredDeepLinkResult {
+    /**
+     * The destination the tap was headed for, with Apex's own routing
+     * params (`apex_dl`, `apex_link`) already stripped.
+     */
+    url: string;
+    /**
+     * The link's `apex_dl` value — whatever screen identifier you put on
+     * the link in Apex. Null when the link carried none.
+     */
+    deepLinkHint: string | null;
+    /** Apex Link slug the tap came through, when it came through one. */
+    slug?: string;
+    /** Affiliate handle, for namespaced partner links. */
+    handle?: string;
+    source?: string;
+    campaign?: string;
+    /** ISO timestamp of the original tap. */
+    clickedAt: string;
+    /**
+     * How the launch was matched to the tap.
+     *
+     * `deterministic` means Google Play handed us the exact link the user
+     * tapped, via the install referrer — there is no guesswork in it.
+     * `probabilistic` means we matched on network address and OS, which is
+     * the best available on iOS and can, on a shared network, be wrong.
+     * Route on either; only gate irreversible actions (granting a credit,
+     * applying a referral bonus) on `deterministic`.
+     */
+    matchType: "deterministic" | "probabilistic";
+}
+export interface FetchDeferredDeepLinkOptions {
+    apiUrl: string;
+    workspaceKey: string;
+    platform: "ios" | "android";
+    apiKey?: string;
+    /** Abort the call after this many ms. Defaults to 5000. */
+    timeoutMs?: number;
+}
+export declare function fetchDeferredDeepLink(options: FetchDeferredDeepLinkOptions): Promise<DeferredDeepLinkResult | null>;
+//# sourceMappingURL=deferred-link.d.ts.map

package/dist/deferred-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-link.d.ts","sourceRoot":"","sources":["../src/deferred-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,SAAS,EAAE,eAAe,GAAG,eAAe,CAAC;CAC9C;AAED,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,KAAK,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAwCxC"}

package/dist/deferred-link.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Deferred deep-link resolution.
+ *
+ * The problem this solves: a user taps a link in Safari or Chrome, does
+ * not have your app, installs it from the store, and opens it. The tap
+ * and the launch share no cookie and no storage, so by default your app
+ * has no idea the user was headed for a specific screen and drops them
+ * on your home screen. The tap that cost you money lands nowhere.
+ *
+ * Apex matches the launch back to the tap server-side and hands you the
+ * destination. Call it once, early, and route on the result:
+ *
+ * ```ts
+ * const link = await Apex.getDeferredDeepLink();
+ * if (link) router.navigateByUrl(link.deepLinkHint ?? new URL(link.url).pathname);
+ * ```
+ *
+ * Two properties worth knowing before you build on it:
+ *
+ *   - **One-shot.** The match key is coarse (network + OS), so a link can
+ *     only be claimed once. Call this on first launch and persist what
+ *     you get; a second call returns null.
+ *   - **Best-effort.** Matching is probabilistic and returns null more
+ *     often than it returns a link — no network address, a VPN between
+ *     tap and install, or a slow install all produce a miss. Treat a
+ *     link as a bonus that improves the first run, never as a
+ *     precondition for it.
+ *
+ * Implemented in TypeScript rather than in the native bridges because it
+ * is one HTTPS call with no platform APIs involved, and the webview can
+ * make it identically on iOS, Android, and in browser preview.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchDeferredDeepLink = fetchDeferredDeepLink;
+const DEFAULT_TIMEOUT_MS = 5000;
+async function fetchDeferredDeepLink(options) {
+    const { apiUrl, workspaceKey, platform, apiKey } = options;
+    if (!workspaceKey)
+        return null;
+    // First launch is the most latency-sensitive moment in the app's life.
+    // A slow or unreachable Apex must never hold up the first screen, so
+    // the call is bounded and every failure resolves to null.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    try {
+        const headers = {
+            "Content-Type": "application/json",
+            "x-apex-workspace": workspaceKey,
+        };
+        if (apiKey)
+            headers["x-apex-api-key"] = apiKey;
+        const response = await fetch(`${apiUrl.replace(/\/+$/, "")}/api/mobile/deferred-link`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ workspaceKey, platform }),
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return null;
+        const payload = (await response.json());
+        return payload.data ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=deferred-link.js.map

package/dist/deferred-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-link.js","sourceRoot":"","sources":["../src/deferred-link.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;AA6CH,sDA0CC;AA5CD,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEzB,KAAK,UAAU,qBAAqB,CACzC,OAAqC;IAErC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC3D,IAAI,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IAE/B,uEAAuE;IACvE,qEAAqE;IACrE,0DAA0D;IAC1D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CACtB,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EACxB,OAAO,CAAC,SAAS,IAAI,kBAAkB,CACxC,CAAC;IAEF,IAAI,CAAC;QACH,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;YAClC,kBAAkB,EAAE,YAAY;SACjC,CAAC;QACF,IAAI,MAAM;YAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,MAAM,CAAC;QAE/C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAC1B,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,2BAA2B,EACxD;YACE,MAAM,EAAE,MAAM;YACd,OAAO;YACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;YAChD,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CACF,CAAC;QAEF,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAC9B,MAAM,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAErC,CAAC;QACF,OAAO,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/definitions.d.ts

@@ -10,6 +10,10 @@
  * See `plans/mobile-measurement-platform.md` Phase 1b for scope and rationale.
  */
 import type { PluginListenerHandle } from "@capacitor/core";
+import type { DeferredDeepLinkResult } from "./deferred-link";
+import type { SkanSchemaSnapshot } from "./skan-conversion-values";
+export type { DeferredDeepLinkResult } from "./deferred-link";
+export type { SkanConversionSchema, SkanConversionValueEntry, SkanConversionWindow, SkanSchemaSnapshot, SkanWindow, } from "./skan-conversion-values";
 /** iOS App Tracking Transparency authorization status. */
 export type AttStatus = "authorized" | "denied" | "restricted" | "not-determined";
 /** User-notification permission state returned by `registerForPushNotifications`. */
@@ -227,6 +231,25 @@ export interface InitializeOptions {
      * server stamps `releaseChannelSource: "auto"` regardless.
      */
     releaseChannel?: ReleaseChannel;
+    /**
+     * Mobile Measurement P2 — let Apex drive SKAdNetwork conversion values.
+     *
+     * When true (the default on iOS), the plugin fetches what Apple's 0–63
+     * numbers mean for this app — the table Set up Apex derives from "which
+     * event means an install was worth it?" — caches it for a day, and
+     * calls `updatePostbackConversionValue` whenever `track()` sees an
+     * event in that table. The first manual `updateConversionValue` call
+     * switches this off for the install, so a hand-rolled ladder always
+     * wins. No-op on Android and web.
+     *
+     * Set false to keep full manual control.
+     */
+    autoConversionValues?: boolean;
+    /**
+     * Which registered app's conversion value table to use, when the
+     * workspace has more than one. Defaults to the workspace's first app.
+     */
+    mobileAppId?: string;
 }
 /**
  * Options for {@link ApexCapacitorPlugin.identify}.
@@ -377,11 +400,19 @@ export interface ApexCapacitorPlugin {
      */
     getAdvertisingId(): Promise<AdvertisingIdResult>;
     /**
-     * Android: returns decoded Play Install Referrer string on first launch.
-     * iOS: returns `{ referrer: null }` (no equivalent).
+     * Android: returns the decoded Play Install Referrer string, waiting
+     * briefly for Play to connect if the call arrives during first launch.
+     * `clickTimestamp` is the Unix-seconds time of the original ad tap
+     * (0 when Play didn't report one), which is what makes a stale
+     * referrer detectable — Play keeps the string forever.
+     *
+     * iOS: returns `{ referrer: null, clickTimestamp: 0 }`. The App Store
+     * forwards nothing across an install, which is why iOS deferred deep
+     * linking has to fall back to a probabilistic server match.
      */
     getInstallReferrer(): Promise<{
         referrer: string | null;
+        clickTimestamp: number;
     }>;
     /** Gets the plugin-managed visitor ID. */
     getVisitorId(): Promise<{
@@ -411,20 +442,55 @@ export interface ApexCapacitorPlugin {
     /**
      * Updates the SKAdNetwork 4.0 postback conversion value. No-op on Android.
      * `fineValue` is 0-63 (fine conversion value); `coarseValue` is optional
-     * for SKAN 4.0's coarse-grained reporting.
+     * for SKAN 4.0's coarse-grained reporting; `lockWindow` asks Apple to
+     * send the current window's postback now rather than waiting it out.
+     *
+     * Calling this yourself turns off `autoConversionValues` for the
+     * install — manual always wins.
      */
     updateConversionValue(options: {
         fineValue: number;
         coarseValue?: SkanCoarseValue;
+        lockWindow?: boolean;
     }): Promise<void>;
+    /**
+     * The conversion value table the plugin is acting on: what each of
+     * Apple's numbers means for this app, as set in Set up Apex. `schema`
+     * is null until the shop has answered the SKAN question (or before
+     * the first fetch lands). Read-only; edit it in the Apex dashboard.
+     */
+    getConversionValueSchema(): Promise<SkanSchemaSnapshot>;
     /**
      * Returns the URL the app was opened with on cold start (Universal Link on
      * iOS, App Link on Android). Returns `{ url: null }` if launched without a
      * link. Use the `deepLink` listener for subsequent warm-start links.
+     *
+     * `deepLinkHint` is the `apex_dl` value the Apex Link carried, already pulled
+     * off the query string — null when the link had none. It is whatever the
+     * merchant put on the link in Apex; nothing interprets it but your router.
      */
     getInitialDeepLink(): Promise<{
         url: string | null;
+        deepLinkHint: string | null;
     }>;
+    /**
+     * Resolve the link the user tapped BEFORE they installed the app.
+     *
+     * `getInitialDeepLink()` above covers the case where the app already
+     * exists and the OS hands it a URL. This covers the other case: the
+     * user tapped an Apex Link in a browser, did not have the app, went
+     * through the store, and is now opening it for the first time. No URL
+     * reaches the app in that flow, so Apex matches the launch back to the
+     * tap server-side and returns the destination it was headed for.
+     *
+     * Returns null when there is no match, which is the common case — call
+     * it, route on a hit, and carry on normally otherwise. Resolution is
+     * one-shot per tap, so call it once at first launch and persist the
+     * result rather than calling it again later.
+     *
+     * See `deferred-link.ts` for the matching properties and their limits.
+     */
+    getDeferredDeepLink(): Promise<DeferredDeepLinkResult | null>;
     getDeviceInfo(): Promise<DeviceInfo>;
     /** Force-starts a new session, ending any current one. */
     startSession(): Promise<{
@@ -514,9 +580,15 @@ export interface ApexCapacitorPlugin {
     getConsent(): Promise<{
         granted: boolean;
     }>;
-    /** Fires when a deep link opens the app while it is already running. */
+    /**
+     * Fires when a deep link opens the app while it is already running.
+     *
+     * `deepLinkHint` carries the link's `apex_dl` value when it had one — see
+     * `getInitialDeepLink()`.
+     */
     addListener(eventName: "deepLink", listenerFunc: (event: {
         url: string;
+        deepLinkHint: string | null;
     }) => void): Promise<PluginListenerHandle>;
     /** Fires when the app moves between foreground and background. */
     addListener(eventName: "appStateChange", listenerFunc: (event: {