@datalyr/web 1.6.3 → 1.6.5

package/dist/datalyr.esm.js

@@ -1,5 +1,5 @@
 /**
- * @datalyr/web v1.6.3
+ * @datalyr/web v1.6.5
  * Datalyr Web SDK - Modern attribution tracking for web applications
  * (c) 2026 Datalyr Inc.
  * Released under the MIT License
@@ -1524,6 +1524,7 @@ class AttributionManager {
      * Capture advertising platform cookies
      */
     captureAdCookies() {
+        var _a, _b;
         const adCookies = {};
         // Facebook/Meta cookies
         adCookies._fbp = cookies.get('_fbp');
@@ -1548,13 +1549,29 @@ class AttributionManager {
             // Optionally set the cookie for future use
             cookies.set('_fbp', adCookies._fbp, 90);
         }
+        // Persist the click time the FIRST time we see fbclid/gclid in URL so we can
+        // rebuild fbc (and stamp real click time on server-side events) later even
+        // when _fbc/_gclid cookies get evicted. Once-only: never overwrite.
+        const fbclid = this.getCurrentFbclid();
+        if (fbclid && !cookies.get('_dl_fbclid_at')) {
+            cookies.set('_dl_fbclid_at', String(Date.now()), 90);
+        }
+        const gclid = this.hasClickId('gclid') ? ((_b = (_a = this.queryParamsCache) === null || _a === void 0 ? void 0 : _a.gclid) !== null && _b !== void 0 ? _b : null) : null;
+        if (gclid && !cookies.get('_dl_gclid_at')) {
+            cookies.set('_dl_gclid_at', String(Date.now()), 90);
+        }
         // Generate _fbc if we have fbclid but no _fbc.
         // Meta's fbc format is `fb.{subdomainIndex}.{creationTime}.{fbclid}` where
         // creationTime is UNIX time in MILLISECONDS (matches the _fbp generation above
         // and the real _fbc cookie the Meta Pixel writes). Do NOT use seconds here.
-        const fbclid = this.getCurrentFbclid();
         if (fbclid && !adCookies._fbc) {
-            const timestamp = Date.now();
+            // Prefer the persisted click time when valid; fall back to now if the
+            // cookie is missing or corrupted (e.g. user edited it to garbage).
+            // Without this guard, Number("abc") = NaN and Meta would reject
+            // `fb.1.NaN.{fbclid}`.
+            const stored = cookies.get('_dl_fbclid_at');
+            const parsed = stored ? Number(stored) : NaN;
+            const timestamp = Number.isFinite(parsed) && parsed > 0 ? parsed : Date.now();
             adCookies._fbc = `fb.1.${timestamp}.${fbclid}`;
             // Optionally set the cookie for future use
             cookies.set('_fbc', adCookies._fbc, 90);
@@ -3511,6 +3528,14 @@ class Datalyr {
         }
         // Set default config values
         this.config = Object.assign({ endpoint: 'https://ingest.datalyr.com', debug: false, batchSize: 10, flushInterval: 5000, flushAt: 10, criticalEvents: undefined, highPriorityEvents: undefined, sessionTimeout: 60 * 60 * 1000, trackSessions: true, attributionWindow: 90 * 24 * 60 * 60 * 1000, trackedParams: [], respectDoNotTrack: false, respectGlobalPrivacyControl: true, privacyMode: 'standard', cookieDomain: 'auto', cookieExpires: 365, secureCookie: 'auto', sameSite: 'Lax', cookiePrefix: '__dl_', enablePerformanceTracking: true, enableFingerprinting: true, maxRetries: 5, retryDelay: 1000, maxOfflineQueueSize: 100, trackSPA: true, trackPageViews: true, fallbackEndpoints: [], plugins: [] }, config);
+        // platform:'shopify' implies cart-attribute sync: stamp visitor_id + Meta
+        // click signals into note_attributes so server-side order webhooks can
+        // attribute guest checkouts. Lets the Shopify theme app-embed enable it via
+        // data-platform="shopify" alone. `=== undefined` so an explicit
+        // shopifyCartAttributes:false still wins.
+        if (this.config.platform === 'shopify' && this.config.shopifyCartAttributes === undefined) {
+            this.config.shopifyCartAttributes = true;
+        }
         // Initialize cookie storage with config
         this.cookies = new CookieStorage({
             domain: this.config.cookieDomain,
@@ -3522,6 +3547,12 @@ class Datalyr {
         storage.migrateFromLegacyPrefix();
         // Check opt-out AFTER cookies configured (Issue #14)
         this.optedOut = this.cookies.get('__dl_opt_out') === 'true';
+        // CC funnel page entry: restore the _dl_* URL bridge BEFORE IdentityManager
+        // initializes so the storefront's visitor_id is the one used here (instead
+        // of auto-generating a fresh one on this domain).
+        if (this.config.platform === 'checkoutchamp') {
+            this.restoreFromURL();
+        }
         // Initialize modules
         this.identity = new IdentityManager();
         this.session = new SessionManager(this.config.sessionTimeout);
@@ -3605,6 +3636,26 @@ class Datalyr {
                         yield this.container.init().catch(error => {
                             this.log('Container initialization failed:', error);
                         });
+                        // Checkout Champ thank-you/upsell page: co-fire the browser Meta Pixel
+                        // Purchase with the SAME deterministic event_id the CC webhook stamps
+                        // server-side, so Meta dedupes the browser event against the server-side
+                        // CAPI event (dedup = event_name + event_id). Pixel-only — the CC Export
+                        // Profile webhook owns the server event + CAPI postback. No-op anywhere
+                        // except a post-purchase page (keyed on CC's sessionStorage orderData).
+                        // Must run AFTER container.init() so fbq is loaded + init'd.
+                        if (this.config.platform === 'checkoutchamp') {
+                            this.fireCheckoutChampPurchasePixel();
+                        }
+                    }
+                    // autoIdentify default for the CC bridge:
+                    // - platform === 'checkoutchamp' (CC funnel pages) OR
+                    // - checkoutChampDomains set (Shopify storefronts feeding a CC funnel)
+                    // turn autoIdentify on unless the caller explicitly set it to false.
+                    // The 95% claim relies on email capture on BOTH ends of the bridge.
+                    const ccBridgeActive = this.config.platform === 'checkoutchamp'
+                        || (Array.isArray(this.config.checkoutChampDomains) && this.config.checkoutChampDomains.length > 0);
+                    if (ccBridgeActive && this.config.autoIdentify === undefined) {
+                        this.config.autoIdentify = true;
                     }
                     // Initialize auto-identify if explicitly enabled (opt-in)
                     if (this.config.autoIdentify === true) {
@@ -3638,6 +3689,12 @@ class Datalyr {
                             this.log('Shopify cart attribute sync failed:', error);
                         });
                     }
+                    // Storefront → CC bridge: stamp _dl_* params on outbound links to the
+                    // configured CC domains so visitor_id + click signals cross the domain
+                    // boundary. Inert unless checkoutChampDomains is set.
+                    if (Array.isArray(this.config.checkoutChampDomains) && this.config.checkoutChampDomains.length > 0) {
+                        this.syncOutboundLinkParams(this.config.checkoutChampDomains);
+                    }
                     // Track initial page view if enabled (AFTER encryption ready)
                     if (this.config.trackPageViews) {
                         this.page();
@@ -4108,6 +4165,7 @@ class Datalyr {
             const visitorId = this.identity.getAnonymousId();
             const fbc = this.cookies.get("_fbc") || attribution._fbc;
             const fbp = this.cookies.get("_fbp") || attribution._fbp;
+            const fbclidAt = this.cookies.get("_dl_fbclid_at");
             if (visitorId)
                 attributes._datalyr_visitor_id = visitorId;
             if (fbc)
@@ -4116,6 +4174,8 @@ class Datalyr {
                 attributes._datalyr_fbp = String(fbp);
             if (fbclid)
                 attributes._datalyr_fbclid = String(fbclid);
+            if (fbclidAt)
+                attributes._datalyr_fbclid_at = String(fbclidAt);
             if (Object.keys(attributes).length === 0)
                 return;
             try {
@@ -4133,6 +4193,305 @@ class Datalyr {
             }
         });
     }
+    /**
+     * Restore _dl_* URL bridge params on a Checkout Champ funnel page.
+     * Runs BEFORE IdentityManager so the storefront's visitor_id wins over a
+     * freshly auto-generated one. Also restores _fbc / _fbp cookies and the
+     * fbclid click time so server-side rebuilds carry the real click moment.
+     *
+     * Strategy: stamp matching cookies (without clobbering pre-existing values),
+     * then rewrite the URL so `_dl_fbclid` becomes `fbclid` — that way the rest
+     * of the SDK's attribution layer (which reads `params.fbclid`) works
+     * unchanged, and any merchant analytics also see the canonical click ID.
+     */
+    restoreFromURL() {
+        var _a;
+        if (typeof window === "undefined" || typeof document === "undefined")
+            return;
+        try {
+            const params = new URLSearchParams(window.location.search);
+            const get = (k) => params.get(k);
+            const vid = get("_dl_vid");
+            const fbc = get("_dl_fbc");
+            const fbp = get("_dl_fbp");
+            const fbclid = get("_dl_fbclid");
+            const fbclidAt = get("_dl_fbclid_at");
+            const gclid = get("_dl_gclid");
+            const gclidAt = get("_dl_gclid_at");
+            // visitor_id: bridge wins. The whole point of `_dl_vid` is to unify the
+            // storefront's session with the CC funnel session. A pre-existing local
+            // cookie from a prior direct CC visit would silently sink the integration
+            // (CC events stay on the local id; storefront events use the bridged id;
+            // the two never link). Overwrite — orphaned local events are fine.
+            if (vid)
+                this.cookies.set("__dl_visitor_id", vid, 365);
+            // Meta cookies + click-time cookies: existing wins. _fbc / _fbp may have
+            // been written by Meta Pixel on the CC funnel page itself (more recent
+            // than the bridged value); _dl_fbclid_at should record first-touch click
+            // time per device, not get reset by a bridge from a new campaign.
+            const setIfMissing = (name, value) => {
+                if (!value)
+                    return;
+                if (this.cookies.get(name))
+                    return;
+                this.cookies.set(name, value, 365);
+            };
+            setIfMissing("_fbc", fbc);
+            setIfMissing("_fbp", fbp);
+            setIfMissing("_dl_fbclid_at", fbclidAt);
+            setIfMissing("_dl_gclid_at", gclidAt);
+            // Rewrite URL: _dl_fbclid → fbclid (etc.) so captureAttribution() picks
+            // them up via its existing `params.fbclid` path. Strip the _dl_* params
+            // either way so they don't leak into downstream analytics URLs.
+            let rewrote = false;
+            const mappings = [
+                ["fbclid", fbclid],
+                ["gclid", gclid]
+            ];
+            for (const [canonical, value] of mappings) {
+                if (value && !params.get(canonical)) {
+                    params.set(canonical, value);
+                    rewrote = true;
+                }
+            }
+            for (const k of ["_dl_vid", "_dl_fbc", "_dl_fbp", "_dl_fbclid", "_dl_fbclid_at", "_dl_gclid", "_dl_gclid_at"]) {
+                if (params.has(k)) {
+                    params.delete(k);
+                    rewrote = true;
+                }
+            }
+            if (rewrote && typeof ((_a = window.history) === null || _a === void 0 ? void 0 : _a.replaceState) === "function") {
+                const newSearch = params.toString();
+                const newUrl = window.location.pathname +
+                    (newSearch ? "?" + newSearch : "") +
+                    window.location.hash;
+                window.history.replaceState(window.history.state, "", newUrl);
+            }
+            this.log("Checkout Champ bridge restored:", {
+                had_vid: !!vid,
+                had_fbc: !!fbc,
+                had_fbp: !!fbp,
+                had_fbclid: !!fbclid,
+                had_gclid: !!gclid
+            });
+        }
+        catch (error) {
+            // Don't let bridge restoration block init — fall through to normal SDK
+            // behavior (a fresh visitor_id, no restored click signals).
+            this.log("restoreFromURL failed:", error);
+        }
+    }
+    /**
+     * Checkout Champ Meta Pixel ⇄ CAPI deduplication.
+     *
+     * On a CC thank-you / upsell page, fire the BROWSER Meta Pixel Purchase with the
+     * exact same event_id the CC webhook stamps server-side, so Meta collapses the
+     * browser Pixel event and the server-side CAPI event into one (dedup key =
+     * event_name + event_id). This gives the EMQ lift of a matched browser+server
+     * event without double-counting conversions in Ads Manager.
+     *
+     * PIXEL-ONLY by design. We do NOT enqueue a server event here: the CC Export
+     * Profile webhook (webhooks/platforms/checkoutchamp.js) already ingests the
+     * purchase and fires CAPI. Calling track() here would create a second server
+     * event (source='web') AND double-fire CAPI — defeating the whole point.
+     *
+     * The event_id MUST stay byte-identical to the server formula:
+     *   webhooks/platforms/checkoutchamp.js:250
+     *     generateEventId('checkoutchamp', `${event_type}_${order_id}`)
+     *   webhooks/core/ingest.js:122  →  `${platform}_${webhookEventId}`
+     *   ⇒ `checkoutchamp_purchase_<order_id>`
+     * where <order_id> is the value CC posts to the webhook via its [orderId] macro.
+     * We read the browser-side counterpart from CC's own client-side order object:
+     *   JSON.parse(sessionStorage.getItem('orderData')).orderId
+     * (CC docs: referenced in custom scripts as `orderDataTmp.orderId`).
+     *
+     * ASSUMPTION TO VERIFY ON A REAL CC TEST ORDER: that sessionStorage
+     * orderData.orderId === the [orderId] CC sends to the postback. If a merchant's
+     * CC plan exposes a different id client-side, the two event_ids won't match and
+     * Meta will show duplicates — caught by the test order in the setup checklist.
+     *
+     * v1 scope: the primary order only. Per-upsell Pixel dedup (each upsell is its
+     * own order_id + parent_order_id server-side) needs the upsell sessionStorage
+     * shape confirmed on a live funnel first — tracked as a follow-up.
+     */
+    fireCheckoutChampPurchasePixel() {
+        var _a;
+        if (typeof window === "undefined")
+            return;
+        try {
+            // Needs the container (where the Meta Pixel lives). trackToPixels itself
+            // no-ops unless a Meta pixel is enabled + fbq is present, so an
+            // unconfigured workspace silently does nothing.
+            if (!this.container)
+                return;
+            const raw = (_a = window.sessionStorage) === null || _a === void 0 ? void 0 : _a.getItem("orderData");
+            if (!raw)
+                return; // not a post-purchase page — nothing to dedupe
+            const order = JSON.parse(raw) || {};
+            const orderId = order.orderId;
+            if (!orderId)
+                return;
+            // orderData persists across upsell page loads — fire the primary Purchase
+            // Pixel once per order. (Meta also dedupes by event_id over 48h, so this is
+            // belt-and-suspenders against a per-page re-fire.)
+            const guardKey = `__dl_cc_purchase_${orderId}`;
+            if (window.sessionStorage.getItem(guardKey))
+                return;
+            window.sessionStorage.setItem(guardKey, "1");
+            // KEEP IN SYNC with the server formula above.
+            const eventId = `checkoutchamp_purchase_${orderId}`;
+            // value/currency are for EMQ quality only — Meta dedup is event_id+name, so
+            // a mismatch here never breaks dedup. Best-effort parse of CC's fields.
+            const value = Number(order.totalAmount);
+            const properties = {
+                order_id: String(orderId),
+                content_type: "product",
+            };
+            if (Number.isFinite(value))
+                properties.value = value;
+            const currency = order.currencyCode || order.currency;
+            if (currency)
+                properties.currency = String(currency);
+            if (order.productId)
+                properties.content_ids = [String(order.productId)];
+            // Pixel-only co-fire. 'purchase' maps to Meta 'Purchase' in trackToPixels,
+            // matching the server-side rule's platform_event_name.
+            this.container.trackToPixels("purchase", properties, eventId);
+            this.log("Checkout Champ Purchase Pixel co-fired (CAPI dedup):", {
+                eventId,
+                value: properties.value,
+                currency: properties.currency,
+            });
+        }
+        catch (error) {
+            // Never let dedup co-fire break the page or init.
+            this.log("fireCheckoutChampPurchasePixel failed:", error);
+        }
+    }
+    /**
+     * Storefront → Checkout Champ link stamping. Finds every `<a href>` whose host
+     * matches the configured CC domain list and appends `?_dl_vid=…&_dl_fbc=…&
+     * _dl_fbp=…&_dl_fbclid=…&_dl_fbclid_at=…&_dl_gclid=…` so the user's
+     * visitor_id + Meta click signals cross the domain. MutationObserver watches
+     * for dynamically-injected links. On click, force-flush the event queue so
+     * any pending track() events land before the browser navigates away.
+     */
+    syncOutboundLinkParams(domains) {
+        if (typeof window === "undefined" || typeof document === "undefined")
+            return;
+        const lowerDomains = domains.map((d) => d.toLowerCase());
+        const matchesCcDomain = (href) => {
+            try {
+                const host = new URL(href, window.location.href).hostname.toLowerCase();
+                return lowerDomains.some((d) => host === d || host.endsWith("." + d));
+            }
+            catch (_a) {
+                return false;
+            }
+        };
+        const buildBridgeParams = () => {
+            const attribution = this.attribution.getAttributionData();
+            const out = {};
+            const vid = this.identity.getAnonymousId();
+            const fbc = this.cookies.get("_fbc") || attribution._fbc;
+            const fbp = this.cookies.get("_fbp") || attribution._fbp;
+            const fbclid = attribution.clickIdType === "fbclid" ? attribution.clickId : null;
+            const fbclidAt = this.cookies.get("_dl_fbclid_at");
+            const gclid = attribution.clickIdType === "gclid" ? attribution.clickId : null;
+            const gclidAt = this.cookies.get("_dl_gclid_at");
+            if (vid)
+                out._dl_vid = vid;
+            if (fbc)
+                out._dl_fbc = String(fbc);
+            if (fbp)
+                out._dl_fbp = String(fbp);
+            if (fbclid)
+                out._dl_fbclid = String(fbclid);
+            if (fbclidAt)
+                out._dl_fbclid_at = String(fbclidAt);
+            if (gclid)
+                out._dl_gclid = String(gclid);
+            if (gclidAt)
+                out._dl_gclid_at = String(gclidAt);
+            return out;
+        };
+        const stampLink = (anchor) => {
+            if (!anchor.href || !matchesCcDomain(anchor.href))
+                return;
+            try {
+                const u = new URL(anchor.href, window.location.href);
+                const bridge = buildBridgeParams();
+                let mutated = false;
+                for (const [k, v] of Object.entries(bridge)) {
+                    if (!u.searchParams.get(k)) {
+                        u.searchParams.set(k, v);
+                        mutated = true;
+                    }
+                }
+                if (mutated)
+                    anchor.href = u.toString();
+            }
+            catch (_a) {
+                // Ignore malformed URLs — don't break the page.
+            }
+        };
+        const stampAll = () => {
+            document.querySelectorAll("a[href]").forEach((el) => stampLink(el));
+        };
+        const onClick = (e) => {
+            var _a, _b;
+            const target = (_a = e.target) === null || _a === void 0 ? void 0 : _a.closest("a[href]");
+            if (!target)
+                return;
+            const anchor = target;
+            if (!matchesCcDomain(anchor.href))
+                return;
+            stampLink(anchor); // re-stamp in case attribution changed since DOMReady
+            try {
+                (_b = this.queue) === null || _b === void 0 ? void 0 : _b.flush();
+            }
+            catch (_c) {
+                // Best-effort — never block navigation.
+            }
+        };
+        stampAll();
+        document.addEventListener("click", onClick, true);
+        try {
+            // Debounce re-stamping. A busy SPA (infinite scroll, animations,
+            // React/Vue updates) can fire thousands of mutations per second; a naive
+            // re-stamp on every notification would burn CPU pointlessly when
+            // outbound link sets only change occasionally. 150ms is small enough to
+            // catch links before the user can click them, large enough to coalesce
+            // bursts.
+            let restampTimer = null;
+            const scheduleRestamp = () => {
+                if (restampTimer != null)
+                    return;
+                restampTimer = setTimeout(() => {
+                    restampTimer = null;
+                    stampAll();
+                }, 150);
+            };
+            const observer = new MutationObserver(scheduleRestamp);
+            observer.observe(document.documentElement, { childList: true, subtree: true });
+            // Observer + click listener live for the session; pagehide cleans up on
+            // full-page unload. SPA route changes are fine — we WANT stamping to keep
+            // working across virtual navigations.
+            window.addEventListener("pagehide", () => {
+                try {
+                    observer.disconnect();
+                }
+                catch ( /* idempotent */_a) { /* idempotent */ }
+                if (restampTimer != null)
+                    clearTimeout(restampTimer);
+                document.removeEventListener("click", onClick, true);
+            }, { once: true });
+        }
+        catch (error) {
+            this.log("MutationObserver setup failed (CC link sync):", error);
+        }
+        this.log("Checkout Champ outbound-link sync active for:", lowerDomains);
+    }
     /**
      * Create event payload
      */
@@ -4193,7 +4552,7 @@ class Datalyr {
             resolution_method: 'browser_sdk',
             resolution_confidence: 1.0,
             // SDK metadata (keep in sync with package.json version)
-            sdk_version: '1.6.3',
+            sdk_version: '1.6.5',
             sdk_name: 'datalyr-web-sdk'
         };
         return payload;