@formo/analytics 1.28.5 → 1.29.0

package/dist/cjs/src/solana/types.d.ts

@@ -1,10 +1,10 @@
 /**
  * Solana-specific type definitions for wallet event tracking
  *
- * These types provide TypeScript interfaces for Solana Wallet Adapter integration,
- * allowing the SDK to hook into Solana wallet events to track wallet interactions.
+ * Core types for the Solana integration: cluster mappings, chain ID utilities,
+ * and configuration options. Framework-kit store types are in storeTypes.ts.
  *
- * @see https://github.com/anza-xyz/wallet-adapter
+ * @see https://github.com/solana-foundation/framework-kit
  */
 /**
  * Solana cluster/network types
@@ -33,7 +33,7 @@ export declare const DEFAULT_SOLANA_CHAIN_ID: number;
 export declare function isSolanaChainId(chainId: number | undefined | null): boolean;
 /**
  * Solana PublicKey interface
- * Represents a Solana public key (32 bytes, Base58 encoded)
+ * Used by address validation utilities.
  */
 export interface SolanaPublicKey {
     toBase58(): string;
@@ -42,165 +42,34 @@ export interface SolanaPublicKey {
     equals(other: SolanaPublicKey): boolean;
 }
 /**
- * Solana transaction signature (64 bytes, Base58 encoded)
- */
-export type TransactionSignature = string;
-/**
- * Solana wallet adapter state
- */
-export type WalletAdapterState = "connected" | "disconnected" | "connecting" | "disconnecting";
-/**
- * Solana wallet adapter interface
- * Based on @solana/wallet-adapter-base WalletAdapter
- */
-export interface ISolanaAdapter {
-    name: string;
-    url: string;
-    icon: string;
-    readyState: WalletReadyState;
-    publicKey: SolanaPublicKey | null;
-    connecting: boolean;
-    connected: boolean;
-    connect(): Promise<void>;
-    disconnect(): Promise<void>;
-    sendTransaction?(transaction: SolanaTransaction, connection: SolanaConnection, options?: SendTransactionOptions): Promise<TransactionSignature>;
-    signTransaction?(transaction: SolanaTransaction): Promise<SolanaTransaction>;
-    signAllTransactions?(transactions: SolanaTransaction[]): Promise<SolanaTransaction[]>;
-    signMessage?(message: Uint8Array): Promise<Uint8Array>;
-    on(event: "connect", listener: (publicKey: SolanaPublicKey) => void): void;
-    on(event: "disconnect", listener: () => void): void;
-    on(event: "error", listener: (error: WalletError) => void): void;
-    on(event: "readyStateChange", listener: (readyState: WalletReadyState) => void): void;
-    off(event: string, listener: (...args: unknown[]) => void): void;
-    removeAllListeners?(event?: string): void;
-}
-/**
- * Solana wallet ready state
- */
-export declare enum WalletReadyState {
-    Installed = "Installed",
-    NotDetected = "NotDetected",
-    Loadable = "Loadable",
-    Unsupported = "Unsupported"
-}
-/**
- * Solana wallet error
- */
-export interface WalletError extends Error {
-    error?: unknown;
-}
-/**
- * Solana transaction interface (minimal)
- */
-export interface SolanaTransaction {
-    signature?: Uint8Array;
-    serialize(): Uint8Array;
-    feePayer?: SolanaPublicKey;
-    recentBlockhash?: string;
-}
-/**
- * Solana connection interface (minimal)
- */
-export interface SolanaConnection {
-    rpcEndpoint: string;
-    commitment?: string;
-    getSignatureStatus?(signature: string): Promise<{
-        value: SignatureStatus | null;
-    }>;
-    getSignatureStatuses?(signatures: string[]): Promise<{
-        value: (SignatureStatus | null)[];
-    }>;
-}
-/**
- * Solana signature status
- */
-export interface SignatureStatus {
-    slot: number;
-    confirmations: number | null;
-    err: unknown | null;
-    confirmationStatus?: "processed" | "confirmed" | "finalized";
-}
-/**
- * Send transaction options
- */
-export interface SendTransactionOptions {
-    skipPreflight?: boolean;
-    preflightCommitment?: string;
-    maxRetries?: number;
-    minContextSlot?: number;
-}
-/**
- * Wallet entry as returned by @solana/wallet-adapter-react useWallet().wallet
- * This is { adapter, readyState }, not a direct adapter.
- */
-export interface SolanaWalletEntry {
-    adapter: ISolanaAdapter;
-    readyState: WalletReadyState;
-}
-/**
- * @deprecated Use SolanaWalletEntry instead
- */
-export type SolanaWallet = SolanaWalletEntry;
-/**
- * Solana Wallet Context interface
- * Based on @solana/wallet-adapter-react useWallet hook
- * @see https://github.com/anza-xyz/wallet-adapter/blob/master/packages/core/react/src/useWallet.ts
+ * Unsubscribe function type
  */
-export interface SolanaWalletContext {
-    autoConnect: boolean;
-    wallets: SolanaWalletEntry[];
-    wallet: SolanaWalletEntry | null;
-    publicKey: SolanaPublicKey | null;
-    connecting: boolean;
-    connected: boolean;
-    disconnecting: boolean;
-    select(walletName: string | null): void;
-    connect(): Promise<void>;
-    disconnect(): Promise<void>;
-    sendTransaction(transaction: SolanaTransaction, connection: SolanaConnection, options?: SendTransactionOptions): Promise<TransactionSignature>;
-    signTransaction?(transaction: SolanaTransaction): Promise<SolanaTransaction>;
-    signAllTransactions?(transactions: SolanaTransaction[]): Promise<SolanaTransaction[]>;
-    signMessage?(message: Uint8Array): Promise<Uint8Array>;
-}
+export type UnsubscribeFn = () => void;
 /**
  * Solana options for FormoAnalytics
  */
 export interface SolanaOptions {
     /**
-     * The Solana wallet adapter instance or wallet context
-     * Can be a single wallet adapter or the useWallet() context
-     */
-    wallet?: ISolanaAdapter | SolanaWalletContext;
-    /**
-     * The Solana connection for tracking transaction confirmations
+     * The framework-kit client store (client.store) for automatic event tracking.
+     * When provided, wallet connect/disconnect and transaction events are tracked
+     * automatically by subscribing to zustand store state changes.
+     *
+     * This is the recommended approach for apps using @solana-foundation/framework-kit.
+     *
+     * @example
+     * ```tsx
+     * import { createClient } from '@solana-foundation/framework-kit';
+     * const client = createClient({ endpoint, walletConnectors: autoDiscover() });
+     * const formo = await Formo.init(writeKey, { solana: { store: client.store } });
+     * ```
      */
-    connection?: SolanaConnection;
+    store?: import("./storeTypes").SolanaClientStore;
     /**
-     * The Solana cluster/network
-     * @default "mainnet-beta"
+     * The Solana cluster/network.
+     * Usually auto-detected from the store's endpoint URL.
+     * Only needed for custom RPC URLs that don't contain a recognizable cluster name.
+     * @default auto-detected, or "mainnet-beta" if detection fails
      */
     cluster?: SolanaCluster;
 }
-/**
- * Internal connection state for Solana event handler.
- * Tracks the last known wallet connection for disconnect event payloads
- * and provides a reentrancy guard for concurrent event handling.
- */
-export interface SolanaConnectionState {
-    lastAddress?: string;
-    lastChainId?: number;
-    isProcessing: boolean;
-}
-/**
- * Unsubscribe function type
- */
-export type UnsubscribeFn = () => void;
-/**
- * Check if an object is a SolanaWalletContext (has wallets array)
- */
-export declare function isSolanaWalletContext(obj: ISolanaAdapter | SolanaWalletContext | undefined | null): obj is SolanaWalletContext;
-/**
- * Check if an object is a ISolanaAdapter
- */
-export declare function isSolanaAdapter(obj: ISolanaAdapter | SolanaWalletContext | undefined | null): obj is ISolanaAdapter;
 //# sourceMappingURL=types.d.ts.map

package/dist/cjs/src/solana/types.js

@@ -2,16 +2,14 @@
 /**
  * Solana-specific type definitions for wallet event tracking
  *
- * These types provide TypeScript interfaces for Solana Wallet Adapter integration,
- * allowing the SDK to hook into Solana wallet events to track wallet interactions.
+ * Core types for the Solana integration: cluster mappings, chain ID utilities,
+ * and configuration options. Framework-kit store types are in storeTypes.ts.
  *
- * @see https://github.com/anza-xyz/wallet-adapter
+ * @see https://github.com/solana-foundation/framework-kit
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WalletReadyState = exports.DEFAULT_SOLANA_CHAIN_ID = exports.SOLANA_CLUSTERS_BY_ID = exports.SOLANA_CHAIN_IDS = void 0;
+exports.DEFAULT_SOLANA_CHAIN_ID = exports.SOLANA_CLUSTERS_BY_ID = exports.SOLANA_CHAIN_IDS = void 0;
 exports.isSolanaChainId = isSolanaChainId;
-exports.isSolanaWalletContext = isSolanaWalletContext;
-exports.isSolanaAdapter = isSolanaAdapter;
 /**
  * Mapping of Solana clusters to numeric chain IDs for consistency with EVM events
  * These IDs are non-standard but provide a way to identify Solana networks in our analytics
@@ -46,35 +44,4 @@ function isSolanaChainId(chainId) {
         return false;
     return Object.values(exports.SOLANA_CHAIN_IDS).includes(chainId);
 }
-/**
- * Solana wallet ready state
- */
-var WalletReadyState;
-(function (WalletReadyState) {
-    WalletReadyState["Installed"] = "Installed";
-    WalletReadyState["NotDetected"] = "NotDetected";
-    WalletReadyState["Loadable"] = "Loadable";
-    WalletReadyState["Unsupported"] = "Unsupported";
-})(WalletReadyState || (exports.WalletReadyState = WalletReadyState = {}));
-/**
- * Check if an object is a SolanaWalletContext (has wallets array)
- */
-function isSolanaWalletContext(obj) {
-    return (obj !== null &&
-        obj !== undefined &&
-        typeof obj === "object" &&
-        "wallets" in obj &&
-        Array.isArray(obj.wallets));
-}
-/**
- * Check if an object is a ISolanaAdapter
- */
-function isSolanaAdapter(obj) {
-    return (obj !== null &&
-        obj !== undefined &&
-        typeof obj === "object" &&
-        "name" in obj &&
-        "connect" in obj &&
-        !("wallets" in obj));
-}
 //# sourceMappingURL=types.js.map

package/dist/cjs/src/storage/StorageManager.d.ts

@@ -5,5 +5,6 @@ export declare class StorageManager {
     constructor(writeKey: string);
     getStorage(type: StorageType): IStorage;
     private createStorage;
+    private getWebStorage;
 }
 //# sourceMappingURL=StorageManager.d.ts.map

package/dist/cjs/src/storage/StorageManager.js

@@ -47,14 +47,22 @@ var StorageManager = /** @class */ (function () {
             case "cookieStorage":
                 return new cookie_1.default(this.writeKey);
             case "localStorage":
-                return new web_1.default(this.writeKey, localStorage);
             case "sessionStorage":
-                return new web_1.default(this.writeKey, sessionStorage);
+                return new web_1.default(this.writeKey, this.getWebStorage(type));
             case "memoryStorage":
             default:
                 return new memory_1.default(this.writeKey);
         }
     };
+    StorageManager.prototype.getWebStorage = function (type) {
+        try {
+            var storage = type === "localStorage" ? localStorage : sessionStorage;
+            return storage !== null && storage !== void 0 ? storage : null;
+        }
+        catch (_a) {
+            return null;
+        }
+    };
     return StorageManager;
 }());
 exports.StorageManager = StorageManager;

package/dist/cjs/src/types/base.d.ts

@@ -164,6 +164,14 @@ export interface Options {
      * @default true
      */
     autocapture?: boolean | AutocaptureOptions;
+    /**
+     * EVM provider tracking.
+     * Set to `false` to disable all EVM provider detection and tracking
+     * (EIP-1193, EIP-6963, window.ethereum). Useful for Solana-only apps
+     * that don't need EVM wallet event capture.
+     * @default true
+     */
+    evm?: boolean;
     /**
      * Wagmi integration configuration
      * When provided, the SDK will hook into Wagmi's event system instead of wrapping EIP-1193 providers
@@ -173,11 +181,14 @@ export interface Options {
      */
     wagmi?: WagmiOptions;
     /**
-     * Solana Wallet Adapter integration configuration
-     * When provided, the SDK will track Solana wallet events in addition to EVM wallet events
-     * This works alongside EIP-1193/Wagmi tracking - you can track both EVM and Solana wallets
-     * @requires @solana/wallet-adapter-base (optional peer dependency)
-     * @requires @solana/wallet-adapter-react (optional peer dependency, for React apps)
+     * Solana integration configuration.
+     * Pass `store: client.store` from framework-kit for automatic tracking of
+     * wallet connect/disconnect and transaction events.
+     *
+     * For signMessage/signTransaction, use formo.signature() directly
+     * (framework-kit doesn't track these in the store).
+     *
+     * @see https://github.com/solana-foundation/framework-kit
      */
     solana?: SolanaOptions;
     /**

package/dist/cjs/src/types/events.d.ts

@@ -1,6 +1,7 @@
 import { UUID } from "crypto";
 import { Address, ChainID, Nullable } from "./base";
 import { TEventChannel, TEventType } from "../constants";
+import { CLICK_ID_PARAMS } from "../event/constants";
 export type AnonymousID = UUID;
 export interface ICommonProperties {
     anonymous_id: AnonymousID;
@@ -21,7 +22,10 @@ export type UTMParameters = {
     utm_term: string;
     utm_content: string;
 };
-export type ITrafficSource = UTMParameters & {
+export type ClickIdParameters = {
+    [K in (typeof CLICK_ID_PARAMS)[number]]: string;
+};
+export type ITrafficSource = UTMParameters & ClickIdParameters & {
     ref: string;
     referrer: string;
 };

package/dist/cjs/src/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "1.28.5";
+export declare const version = "1.29.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/cjs/src/version.js

@@ -3,5 +3,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
 // This file is auto-generated by scripts/update-version.js during npm version
 // Do not edit manually - it will be overwritten
-exports.version = '1.28.5';
+exports.version = '1.29.0';
 //# sourceMappingURL=version.js.map

package/dist/esm/src/FormoAnalytics.d.ts

@@ -45,8 +45,15 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * When true, EIP-1193 provider wrapping is skipped
      */
     private isWagmiMode;
+    /**
+     * Flag indicating if EVM provider tracking is disabled.
+     * When true, all EIP-1193/EIP-6963 detection and wrapping is skipped.
+     */
+    private isEvmDisabled;
     /** Instance-level flag so multiple SDK instances don't interfere. */
     private crossSubdomainCookies;
+    /** In-memory URL used to deduplicate SPA pageview events. */
+    private _currentUrl;
     config: Config;
     currentChainId?: ChainID;
     currentAddress?: Address;
@@ -294,10 +301,9 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      *
      * @example
      * ```tsx
-     * formo.solana.setWallet(wallet);
-     * formo.solana.setConnection(connection);
+     * formo.solana.setStore(client.store);
      * formo.solana.setCluster("devnet");
-     * formo.solana.syncWalletState();
+     * // For signatures, use formo.signature() directly
      * ```
      */
     get solana(): SolanaManager;

package/dist/esm/src/FormoAnalytics.js

@@ -55,7 +55,7 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
     return to.concat(ar || Array.prototype.slice.call(from));
 };
 import { createStore } from "mipd";
-import { EVENTS_API_HOST, EventType, LOCAL_ANONYMOUS_ID_KEY, SESSION_CURRENT_URL_KEY, SESSION_USER_ID_KEY, CONSENT_OPT_OUT_KEY, } from "./constants";
+import { EVENTS_API_HOST, EventType, LOCAL_ANONYMOUS_ID_KEY, SESSION_USER_ID_KEY, CONSENT_OPT_OUT_KEY, } from "./constants";
 import { cookie, initStorageManager } from "./storage";
 import { getIdentityCookieDomain } from "./storage/cookiePolicy";
 import { EventManager } from "./event";
@@ -114,6 +114,13 @@ var FormoAnalytics = /** @class */ (function () {
          * When true, EIP-1193 provider wrapping is skipped
          */
         this.isWagmiMode = false;
+        /**
+         * Flag indicating if EVM provider tracking is disabled.
+         * When true, all EIP-1193/EIP-6963 detection and wrapping is skipped.
+         */
+        this.isEvmDisabled = false;
+        /** In-memory URL used to deduplicate SPA pageview events. */
+        this._currentUrl = "";
         this.currentUserId = "";
         this.config = {
             writeKey: writeKey,
@@ -121,6 +128,7 @@ var FormoAnalytics = /** @class */ (function () {
         this.options = options;
         // Check if Wagmi mode is enabled
         this.isWagmiMode = !!options.wagmi;
+        this.isEvmDisabled = options.evm === false;
         this.crossSubdomainCookies = (_a = options.crossSubdomainCookies) !== null && _a !== void 0 ? _a : true;
         // Normalize so downstream consumers (EventFactory) read the resolved value.
         options.crossSubdomainCookies = this.crossSubdomainCookies;
@@ -153,8 +161,11 @@ var FormoAnalytics = /** @class */ (function () {
         if (this.hasOptedOutTracking()) {
             logger.info("User has previously opted out of tracking");
         }
-        // Initialize Wagmi handler if Wagmi mode is enabled
-        if (this.isWagmiMode && options.wagmi) {
+        // Initialize EVM provider tracking (unless explicitly disabled)
+        if (this.isEvmDisabled) {
+            logger.info("FormoAnalytics: EVM provider tracking disabled");
+        }
+        else if (this.isWagmiMode && options.wagmi) {
             logger.info("FormoAnalytics: Initializing in Wagmi mode");
             this.wagmiHandler = new WagmiEventHandler(this, options.wagmi.config, options.wagmi.queryClient);
         }
@@ -176,6 +187,7 @@ var FormoAnalytics = /** @class */ (function () {
         if (options.solana) {
             this.solanaManager = new SolanaManager(this, options.solana);
         }
+        this._currentUrl = window.location.href;
         this.trackPageHit();
         this.trackPageHits();
     }
@@ -223,22 +235,26 @@ var FormoAnalytics = /** @class */ (function () {
                     case 0:
                         initStorageManager(writeKey);
                         analytics = new FormoAnalytics(writeKey, options);
-                        if (!!analytics.isWagmiMode) return [3 /*break*/, 3];
+                        if (!analytics.isEvmDisabled) return [3 /*break*/, 1];
+                        logger.info("FormoAnalytics: Skipping provider detection (EVM disabled)");
+                        return [3 /*break*/, 5];
+                    case 1:
+                        if (!!analytics.isWagmiMode) return [3 /*break*/, 4];
                         // Auto-detect wallet provider
                         _a = analytics;
                         return [4 /*yield*/, analytics.getProviders()];
-                    case 1:
+                    case 2:
                         // Auto-detect wallet provider
                         _a._providers = _b.sent();
                         return [4 /*yield*/, analytics.detectWallets(analytics._providers)];
-                    case 2:
+                    case 3:
                         _b.sent();
                         analytics.trackProviders(analytics._providers);
-                        return [3 /*break*/, 4];
-                    case 3:
+                        return [3 /*break*/, 5];
+                    case 4:
                         logger.info("FormoAnalytics: Skipping provider detection (Wagmi mode)");
-                        _b.label = 4;
-                    case 4: return [2 /*return*/, analytics];
+                        _b.label = 5;
+                    case 5: return [2 /*return*/, analytics];
                 }
             });
         });
@@ -1424,11 +1440,9 @@ var FormoAnalytics = /** @class */ (function () {
     };
     FormoAnalytics.prototype.onLocationChange = function () {
         return __awaiter(this, void 0, void 0, function () {
-            var currentUrl;
             return __generator(this, function (_a) {
-                currentUrl = cookie().get(SESSION_CURRENT_URL_KEY);
-                if (currentUrl !== window.location.href) {
-                    cookie().set(SESSION_CURRENT_URL_KEY, window.location.href);
+                if (this._currentUrl !== window.location.href) {
+                    this._currentUrl = window.location.href;
                     this.trackPageHit();
                 }
                 return [2 /*return*/];
@@ -1767,10 +1781,9 @@ var FormoAnalytics = /** @class */ (function () {
          *
          * @example
          * ```tsx
-         * formo.solana.setWallet(wallet);
-         * formo.solana.setConnection(connection);
+         * formo.solana.setStore(client.store);
          * formo.solana.setCluster("devnet");
-         * formo.solana.syncWalletState();
+         * // For signatures, use formo.signature() directly
          * ```
          */
         get: function () {

package/dist/esm/src/constants/base.d.ts

@@ -1,5 +1,4 @@
 export declare const SESSION_TRAFFIC_SOURCE_KEY = "traffic-source";
-export declare const SESSION_CURRENT_URL_KEY = "analytics-current-url";
 export declare const SESSION_USER_ID_KEY = "user-id";
 export declare const LOCAL_ANONYMOUS_ID_KEY = "anonymous-id";
 export declare const CONSENT_OPT_OUT_KEY = "opt-out-tracking";

package/dist/esm/src/constants/base.js

@@ -1,7 +1,6 @@
 export var SESSION_TRAFFIC_SOURCE_KEY = "traffic-source";
 // SESSION_WALLET_DETECTED_KEY and SESSION_WALLET_IDENTIFIED_KEY
 // are now defined in src/session/index.ts
-export var SESSION_CURRENT_URL_KEY = "analytics-current-url";
 export var SESSION_USER_ID_KEY = "user-id";
 export var LOCAL_ANONYMOUS_ID_KEY = "anonymous-id";
 // Consent management keys

package/dist/esm/src/event/EventFactory.d.ts

@@ -17,6 +17,7 @@ declare class EventFactory implements IEventFactory {
     private getLanguage;
     private getLibraryVersion;
     private extractUTMParameters;
+    private extractClickIdParameters;
     private extractReferralParameter;
     private getTrafficSources;
     private getScreen;

package/dist/esm/src/event/EventFactory.js

@@ -54,7 +54,7 @@ import { logger } from "../logger";
 import mergeDeepRight from "../ramda/mergeDeepRight";
 import { session } from "../storage";
 import { version } from "../version";
-import { CHANNEL, VERSION, PAGE_PROPERTIES_EXCLUDED_FIELDS } from "./constants";
+import { CHANNEL, CLICK_ID_PARAMS, PAGE_PROPERTIES_EXCLUDED_FIELDS, VERSION, } from "./constants";
 import { generateAnonymousId } from "./utils";
 import { detectBrowser } from "../browser/browsers";
 var EventFactory = /** @class */ (function () {
@@ -81,6 +81,15 @@ var EventFactory = /** @class */ (function () {
             catch (_a) { }
             return result;
         };
+        this.extractClickIdParameters = function (urlObj) {
+            var result = {};
+            for (var _i = 0, CLICK_ID_PARAMS_1 = CLICK_ID_PARAMS; _i < CLICK_ID_PARAMS_1.length; _i++) {
+                var param = CLICK_ID_PARAMS_1[_i];
+                var value = urlObj.searchParams.get(param);
+                result[param] = value ? value.trim() : "";
+            }
+            return result;
+        };
         this.extractReferralParameter = function (urlObj) {
             var _a, _b, _c;
             // Strategy: Check query params first, then check path pattern if configured
@@ -113,25 +122,23 @@ var EventFactory = /** @class */ (function () {
         };
         this.getTrafficSources = function (url) {
             var urlObj = new URL(url);
-            var contextTrafficSources = __assign(__assign({}, _this.extractUTMParameters(url)), { ref: _this.extractReferralParameter(urlObj), referrer: document.referrer });
+            var contextTrafficSources = __assign(__assign(__assign({}, _this.extractUTMParameters(url)), _this.extractClickIdParameters(urlObj)), { ref: _this.extractReferralParameter(urlObj), referrer: document.referrer });
             var storedTrafficSources = session().get(SESSION_TRAFFIC_SOURCE_KEY) || {};
-            var finalTrafficSources = {
-                ref: contextTrafficSources.ref || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.ref) || "",
-                referrer: contextTrafficSources.referrer || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.referrer) || "",
-                utm_campaign: contextTrafficSources.utm_campaign ||
+            var mergedClickIds = {};
+            for (var _i = 0, CLICK_ID_PARAMS_2 = CLICK_ID_PARAMS; _i < CLICK_ID_PARAMS_2.length; _i++) {
+                var p = CLICK_ID_PARAMS_2[_i];
+                mergedClickIds[p] =
+                    contextTrafficSources[p] || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources[p]) || "";
+            }
+            var finalTrafficSources = __assign({ ref: contextTrafficSources.ref || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.ref) || "", referrer: contextTrafficSources.referrer || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.referrer) || "", utm_campaign: contextTrafficSources.utm_campaign ||
                     (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_campaign) ||
-                    "",
-                utm_content: contextTrafficSources.utm_content ||
+                    "", utm_content: contextTrafficSources.utm_content ||
                     (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_content) ||
-                    "",
-                utm_medium: contextTrafficSources.utm_medium ||
+                    "", utm_medium: contextTrafficSources.utm_medium ||
                     (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_medium) ||
-                    "",
-                utm_source: contextTrafficSources.utm_source ||
+                    "", utm_source: contextTrafficSources.utm_source ||
                     (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_source) ||
-                    "",
-                utm_term: contextTrafficSources.utm_term || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_term) || "",
-            };
+                    "", utm_term: contextTrafficSources.utm_term || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_term) || "" }, mergedClickIds);
             // Store to session
             var sessionStoredTrafficSources = Object.keys(finalTrafficSources).reduce(function (res, key) {
                 var value = finalTrafficSources[key];

package/dist/esm/src/event/constants.d.ts

@@ -1,11 +1,17 @@
 declare const CHANNEL = "web";
 declare const VERSION = "0";
+/**
+ * Paid-attribution click IDs captured from the landing-page URL and persisted
+ * across the session alongside UTM parameters. Keep the ClickIdParameters type
+ * in src/types/events.ts derived from this array.
+ */
+declare const CLICK_ID_PARAMS: readonly ["gclid", "gad_source", "fbclid", "msclkid", "twclid", "li_fat_id", "rdt_cid", "ttclid"];
 /**
  * Fields that should be excluded from page event properties parsing
  * These are either:
- * - Already captured in event context (UTM params, referral params)
+ * - Already captured in event context (UTM params, referral params, click IDs)
  * - Semantic event properties that should not be overridden by URL params
  */
 declare const PAGE_PROPERTIES_EXCLUDED_FIELDS: Set<string>;
-export { CHANNEL, VERSION, PAGE_PROPERTIES_EXCLUDED_FIELDS };
+export { CHANNEL, VERSION, CLICK_ID_PARAMS, PAGE_PROPERTIES_EXCLUDED_FIELDS };
 //# sourceMappingURL=constants.d.ts.map