@adobe/alloy 2.32.0 → 2.32.1-beta.1

package/src/allOptionalComponents.js

@@ -0,0 +1,14 @@
+/*
+Copyright 2026 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 * from "@adobe/alloy-core/core/componentCreators.js";
+export * from "./components/componentCreators.js";

package/src/components/ActivityCollector/attachClickActivityCollector.js

@@ -0,0 +1,55 @@
+/*
+Copyright 2022 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 { noop } from "@adobe/alloy-core/utils";
+
+const createClickHandler = ({ eventManager, lifecycle, handleError }) => {
+  return (clickEvent) => {
+    // Ignore repropagated clicks from AppMeasurement
+    if (clickEvent.s_fe) {
+      return Promise.resolve();
+    }
+    // TODO: Consider safeguarding from the same object being clicked multiple times in rapid succession?
+    const clickedElement =
+      "composedPath" in clickEvent && clickEvent.composedPath().length > 0
+        ? clickEvent.composedPath()[0]
+        : clickEvent.target;
+    const event = eventManager.createEvent();
+    // this is to make sure a exit link personalization metric use send beacon
+    event.documentMayUnload();
+    return (
+      lifecycle
+        .onClick({ event, clickedElement })
+        .then(() => {
+          if (event.isEmpty()) {
+            return Promise.resolve();
+          }
+          return eventManager.sendEvent(event);
+        })
+        // eventManager.sendEvent() will return a promise resolved to an
+        // object and we want to avoid returning any value to the customer
+        .then(noop)
+        .catch((error) => {
+          handleError(error, "click collection");
+        })
+    );
+  };
+};
+
+export default ({ eventManager, lifecycle, handleError }) => {
+  const clickHandler = createClickHandler({
+    eventManager,
+    lifecycle,
+    handleError,
+  });
+  document.addEventListener("click", clickHandler, true);
+};

package/src/components/ActivityCollector/configValidators.js

@@ -0,0 +1,52 @@
+/*
+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 {
+  boolean,
+  callback,
+  objectOf,
+  string,
+} from "@adobe/alloy-core/utils/validation";
+
+const DEFAULT_DOWNLOAD_QUALIFIER =
+  "\\.(exe|zip|wav|mp3|mov|mpg|avi|wmv|pdf|doc|docx|xls|xlsx|ppt|pptx)$";
+
+export const downloadLinkQualifier = string()
+  .regexp()
+  .default(DEFAULT_DOWNLOAD_QUALIFIER);
+
+const validators = objectOf({
+  clickCollectionEnabled: boolean().default(true),
+  clickCollection: objectOf({
+    internalLinkEnabled: boolean().default(true),
+    externalLinkEnabled: boolean().default(true),
+    downloadLinkEnabled: boolean().default(true),
+    // TODO: Consider moving downloadLinkQualifier here.
+    sessionStorageEnabled: boolean().default(false),
+    eventGroupingEnabled: boolean().default(false),
+    filterClickProperties: callback(),
+  }).default({
+    internalLinkEnabled: true,
+    externalLinkEnabled: true,
+    downloadLinkEnabled: true,
+    sessionStorageEnabled: false,
+    eventGroupingEnabled: false,
+  }),
+  downloadLinkQualifier,
+  onBeforeLinkClickSend: callback().deprecated(
+    'The field "onBeforeLinkClickSend" has been deprecated. Use "clickCollection.filterClickDetails" instead.',
+  ),
+});
+
+// Export both the validators and the default qualifier
+export { DEFAULT_DOWNLOAD_QUALIFIER };
+export default validators;

package/src/components/ActivityCollector/createClickActivityStorage.js

@@ -0,0 +1,33 @@
+/*
+Copyright 2024 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.
+*/
+
+const CLICK_ACTIVITY_DATA = "clickData";
+
+export default ({ storage }) => {
+  return {
+    save: (data) => {
+      const jsonData = JSON.stringify(data);
+      storage.setItem(CLICK_ACTIVITY_DATA, jsonData);
+    },
+    load: () => {
+      let jsonData = null;
+      const data = storage.getItem(CLICK_ACTIVITY_DATA);
+      if (data) {
+        jsonData = JSON.parse(data);
+      }
+      return jsonData;
+    },
+    remove: () => {
+      storage.removeItem(CLICK_ACTIVITY_DATA);
+    },
+  };
+};

package/src/components/ActivityCollector/createClickedElementProperties.js

@@ -0,0 +1,224 @@
+/*
+Copyright 2022 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.
+*/
+
+const buildXdmFromClickedElementProperties = (props) => {
+  return {
+    eventType: "web.webinteraction.linkClicks",
+    web: {
+      webInteraction: {
+        name: props.linkName,
+        region: props.linkRegion,
+        type: props.linkType,
+        URL: props.linkUrl,
+        linkClicks: {
+          value: 1,
+        },
+      },
+    },
+  };
+};
+
+const buildDataFromClickedElementProperties = (props) => {
+  return {
+    __adobe: {
+      analytics: {
+        contextData: {
+          a: {
+            activitymap: {
+              page: props.pageName,
+              link: props.linkName,
+              region: props.linkRegion,
+              pageIDType: props.pageIDType,
+            },
+          },
+        },
+      },
+    },
+  };
+};
+
+const populateClickedElementPropertiesFromOptions = (options, props) => {
+  const { xdm, data, clickedElement } = options;
+  props.clickedElement = clickedElement;
+  if (xdm && xdm.web && xdm.web.webInteraction) {
+    const { name, region, type, URL } = xdm.web.webInteraction;
+    props.linkName = name;
+    props.linkRegion = region;
+    props.linkType = type;
+    props.linkUrl = URL;
+  }
+  // DATA has priority over XDM
+  /* eslint no-underscore-dangle: 0 */
+  if (data && data.__adobe && data.__adobe.analytics) {
+    const { contextData } = data.__adobe.analytics;
+    if (contextData && contextData.a && contextData.a.activitymap) {
+      // Set the properties if they exists
+      const { page, link, region, pageIDType } = contextData.a.activitymap;
+      props.pageName = page || props.pageName;
+      props.linkName = link || props.linkName;
+      props.linkRegion = region || props.linkRegion;
+      if (pageIDType !== undefined) {
+        props.pageIDType = pageIDType;
+      }
+    }
+  }
+};
+
+export default ({ properties, logger } = {}) => {
+  let props = properties || {};
+  const clickedElementProperties = {
+    get pageName() {
+      return props.pageName;
+    },
+    set pageName(value) {
+      props.pageName = value;
+    },
+    get linkName() {
+      return props.linkName;
+    },
+    set linkName(value) {
+      props.linkName = value;
+    },
+    get linkRegion() {
+      return props.linkRegion;
+    },
+    set linkRegion(value) {
+      props.linkRegion = value;
+    },
+    get linkType() {
+      return props.linkType;
+    },
+    set linkType(value) {
+      props.linkType = value;
+    },
+    get linkUrl() {
+      return props.linkUrl;
+    },
+    set linkUrl(value) {
+      props.linkUrl = value;
+    },
+    get pageIDType() {
+      return props.pageIDType;
+    },
+    set pageIDType(value) {
+      props.pageIDType = value;
+    },
+    get clickedElement() {
+      return props.clickedElement;
+    },
+    set clickedElement(value) {
+      props.clickedElement = value;
+    },
+    get properties() {
+      return {
+        pageName: props.pageName,
+        linkName: props.linkName,
+        linkRegion: props.linkRegion,
+        linkType: props.linkType,
+        linkUrl: props.linkUrl,
+        pageIDType: props.pageIDType,
+      };
+    },
+    isValidLink() {
+      return (
+        !!props.linkUrl &&
+        !!props.linkType &&
+        !!props.linkName &&
+        !!props.linkRegion
+      );
+    },
+    isInternalLink() {
+      return this.isValidLink() && props.linkType === "other";
+    },
+    isValidActivityMapData() {
+      return (
+        !!props.pageName &&
+        !!props.linkName &&
+        !!props.linkRegion &&
+        props.pageIDType !== undefined
+      );
+    },
+    get xdm() {
+      if (props.filteredXdm) {
+        return props.filteredXdm;
+      }
+      return buildXdmFromClickedElementProperties(this);
+    },
+    get data() {
+      if (props.filteredData) {
+        return props.filteredData;
+      }
+      return buildDataFromClickedElementProperties(this);
+    },
+    applyPropertyFilter(filter) {
+      if (filter && filter(props) === false) {
+        if (logger) {
+          logger.info(
+            `Clicked element properties were rejected by filter function: ${JSON.stringify(
+              this.properties,
+              null,
+              2,
+            )}`,
+          );
+        }
+        props = {};
+      }
+    },
+    applyOptionsFilter(filter) {
+      const opts = this.options;
+      if (opts && opts.clickedElement && (opts.xdm || opts.data)) {
+        // Properties are rejected if filter is explicitly false.
+        if (filter && filter(opts) === false) {
+          if (logger) {
+            logger.info(
+              `Clicked element properties were rejected by filter function: ${JSON.stringify(
+                this.properties,
+                null,
+                2,
+              )}`,
+            );
+          }
+          this.options = undefined;
+          return;
+        }
+        this.options = opts;
+        // This is just to ensure that any fields outside clicked element properties
+        // set by the user filter persists.
+        props.filteredXdm = opts.xdm;
+        props.filteredData = opts.data;
+      }
+    },
+    get options() {
+      const opts = {};
+      if (this.isValidLink()) {
+        opts.xdm = this.xdm;
+      }
+      if (this.isValidActivityMapData()) {
+        opts.data = this.data;
+      }
+      if (this.clickedElement) {
+        opts.clickedElement = this.clickedElement;
+      }
+      if (!opts.xdm && !opts.data) {
+        return undefined;
+      }
+      return opts;
+    },
+    set options(value) {
+      props = {};
+      if (value) {
+        populateClickedElementPropertiesFromOptions(value, props);
+      }
+    },
+  };
+  return clickedElementProperties;
+};

package/src/components/ActivityCollector/createGetClickedElementProperties.js

@@ -0,0 +1,68 @@
+/*
+Copyright 2022 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 createClickedElementProperties from "./createClickedElementProperties.js";
+
+export default ({
+  window,
+  getLinkName,
+  getLinkRegion,
+  getAbsoluteUrlFromAnchorElement,
+  findClickableElement,
+  determineLinkType,
+}) => {
+  return ({ clickedElement, config, logger, clickActivityStorage }) => {
+    const {
+      onBeforeLinkClickSend: optionsFilter, // Deprecated
+      clickCollection,
+    } = config;
+    const { filterClickDetails: propertyFilter } = clickCollection;
+    const elementProperties = createClickedElementProperties({ logger });
+    if (clickedElement) {
+      const clickableElement = findClickableElement(clickedElement);
+      if (clickableElement) {
+        elementProperties.clickedElement = clickedElement;
+        elementProperties.linkUrl = getAbsoluteUrlFromAnchorElement(
+          window,
+          clickableElement,
+        );
+        elementProperties.linkType = determineLinkType(
+          window,
+          config,
+          elementProperties.linkUrl,
+          clickableElement,
+        );
+        elementProperties.linkRegion = getLinkRegion(clickableElement);
+        elementProperties.linkName = getLinkName(clickableElement);
+        elementProperties.pageIDType = 0;
+        elementProperties.pageName = window.location.href;
+        // Check if we have a page-name stored from an earlier page view event
+        const storedLinkData = clickActivityStorage.load();
+        if (storedLinkData && storedLinkData.pageName) {
+          elementProperties.pageName = storedLinkData.pageName;
+          // Perhaps pageIDType should be established after customer filter is applied
+          // Like if pageName starts with "http" then pageIDType = 0
+          elementProperties.pageIDType = 1;
+        }
+        // If defined, run user provided filter function
+        if (propertyFilter) {
+          // clickCollection.filterClickDetails
+          elementProperties.applyPropertyFilter(propertyFilter);
+        } else if (optionsFilter) {
+          // onBeforeLinkClickSend
+          elementProperties.applyOptionsFilter(optionsFilter);
+        }
+      }
+    }
+    return elementProperties;
+  };
+};

package/src/components/ActivityCollector/createInjectClickedElementProperties.js

@@ -0,0 +1,80 @@
+/*
+Copyright 2022 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 activityMapExtensionEnabled from "./utils/activityMapExtensionEnabled.js";
+import isDifferentDomains from "./utils/isDifferentDomains.js";
+
+const isDissallowedLinkType = (clickCollection, linkType) => {
+  return (
+    linkType &&
+    ((linkType === "download" && !clickCollection.downloadLinkEnabled) ||
+      (linkType === "exit" && !clickCollection.externalLinkEnabled) ||
+      (linkType === "other" && !clickCollection.internalLinkEnabled))
+  );
+};
+
+export default ({
+  config,
+  logger,
+  getClickedElementProperties,
+  clickActivityStorage,
+}) => {
+  const { clickCollectionEnabled, clickCollection } = config;
+  if (!clickCollectionEnabled) {
+    return () => undefined;
+  }
+
+  return ({ event, clickedElement }) => {
+    const elementProperties = getClickedElementProperties({
+      clickActivityStorage,
+      clickedElement,
+      config,
+      logger,
+    });
+    const linkType = elementProperties.linkType;
+    // Avoid clicks to be collected for the ActivityMap interface
+    if (activityMapExtensionEnabled()) {
+      return;
+    }
+    if (
+      elementProperties.isValidLink() &&
+      isDissallowedLinkType(clickCollection, linkType)
+    ) {
+      logger.info(
+        `Cancelling link click event due to clickCollection.${linkType}LinkEnabled = false.`,
+      );
+    } else if (
+      // Determine if element properties should be sent with event now, or be saved
+      // and grouped with a future page view event.
+      // Event grouping is not supported for the deprecated onBeforeLinkClickSend callback
+      // because only click properties is saved and not XDM and DATA (which could have been modified).
+      // However, if the filterClickDetails callback is available we group events because it takes
+      // priority over onBeforeLinkClickSend and only supports processing click properties.
+      elementProperties.isInternalLink() &&
+      clickCollection.eventGroupingEnabled &&
+      (!config.onBeforeLinkClickSend || clickCollection.filterClickDetails) &&
+      !isDifferentDomains(window.location.hostname, elementProperties.linkUrl)
+    ) {
+      clickActivityStorage.save(elementProperties.properties);
+    } else if (elementProperties.isValidLink()) {
+      // Event will be sent
+      event.mergeXdm(elementProperties.xdm);
+      event.mergeData(elementProperties.data);
+      clickActivityStorage.save({
+        pageName: elementProperties.pageName,
+        pageIDType: elementProperties.pageIDType,
+      });
+    } else if (elementProperties.isValidActivityMapData()) {
+      clickActivityStorage.save(elementProperties.properties);
+    }
+  };
+};

package/src/components/ActivityCollector/createRecallAndInjectClickedElementProperties.js

@@ -0,0 +1,45 @@
+/*
+Copyright 2024 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 createClickedElementProperties from "./createClickedElementProperties.js";
+import activityMapExtensionEnabled from "./utils/activityMapExtensionEnabled.js";
+
+export default ({ clickActivityStorage }) => {
+  return (event) => {
+    // Avoid clicks to be collected for the ActivityMap interface
+    if (activityMapExtensionEnabled()) {
+      return;
+    }
+    const properties = clickActivityStorage.load();
+    const elementProperties = createClickedElementProperties({ properties });
+    if (
+      elementProperties.isValidLink() ||
+      elementProperties.isValidActivityMapData()
+    ) {
+      if (elementProperties.isValidLink()) {
+        const xdm = elementProperties.xdm;
+        // Have to delete the eventType not to override the page view
+        delete xdm.eventType;
+        event.mergeXdm(xdm);
+      }
+      if (elementProperties.isValidActivityMapData()) {
+        event.mergeData(elementProperties.data);
+      }
+      // NOTE: We can't clear out all the storage here because we might still need to
+      // keep a page-name for multiple link-clicks (e.g. downloads) on the same page.
+      clickActivityStorage.save({
+        pageName: elementProperties.pageName,
+        pageIDType: elementProperties.pageIDType,
+      });
+    }
+  };
+};

package/src/components/ActivityCollector/createStorePageViewProperties.js

@@ -0,0 +1,20 @@
+/*
+Copyright 2024 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 ({ clickActivityStorage }) => {
+  return (event) => {
+    clickActivityStorage.save({
+      pageName: event.getContent().xdm.web.webPageDetails.name,
+      pageIDType: 1, // 1 = name, 0 = URL
+    });
+  };
+};