@adobe/alloy 2.32.1-beta.1 → 2.33.0

package/src/components/Advertising/handlers/createOnBeforeSendEventHandler.js

@@ -0,0 +1,177 @@
+/*
+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 { SURFER_ID, HASHED_IP, ID5_ID, RAMP_ID } from "../constants/index.js";
+import { AUTO, WAIT } from "@adobe/alloy-core/constants/consentStatus.js";
+import { CHROME } from "@adobe/alloy-core/constants/browser.js";
+
+const isAdvertisingDisabled = (advertising) => {
+  return ![AUTO, WAIT].includes(
+    advertising?.handleAdvertisingData?.toLowerCase(),
+  );
+};
+
+const waitForAdvertisingId = (advertising) => {
+  return advertising?.handleAdvertisingData?.toLowerCase() === WAIT;
+};
+
+/**
+ * Creates an onBeforeSendEvent handler that appends advertising IDs to events.
+ *
+ * @param {Object} dependencies
+ * @param {Object} dependencies.cookieManager
+ * @param {Object} dependencies.logger
+ * @param {Object} dependencies.componentConfig
+ * @param {Function} dependencies.getBrowser
+ * @param {Object} dependencies.consent
+ * @param {Function} dependencies.collectSurferId - factory-created, already bound to cookieManager/getBrowser
+ * @param {Function} dependencies.getID5Id
+ * @param {Function} dependencies.getRampId
+ * @param {Function} dependencies.appendAdvertisingIdQueryToEvent
+ * @param {Function} dependencies.appendAdCloudIdentityToEvent
+ * @param {Function} dependencies.collectHashedIPAddr
+ * @param {Function} dependencies.getUrlParams
+ * @param {Function} dependencies.isThrottled
+ * @param {Function} dependencies.normalizeAdvertiser
+ */
+export default ({
+  cookieManager,
+  logger,
+  componentConfig,
+  getBrowser,
+  consent,
+  collectSurferId,
+  getID5Id,
+  getRampId,
+  appendAdvertisingIdQueryToEvent,
+  appendAdCloudIdentityToEvent,
+  collectHashedIPAddr,
+  getUrlParams,
+  isThrottled,
+  normalizeAdvertiser,
+}) => {
+  /**
+   * Appends advertising identity IDs to AEP event query if not already added.
+   *
+   * @param {Object} options
+   * @param {Object} options.event
+   * @param {Object} [options.advertising={}]
+   * @returns {Promise<void>}
+   */
+  return async ({ event, advertising = {} }) => {
+    const { state } = consent.current();
+    if (state !== "in") {
+      return;
+    }
+    const { skwcid, efid } = getUrlParams();
+    const isClickThru = !!(skwcid && efid);
+    // Skip identity resolution when no enabled advertiser IDs are configured —
+    // there is nothing meaningful to enrich the event with downstream.
+    const activeAdvertiserIds = normalizeAdvertiser(
+      componentConfig?.advertiserSettings,
+    );
+    const hasAdvertiserIds = activeAdvertiserIds.length > 0;
+    if (
+      isAdvertisingDisabled(advertising) ||
+      isClickThru ||
+      !hasAdvertiserIds ||
+      (isThrottled(SURFER_ID, cookieManager) &&
+        isThrottled(ID5_ID, cookieManager) &&
+        isThrottled(RAMP_ID, cookieManager))
+    )
+      return;
+
+    try {
+      const useShortTimeout = waitForAdvertisingId(advertising);
+
+      let rampIdPromise = null;
+      if (!getBrowser || getBrowser() !== CHROME) {
+        rampIdPromise = getRampId(
+          logger,
+          componentConfig.rampIdJSPath,
+          cookieManager,
+          useShortTimeout,
+          useShortTimeout,
+        );
+      }
+      const id5Promise = componentConfig.id5PartnerId
+        ? getID5Id(
+            logger,
+            componentConfig.id5PartnerId,
+            useShortTimeout,
+            useShortTimeout,
+          )
+        : Promise.resolve(null);
+
+      const [surferIdResult, hashedIPResult, id5IdResult, rampIdResult] =
+        await Promise.allSettled([
+          collectSurferId(useShortTimeout),
+          collectHashedIPAddr(),
+          id5Promise,
+          rampIdPromise,
+        ]);
+
+      const availableIds = {};
+      const availableIdsForIdentity = {};
+
+      if (surferIdResult.status === "fulfilled" && surferIdResult.value) {
+        availableIdsForIdentity[SURFER_ID] = surferIdResult.value;
+        if (!isThrottled(SURFER_ID, cookieManager)) {
+          availableIds[SURFER_ID] = surferIdResult.value;
+        }
+      }
+      if (hashedIPResult.status === "fulfilled" && hashedIPResult.value) {
+        availableIdsForIdentity[HASHED_IP] = hashedIPResult.value;
+        if (!isThrottled(SURFER_ID, cookieManager)) {
+          availableIds[HASHED_IP] = hashedIPResult.value;
+        }
+      }
+      if (
+        id5IdResult.status === "fulfilled" &&
+        id5IdResult.value &&
+        !isThrottled(ID5_ID, cookieManager)
+      ) {
+        availableIds.id5Id = id5IdResult.value;
+      }
+      if (
+        rampIdResult.status === "fulfilled" &&
+        rampIdResult.value &&
+        !isThrottled(RAMP_ID, cookieManager)
+      ) {
+        availableIds.rampId = rampIdResult.value;
+      }
+
+      if (Object.keys(availableIdsForIdentity).length !== 0) {
+        appendAdCloudIdentityToEvent(availableIdsForIdentity, event);
+      }
+
+      // If no IDs are available and any ID is throttled, skip — no new info to send
+      if (
+        Object.keys(availableIds).length === 0 &&
+        (isThrottled(SURFER_ID, cookieManager) ||
+          isThrottled(ID5_ID, cookieManager) ||
+          isThrottled(RAMP_ID, cookieManager))
+      ) {
+        return;
+      }
+
+      appendAdvertisingIdQueryToEvent(
+        availableIds,
+        event,
+        cookieManager,
+        componentConfig,
+      );
+    } catch (error) {
+      logger.error("Error in onBeforeSendEvent hook:", error);
+    }
+  };
+};

package/src/components/Advertising/handlers/sendAdConversion.js

@@ -0,0 +1,74 @@
+/*
+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 handleClickThrough from "./clickThroughHandler.js";
+import handleViewThrough from "./viewThroughHandler.js";
+import { getUrlParams, normalizeAdvertiser } from "../utils/helpers.js";
+
+/**
+ * Creates a handler for sending ad conversions.
+ * Handles both click-through and view-through conversions.
+ * This is a workaround to avoid the full lifecycle of the eventManager.sendEvent
+ */
+export default ({
+  eventManager,
+  cookieManager,
+  adConversionHandler,
+  logger,
+  componentConfig,
+  getBrowser,
+  consent,
+  collectSurferId,
+  collectHashedIPAddr,
+}) => {
+  const activeAdvertiserIds = componentConfig?.advertiserSettings
+    ? normalizeAdvertiser(componentConfig.advertiserSettings)
+    : "";
+
+  return async () => {
+    try {
+      // Wait for consent before any ad conversion processing.
+      // This ensures no advertising cookies are set without user consent.
+      // If consent is declined, awaitConsent() rejects and we exit gracefully.
+      await consent.awaitConsent();
+
+      const { skwcid, efid } = getUrlParams();
+      const isClickThru = !!(skwcid || efid);
+
+      if (isClickThru) {
+        // wait for click through to complete
+        return handleClickThrough({
+          eventManager,
+          cookieManager,
+          adConversionHandler,
+          logger,
+          skwcid,
+          efid,
+        });
+      } else if (activeAdvertiserIds) {
+        // fire and forget view through
+        handleViewThrough({
+          eventManager,
+          cookieManager,
+          logger,
+          componentConfig,
+          adConversionHandler,
+          getBrowser,
+          collectSurferId,
+          collectHashedIPAddr,
+        }).catch((error) => logger.error("Error in view through:", error));
+      }
+    } catch (error) {
+      logger.error("Error in sendAdConversion:", error);
+    }
+  };
+};

package/src/components/Advertising/handlers/viewThroughHandler.js

@@ -0,0 +1,107 @@
+/*
+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 collectAllIdentities from "../identities/collectAllIdentities.js";
+import {
+  LOG_ERROR_RESOLVING_ID,
+  LOG_AD_CONVERSION_FAILED,
+  AD_CONVERSION_VIEW_EVENT_TYPE,
+  HASHED_IP,
+} from "../constants/index.js";
+import {
+  isAnyIdUnused,
+  appendAdvertisingIdQueryToEvent,
+  markIdsAsConverted,
+} from "../utils/helpers.js";
+
+export default async function handleViewThrough({
+  eventManager,
+  cookieManager,
+  logger,
+  componentConfig,
+  adConversionHandler,
+  getBrowser,
+  collectSurferId,
+  collectHashedIPAddr,
+}) {
+  const resolvedIds = {};
+  const usedIdTracker = {};
+
+  // Start hashedIp collection early — shares the same iframe as surferId so
+  // it resolves at the same time. Awaiting it in triggerConversion adds no
+  // real delay and keeps the enrichment to a single call.
+  const hashedIpPromise = collectHashedIPAddr
+    ? collectHashedIPAddr().catch(() => null)
+    : Promise.resolve(null);
+
+  const triggerConversion = async () => {
+    if (!isAnyIdUnused(resolvedIds, usedIdTracker)) return null;
+
+    const hashedIp = await hashedIpPromise;
+    const idsForEvent = hashedIp
+      ? { ...resolvedIds, [HASHED_IP]: hashedIp }
+      : { ...resolvedIds };
+
+    const idTypesToUse = Object.keys(resolvedIds);
+
+    try {
+      const event = appendAdvertisingIdQueryToEvent(
+        idsForEvent,
+        eventManager.createEvent(),
+        cookieManager,
+        componentConfig,
+        true,
+      );
+      const xdm = {
+        eventType: AD_CONVERSION_VIEW_EVENT_TYPE,
+        timestamp: new Date().toISOString(),
+      };
+      event.setUserXdm(xdm);
+
+      const result = await adConversionHandler.trackAdConversion({ event });
+
+      markIdsAsConverted(idTypesToUse, usedIdTracker, cookieManager, logger);
+      return result;
+    } catch (error) {
+      logger.error(LOG_AD_CONVERSION_FAILED, error);
+      return null;
+    }
+  };
+
+  const identityPromisesMap = collectAllIdentities(
+    logger,
+    componentConfig,
+    cookieManager,
+    getBrowser,
+    collectSurferId,
+  );
+
+  if (Object.keys(identityPromisesMap).length === 0) {
+    return [];
+  }
+
+  const identityPromises = Object.entries(identityPromisesMap).map(
+    ([idType, idPromise]) =>
+      idPromise
+        .then((idValue) => {
+          if (idValue) {
+            resolvedIds[idType] = idValue;
+            return triggerConversion();
+          }
+        })
+        .catch((error) => {
+          logger.error(LOG_ERROR_RESOLVING_ID.replace("{0}", idType), error);
+          return null;
+        }),
+  );
+  return Promise.allSettled(identityPromises);
+}

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

@@ -0,0 +1,57 @@
+/*
+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 { getRampId } from "./collectRampId.js";
+import { getID5Id } from "./collectID5Id.js";
+import { ID5_ID, RAMP_ID, SURFER_ID } from "../constants/index.js";
+import { isThrottled } from "../utils/helpers.js";
+
+const collectAllIdentities = (
+  logger,
+  componentConfig,
+  cookieManager,
+  getBrowser,
+  collectSurferId,
+) => {
+  const promises = {};
+
+  if (!isThrottled(SURFER_ID, cookieManager)) {
+    promises.surferId = collectSurferId(true).catch(() => null);
+  }
+
+  if (
+    componentConfig.id5PartnerId &&
+    componentConfig.dspEnabled &&
+    !isThrottled(ID5_ID, cookieManager)
+  ) {
+    promises.id5Id = getID5Id(logger, componentConfig.id5PartnerId).catch(
+      () => null,
+    );
+  }
+
+  if (
+    componentConfig.rampIdJSPath &&
+    componentConfig.dspEnabled &&
+    !isThrottled(RAMP_ID, cookieManager)
+  ) {
+    promises.rampId = getRampId(
+      logger,
+      componentConfig.rampIdJSPath,
+      cookieManager,
+      true,
+    ).catch(() => null);
+  }
+
+  return promises;
+};
+
+export default collectAllIdentities;

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

@@ -0,0 +1,133 @@
+/*
+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 { ID5_SCRIPT_URL } from "../constants/index.js";
+
+let id5Id = "";
+let inProgressId5Promise = null;
+const SHORT_TIMEOUT_MS = 2000;
+const DEFAULT_TIMEOUT_MS = 30000;
+
+const initiateID5Call = (partnerId, useShortTimeout, logger) => {
+  partnerId = Math.floor(Number(partnerId));
+
+  if (inProgressId5Promise) {
+    return inProgressId5Promise;
+  }
+
+  const timeoutMs = useShortTimeout ? SHORT_TIMEOUT_MS : DEFAULT_TIMEOUT_MS;
+
+  let iD5TimedOut = false;
+
+  const id5ResolutionPromise = new Promise((resolve, reject) => {
+    if (!partnerId) {
+      logger.error("Missing partner ID");
+      reject(new Error("ID5 partner ID is required"));
+      return;
+    }
+
+    const handleId5 = () => {
+      try {
+        if (typeof window.ID5 === "undefined") {
+          reject(new Error("ID5 object not available after script load"));
+          return;
+        }
+
+        const id5Instance = window.ID5.init({ partnerId });
+        id5Id = id5Instance.getUserId();
+
+        const safeResolve = (val) => {
+          if (!iD5TimedOut) resolve(val);
+        };
+
+        if (!id5Id) {
+          window.ID5.init({ partnerId }).onAvailable(function firstRetry(
+            retryStatus,
+          ) {
+            id5Id = retryStatus.getUserId();
+            if (id5Id) {
+              safeResolve(id5Id);
+            } else {
+              window.ID5.init({ partnerId }).onAvailable(
+                function secondRetry(secondRetryStatus) {
+                  id5Id = secondRetryStatus.getUserId();
+                  if (id5Id) {
+                    safeResolve(id5Id);
+                  } else {
+                    logger.error("Failed to get ID5 ID after all retries");
+                    safeResolve(null);
+                  }
+                },
+              );
+            }
+          }, 1000);
+        } else {
+          safeResolve(id5Id);
+        }
+      } catch (error) {
+        logger.error("Error during ID5 initialization", error);
+        reject(error);
+      }
+    };
+
+    if (typeof window.ID5 !== "undefined") {
+      handleId5();
+    } else {
+      loadScript(ID5_SCRIPT_URL, {
+        onLoad: handleId5,
+        onError: (error) => {
+          logger.error("Script loading failed", error);
+          reject(error);
+        },
+      });
+    }
+  });
+
+  const timeoutPromise = new Promise((resolve) => {
+    setTimeout(() => {
+      iD5TimedOut = true;
+      resolve(null);
+    }, timeoutMs);
+  });
+
+  inProgressId5Promise = Promise.race([
+    id5ResolutionPromise,
+    timeoutPromise,
+  ]).finally(() => {
+    inProgressId5Promise = null;
+  });
+
+  return inProgressId5Promise;
+};
+
+const getID5Id = function getID5Id(
+  logger,
+  partnerId,
+  resolveId5IfNotAvailable = true,
+  useShortTimeout = false,
+) {
+  if (id5Id && id5Id !== "") {
+    return Promise.resolve(id5Id);
+  }
+  if (!resolveId5IfNotAvailable) {
+    return Promise.resolve(null);
+  }
+
+  return initiateID5Call(partnerId, useShortTimeout, logger)
+    .then((resolvedId) => resolvedId)
+    .catch((error) => {
+      logger.error("Failed to get ID5 ID", error);
+      throw error;
+    });
+};
+
+export { getID5Id, initiateID5Call };