@apex-inc/capacitor-plugin 2.4.0 → 2.5.0

package/dist/skan-conversion-values.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Automatic SKAdNetwork conversion values.
+ *
+ * The shop answers one question in Set up Apex ("which event means an
+ * install was worth it?") and Apex turns it into a table of what Apple's
+ * 0–63 numbers mean for the app. This module reads that table and, every
+ * time the app tracks an event that appears in it, tells Apple the new
+ * value — so the shop never writes `updateConversionValue` by hand.
+ *
+ * Behaviour, in order of importance:
+ *
+ *   - **Manual wins.** The first time the app calls
+ *     `Apex.updateConversionValue` itself, automatic updates stop for
+ *     that install. A shop that hand-rolls its ladder keeps its ladder.
+ *   - **Values only go up.** Apple keeps the last value it was given, and
+ *     every network reads the ladder as "higher means more". Within a
+ *     postback window the plugin never sends a lower value than it has
+ *     already sent.
+ *   - **Never in the way.** The schema is fetched once per day and cached;
+ *     a slow or unreachable Apex means the app runs with yesterday's
+ *     table (or none), never a delayed first screen.
+ *
+ * SKAN 4 windows, counted from first launch: window 1 covers days 0–2,
+ * window 2 days 3–7, window 3 days 8–35. After day 35 Apple is no longer
+ * listening and nothing is sent.
+ *
+ * Pure TypeScript on purpose: one HTTPS call and a little arithmetic, no
+ * platform APIs, so it runs identically under the native iOS bridge and
+ * in browser preview (where the update itself is a no-op).
+ */
+import type { SkanCoarseValue } from "./definitions";
+export type SkanWindow = 1 | 2 | 3;
+export interface SkanConversionValueEntry {
+    eventName: string;
+    fineValue: number;
+    coarseValue: SkanCoarseValue;
+    lockWindow?: boolean;
+}
+export interface SkanConversionWindow {
+    window: SkanWindow;
+    values: SkanConversionValueEntry[];
+}
+export interface SkanConversionSchema {
+    windows: SkanConversionWindow[];
+    updatedAt: string;
+}
+/** What {@link fetchSkanConversionSchema} and the cache carry. */
+export interface SkanSchemaSnapshot {
+    schema: SkanConversionSchema | null;
+    mobileAppId: string | null;
+    /** Weak ETag from the server, replayed as `If-None-Match`. */
+    etag: string | null;
+    /** Epoch ms when this snapshot was confirmed fresh. */
+    fetchedAt: number;
+}
+export interface FetchSkanSchemaOptions {
+    apiUrl: string;
+    workspaceKey: string;
+    mobileAppId?: string | null;
+    /** Previous ETag; a matching server tag returns `not_modified`. */
+    etag?: string | null;
+    /** Abort after this many ms. Defaults to 5000. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+export type FetchSkanSchemaResult = {
+    status: "fresh";
+    snapshot: SkanSchemaSnapshot;
+} | {
+    status: "not_modified";
+} | {
+    status: "error";
+};
+export declare function fetchSkanConversionSchema(options: FetchSkanSchemaOptions, now?: () => number): Promise<FetchSkanSchemaResult>;
+/**
+ * Keep only rungs the plugin can act on. The server validates on write,
+ * but a cached snapshot may outlive a schema change, so be strict here
+ * too: a bad rung is dropped, never sent to Apple.
+ */
+export declare function normalizeSchema(raw: SkanConversionSchema | null | undefined): SkanConversionSchema | null;
+/**
+ * Which SKAN 4 postback window a moment falls in, counted from first
+ * launch. Null once Apple has stopped listening (after day 35).
+ */
+export declare function skanWindowAt(installedAt: number, now: number): SkanWindow | null;
+/** What to tell Apple, when an event maps and is worth telling. */
+export interface ConversionValueUpdate {
+    fineValue: number;
+    coarseValue: SkanCoarseValue;
+    lockWindow?: boolean;
+    window: SkanWindow;
+}
+/**
+ * Decide whether tracking `eventName` should change Apple's value.
+ * Returns null when the event has no meaning in the current window or
+ * when the mapped value would not move the ladder up.
+ */
+export declare function pickConversionValue(schema: SkanConversionSchema | null, eventName: string, ctx: {
+    installedAt: number;
+    now: number;
+    highestSent: number | null;
+}): ConversionValueUpdate | null;
+/** Minimal key/value store; `localStorage` fits, so does a Map in tests. */
+export interface SkanValueStore {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export declare const SKAN_STORAGE_KEYS: {
+    readonly snapshot: "apex_skan_schema_v1";
+    readonly installedAt: "apex_skan_installed_at";
+    readonly manual: "apex_skan_manual";
+    readonly highest: "apex_skan_highest_v1";
+};
+/** How long a cached schema is trusted before revalidating. */
+export declare const SKAN_SCHEMA_MAX_AGE_MS: number;
+export interface SkanAutoConversionValuesOptions {
+    /** Sends the value to Apple (the bridge's `updateConversionValue`). */
+    update: (value: {
+        fineValue: number;
+        coarseValue?: SkanCoarseValue;
+        lockWindow?: boolean;
+    }) => Promise<void>;
+    store?: SkanValueStore | null;
+    fetch?: typeof fetch;
+    now?: () => number;
+    /** Debug sink; receives one line per decision when set. */
+    log?: (message: string) => void;
+}
+/**
+ * Owns the cached schema and the "what have I already told Apple"
+ * bookkeeping for one install. Created by the plugin proxy on
+ * `initialize({ autoConversionValues: true })`; not something an app
+ * constructs itself.
+ */
+export declare class SkanAutoConversionValues {
+    private readonly update;
+    private readonly store;
+    private readonly fetchImpl?;
+    private readonly now;
+    private readonly log?;
+    private snapshot;
+    private installedAt;
+    private manual;
+    private highest;
+    private ready;
+    private endpoint;
+    constructor(options: SkanAutoConversionValuesOptions);
+    /**
+     * Point at a workspace and refresh the schema if the cache is stale.
+     * Resolves as soon as the cache has been read; the network revalidate
+     * runs in the background and never blocks the caller.
+     */
+    initialize(endpoint: {
+        apiUrl: string;
+        workspaceKey: string;
+        mobileAppId?: string | null;
+    }): Promise<void>;
+    /** Force a network revalidation (ETag-aware). */
+    revalidate(): Promise<void>;
+    /** Wait for any in-flight revalidation (tests and debug UIs). */
+    whenReady(): Promise<void>;
+    /** The schema the plugin is acting on right now. */
+    getSchema(): SkanSchemaSnapshot;
+    /** True once the app has called `updateConversionValue` itself. */
+    get manualMode(): boolean;
+    /** Called when the app updates Apple's value by hand. Auto steps aside. */
+    noteManualUpdate(): void;
+    /**
+     * Called after every `track`. Sends the mapped value when the event has
+     * one in the current window and it moves the ladder up.
+     */
+    onTrack(eventName: string): Promise<ConversionValueUpdate | null>;
+    private readInstalledAt;
+}
+//# sourceMappingURL=skan-conversion-values.d.ts.map

package/dist/skan-conversion-values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skan-conversion-values.d.ts","sourceRoot":"","sources":["../src/skan-conversion-values.ts"],"names":[],"mappings":"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"}

package/dist/skan-conversion-values.js

@@ -0,0 +1,331 @@
+"use strict";
+/**
+ * Automatic SKAdNetwork conversion values.
+ *
+ * The shop answers one question in Set up Apex ("which event means an
+ * install was worth it?") and Apex turns it into a table of what Apple's
+ * 0–63 numbers mean for the app. This module reads that table and, every
+ * time the app tracks an event that appears in it, tells Apple the new
+ * value — so the shop never writes `updateConversionValue` by hand.
+ *
+ * Behaviour, in order of importance:
+ *
+ *   - **Manual wins.** The first time the app calls
+ *     `Apex.updateConversionValue` itself, automatic updates stop for
+ *     that install. A shop that hand-rolls its ladder keeps its ladder.
+ *   - **Values only go up.** Apple keeps the last value it was given, and
+ *     every network reads the ladder as "higher means more". Within a
+ *     postback window the plugin never sends a lower value than it has
+ *     already sent.
+ *   - **Never in the way.** The schema is fetched once per day and cached;
+ *     a slow or unreachable Apex means the app runs with yesterday's
+ *     table (or none), never a delayed first screen.
+ *
+ * SKAN 4 windows, counted from first launch: window 1 covers days 0–2,
+ * window 2 days 3–7, window 3 days 8–35. After day 35 Apple is no longer
+ * listening and nothing is sent.
+ *
+ * Pure TypeScript on purpose: one HTTPS call and a little arithmetic, no
+ * platform APIs, so it runs identically under the native iOS bridge and
+ * in browser preview (where the update itself is a no-op).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkanAutoConversionValues = exports.SKAN_SCHEMA_MAX_AGE_MS = exports.SKAN_STORAGE_KEYS = void 0;
+exports.fetchSkanConversionSchema = fetchSkanConversionSchema;
+exports.normalizeSchema = normalizeSchema;
+exports.skanWindowAt = skanWindowAt;
+exports.pickConversionValue = pickConversionValue;
+const DEFAULT_TIMEOUT_MS = 5000;
+async function fetchSkanConversionSchema(options, now = Date.now) {
+    const { apiUrl, workspaceKey, mobileAppId } = options;
+    if (!workspaceKey)
+        return { status: "error" };
+    const doFetch = options.fetch ?? globalThis.fetch;
+    if (typeof doFetch !== "function")
+        return { status: "error" };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    try {
+        const url = new URL(`${apiUrl.replace(/\/+$/, "")}/api/mobile/skan/schema/resolve`);
+        url.searchParams.set("workspace", workspaceKey);
+        if (mobileAppId)
+            url.searchParams.set("mobileAppId", mobileAppId);
+        const headers = {
+            "x-apex-workspace": workspaceKey,
+        };
+        if (options.etag)
+            headers["If-None-Match"] = options.etag;
+        const response = await doFetch(url.toString(), {
+            method: "GET",
+            headers,
+            signal: controller.signal,
+        });
+        if (response.status === 304)
+            return { status: "not_modified" };
+        if (!response.ok)
+            return { status: "error" };
+        const payload = (await response.json());
+        return {
+            status: "fresh",
+            snapshot: {
+                schema: normalizeSchema(payload.data?.schema),
+                mobileAppId: payload.data?.mobileAppId ?? null,
+                etag: response.headers.get("etag"),
+                fetchedAt: now(),
+            },
+        };
+    }
+    catch {
+        return { status: "error" };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Keep only rungs the plugin can act on. The server validates on write,
+ * but a cached snapshot may outlive a schema change, so be strict here
+ * too: a bad rung is dropped, never sent to Apple.
+ */
+function normalizeSchema(raw) {
+    if (!raw || !Array.isArray(raw.windows))
+        return null;
+    const windows = [];
+    for (const w of raw.windows) {
+        if (!w || (w.window !== 1 && w.window !== 2 && w.window !== 3))
+            continue;
+        if (!Array.isArray(w.values))
+            continue;
+        const values = w.values.filter((v) => !!v &&
+            typeof v.eventName === "string" &&
+            v.eventName.length > 0 &&
+            Number.isInteger(v.fineValue) &&
+            v.fineValue >= 0 &&
+            v.fineValue <= 63 &&
+            (v.coarseValue === "low" ||
+                v.coarseValue === "medium" ||
+                v.coarseValue === "high"));
+        windows.push({ window: w.window, values });
+    }
+    return {
+        windows,
+        updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : "",
+    };
+}
+// ─── Window arithmetic ────────────────────────────────────────────────────
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Which SKAN 4 postback window a moment falls in, counted from first
+ * launch. Null once Apple has stopped listening (after day 35).
+ */
+function skanWindowAt(installedAt, now) {
+    const elapsed = now - installedAt;
+    if (elapsed < 0)
+        return 1;
+    if (elapsed < 2 * DAY_MS)
+        return 1;
+    if (elapsed < 7 * DAY_MS)
+        return 2;
+    if (elapsed < 35 * DAY_MS)
+        return 3;
+    return null;
+}
+/**
+ * Decide whether tracking `eventName` should change Apple's value.
+ * Returns null when the event has no meaning in the current window or
+ * when the mapped value would not move the ladder up.
+ */
+function pickConversionValue(schema, eventName, ctx) {
+    if (!schema)
+        return null;
+    const window = skanWindowAt(ctx.installedAt, ctx.now);
+    if (!window)
+        return null;
+    const entry = schema.windows
+        .find((w) => w.window === window)
+        ?.values.find((v) => v.eventName === eventName);
+    if (!entry)
+        return null;
+    if (ctx.highestSent !== null && entry.fineValue <= ctx.highestSent) {
+        return null;
+    }
+    return {
+        fineValue: entry.fineValue,
+        coarseValue: entry.coarseValue,
+        ...(entry.lockWindow ? { lockWindow: true } : {}),
+        window,
+    };
+}
+exports.SKAN_STORAGE_KEYS = {
+    snapshot: "apex_skan_schema_v1",
+    installedAt: "apex_skan_installed_at",
+    manual: "apex_skan_manual",
+    highest: "apex_skan_highest_v1",
+};
+/** How long a cached schema is trusted before revalidating. */
+exports.SKAN_SCHEMA_MAX_AGE_MS = DAY_MS;
+/**
+ * Owns the cached schema and the "what have I already told Apple"
+ * bookkeeping for one install. Created by the plugin proxy on
+ * `initialize({ autoConversionValues: true })`; not something an app
+ * constructs itself.
+ */
+class SkanAutoConversionValues {
+    constructor(options) {
+        this.snapshot = null;
+        this.manual = false;
+        this.highest = {};
+        this.ready = Promise.resolve();
+        this.endpoint = null;
+        this.update = options.update;
+        this.store = options.store === undefined ? defaultStore() : options.store;
+        this.fetchImpl = options.fetch;
+        this.now = options.now ?? Date.now;
+        this.log = options.log;
+        this.installedAt = this.readInstalledAt();
+        this.manual = this.store?.getItem(exports.SKAN_STORAGE_KEYS.manual) === "1";
+        this.highest = readJson(this.store, exports.SKAN_STORAGE_KEYS.highest) ?? {};
+        this.snapshot = readJson(this.store, exports.SKAN_STORAGE_KEYS.snapshot);
+    }
+    /**
+     * Point at a workspace and refresh the schema if the cache is stale.
+     * Resolves as soon as the cache has been read; the network revalidate
+     * runs in the background and never blocks the caller.
+     */
+    initialize(endpoint) {
+        this.endpoint = {
+            apiUrl: endpoint.apiUrl,
+            workspaceKey: endpoint.workspaceKey,
+            mobileAppId: endpoint.mobileAppId ?? null,
+        };
+        const stale = !this.snapshot ||
+            this.now() - this.snapshot.fetchedAt >= exports.SKAN_SCHEMA_MAX_AGE_MS;
+        if (stale) {
+            this.ready = this.revalidate();
+        }
+        return Promise.resolve();
+    }
+    /** Force a network revalidation (ETag-aware). */
+    async revalidate() {
+        if (!this.endpoint)
+            return;
+        const result = await fetchSkanConversionSchema({
+            ...this.endpoint,
+            etag: this.snapshot?.etag ?? null,
+            fetch: this.fetchImpl,
+        }, this.now);
+        if (result.status === "fresh") {
+            this.snapshot = result.snapshot;
+            writeJson(this.store, exports.SKAN_STORAGE_KEYS.snapshot, this.snapshot);
+            this.log?.(`skan schema refreshed (${countRungs(this.snapshot.schema)} rungs)`);
+        }
+        else if (result.status === "not_modified" && this.snapshot) {
+            this.snapshot = { ...this.snapshot, fetchedAt: this.now() };
+            writeJson(this.store, exports.SKAN_STORAGE_KEYS.snapshot, this.snapshot);
+            this.log?.("skan schema unchanged");
+        }
+        else if (result.status === "error") {
+            this.log?.("skan schema fetch failed; keeping cached copy");
+        }
+    }
+    /** Wait for any in-flight revalidation (tests and debug UIs). */
+    whenReady() {
+        return this.ready;
+    }
+    /** The schema the plugin is acting on right now. */
+    getSchema() {
+        return (this.snapshot ?? {
+            schema: null,
+            mobileAppId: this.endpoint?.mobileAppId ?? null,
+            etag: null,
+            fetchedAt: 0,
+        });
+    }
+    /** True once the app has called `updateConversionValue` itself. */
+    get manualMode() {
+        return this.manual;
+    }
+    /** Called when the app updates Apple's value by hand. Auto steps aside. */
+    noteManualUpdate() {
+        if (this.manual)
+            return;
+        this.manual = true;
+        this.store?.setItem(exports.SKAN_STORAGE_KEYS.manual, "1");
+        this.log?.("skan manual updateConversionValue seen; auto values off");
+    }
+    /**
+     * Called after every `track`. Sends the mapped value when the event has
+     * one in the current window and it moves the ladder up.
+     */
+    async onTrack(eventName) {
+        if (this.manual)
+            return null;
+        const now = this.now();
+        const window = skanWindowAt(this.installedAt, now);
+        if (!window)
+            return null;
+        const pick = pickConversionValue(this.snapshot?.schema ?? null, eventName, {
+            installedAt: this.installedAt,
+            now,
+            highestSent: this.highest[window] ?? null,
+        });
+        if (!pick)
+            return null;
+        try {
+            await this.update({
+                fineValue: pick.fineValue,
+                coarseValue: pick.coarseValue,
+                ...(pick.lockWindow ? { lockWindow: true } : {}),
+            });
+        }
+        catch (err) {
+            this.log?.(`skan updateConversionValue failed for ${eventName}: ${String(err)}`);
+            return null;
+        }
+        this.highest[window] = pick.fineValue;
+        writeJson(this.store, exports.SKAN_STORAGE_KEYS.highest, this.highest);
+        this.log?.(`skan updatePostbackConversionValue(${pick.fineValue}, ${pick.coarseValue}) for ${eventName} in window ${window}`);
+        return pick;
+    }
+    readInstalledAt() {
+        const raw = this.store?.getItem(exports.SKAN_STORAGE_KEYS.installedAt);
+        const parsed = raw ? Number(raw) : NaN;
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+        const now = this.now();
+        this.store?.setItem(exports.SKAN_STORAGE_KEYS.installedAt, String(now));
+        return now;
+    }
+}
+exports.SkanAutoConversionValues = SkanAutoConversionValues;
+// ─── Storage helpers ──────────────────────────────────────────────────────
+function defaultStore() {
+    try {
+        const ls = globalThis.localStorage;
+        return ls ? { getItem: (k) => ls.getItem(k), setItem: (k, v) => ls.setItem(k, v) } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readJson(store, key) {
+    try {
+        const raw = store?.getItem(key);
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeJson(store, key, value) {
+    try {
+        store?.setItem(key, JSON.stringify(value));
+    }
+    catch {
+        // Private mode / quota. Worst case we refetch tomorrow's schema early.
+    }
+}
+function countRungs(schema) {
+    return schema?.windows.reduce((n, w) => n + w.values.length, 0) ?? 0;
+}
+//# sourceMappingURL=skan-conversion-values.js.map

package/dist/skan-conversion-values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skan-conversion-values.js","sourceRoot":"","sources":["../src/skan-conversion-values.ts"],"names":[],"mappings":"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"}

package/dist/web.d.ts

@@ -11,7 +11,7 @@
  * in separate files so unit tests can cover them without DOM mocking.
  */
 import { WebPlugin } from "@capacitor/core";
-import type { AdvertisingIdResult, ApexCapacitorPlugin, ApexEvent, AttStatus, DeviceInfo, FlushResult, IdentifyOptions, InitializeOptions, PushRegistrationResult, QueueStatus, SessionInfo, SkanCoarseValue, VariantAssignmentResult } from "./definitions";
+import type { AdvertisingIdResult, ApexCapacitorPlugin, ApexEvent, AttStatus, DeferredDeepLinkResult, DeviceInfo, FlushResult, IdentifyOptions, InitializeOptions, PushRegistrationResult, QueueStatus, SessionInfo, SkanCoarseValue, SkanSchemaSnapshot, VariantAssignmentResult } from "./definitions";
 export declare class ApexCapacitorWeb extends WebPlugin implements ApexCapacitorPlugin {
     private queue?;
     private session?;
@@ -54,6 +54,7 @@ export declare class ApexCapacitorWeb extends WebPlugin implements ApexCapacitor
     getAdvertisingId(): Promise<AdvertisingIdResult>;
     getInstallReferrer(): Promise<{
         referrer: string | null;
+        clickTimestamp: number;
     }>;
     getVisitorId(): Promise<{
         visitorId: string;
@@ -80,10 +81,14 @@ export declare class ApexCapacitorWeb extends WebPlugin implements ApexCapacitor
     updateConversionValue(_options: {
         fineValue: number;
         coarseValue?: SkanCoarseValue;
+        lockWindow?: boolean;
     }): Promise<void>;
+    getConversionValueSchema(): Promise<SkanSchemaSnapshot>;
     getInitialDeepLink(): Promise<{
         url: string | null;
+        deepLinkHint: string | null;
     }>;
+    getDeferredDeepLink(): Promise<DeferredDeepLinkResult | null>;
     getDeviceInfo(): Promise<DeviceInfo>;
     startSession(): Promise<{
         sessionId: string;

package/dist/web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"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"}

package/dist/web.js

@@ -215,7 +215,7 @@ class ApexCapacitorWeb extends core_1.WebPlugin {
         return { id: null, fallback: null };
     }
     async getInstallReferrer() {
-        return { referrer: null };
+        return { referrer: null, clickTimestamp: 0 };
     }
     async getVisitorId() {
         if (!this.visitorId) {
@@ -286,11 +286,34 @@ class ApexCapacitorWeb extends core_1.WebPlugin {
     async updateConversionValue(_options) {
         // No-op on web / non-iOS.
     }
+    async getConversionValueSchema() {
+        // The proxy in `index.ts` answers this from its cache on iOS. Reached
+        // directly only when the web fallback is used as a bare class, where
+        // Apple is not listening anyway.
+        return { schema: null, mobileAppId: null, etag: null, fetchedAt: 0 };
+    }
     async getInitialDeepLink() {
         if (typeof window !== "undefined" && window.location) {
-            return { url: window.location.href };
+            const href = window.location.href;
+            let deepLinkHint = null;
+            try {
+                deepLinkHint = new URL(href).searchParams.get("apex_dl");
+            }
+            catch {
+                // Non-parseable location (rare, e.g. an about: page) — no hint.
+            }
+            return { url: href, deepLinkHint };
         }
-        return { url: null };
+        return { url: null, deepLinkHint: null };
+    }
+    async getDeferredDeepLink() {
+        // Deferred deep linking exists to bridge a gap that only exists on
+        // native: browser tap → app store → fresh app with no shared state.
+        // In a browser there is no gap — the URL the user tapped is the URL
+        // the page is already on, and `getInitialDeepLink()` returns it.
+        // Claiming a deferred link here would also burn the one-shot match
+        // that the real app install needs.
+        return null;
     }
     async getDeviceInfo() {
         // Best-effort on web — mostly placeholders so callers get consistent shape.
@@ -377,7 +400,12 @@ class ApexCapacitorWeb extends core_1.WebPlugin {
             // denominator for results). Deduped per (experiment, variant); batched
             // through track() so it doesn't add a synchronous network call.
             if (result.eligible) {
-                const expoKey = `${experimentId}:${result.variant}`;
+                // DBS-5 — dedupe per (session, experiment, variant) so a new session
+                // re-fires exactly one exposure. The exposure event itself carries the
+                // same sessionId (stamped in track()); this keeps the per-process
+                // guard aligned with the per-session Events-meter unit.
+                const expoSessionId = this.session?.getCurrent()?.sessionId ?? "";
+                const expoKey = `${expoSessionId}:${experimentId}:${result.variant}`;
                 if (!firedMobileExposures.has(expoKey)) {
                     firedMobileExposures.add(expoKey);
                     void this.track({