@datalyr/web 1.6.1 → 1.6.3

package/dist/datalyr.esm.js

@@ -1,5 +1,5 @@
 /**
- * @datalyr/web v1.6.1
+ * @datalyr/web v1.6.3
  * Datalyr Web SDK - Modern attribution tracking for web applications
  * (c) 2026 Datalyr Inc.
  * Released under the MIT License
@@ -243,15 +243,21 @@ class SafeStorage {
         this.prefix = 'dl_';
         // Test if storage is available
         try {
+            if (!storage)
+                throw new Error('no storage'); // server / SSR
             const testKey = 'dl_test__' + Math.random();
             storage.setItem(testKey, '1');
             storage.removeItem(testKey);
             this.storage = storage;
         }
         catch (_a) {
-            // Storage not available (Safari private mode, etc.)
+            // Storage not available (server-side render, Safari private mode, etc.)
             this.storage = null;
-            console.warn('[Datalyr] Storage not available, using memory fallback');
+            // Only warn in the browser — on the server there's intentionally no
+            // storage and the SDK does no real work until init() runs client-side.
+            if (typeof window !== 'undefined') {
+                console.warn('[Datalyr] Storage not available, using memory fallback');
+            }
         }
     }
     get(key, defaultValue = null) {
@@ -560,15 +566,53 @@ class CookieStorage {
         return '';
     }
 }
-// Export singleton instances for storage
-const storage = new SafeStorage(window.localStorage);
-new SafeStorage(window.sessionStorage);
+// Export singleton instances for storage.
+// Guard the browser globals so importing the SDK on the server (SSR / Node)
+// doesn't throw `window is not defined`. On the server these fall back to
+// in-memory storage; real storage is wired when the module re-evaluates in the
+// browser. (Without this, any static `import` of the SDK in a Next.js client
+// component crashes server rendering.)
+const browserLocalStorage = typeof window !== 'undefined' ? window.localStorage : undefined;
+const browserSessionStorage = typeof window !== 'undefined' ? window.sessionStorage : undefined;
+const storage = new SafeStorage(browserLocalStorage);
+new SafeStorage(browserSessionStorage);
 // Default cookie instance for backwards compatibility
 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
  */
@@ -2298,6 +2342,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);
@@ -2341,9 +2386,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');
@@ -2635,57 +2682,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
@@ -3505,7 +3587,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 => {
@@ -4099,7 +4193,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;