Instrument analytics events without drop-ins

If your storefront doesn’t use the AEM Commerce drop-ins — or replaces one with a custom block — you lose the automatic Adobe Client Data Layer (ACDL) instrumentation that the drop-ins provide. This tutorial shows you how to publish some Commerce events yourself using a small helper script, so that analytics data is collected to power Commerce tooling.

Tip

For the full event lifecycle and the list of events drop-ins emit, see the Analytics events reference.

What You’ll Build

By the end of this tutorial, you’ll have a reusable scripts/acdlHelper.js file with the shared primitives for reading and writing to the ACDL. Each focused example below then defines its own event-specific context and publish functions on top of those primitives:

• Instrument analytics product page view event
• Instrument analytics add to cart event

Prerequisites

Before starting this tutorial, make sure you have:

• A working Commerce storefront on Edge Delivery Services
• Basic understanding of JavaScript and asynchronous operations
• The following packages at version 1.17.0 or later in package.json:

package.json

"@adobe/magento-storefront-event-collector": "^1.17.0",
"@adobe/magento-storefront-events-sdk": "^1.17.0"

These packages are included by default in the AEM Commerce boilerplate, but the versions in an existing project may be outdated. Confirm the versions in package.json, then run npm install. If the packages are missing entirely, add them manually to package.json before running npm install.

Note

storefrontInstanceContext and pageContext should already be set in the ACDL before any of the publish functions in this tutorial are called. These contexts are typically seeded once during page initialization — see Scripts in the Analytics events reference. Events fired before these contexts are set still push successfully, but their eventInfo snapshot won’t include storefront or page data.

Add the ACDL helper script

Create scripts/acdlHelper.js in your project, at the root of your AEM boilerplate:

your-project/
└── scripts/
    └── acdlHelper.js   (create this file)

This file centralizes access to the ACDL - getting the data layer, setting a context, and pushing an event - so each event-specific example can build on shared logic instead of duplicating it. It doesn’t contain any event-specific code: each focused example defines its own context and publish functions on top of these primitives, and imports only what it needs from here.

scripts/acdlHelper.js

export function getAdobeDataLayer() {
  window.adobeDataLayer = window.adobeDataLayer || [];
  return window.adobeDataLayer;
}

/**
 * Sets a context in the Adobe Client Data Layer (ACDL).
 * Logic based on: https://github.com/adobe/commerce-events/blob/main/packages/storefront-events-sdk/src/Base.ts#L6
 */
export function setContext(name, data) {
  const adobeDataLayer = getAdobeDataLayer();

  // Clear existing context
  adobeDataLayer.push({
    [name]: null,
  });

  // Set new context
  adobeDataLayer.push({
    [name]: data,
  });
}

/**
 * Pushes an event to the Adobe Client Data Layer (ACDL).
 * Logic based on: https://github.com/adobe/commerce-events/blob/main/packages/storefront-events-sdk/src/Base.ts#L34
 */
export function pushEvent(event, additionalContext) {
  const adobeDataLayer = getAdobeDataLayer();

  adobeDataLayer.push((acdl) => {
    const state = acdl.getState ? acdl.getState() : {};

    acdl.push({
      event,
      eventInfo: {
        ...state,
        ...additionalContext,
      },
    });
  });
}

Instrument specific events

The helper script exposes the shared primitives (getAdobeDataLayer, setContext, pushEvent) used to build event-specific publish functions. Each of the following examples is a short, independent tutorial that defines its own context and publish functions on top of these primitives — instrument only the events your custom implementation actually needs, in any order:

• Instrument analytics product page view event - publish a product-page-view event with a complete product context
• Instrument analytics add to cart event - publish an add-to-cart event with the full updated cart

Implementation Checklist

When adding ACDL tracking to a new page or interaction:

1. Copy scripts/acdlHelper.js into your project’s scripts/ directory.
2. Ensure storefrontInstanceContext and pageContext are set before any publish call.
3. On product page load, call the publishProductPageViewEvent function from Instrument analytics product page view event with the resolved product data.
4. On successful add-to-cart, call the publishAddToCartEvent function from Instrument analytics add to cart event with the full updated cart, not just the item that was added.
5. On cart update (quantity change, removal), call setShoppingCartContext directly to keep the context in sync without firing an event.
6. On variant or option selection change, call setProductContext so the context always reflects the currently selected variant.

Troubleshooting

Common Issues

• Events push successfully but eventInfo is missing storefront or page data

  Confirm storefrontInstanceContext and pageContext are pushed to the ACDL before any publish* call runs. See Scripts in the Analytics events reference for when these are normally seeded.

• setShoppingCartContext or setProductContext throws a missing field error

  Check the JSDoc on setShoppingCartContext in Instrument analytics add to cart event, or on setProductContext in Instrument analytics product page view event, for the required fields on items, product, and pricing. Each function validates its input and throws before pushing an incomplete context.

• Events aren’t appearing in Adobe Experience Platform

  Verify AEP forwarding is configured — see Adobe Experience Platform. Events still push to window.adobeDataLayer even if AEP forwarding isn’t enabled, so check the browser console first before assuming the helper script is broken.

Getting Help

If you encounter issues not covered here:

• Review the Analytics events reference for the full list of events and the contexts each one sets
• Review Analytics instrumentation for ACDL validation and debugging steps
• Consult the Commerce Events GitHub repository for the underlying SDK source

Summary

In this tutorial, you learned how to:

• Add a reusable scripts/acdlHelper.js file with the shared primitives for reading and writing to the ACDL
• Identify where to go next to instrument specific analytics events

Continue with Instrument analytics product page view event or Instrument analytics add to cart event to see the helper script in action.