@blotoutio/providers-universal-ads-sdk 1.66.0 → 1.66.2

package/index.js

@@ -1,7 +1,160 @@
 var ProvidersUniversalAdsSdk = (function () {
     'use strict';
 
+    /**
+     * The Universal Ads pixel vocabulary.
+     *
+     * Every name here is taken verbatim from Universal Ads' own tooling — the
+     * event-level snippets the UA dashboard generates and the official GTM
+     * community template (`Universal-Ads/universal-ads-pixel-gtm`, `template.tpl`).
+     * uap.js lower-cases the conversion name before it posts it (`eventName:
+     * name.toLowerCase()`) but validates nothing else and aliases nothing, so a
+     * near-miss (`start_checkout` instead of `checkout_start`) is accepted by the
+     * pixel and then silently records nothing. Do not "tidy" these strings.
+     */
+    /** All 18 conversions the pixel accepts, including the two custom slots. */
+    const UA_CONVERSIONS = [
+        'page_view',
+        'content_view',
+        'product_view',
+        'search',
+        'sign_in',
+        'sign_up',
+        'schedule_appointment',
+        'start_trial',
+        'view_cart',
+        'wish_list',
+        'purchase',
+        'checkout_start',
+        'add_to_cart',
+        'add_payment_info',
+        'add_address_info',
+        'subscribe',
+        'custom_event_1',
+        'custom_event_2',
+    ];
+    /**
+     * Which parameters UA offers per event, mirroring the event-level snippets the
+     * dashboard generates. `page_view` is carried by the base code and takes none.
+     */
+    const UA_EVENT_PARAMS = {
+        page_view: [],
+        content_view: ['description', 'content_id', 'user_id'],
+        product_view: ['price', 'currency', 'description', 'content_id', 'user_id'],
+        search: ['price', 'currency', 'description', 'content_id', 'user_id'],
+        sign_in: ['description', 'user_id', 'user_name'],
+        sign_up: ['description', 'user_id', 'user_name'],
+        schedule_appointment: ['description', 'user_id', 'user_name'],
+        start_trial: ['price', 'currency', 'description', 'user_id', 'user_name'],
+        subscribe: ['price', 'currency', 'description', 'user_id', 'user_name'],
+        view_cart: [
+            'price',
+            'currency',
+            'description',
+            'content_id',
+            'item_quantity',
+            'user_id',
+        ],
+        wish_list: [
+            'price',
+            'currency',
+            'description',
+            'content_id',
+            'item_quantity',
+            'user_id',
+        ],
+        checkout_start: [
+            'price',
+            'currency',
+            'description',
+            'content_id',
+            'item_quantity',
+            'user_id',
+        ],
+        add_to_cart: [
+            'price',
+            'currency',
+            'description',
+            'content_id',
+            'item_quantity',
+            'user_id',
+        ],
+        add_payment_info: [
+            'price',
+            'currency',
+            'description',
+            'content_id',
+            'item_quantity',
+            'user_id',
+        ],
+        add_address_info: [
+            'price',
+            'currency',
+            'description',
+            'content_id',
+            'item_quantity',
+            'user_id',
+        ],
+        purchase: [
+            'price',
+            'currency',
+            'order_id',
+            'description',
+            'content_id',
+            'item_quantity',
+            'user_id',
+            'user_name',
+        ],
+        custom_event_1: [
+            'price',
+            'currency',
+            'order_id',
+            'description',
+            'content_id',
+            'item_quantity',
+            'user_id',
+            'user_name',
+        ],
+        custom_event_2: [
+            'price',
+            'currency',
+            'order_id',
+            'description',
+            'content_id',
+            'item_quantity',
+            'user_id',
+            'user_name',
+        ],
+    };
+    /**
+     * EdgeTag event -> UA conversion, applied when a tag configures no override.
+     *
+     * `RemoveFromCart` and `SessionStart` are absent on purpose: UA has no
+     * equivalent, so they are dropped rather than mapped onto something adjacent.
+     * The UA conversions with no EdgeTag twin (sign_in, product_view, start_trial,
+     * view_cart, wish_list, schedule_appointment, custom_event_1/2) are reachable
+     * through the per-tag event mapping.
+     */
+    const DEFAULT_EVENT_MAP = {
+        PageView: 'page_view',
+        ViewContent: 'content_view',
+        AddToCart: 'add_to_cart',
+        InitiateCheckout: 'checkout_start',
+        AddPaymentInfo: 'add_payment_info',
+        AddShippingInfo: 'add_address_info',
+        Purchase: 'purchase',
+        Subscribe: 'subscribe',
+        Search: 'search',
+        Lead: 'sign_up',
+    };
+
     const packageName = 'universalAds';
+    // The pixel library UA serves; it aliases itself onto `window[data-sdk-name]`.
+    const SDK_URL = 'https://connect.universalads.com/uap.js';
+    // The global the pixel is reachable through once loaded with our script tag.
+    const SDK_NAME = 'uapx';
+
+    const keyPrefix = `_worker`;
 
     const canLog = () => {
         try {
@@ -35,6 +188,176 @@ var ProvidersUniversalAdsSdk = (function () {
         },
     };
 
+    const initKey = `${keyPrefix}StoreMultiple`;
+    const getData = (destination, persistType, key = initKey) => {
+        let data;
+        if (persistType === 'session') {
+            data = getSession(key);
+        }
+        else {
+            data = getLocal(key);
+        }
+        return (data === null || data === void 0 ? void 0 : data[destination]) || {};
+    };
+    const getLocal = (key) => {
+        try {
+            if (!localStorage) {
+                return {};
+            }
+            const data = localStorage.getItem(key);
+            if (!data) {
+                return {};
+            }
+            return JSON.parse(data) || {};
+        }
+        catch {
+            return {};
+        }
+    };
+    const getSession = (key) => {
+        try {
+            if (!sessionStorage) {
+                return {};
+            }
+            const data = sessionStorage.getItem(key);
+            if (!data) {
+                return {};
+            }
+            return JSON.parse(data) || {};
+        }
+        catch {
+            return {};
+        }
+    };
+
+    const SCRIPT_ID = 'uapx-sdk';
+    /**
+     * Conversions raised before uap.js finished loading.
+     *
+     * The pixel script is async, so EdgeTag's PageView routinely reaches `tag`
+     * before `window.uapx` exists. UA's own snippet dodges this by sending
+     * page_view from inside `onload`; we send from the tag handler instead, so we
+     * buffer here rather than dropping the event.
+     */
+    const pending = [];
+    /**
+     * Cap on the queue. An ad blocker blocking `connect.universalads.com` is the
+     * expected failure for an ad pixel, and an SPA session can raise events for
+     * hours — the queue must not grow with them.
+     *
+     * @internal Exported for the cap assertion in `pixel.test.ts` only.
+     */
+    const MAX_PENDING = 50;
+    /**
+     * Set once the pixel can never arrive: the script errored, or it loaded without
+     * exposing the global. From then on conversions are dropped instead of queued
+     * for a flush that will never come.
+     */
+    let unavailable = false;
+    /** Give up for the rest of the page: release the queue and say why once. */
+    const abandon = (message) => {
+        unavailable = true;
+        pending.length = 0;
+        logger.log(message);
+    };
+    const flush = () => {
+        var _a;
+        while (pending.length) {
+            const next = pending.shift();
+            if (!next) {
+                return;
+            }
+            // One rejected conversion must not strand the rest of the queue.
+            try {
+                (_a = window.uapx) === null || _a === void 0 ? void 0 : _a.sendConversion(next.conversion, next.params);
+            }
+            catch (error) {
+                logger.error(error);
+            }
+        }
+    };
+    const start = (productId, accessToken) => {
+        if (!window.uapx) {
+            abandon('Universal Ads pixel loaded but window.uapx is missing; conversions will not be sent.');
+            return;
+        }
+        const config = {
+            general: {
+                install_id_enabled: true,
+                pers_tr: true,
+                collect_page_info: true,
+                collect_ga: true,
+                product_id: productId,
+                access_token: accessToken,
+            },
+        };
+        // This runs from the script's `onload`, outside init's try/catch, so a throw
+        // here would surface as an uncaught error on the customer's page.
+        try {
+            window.uapx.startWithConfig(config);
+        }
+        catch (error) {
+            logger.error(error);
+        }
+        flush();
+    };
+    const loadPixel = (productId, accessToken) => {
+        // Already present, either from a previous init or a hand-placed base snippet.
+        // Starting twice would re-run session bookkeeping inside uap.js.
+        if (window.uapx || document.getElementById(SCRIPT_ID)) {
+            return;
+        }
+        const script = document.createElement('script');
+        script.id = SCRIPT_ID;
+        script.type = 'text/javascript';
+        script.async = true;
+        // uap.js reads this off `document.currentScript` to decide which global to
+        // alias itself onto. Without it the pixel is only reachable as
+        // `window.pubSuite` and every sendConversion call below silently no-ops.
+        script.setAttribute('data-sdk-name', SDK_NAME);
+        script.src = SDK_URL;
+        script.onload = () => {
+            start(productId, accessToken);
+        };
+        script.onerror = () => {
+            script.remove();
+            abandon(`Universal Ads pixel failed to load from ${SDK_URL}.`);
+        };
+        document.head.appendChild(script);
+    };
+    const sendConversion = (conversion, params) => {
+        if (window.uapx) {
+            window.uapx.sendConversion(conversion, params);
+            return;
+        }
+        if (unavailable || pending.length >= MAX_PENDING) {
+            return;
+        }
+        pending.push({ conversion, params });
+    };
+
+    const init = ({ manifest }) => {
+        var _a;
+        try {
+            if (typeof window === 'undefined' || typeof document === 'undefined') {
+                return;
+            }
+            if (((_a = manifest.variables) === null || _a === void 0 ? void 0 : _a['enableBrowser']) !== '1') {
+                return;
+            }
+            const productId = manifest.variables['productId'];
+            const accessToken = manifest.variables['accessToken'];
+            if (!productId || !accessToken) {
+                logger.log('Universal Ads pixel is not loaded. Configure UNIVERSAL_ADS_PRODUCT_ID and UNIVERSAL_ADS_ACCESS_TOKEN.');
+                return;
+            }
+            loadPixel(productId, accessToken);
+        }
+        catch (error) {
+            logger.error(error);
+        }
+    };
+
     /**
      * Known ad-network click ID query parameters and the human-readable provider
      * label each one maps to. Used by the CDN worker to resolve `inSessionTouch`
@@ -461,26 +784,6 @@ var ProvidersUniversalAdsSdk = (function () {
         ...caProvinces.keys(),
     ]);
 
-    const normalize = (urlString) => {
-        try {
-            const cleanUrl = urlString.replace(/\t/g, '');
-            const urlObj = new URL(cleanUrl);
-            const pathname = urlObj.pathname.replace(/\/+$/, ''); // Remove trailing slash
-            return `${urlObj.origin}${pathname}`;
-        }
-        catch (e) {
-            // Fallback for non-URL values
-            return urlString.replace(/\t/g, '').replace(/\/+$/, '');
-        }
-    };
-    // Convert wildcard URL pattern to RegExp (e.g. * becomes .+?)
-    const wildcardToRegex = (pattern) => {
-        const escaped = pattern
-            .replace(/[-/\\^$+?.()|[\]{}]/g, '\\$&') // Escape regex special characters
-            .replace(/\*/g, '[^/]+'); // Wildcard * matches one path segment
-        return new RegExp(`^${escaped}$`, 'i'); // Case-insensitive match
-    };
-
     /**
      * Exact utm_source normalization (lowercase key → canonical name).
      *
@@ -602,94 +905,105 @@ var ProvidersUniversalAdsSdk = (function () {
         OFFLINE_TOUCH,
     ]);
 
-    const getUrlMapping = (urlMapping, url) => {
-        const mapping = tryParse(urlMapping, []);
-        if (!mapping.length) {
-            logger.log('Invalid urlMapping JSON:', urlMapping);
-            return null;
-        }
-        const normalizedUrl = normalize(url);
-        const match = mapping.find((item) => {
-            // Skip incomplete rows rather than firing a pixel with `undefined` params.
-            if (!item.url || !item.tagId || !item.segmentKey) {
-                return false;
-            }
-            const normalizedPattern = normalize(item.url);
-            if (normalizedPattern.includes('*')) {
-                const regex = wildcardToRegex(normalizedPattern);
-                return regex.test(normalizedUrl);
+    const isConversion = (value) => UA_CONVERSIONS.includes(value);
+    // A configured row wins for the event it names; every other event keeps its default.
+    const resolveConversion = (eventName, eventMapping) => {
+        var _a;
+        const configured = tryParse(eventMapping, []);
+        if (Array.isArray(configured)) {
+            const override = configured.find((row) => (row === null || row === void 0 ? void 0 : row.event) === eventName);
+            // A row naming a conversion UA does not accept is ignored rather than
+            // dropping the event: the form's conversion select is not creatable, so this
+            // only reaches us from a legacy or hand-edited worker value, and the default
+            // conversion is a better outcome there than silently sending nothing.
+            if (override && isConversion(override.conversion)) {
+                return override.conversion;
             }
-            return normalizedUrl === normalizedPattern;
-        });
-        return match ? { tagId: match.tagId, segmentKey: match.segmentKey } : null;
+        }
+        return (_a = DEFAULT_EVENT_MAP[eventName]) !== null && _a !== void 0 ? _a : null;
     };
-
-    const getUrl = (mapping, buzzKey, accountId) => {
-        const cacheBuster = Math.floor(Math.random() * 10000000000);
-        const url = new URL('https://cnv.event.prod.bidr.io/log/cnv');
-        url.searchParams.set('tag_id', mapping.tagId);
-        url.searchParams.set('buzz_key', buzzKey);
-        url.searchParams.set('value', '');
-        url.searchParams.set('segment_key', mapping.segmentKey);
-        url.searchParams.set('account_id', accountId);
-        url.searchParams.set('ord', cacheBuster.toString());
-        return url.toString();
+    const contentsOf = (data) => Array.isArray(data['contents']) ? data['contents'] : [];
+    const asParam = (value) => {
+        if (value === undefined || value === null || value === '') {
+            return undefined;
+        }
+        if (typeof value === 'number') {
+            return Number.isFinite(value) ? String(value) : undefined;
+        }
+        return typeof value === 'string' ? value : undefined;
     };
-    const initUniversalAds = (accountId, buzzKey, urlMapping, pageUrl) => {
-        var _a;
-        if (typeof document == 'undefined') {
-            return;
+    const itemQuantity = (contents) => {
+        if (!contents.length) {
+            return undefined;
         }
-        let url;
-        if (pageUrl) {
-            try {
-                const parsed = new URL(pageUrl);
-                url = parsed.origin + parsed.pathname;
-            }
-            catch {
-                url = window.location.origin + window.location.pathname;
+        const total = contents.reduce((sum, item) => {
+            const quantity = Number(item === null || item === void 0 ? void 0 : item.quantity);
+            return sum + (Number.isFinite(quantity) ? quantity : 0);
+        }, 0);
+        return total || undefined;
+    };
+    // Only the parameters UA allows for that conversion; empty values are dropped.
+    const buildParams = (conversion, data, userId, kvEmail) => {
+        var _a, _b, _c;
+        const contents = contentsOf(data);
+        const available = {
+            price: asParam(data['value']),
+            currency: asParam(data['currency']),
+            order_id: asParam(data['orderId']),
+            description: (_a = asParam(data['name'])) !== null && _a !== void 0 ? _a : asParam((_b = contents[0]) === null || _b === void 0 ? void 0 : _b.title),
+            // UA's snippets carry a single content id, so a multi-item cart reports the
+            // first usable one rather than a list UA would not parse.
+            content_id: contents.map((item) => asParam(item === null || item === void 0 ? void 0 : item.id)).find(Boolean),
+            item_quantity: asParam(itemQuantity(contents)),
+            user_id: asParam(userId),
+            // UA labels `user_name` "User Email" in both the dashboard and the GTM
+            // template — it carries the email, not a display name. It goes out in the
+            // clear on purpose: UA's dashboard snippets and their GTM template both pass
+            // the plain address and uap.js normalizes it on their side, so a sha256'd
+            // value (as criteo/spotify need) would simply fail to match. Same shape as
+            // facebook's `em` and tiktok's `email` here.
+            //
+            // The event rarely carries it — email usually arrives through the data API
+            // and lands in session KV — so fall back to the KV value.
+            user_name: (_c = asParam(data['email'])) !== null && _c !== void 0 ? _c : asParam(kvEmail),
+        };
+        const params = {};
+        for (const key of UA_EVENT_PARAMS[conversion]) {
+            const value = available[key];
+            if (value !== undefined) {
+                params[key] = value;
             }
         }
-        else {
-            url = window.location.origin + window.location.pathname;
-        }
+        return params;
+    };
+
+    const tag = ({ eventName, data, userId, manifestVariables, destination, }) => {
         try {
-            const mapping = getUrlMapping(urlMapping, url);
-            if (mapping) {
-                const pixel = document.createElement('img');
-                pixel.src = getUrl(mapping, buzzKey, accountId);
-                pixel.width = 0;
-                pixel.height = 0;
-                pixel.style.position = 'absolute';
-                pixel.style.visibility = 'hidden';
-                pixel.setAttribute('border', '0');
-                const firstScript = document.getElementsByTagName('script')[0];
-                (_a = firstScript.parentNode) === null || _a === void 0 ? void 0 : _a.insertBefore(pixel, firstScript);
+            if (typeof window === 'undefined') {
+                return {};
             }
-            else {
-                logger.log('URL is not mapped for Universal Ads');
+            const conversion = resolveConversion(eventName, manifestVariables === null || manifestVariables === void 0 ? void 0 : manifestVariables['eventMapping']);
+            // UA has no conversion for this event (RemoveFromCart, SessionStart, or an
+            // unmapped custom event) — sending an invented name would record nothing.
+            if (!conversion) {
+                return {};
             }
+            // The email UA wants for `user_name` usually arrives via the data API and is
+            // held in session KV rather than on the event payload.
+            const kv = getData(destination, 'session')['kv'];
+            sendConversion(conversion, buildParams(conversion, data, userId, kv === null || kv === void 0 ? void 0 : kv['email']));
         }
-        catch {
-            logger.log('Not able to parse the URL mapping for Universal Ads');
-        }
-    };
-    const init = ({ manifest, pageUrl }) => {
-        if (typeof window == 'undefined' ||
-            !manifest.variables ||
-            manifest.variables['enableBrowser'] !== '1' ||
-            !manifest.variables['accountId'] ||
-            !manifest.variables['buzzKey'] ||
-            !manifest.variables['urlMapping']) {
-            return;
+        catch (error) {
+            logger.error(error);
         }
-        initUniversalAds(manifest.variables['accountId'], manifest.variables['buzzKey'], manifest.variables['urlMapping'], pageUrl);
+        return {};
     };
 
     // eslint-disable-next-line @nx/enforce-module-boundaries
     const data = {
         name: packageName,
         init,
+        tag,
     };
     try {
         if (window) {