@adobe/alloy 2.32.1-beta.1 → 2.33.0

package/src/components/Advertising/utils/advertisingCookieManager.js

@@ -0,0 +1,92 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import { getNamespacedCookieName, cookieJar } from "@adobe/alloy-core/utils";
+import createLoggingCookieJar from "@adobe/alloy-core/utils/createLoggingCookieJar.js";
+import {
+  ADVERTISING_COOKIE_KEY,
+  DEFAULT_COOKIE_EXPIRATION_MINUTES,
+  DEFAULT_THROTTLE_MINUTES,
+} from "../constants/index.js";
+
+export default ({ orgId, logger }) => {
+  const loggingCookieJar = createLoggingCookieJar({ logger, cookieJar });
+
+  const getCookieName = (key, useNamespace = true) =>
+    useNamespace ? getNamespacedCookieName(orgId, key) : key;
+
+  const getDefaultExpiration = (minutes = DEFAULT_THROTTLE_MINUTES) =>
+    new Date(Date.now() + minutes * 60 * 1000);
+
+  const safeJsonParse = (value) => {
+    try {
+      if (value?.startsWith("%7B") || value?.startsWith("{")) {
+        return JSON.parse(decodeURIComponent(value));
+      }
+    } catch {
+      // pass
+    }
+    return value;
+  };
+
+  const safeJsonStringify = (value) =>
+    typeof value === "object" && value !== null
+      ? encodeURIComponent(JSON.stringify(value))
+      : value;
+
+  const readCookie = (key, useNamespace = true) => {
+    try {
+      const name = getCookieName(key, useNamespace);
+      const value = loggingCookieJar.get(name);
+      return value ? safeJsonParse(value) : null;
+    } catch (error) {
+      logger.error(`Error reading cookie: ${key}`, error);
+      return null;
+    }
+  };
+
+  const writeCookie = (key, value, options = {}, useNamespace = true) => {
+    try {
+      const name = getCookieName(key, useNamespace);
+      const storedValue = safeJsonStringify(value);
+      loggingCookieJar.set(name, storedValue, options);
+      return true;
+    } catch (error) {
+      logger.error(`Error writing cookie: ${key}`, error);
+      return false;
+    }
+  };
+
+  const setValue = (key, value, options = {}) => {
+    const existing = readCookie(ADVERTISING_COOKIE_KEY) || {};
+
+    const updated = {
+      ...existing,
+      [key]: value,
+    };
+
+    return writeCookie(ADVERTISING_COOKIE_KEY, updated, {
+      expires: getDefaultExpiration(DEFAULT_COOKIE_EXPIRATION_MINUTES),
+      ...options,
+    });
+  };
+
+  const getValue = (key) => {
+    const data = readCookie(ADVERTISING_COOKIE_KEY) || {};
+    return data[key];
+  };
+
+  return {
+    setValue,
+    getValue,
+  };
+};

package/src/components/Advertising/utils/helpers.js

@@ -0,0 +1,190 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import {
+  SKWCID_PARAM,
+  EFID_PARAM,
+  UNKNOWN_ADVERTISER,
+  LAST_CLICK_COOKIE_KEY,
+  LOG_ID_CONVERSION_SUCCESS,
+  LAST_CONVERSION_TIME_KEY,
+  DISPLAY_CLICK_COOKIE_KEY,
+  AD_CONVERSION_VIEW_EVENT_TYPE,
+  SURFER_ID,
+  HASHED_IP,
+  ID5_ID,
+  RAMP_ID,
+  DISPLAY_CLICK_COOKIE_KEY_EXPIRES,
+} from "../constants/index.js";
+
+import { queryString } from "@adobe/alloy-core/utils";
+
+const getUrlParams = () => {
+  const parsedParams = queryString.parse(window.location.search);
+  return {
+    skwcid: parsedParams[SKWCID_PARAM], // "s_kwcid"
+    efid: parsedParams[EFID_PARAM], // "ef_id"
+  };
+};
+
+/**
+ * Manages a single, ongoing asynchronous operation to prevent redundant calls.
+ * @param {string} operationName - A name for the operation for logging purposes.
+ * @param {Function} workerFn - A function that returns a Promise to be executed.
+ * @returns {Function} A function that, when called, will either start the worker or return the in-progress promise.
+ */
+const createManagedAsyncOperation = (operationName, workerFn) => {
+  let inProgressPromise = null;
+
+  return (...args) => {
+    if (inProgressPromise) {
+      return inProgressPromise;
+    }
+    inProgressPromise = workerFn(...args).finally(() => {
+      inProgressPromise = null;
+    });
+
+    return inProgressPromise;
+  };
+};
+
+/**
+ * Normalizes advertiser settings - extracts enabled advertiser IDs
+ * @param {Object[]} advertiserSettings - Array of advertiserSettings objects with advertiserId and enabled properties
+ * @returns {string} Comma-separated string of enabled advertiser IDs
+ */
+const normalizeAdvertiser = (advertiserSettings) => {
+  if (!advertiserSettings || !Array.isArray(advertiserSettings)) {
+    return UNKNOWN_ADVERTISER;
+  }
+
+  return advertiserSettings
+    .filter((item) => item && item.enabled === true && item.advertiserId)
+    .map((item) => item.advertiserId)
+    .join(", ");
+};
+
+/**
+ * Appends AdCloud identity data to the event XDM as _experience.adcloud.stitchId.
+ * @param {{ surferId?: string, hashedIp?: string, id5Id?: string, rampId?: string, adfId?: string }} idsToInclude
+ * @param {{ mergeXdm: (xdm: Object) => void }} event
+ */
+const appendAdCloudIdentityToEvent = (idsToInclude, event) => {
+  const ID_SEPARATOR = "|";
+  // Order is a downstream AdCloud contract — consumers parse this string positionally.
+  // Do not reorder. adfId is a forward-looking placeholder for a future ID type; always serializes as an empty slot for now.
+  const ADCLOUD_ID_ORDER = [SURFER_ID, HASHED_IP, ID5_ID, RAMP_ID, "adfId"];
+  const concatenatedId = ADCLOUD_ID_ORDER.map(
+    (key) => idsToInclude[key] ?? "",
+  ).join(ID_SEPARATOR);
+
+  event.mergeXdm({
+    _experience: {
+      adcloud: {
+        stitchId: concatenatedId,
+      },
+    },
+  });
+};
+
+const appendAdvertisingIdQueryToEvent = (
+  idsToInclude,
+  event,
+  cookieManager,
+  componentConfig,
+  addEventType = false,
+) => {
+  const searchClickData = cookieManager.getValue(LAST_CLICK_COOKIE_KEY);
+  let displayClickCookie = null;
+  const displayClickCookieExpires = cookieManager.getValue(
+    DISPLAY_CLICK_COOKIE_KEY_EXPIRES,
+  );
+  if (displayClickCookieExpires && displayClickCookieExpires > Date.now()) {
+    displayClickCookie = cookieManager.getValue(DISPLAY_CLICK_COOKIE_KEY);
+  }
+  const query = {
+    advertising: {
+      ...(searchClickData?.click_time && {
+        lastSearchClick: searchClickData.click_time,
+      }),
+      ...(displayClickCookie && {
+        lastDisplayClick: displayClickCookie,
+      }),
+      stitchIds: {
+        ...(idsToInclude[SURFER_ID] && {
+          surferId: idsToInclude[SURFER_ID],
+        }),
+        ...(idsToInclude[ID5_ID] && { id5: idsToInclude[ID5_ID] }),
+        ...(idsToInclude[RAMP_ID] && { rampIdEnv: idsToInclude[RAMP_ID] }),
+        ...(idsToInclude[HASHED_IP] && {
+          hashedIp: idsToInclude[HASHED_IP],
+        }),
+      },
+      advIds: normalizeAdvertiser(componentConfig.advertiserSettings),
+      ...(addEventType && { eventType: AD_CONVERSION_VIEW_EVENT_TYPE }),
+    },
+  };
+
+  event.mergeQuery(query);
+  return event;
+};
+
+const isAnyIdUnused = (availableIds, conversionCalled) => {
+  return Object.entries(availableIds).some(([idType]) => {
+    return !conversionCalled[idType];
+  });
+};
+
+const markIdsAsConverted = (
+  idTypes,
+  conversionCalled,
+  cookieManager,
+  logger,
+) => {
+  const now = Date.now();
+
+  idTypes.forEach((idType) => {
+    conversionCalled[idType] = true;
+    cookieManager.setValue(`${idType}_last_conversion`, now);
+    logger.info(LOG_ID_CONVERSION_SUCCESS.replace("{0}", idType));
+  });
+
+  cookieManager.setValue(LAST_CONVERSION_TIME_KEY, now);
+};
+
+const isThrottled = (idType, cookieManager) => {
+  const now = Date.now();
+  const THROTTLE_WINDOW = 30 * 60 * 1000; // 30 minutes
+  const lastSuccessfulConversion = cookieManager.getValue(
+    `${idType}_last_conversion`,
+  );
+  return Boolean(
+    lastSuccessfulConversion &&
+    now - lastSuccessfulConversion < THROTTLE_WINDOW,
+  );
+};
+
+const shouldThrottle = (idType, cookieManager) => {
+  return isThrottled(idType, cookieManager);
+};
+
+export {
+  getUrlParams,
+  normalizeAdvertiser,
+  createManagedAsyncOperation,
+  appendAdvertisingIdQueryToEvent,
+  appendAdCloudIdentityToEvent,
+  isAnyIdUnused,
+  markIdsAsConverted,
+  isThrottled,
+  shouldThrottle,
+};

package/src/components/Advertising/utils/murmurHash128GuavaHex.js

@@ -0,0 +1,195 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/* eslint-disable no-bitwise */
+
+/**
+ * MurmurHash3 128-bit (x64) — matches Guava
+ * `com.google.common.hash.Hashing.murmur3_128(seed).hashString(str, UTF_8).toString()`.
+ *
+ * Implementation follows Guava’s `Murmur3_128HashFunction` (same as smhasher
+ * `MurmurHash3_x64_128` with Guava’s seeding and byte order for `HashCode.toString()`).
+ *
+ * @see https://github.com/google/guava/blob/master/guava/src/com/google/common/hash/Murmur3_128HashFunction.java
+ *
+ * Returns **32** lowercase hex characters (128 bits).
+ */
+
+const U64 = 0xffffffffffffffffn;
+
+const rotl64 = (x, r) => ((x << BigInt(r)) | (x >> BigInt(64 - r))) & U64;
+
+const u8 = (b) => BigInt(b & 0xff);
+
+const readInt64LE = (bytes, offset) => {
+  let v = 0n;
+  for (let i = 0; i < 8; i += 1) {
+    v |= u8(bytes[offset + i]) << (8n * BigInt(i));
+  }
+  return v & U64;
+};
+
+const C1 = 0x87c37b91114253d5n;
+const C2 = 0x4cf5ad432745937fn;
+
+const mixK1 = (k1) => {
+  let k = k1 & U64;
+  k = (k * C1) & U64;
+  k = rotl64(k, 31);
+  k = (k * C2) & U64;
+  return k;
+};
+
+const mixK2 = (k2) => {
+  let k = k2 & U64;
+  k = (k * C2) & U64;
+  k = rotl64(k, 33);
+  k = (k * C1) & U64;
+  return k;
+};
+
+const fmix64 = (k) => {
+  let x = k & U64;
+  x ^= x >> 33n;
+  x = (x * 0xff51afd7ed558ccdn) & U64;
+  x ^= x >> 33n;
+  x = (x * 0xc4ceb9fe1a85ec53n) & U64;
+  x ^= x >> 33n;
+  return x & U64;
+};
+
+/** Java `int` seed sign-extended to 64-bit (Guava `Murmur3_128Hasher` initial state). */
+const intSeedToLong64 = (seed) =>
+  BigInt.asIntN(64, BigInt.asIntN(32, BigInt(Math.trunc(Number(seed)))));
+
+/**
+ * 128-bit MurmurHash3 (Guava-compatible), lowercase hex, no `0x` prefix.
+ * @param {string} str - hashed as UTF-8 bytes
+ * @param {number} [seed=0] - 32-bit seed (Guava `murmur3_128(int seed)`)
+ * @returns {string} 32 hex characters
+ */
+export const murmurHash128GuavaHex = (str, seed = 0) => {
+  // Match Java long bit pattern for (long) int seed (e.g. -1 → 0xff…ff)
+  const hSeed = intSeedToLong64(seed) & U64;
+  let h1 = hSeed;
+  let h2 = hSeed;
+  let length = 0;
+
+  const bytes = new TextEncoder().encode(str);
+
+  const bmix64 = (k1, k2) => {
+    h1 ^= mixK1(k1);
+    h1 = rotl64(h1, 27);
+    h1 = (h1 + h2) & U64;
+    h1 = (h1 * 5n + 0x52dce729n) & U64;
+
+    h2 ^= mixK2(k2);
+    h2 = rotl64(h2, 31);
+    h2 = (h2 + h1) & U64;
+    h2 = (h2 * 5n + 0x38495ab5n) & U64;
+  };
+
+  let offset = 0;
+  const nblocks = Math.floor(bytes.length / 16);
+  for (let i = 0; i < nblocks; i += 1) {
+    bmix64(readInt64LE(bytes, offset), readInt64LE(bytes, offset + 8));
+    offset += 16;
+    length += 16;
+  }
+
+  const rem = bytes.length - offset;
+  length += rem;
+  let k1 = 0n;
+  let k2 = 0n;
+  const t = offset;
+
+  switch (rem) {
+    case 15:
+      k2 ^= u8(bytes[t + 14]) << 48n;
+    // falls through
+    case 14:
+      k2 ^= u8(bytes[t + 13]) << 40n;
+    // falls through
+    case 13:
+      k2 ^= u8(bytes[t + 12]) << 32n;
+    // falls through
+    case 12:
+      k2 ^= u8(bytes[t + 11]) << 24n;
+    // falls through
+    case 11:
+      k2 ^= u8(bytes[t + 10]) << 16n;
+    // falls through
+    case 10:
+      k2 ^= u8(bytes[t + 9]) << 8n;
+    // falls through
+    case 9:
+      k2 ^= u8(bytes[t + 8]);
+    // falls through
+    case 8:
+      k1 ^= readInt64LE(bytes, t);
+      break;
+    case 7:
+      k1 ^= u8(bytes[t + 6]) << 48n;
+    // falls through
+    case 6:
+      k1 ^= u8(bytes[t + 5]) << 40n;
+    // falls through
+    case 5:
+      k1 ^= u8(bytes[t + 4]) << 32n;
+    // falls through
+    case 4:
+      k1 ^= u8(bytes[t + 3]) << 24n;
+    // falls through
+    case 3:
+      k1 ^= u8(bytes[t + 2]) << 16n;
+    // falls through
+    case 2:
+      k1 ^= u8(bytes[t + 1]) << 8n;
+    // falls through
+    case 1:
+      k1 ^= u8(bytes[t]);
+      break;
+    default:
+      break;
+  }
+
+  h1 ^= mixK1(k1);
+  h2 ^= mixK2(k2);
+
+  const len64 = BigInt(length >>> 0);
+  h1 ^= len64;
+  h2 ^= len64;
+
+  h1 = (h1 + h2) & U64;
+  h2 = (h2 + h1) & U64;
+
+  h1 = fmix64(h1);
+  h2 = fmix64(h2);
+
+  h1 = (h1 + h2) & U64;
+  h2 = (h2 + h1) & U64;
+
+  const out = new Uint8Array(16);
+  const writeLongLE = (val, pos) => {
+    let v = val & U64;
+    for (let i = 0; i < 8; i += 1) {
+      out[pos + i] = Number(v & 0xffn);
+      v >>= 8n;
+    }
+  };
+  writeLongLE(h1, 0);
+  writeLongLE(h2, 8);
+
+  return [...out].map((b) => b.toString(16).padStart(2, "0")).join("");
+};
+
+export default murmurHash128GuavaHex;

package/src/components/Context/createComponent.js

@@ -0,0 +1,35 @@
+/*
+Copyright 2019 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+export default (config, logger, optionalContexts, requiredContexts) => {
+  const configuredContexts = config.context;
+
+  const contexts = configuredContexts
+    .flatMap((context, i) => {
+      if (optionalContexts[context]) {
+        return [optionalContexts[context]];
+      }
+      logger.warn(`Invalid context[${i}]: '${context}' is not available.`);
+      return [];
+    })
+    .concat(requiredContexts);
+
+  return {
+    namespace: "Context",
+    lifecycle: {
+      onBeforeEvent({ event }) {
+        return Promise.all(
+          contexts.map((context) => Promise.resolve(context(event, logger))),
+        );
+      },
+    },
+  };
+};

package/src/components/Context/implementationDetails.js

@@ -0,0 +1,23 @@
+/*
+Copyright 2019 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+import libraryName from "@adobe/alloy-core/constants/libraryName.js";
+import libraryVersion from "@adobe/alloy-core/constants/libraryVersion.js";
+
+export default (event) => {
+  event.mergeXdm({
+    implementationDetails: {
+      name: libraryName,
+      version: libraryVersion,
+      environment: "browser",
+    },
+  });
+};

package/src/components/Context/index.js

@@ -0,0 +1,56 @@
+/*
+Copyright 2019 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import injectWeb from "./injectWeb.js";
+import injectDevice from "./injectDevice.js";
+import injectEnvironment from "./injectEnvironment.js";
+import injectPlaceContext from "./injectPlaceContext.js";
+import injectTimestamp from "@adobe/alloy-core/utils/injectTimestamp.js";
+import implementationDetails from "./implementationDetails.js";
+import createComponent from "./createComponent.js";
+import injectHighEntropyUserAgentHints from "./injectHighEntropyUserAgentHints.js";
+import injectOneTimeAnalyticsReferrer from "./injectOneTimeAnalyticsReferrer.js";
+import { arrayOf, objectOf, string } from "@adobe/alloy-core/utils/validation";
+
+const web = injectWeb(window);
+const device = injectDevice(window);
+const environment = injectEnvironment(window);
+const placeContext = injectPlaceContext(() => new Date());
+const timestamp = injectTimestamp(() => new Date());
+const highEntropyUserAgentHints = injectHighEntropyUserAgentHints(navigator);
+const oneTimeAnalyticsReferrer = injectOneTimeAnalyticsReferrer(window);
+
+const defaultEnabledContexts = {
+  web,
+  device,
+  environment,
+  placeContext,
+};
+const defaultDisabledContexts = {
+  highEntropyUserAgentHints,
+  oneTimeAnalyticsReferrer,
+};
+const optionalContexts = {
+  ...defaultEnabledContexts,
+  ...defaultDisabledContexts,
+};
+const requiredContexts = [timestamp, implementationDetails];
+
+const createContext = ({ config, logger }) => {
+  return createComponent(config, logger, optionalContexts, requiredContexts);
+};
+createContext.namespace = "Context";
+createContext.configValidators = objectOf({
+  context: arrayOf(string()).default(Object.keys(defaultEnabledContexts)),
+});
+
+export default createContext;

package/src/components/Context/injectDevice.js

@@ -0,0 +1,77 @@
+/*
+Copyright 2019 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import { isFunction, toInteger } from "@adobe/alloy-core/utils";
+
+const getScreenOrientationViaProperty = (window) => {
+  const {
+    screen: { orientation },
+  } = window;
+
+  if (orientation == null || orientation.type == null) {
+    return null;
+  }
+
+  const parts = orientation.type.split("-");
+
+  if (parts.length === 0) {
+    return null;
+  }
+
+  if (parts[0] !== "portrait" && parts[0] !== "landscape") {
+    return null;
+  }
+
+  return parts[0];
+};
+
+const getScreenOrientationViaMediaQuery = (window) => {
+  if (isFunction(window.matchMedia)) {
+    if (window.matchMedia("(orientation: portrait)").matches) {
+      return "portrait";
+    }
+    if (window.matchMedia("(orientation: landscape)").matches) {
+      return "landscape";
+    }
+  }
+
+  return null;
+};
+
+export default (window) => {
+  return (event) => {
+    const {
+      screen: { width, height },
+    } = window;
+    const device = {};
+
+    const screenHeight = toInteger(height);
+    if (screenHeight >= 0) {
+      device.screenHeight = screenHeight;
+    }
+
+    const screenWidth = toInteger(width);
+    if (screenWidth >= 0) {
+      device.screenWidth = screenWidth;
+    }
+
+    const orientation =
+      getScreenOrientationViaProperty(window) ||
+      getScreenOrientationViaMediaQuery(window);
+    if (orientation) {
+      device.screenOrientation = orientation;
+    }
+    if (Object.keys(device).length > 0) {
+      event.mergeXdm({ device });
+    }
+  };
+};