@datalyr/web 1.6.2 → 1.6.3

package/dist/container.d.ts

@@ -2,6 +2,20 @@
  * Container Script Manager
  * Loads and manages third-party tracking scripts and pixels
  */
+/**
+ * Identity snapshot read at the moment a third-party pixel initializes.
+ * Aligns the browser Pixel's advanced matching with what CAPI sends server-side
+ * (meta.js shovels all of {user_id, visitor_id, anonymous_id} into the CAPI
+ * external_id array) — so any one of those hashes coincides between surfaces.
+ *
+ * `externalId` should be the SDK's distinct_id (user_id when identified, else
+ * anonymous_id). `email` is only populated after identify(); when present, lets
+ * the Pixel match on `em` too.
+ */
+export interface PixelIdentity {
+    externalId?: string | null;
+    email?: string | null;
+}
 export interface ContainerScript {
     id: string;
     name: string;
@@ -50,10 +64,12 @@ export declare class ContainerManager {
     private sandboxedIframes;
     private iframeCleanupTimeouts;
     private messageHandler;
+    private getIdentity?;
     constructor(options: {
         workspaceId: string;
         endpoint?: string;
         debug?: boolean;
+        getIdentity?: () => PixelIdentity | undefined;
     });
     /**
      * Initialize container and load scripts
@@ -110,6 +126,12 @@ export declare class ContainerManager {
     private initializePixels;
     /**
      * Initialize Meta (Facebook) Pixel
+     *
+     * Async because we resolve SHA-256 hashes for advanced matching (Meta's
+     * `external_id` / `em`) before calling fbq('init'). Aligning the hashes the
+     * browser Pixel sends with what CAPI sends (meta.js shovels user_id /
+     * visitor_id / anonymous_id into external_id[], and `em` is sha256 of the
+     * lowercased email) is the dedup-quality lift the CAPI side can't fix alone.
      */
     private initializeMetaPixel;
     /**

package/dist/container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,WAAW,GAAG,WAAW,GAAG,aAAa,GAAG,QAAQ,CAAC;IAC9D,SAAS,EAAE,QAAQ,GAAG,eAAe,GAAG,kBAAkB,CAAC;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,GAAG,CAAC;KACZ,CAAC,CAAC;IACH,QAAQ,CAAC,EAAE;QACT,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE;QACL,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;IACF,MAAM,CAAC,EAAE;QACP,OAAO,EAAE,OAAO,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;IACF,MAAM,CAAC,EAAE;QACP,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,oBAAoB,CAAqB;IACjD,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAA2B;IACnD,OAAO,CAAC,qBAAqB,CAAwC;IACrE,OAAO,CAAC,cAAc,CAAgD;gBAE1D,OAAO,EAAE;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;IA8BD;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAwD3B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAU5B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAkBxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA2B1B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAyB/B;;OAEG;IACH,OAAO,CAAC,UAAU;IA8BlB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IA+DxB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAyBrB;;;OAGG;IACI,iBAAiB,IAAI,IAAI;IAkBhC;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAqC1B;;OAEG;IACH,OAAO,CAAC,SAAS;IAQjB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAmBxB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAiC3B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAyB3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0C7B;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,GAAE,GAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAqF9E;;OAEG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAO3C;;OAEG;IACH,gBAAgB,IAAI,MAAM,EAAE;IAI5B;;;;;;;;;;;;;;;;;;;OAmBG;IAEH;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAyB1B;;OAEG;IACH,OAAO,CAAC,aAAa;IA0BrB;;OAEG;IACH,OAAO,CAAC,GAAG;CAKZ"}
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"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"}

package/dist/datalyr.cjs.js

@@ -1,5 +1,5 @@
 /**
- * @datalyr/web v1.6.2
+ * @datalyr/web v1.6.3
  * Datalyr Web SDK - Modern attribution tracking for web applications
  * (c) 2026 Datalyr Inc.
  * Released under the MIT License
@@ -586,6 +586,37 @@ const cookies = new CookieStorage();
 /**
  * Utility Functions
  */
+/**
+ * SHA-256 hex digest aligned with the worker's CAPI hashing (cloudflare/
+ * postback/core/utils.js `sha256()`). Always lowercases + trims the input
+ * before hashing — Meta's matching requires byte-for-byte identical hashes
+ * on the Pixel side and the CAPI server side, and the worker uniformly
+ * normalizes everything it hashes (em, ph, fn, ln, external_id, etc).
+ *
+ * Pixel-side hashes that don't match CAPI hashes silently fail to dedupe,
+ * which is why this helper does the normalization for callers — easy to
+ * forget, hard to debug after release. Returns null when Web Crypto isn't
+ * available (very old browsers, non-secure contexts) so callers can
+ * gracefully skip advanced matching rather than throwing.
+ */
+function sha256Hex(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (typeof crypto === 'undefined' || !crypto.subtle)
+            return null;
+        if (!input)
+            return null;
+        try {
+            const bytes = new TextEncoder().encode(input.toLowerCase().trim());
+            const digest = yield crypto.subtle.digest('SHA-256', bytes);
+            return Array.from(new Uint8Array(digest))
+                .map((b) => b.toString(16).padStart(2, '0'))
+                .join('');
+        }
+        catch (_a) {
+            return null;
+        }
+    });
+}
 /**
  * Generate UUID v4
  */
@@ -2315,6 +2346,7 @@ class ContainerManager {
         // Container scripts use the same endpoint as tracking (ingest)
         this.endpoint = options.endpoint || 'https://ingest.datalyr.com';
         this.debug = options.debug || false;
+        this.getIdentity = options.getIdentity;
         // Load session scripts from storage
         const sessionScripts = storage.get('dl_session_scripts', []);
         this.sessionLoadedScripts = new Set(sessionScripts);
@@ -2358,9 +2390,11 @@ class ContainerManager {
                 // Store scripts and pixels
                 this.scripts = data.scripts || [];
                 this.pixels = data.pixels || null;
-                // Initialize pixels if configured
+                // Initialize pixels if configured. Awaited so advanced-matching hashes
+                // are resolved before the first dl.track() flushes through trackToPixels
+                // (otherwise fbq('init') would lag fbq('track') in fast-path tracks).
                 if (this.pixels) {
-                    this.initializePixels();
+                    yield this.initializePixels();
                 }
                 // Load scripts based on trigger
                 this.loadScriptsByTrigger('page_load');
@@ -2652,57 +2686,92 @@ class ContainerManager {
      * Initialize third-party pixels (Meta, Google, TikTok)
      */
     initializePixels() {
-        var _a, _b, _c;
-        if (!this.pixels)
-            return;
-        // Initialize Meta Pixel
-        if (((_a = this.pixels.meta) === null || _a === void 0 ? void 0 : _a.enabled) && this.pixels.meta.pixel_id) {
-            this.initializeMetaPixel(this.pixels.meta);
-        }
-        // Initialize Google Tag
-        if (((_b = this.pixels.google) === null || _b === void 0 ? void 0 : _b.enabled) && this.pixels.google.tag_id) {
-            this.initializeGoogleTag(this.pixels.google);
-        }
-        // Initialize TikTok Pixel
-        if (((_c = this.pixels.tiktok) === null || _c === void 0 ? void 0 : _c.enabled) && this.pixels.tiktok.pixel_id) {
-            this.initializeTikTokPixel(this.pixels.tiktok);
-        }
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            if (!this.pixels)
+                return;
+            // Initialize Meta Pixel
+            if (((_a = this.pixels.meta) === null || _a === void 0 ? void 0 : _a.enabled) && this.pixels.meta.pixel_id) {
+                yield this.initializeMetaPixel(this.pixels.meta);
+            }
+            // Initialize Google Tag
+            if (((_b = this.pixels.google) === null || _b === void 0 ? void 0 : _b.enabled) && this.pixels.google.tag_id) {
+                this.initializeGoogleTag(this.pixels.google);
+            }
+            // Initialize TikTok Pixel
+            if (((_c = this.pixels.tiktok) === null || _c === void 0 ? void 0 : _c.enabled) && this.pixels.tiktok.pixel_id) {
+                this.initializeTikTokPixel(this.pixels.tiktok);
+            }
+        });
     }
     /**
      * Initialize Meta (Facebook) Pixel
+     *
+     * Async because we resolve SHA-256 hashes for advanced matching (Meta's
+     * `external_id` / `em`) before calling fbq('init'). Aligning the hashes the
+     * browser Pixel sends with what CAPI sends (meta.js shovels user_id /
+     * visitor_id / anonymous_id into external_id[], and `em` is sha256 of the
+     * lowercased email) is the dedup-quality lift the CAPI side can't fix alone.
      */
     initializeMetaPixel(config) {
-        try {
-            // Load Meta Pixel script
-            (function (f, b, e, v, n, t, s) {
-                if (f.fbq)
-                    return;
-                n = f.fbq = function () {
-                    n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments);
-                };
-                if (!f._fbq)
-                    f._fbq = n;
-                n.push = n;
-                n.loaded = !0;
-                n.version = '2.0';
-                n.queue = [];
-                t = b.createElement(e);
-                t.async = !0;
-                t.src = v;
-                s = b.getElementsByTagName(e)[0];
-                s.parentNode.insertBefore(t, s);
-            })(window, document, 'script', 'https://connect.facebook.net/en_US/fbevents.js');
-            // Initialize pixel only — do NOT fire PageView here. The SDK's own pageview
-            // tracking (track('pageview')) routes through trackToPixels and fires a single
-            // mapped PageView with a shared eventID. Firing it again here produced TWO
-            // PageViews per load (one un-deduped). Note: if the host app disables pageview
-            // tracking entirely, no PageView is sent — which is the correct outcome.
-            window.fbq('init', config.pixel_id);
-            this.log('Meta Pixel initialized:', config.pixel_id);
-        }
-        catch (error) {
-            this.log('Error initializing Meta Pixel:', error);
-        }
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                // Load Meta Pixel script
+                (function (f, b, e, v, n, t, s) {
+                    if (f.fbq)
+                        return;
+                    n = f.fbq = function () {
+                        n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments);
+                    };
+                    if (!f._fbq)
+                        f._fbq = n;
+                    n.push = n;
+                    n.loaded = !0;
+                    n.version = '2.0';
+                    n.queue = [];
+                    t = b.createElement(e);
+                    t.async = !0;
+                    t.src = v;
+                    s = b.getElementsByTagName(e)[0];
+                    s.parentNode.insertBefore(t, s);
+                })(window, document, 'script', 'https://connect.facebook.net/en_US/fbevents.js');
+                // Build advanced-matching object. Skipped silently if Web Crypto isn't
+                // available — Pixel still initializes, just without advanced matching.
+                // Anonymous_id is stable across the session and always present, so we
+                // never need to re-init on identify(): CAPI carries both anonymous_id
+                // AND user_id in its external_id[] array, so either side matching one
+                // hash slot is enough to dedupe.
+                const advancedMatching = {};
+                const identity = (_a = this.getIdentity) === null || _a === void 0 ? void 0 : _a.call(this);
+                if (identity === null || identity === void 0 ? void 0 : identity.externalId) {
+                    const hash = yield sha256Hex(String(identity.externalId));
+                    if (hash)
+                        advancedMatching.external_id = hash;
+                }
+                if (identity === null || identity === void 0 ? void 0 : identity.email) {
+                    const hash = yield sha256Hex(String(identity.email).toLowerCase().trim());
+                    if (hash)
+                        advancedMatching.em = hash;
+                }
+                // Initialize pixel only — do NOT fire PageView here. The SDK's own pageview
+                // tracking (track('pageview')) routes through trackToPixels and fires a single
+                // mapped PageView with a shared eventID. Firing it again here produced TWO
+                // PageViews per load (one un-deduped). Note: if the host app disables pageview
+                // tracking entirely, no PageView is sent — which is the correct outcome.
+                if (Object.keys(advancedMatching).length > 0) {
+                    window.fbq('init', config.pixel_id, advancedMatching);
+                    this.log('Meta Pixel initialized with advanced matching:', config.pixel_id, Object.keys(advancedMatching));
+                }
+                else {
+                    window.fbq('init', config.pixel_id);
+                    this.log('Meta Pixel initialized (no advanced matching):', config.pixel_id);
+                }
+            }
+            catch (error) {
+                this.log('Error initializing Meta Pixel:', error);
+            }
+        });
     }
     /**
      * Initialize Google Tag
@@ -3522,7 +3591,19 @@ class Datalyr {
                         this.container = new ContainerManager({
                             workspaceId: this.config.workspaceId,
                             endpoint: this.config.endpoint,
-                            debug: this.config.debug
+                            debug: this.config.debug,
+                            // Lazy: invoked at the moment a third-party pixel inits, AFTER the
+                            // /container-scripts roundtrip resolves — so a pre-init identify()
+                            // already updated this.identity / this.userProperties. distinctId
+                            // mirrors what CAPI puts in external_id[] (user_id || anonymous_id);
+                            // email lets the Pixel match on em with the same hash CAPI sends.
+                            getIdentity: () => {
+                                var _a, _b;
+                                return ({
+                                    externalId: (_a = this.identity) === null || _a === void 0 ? void 0 : _a.getDistinctId(),
+                                    email: (_b = this.userProperties) === null || _b === void 0 ? void 0 : _b.email,
+                                });
+                            }
                         });
                         // Initialize container asynchronously
                         yield this.container.init().catch(error => {
@@ -4116,7 +4197,7 @@ class Datalyr {
             resolution_method: 'browser_sdk',
             resolution_confidence: 1.0,
             // SDK metadata (keep in sync with package.json version)
-            sdk_version: '1.6.0',
+            sdk_version: '1.6.3',
             sdk_name: 'datalyr-web-sdk'
         };
         return payload;