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

package/index.mjs

@@ -1,4 +1,157 @@
+/**
+ * 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 {
@@ -32,6 +185,176 @@ const logger = {
     },
 };
 
+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`
@@ -458,26 +781,6 @@ new Set([
     ...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).
  *
@@ -599,94 +902,105 @@ new Set([
     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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blotoutio/providers-universal-ads-sdk",
-  "version": "1.66.1",
+  "version": "1.66.2",
   "description": "Universal Ads Browser SDK for EdgeTag",
   "author": "Blotout",
   "license": "MIT",