@adobe/alloy 2.32.1-beta.0 → 2.33.0-beta.2

package/src/components/Advertising/identities/collectRampId.js

@@ -0,0 +1,265 @@
+/*
+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 { loadScript } from "@adobe/alloy-core/utils/dom";
+import { RAMP_ID, RAMP_ID_EXPIRES } from "../constants/index.js";
+
+const RETRY_CONFIG = {
+  MAX_COUNT: 15,
+  MAX_TIME_MS: 30000,
+  DELAY_BASE_MS: 500,
+  MAX_DELAY_MS: 5000,
+  SHORT_TIMEOUT_MS: 2000,
+};
+
+const state = {
+  rampIdEnv: undefined,
+  rampIdCallInitiated: false,
+  inProgressRampIdPromise: null,
+  scriptLoadingInitiated: false,
+  envelopeRetrievalInProgress: false,
+};
+
+const processEnvelope = (envelope, resolve, cookieManager, logger) => {
+  let parsedEnvelope;
+  try {
+    parsedEnvelope = JSON.parse(envelope).envelope;
+  } catch {
+    parsedEnvelope = envelope;
+  }
+
+  if (parsedEnvelope && !state.rampIdCallInitiated) {
+    state.rampIdCallInitiated = true;
+    state.rampIdEnv = parsedEnvelope;
+    state.envelopeRetrievalInProgress = false;
+    state.inProgressRampIdPromise = null;
+    cookieManager.setValue(RAMP_ID, state.rampIdEnv);
+    cookieManager.setValue(RAMP_ID_EXPIRES, Date.now() + 48 * 60 * 60 * 1000); //expires in 48 hours
+    resolve(state.rampIdEnv);
+  } else {
+    logger.warn("Invalid RampID envelope received", {
+      envelope: parsedEnvelope,
+    });
+    state.envelopeRetrievalInProgress = false;
+  }
+};
+
+const retrieveEnvelopeWithRetries = (
+  resolve,
+  reject,
+  cookieManager,
+  logger,
+) => {
+  let retryCount = RETRY_CONFIG.MAX_COUNT;
+  let timerMultiplier = 1;
+  let totalElapsedTime = 0;
+
+  const tryToRetrieve = () => {
+    if (state.rampIdEnv) return;
+
+    if (totalElapsedTime > RETRY_CONFIG.MAX_TIME_MS) {
+      logger.error("Maximum retry time exceeded");
+      state.envelopeRetrievalInProgress = false;
+      reject(new Error("Failed to retrieve RampID - timeout"));
+      state.inProgressRampIdPromise = null;
+      return;
+    }
+
+    if (retryCount === 0) {
+      logger.error("Maximum retries exceeded");
+      state.envelopeRetrievalInProgress = false;
+      reject(new Error("Failed to retrieve RampID after maximum retries"));
+      state.inProgressRampIdPromise = null;
+      return;
+    }
+
+    const delay = Math.min(
+      RETRY_CONFIG.DELAY_BASE_MS * timerMultiplier,
+      RETRY_CONFIG.MAX_DELAY_MS,
+    );
+
+    setTimeout(() => {
+      totalElapsedTime += delay;
+      retryCount -= 1;
+      timerMultiplier += 1;
+
+      if (
+        typeof window.ats !== "undefined" &&
+        window.ats !== null &&
+        !state.rampIdEnv &&
+        !state.envelopeRetrievalInProgress
+      ) {
+        state.envelopeRetrievalInProgress = true;
+        window.ats.retrieveEnvelope().then(
+          (rampIdResponse) => {
+            processEnvelope(rampIdResponse, resolve, cookieManager, logger);
+            if (!state.rampIdEnv) tryToRetrieve();
+          },
+          () => {
+            logger.warn("Failed to retrieve envelope");
+            state.envelopeRetrievalInProgress = false;
+            tryToRetrieve();
+          },
+        );
+      } else {
+        tryToRetrieve();
+      }
+    }, delay);
+  };
+
+  tryToRetrieve();
+};
+
+const initiateRampIDCall = (
+  rampIdScriptPath,
+  cookieManager,
+  logger,
+  useShortTimeout = false,
+) => {
+  if (state.inProgressRampIdPromise) {
+    return state.inProgressRampIdPromise;
+  }
+
+  const timeoutMs = useShortTimeout
+    ? RETRY_CONFIG.SHORT_TIMEOUT_MS
+    : RETRY_CONFIG.MAX_TIME_MS;
+
+  let timedOut = false;
+
+  const mainPromise = new Promise((resolve, reject) => {
+    loadScript(rampIdScriptPath, {
+      onLoad: () => {
+        if (
+          typeof window.ats !== "undefined" &&
+          !state.envelopeRetrievalInProgress
+        ) {
+          state.envelopeRetrievalInProgress = true;
+          window.ats
+            .retrieveEnvelope()
+            .then((envelopeResponse) => {
+              if (envelopeResponse) {
+                if (!timedOut) {
+                  processEnvelope(
+                    envelopeResponse,
+                    resolve,
+                    cookieManager,
+                    logger,
+                  );
+                }
+              } else {
+                state.envelopeRetrievalInProgress = false;
+                window.addEventListener("lrEnvelopePresent", () => {
+                  if (state.envelopeRetrievalInProgress || timedOut) return;
+                  state.envelopeRetrievalInProgress = true;
+                  window.ats.retrieveEnvelope().then(
+                    (envelopeResult) => {
+                      if (!timedOut) {
+                        processEnvelope(
+                          envelopeResult,
+                          resolve,
+                          cookieManager,
+                          logger,
+                        );
+                      }
+                    },
+                    (error) => {
+                      if (!timedOut) {
+                        logger.error(
+                          "Failed to retrieve envelope after event",
+                          error,
+                        );
+                        state.envelopeRetrievalInProgress = false;
+                        reject(error);
+                        state.inProgressRampIdPromise = null;
+                      }
+                    },
+                  );
+                });
+              }
+            })
+            .catch((error) => {
+              if (!timedOut) {
+                logger.error("Error retrieving envelope", error);
+                state.envelopeRetrievalInProgress = false;
+                reject(error);
+                state.inProgressRampIdPromise = null;
+              }
+            });
+        }
+
+        retrieveEnvelopeWithRetries(
+          (val) => {
+            if (!timedOut) resolve(val);
+          },
+          (err) => {
+            if (!timedOut) reject(err);
+          },
+          cookieManager,
+          logger,
+        );
+      },
+      onError: (error) => {
+        if (!timedOut) {
+          reject(error);
+        }
+        state.inProgressRampIdPromise = null;
+      },
+    });
+  });
+
+  const timeoutPromise = new Promise((resolve) => {
+    setTimeout(() => {
+      timedOut = true;
+      resolve(null);
+    }, timeoutMs);
+  });
+
+  state.inProgressRampIdPromise = Promise.race([
+    mainPromise,
+    timeoutPromise,
+  ]).finally(() => {
+    state.inProgressRampIdPromise = null;
+  });
+
+  return state.inProgressRampIdPromise;
+};
+
+const getRampId = (
+  logger,
+  rampIdScriptPath,
+  cookieManager,
+  resolveRampIdIfNotAvailable = true,
+  useShortTimeout = false,
+) => {
+  if (state.rampIdEnv) {
+    return Promise.resolve(state.rampIdEnv);
+  }
+  if (cookieManager) {
+    const rampIdFromCookie = cookieManager.getValue(RAMP_ID);
+    const rampIdExpires = cookieManager.getValue(RAMP_ID_EXPIRES);
+    if (rampIdFromCookie && rampIdExpires && rampIdExpires > Date.now()) {
+      state.rampIdEnv = rampIdFromCookie;
+      return Promise.resolve(rampIdFromCookie);
+    }
+  }
+  if (!resolveRampIdIfNotAvailable || rampIdScriptPath == null) {
+    return Promise.resolve(null);
+  }
+  return initiateRampIDCall(
+    rampIdScriptPath,
+    cookieManager,
+    logger,
+    useShortTimeout,
+  );
+};
+
+export { getRampId, initiateRampIDCall };

package/src/components/Advertising/identities/collectSurferId.js

@@ -0,0 +1,72 @@
+/*
+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 {
+  DISPLAY_CLICK_COOKIE_KEY,
+  SURFER_ID,
+  DISPLAY_CLICK_COOKIE_KEY_EXPIRES,
+} from "../constants/index.js";
+import { injectAreThirdPartyCookiesSupportedByDefault } from "@adobe/alloy-core/utils";
+
+/**
+ * Factory for surferId collection. Cache lives at closure scope — no module-level state.
+ *
+ * @param {Object} deps
+ * @param {Function} deps.initiateAdvertisingIdentityCall
+ * @param {Object} deps.cookieManager
+ * @param {Function} deps.getBrowser
+ * @returns {Function} collectSurferId(useShortTimeout?)
+ */
+const createCollectSurferId = ({
+  initiateAdvertisingIdentityCall,
+  cookieManager,
+  getBrowser,
+}) => {
+  let cachedSurferId = cookieManager.getValue(SURFER_ID) || "";
+
+  return (resolveSurferIdIfNotAvailable = true) => {
+    if (cachedSurferId) {
+      return Promise.resolve(cachedSurferId);
+    }
+
+    if (!resolveSurferIdIfNotAvailable) {
+      return Promise.resolve(null);
+    }
+
+    return initiateAdvertisingIdentityCall().then((resolvedId) => {
+      const areThirdPartyCookiesSupported =
+        !getBrowser ||
+        injectAreThirdPartyCookiesSupportedByDefault({ getBrowser })();
+
+      if (resolvedId && areThirdPartyCookiesSupported) {
+        if (resolvedId.surferId) {
+          cachedSurferId = resolvedId.surferId;
+          cookieManager.setValue(SURFER_ID, resolvedId.surferId);
+        }
+        if (resolvedId.displayClickCookie) {
+          cookieManager.setValue(
+            DISPLAY_CLICK_COOKIE_KEY,
+            resolvedId.displayClickCookie,
+          );
+          cookieManager.setValue(
+            DISPLAY_CLICK_COOKIE_KEY_EXPIRES,
+            Date.now() + 15 * 60 * 1000,
+          );
+        }
+      }
+
+      return areThirdPartyCookiesSupported ? resolvedId.surferId : null;
+    });
+  };
+};
+
+export default createCollectSurferId;

package/src/components/Advertising/identities/createHashedIpHandler.js

@@ -0,0 +1,36 @@
+/*
+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 murmurHash128GuavaHex from "../utils/murmurHash128GuavaHex.js";
+import { HASHED_IP_ADDR } from "../constants/index.js";
+
+export default ({ cookieManager, hash = murmurHash128GuavaHex }) => {
+  let cached = cookieManager.getValue(HASHED_IP_ADDR) || "";
+
+  const captureFromIframe = (clientIp) => {
+    if (!clientIp) return;
+    cached = hash(clientIp);
+    cookieManager.setValue(HASHED_IP_ADDR, cached);
+  };
+
+  return {
+    captureFromIframe,
+    get: () => cached,
+    collect: (initiateCallFn) => {
+      if (cached) return Promise.resolve(cached);
+      return initiateCallFn().then((result) => {
+        captureFromIframe(result.clientIp);
+        return cached;
+      });
+    },
+  };
+};

package/src/components/Advertising/identities/initiateAdvertisingIdentityCall.js

@@ -0,0 +1,153 @@
+/*
+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 {
+  DISPLAY_CLICK_COOKIE_KEY,
+  SURFER_PIXEL_HOST,
+  SURFER_USER_ID,
+  SURFER_TIMEOUT_MS,
+  SURFER_TRUSTED_ORIGIN,
+  SURFER_PARAM_KEY,
+  SURFER_IP,
+} from "../constants/index.js";
+import {
+  appendNode,
+  awaitSelector,
+  createNode,
+} from "@adobe/alloy-core/utils/dom/index.js";
+import { BODY } from "@adobe/alloy-core/constants/tagName.js";
+
+const IFRAME_PROPS = {
+  height: 0,
+  width: 0,
+  frameBorder: 0,
+  style: { display: "none" },
+};
+
+/**
+ * Creates a shared advertising identity caller. Both the SurferID and hashed-IP
+ * flows call this so the pixel iframe is only loaded once per page per request.
+ *
+ * @param {Object} [deps]
+ * @param {Function} [deps.appendNode]
+ * @param {Function} [deps.awaitSelector]
+ * @param {Function} [deps.createNode]
+ * @returns {Function} initiateAdvertisingIdentityCall
+ */
+export const createInitiateAdvertisingIdentityCall = ({
+  appendNode: appendNodeFn = appendNode,
+  awaitSelector: awaitSelectorFn = awaitSelector,
+  createNode: createNodeFn = createNode,
+} = {}) => {
+  let inProgressPromise = null;
+
+  /**
+   * Initiates the advertising identity iframe request. Shared by SurferID
+   * and hashed-IP flows so the pixel is only loaded once per page.
+   * `clientIp` is the raw IP — hashing is the caller's responsibility
+   * (see createHashedIpHandler).
+   * @returns {Promise<{ surferId: string|null, displayClickCookie: string|null, clientIp: string }>}
+   */
+  return () => {
+    if (inProgressPromise) {
+      return inProgressPromise;
+    }
+
+    inProgressPromise = new Promise((resolve, reject) => {
+      const scheme =
+        document.location.protocol === "https:" ? "https:" : "http:";
+
+      const nestedParams = new URLSearchParams({
+        google: "__EFGCK__",
+        gsurfer: "__EFGSURFER__",
+        imsId: "__EFIMSORGID__",
+        is_fb_cookie_synced: "__EFFB__",
+        optout: "__EFOPTOUT__",
+        throttleCookie: "__EFSYNC__",
+        time: "__EFTIME__",
+        ev_lcc: "__LCC__",
+        clientIp: "__EFREMOTEADDR__",
+      });
+      const nestedUrl = `${scheme}//www.everestjs.net/static/pixel_details.html#${nestedParams.toString()}`;
+
+      const mainParams = new URLSearchParams({
+        ev_gb: "0",
+        url: nestedUrl,
+      });
+      const pixelDetailsUrl = `${scheme}//${SURFER_PIXEL_HOST}/${SURFER_USER_ID}/gr?${mainParams.toString()}`;
+
+      const iframeElement = createNodeFn(
+        "iframe",
+        { src: pixelDetailsUrl },
+        IFRAME_PROPS,
+        [],
+      );
+
+      let timeoutId;
+
+      // Single cleanup — called on every exit path (success, no-hash, error, timeout)
+      // so the listener and timer never leak.
+      const pixelDetailsReceiver = (message) => {
+        if (!message.origin.includes(SURFER_TRUSTED_ORIGIN)) {
+          return;
+        }
+
+        clearTimeout(timeoutId);
+        window.removeEventListener("message", pixelDetailsReceiver, false);
+
+        try {
+          const pixelRedirectUri = message.data;
+          const hashIndex = pixelRedirectUri.indexOf("#");
+
+          if (hashIndex === -1) {
+            resolve({ surferId: null, displayClickCookie: null, clientIp: "" });
+            return;
+          }
+
+          const hashParams = new URLSearchParams(
+            pixelRedirectUri.substring(hashIndex + 1),
+          );
+
+          const surferValue = hashParams.get(SURFER_PARAM_KEY) || null;
+          const clientIp = hashParams.get(SURFER_IP) || "";
+          const displayClickValue = hashParams.get(DISPLAY_CLICK_COOKIE_KEY);
+          const displayClickCookie =
+            displayClickValue && displayClickValue !== "__LCC__"
+              ? displayClickValue
+              : null;
+
+          resolve({ surferId: surferValue, displayClickCookie, clientIp });
+        } catch (err) {
+          reject(err);
+        }
+      };
+
+      // Reject if the iframe never responds (ad blocker, CSP, network failure, etc.)
+      timeoutId = setTimeout(() => {
+        window.removeEventListener("message", pixelDetailsReceiver, false);
+        reject(new Error("Advertising identity call timed out"));
+      }, SURFER_TIMEOUT_MS);
+
+      window.addEventListener("message", pixelDetailsReceiver, false);
+
+      // Use awaitSelector(BODY) — consistent with injectFireReferrerHideableImage.js
+      // and more robust than document.body check + load event fallback.
+      awaitSelectorFn(BODY).then(([body]) => {
+        appendNodeFn(body, iframeElement);
+      });
+    }).finally(() => {
+      inProgressPromise = null;
+    });
+
+    return inProgressPromise;
+  };
+};

package/src/components/Advertising/index.js

@@ -0,0 +1,109 @@
+/*
+Copyright 2023 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 createComponent from "./createComponent.js";
+import configValidators from "./configValidators.js";
+import {
+  createDataCollectionRequest,
+  createDataCollectionRequestPayload,
+} from "@adobe/alloy-core/utils/request";
+import createAdConversionHandler from "./handlers/createAdConversionHandler.js";
+import createCookieManager from "./utils/advertisingCookieManager.js";
+import createHandleOnBeforeSendEvent from "./handlers/createOnBeforeSendEventHandler.js";
+import createSendAdConversion from "./handlers/sendAdConversion.js";
+import createCollectSurferId from "./identities/collectSurferId.js";
+import { getID5Id } from "./identities/collectID5Id.js";
+import { getRampId } from "./identities/collectRampId.js";
+import { createInitiateAdvertisingIdentityCall } from "./identities/initiateAdvertisingIdentityCall.js";
+import createHashedIpHandler from "./identities/createHashedIpHandler.js";
+import {
+  appendAdvertisingIdQueryToEvent,
+  appendAdCloudIdentityToEvent,
+  getUrlParams,
+  isThrottled,
+  normalizeAdvertiser,
+} from "./utils/helpers.js";
+
+const createAdvertising = ({
+  logger,
+  config,
+  eventManager,
+  sendEdgeNetworkRequest,
+  consent,
+  getBrowser,
+}) => {
+  const componentConfig = config.advertising;
+  const cookieManager = createCookieManager({
+    orgId: config.orgId,
+    logger,
+  });
+
+  // One shared iframe call — both collectSurferId and hashedIpHandler use it
+  // so the pixel is only loaded once per page.
+  const initiateAdvertisingIdentityCall =
+    createInitiateAdvertisingIdentityCall();
+
+  const collectSurferId = createCollectSurferId({
+    initiateAdvertisingIdentityCall,
+    cookieManager,
+    getBrowser,
+  });
+
+  const hashedIpHandler = createHashedIpHandler({ cookieManager });
+
+  const adConversionHandler = createAdConversionHandler({
+    eventManager,
+    sendEdgeNetworkRequest,
+    consent,
+    createDataCollectionRequest,
+    createDataCollectionRequestPayload,
+    logger,
+  });
+  const handleOnBeforeSendEvent = createHandleOnBeforeSendEvent({
+    cookieManager,
+    logger,
+    getBrowser,
+    consent,
+    componentConfig,
+    collectSurferId,
+    getID5Id,
+    getRampId,
+    appendAdvertisingIdQueryToEvent,
+    appendAdCloudIdentityToEvent,
+    collectHashedIPAddr: () =>
+      hashedIpHandler.collect(initiateAdvertisingIdentityCall),
+    getUrlParams,
+    isThrottled,
+    normalizeAdvertiser,
+  });
+  const sendAdConversionHandler = createSendAdConversion({
+    eventManager,
+    cookieManager,
+    adConversionHandler,
+    logger,
+    componentConfig,
+    getBrowser,
+    consent,
+    collectSurferId,
+    collectHashedIPAddr: () =>
+      hashedIpHandler.collect(initiateAdvertisingIdentityCall),
+  });
+  return createComponent({
+    handleOnBeforeSendEvent,
+    sendAdConversionHandler,
+  });
+};
+
+createAdvertising.namespace = "Advertising";
+createAdvertising.configValidators = configValidators;
+
+export default createAdvertising;