Adobe Client Data Layer (ACDL) cheat sheet

What this is

The Adobe Client Data Layer (ACDL) is an event-driven data layer: an array you push() data and events into, which the library merges into a computed state and broadcasts to listeners. This page is the lookup card for its full API surface — push patterns, getState, listener scopes, the AEM Core Components cmp: events, and the Tags extension mapping.

Load and initialize

window.adobeDataLayer = window.adobeDataLayer || [];

npm install @adobe/adobe-client-data-layer
# ships dist/adobe-client-data-layer.min.js — load it with defer

Before the library initializes, window.adobeDataLayer is a plain array: only push() exists and is safe to call. Every other method must run inside a function push (below), which executes once the library is ready.

Push patterns

Push	Shape	Effect
Data	`{ page: { … } }`	Deep-merged into computed state; fires `adobeDataLayer:change`
Event	`{ event: 'name', eventInfo: { … } }`	Notifies listeners; fires `adobeDataLayer:event`; `event`/`eventInfo` are not stored in state
Function	`function (dl) { … }`	Runs immediately if initialized, else queued; `dl` is the data layer
Removal	`{ key: null }`	`null` (or `undefined`) deletes that key from state

window.adobeDataLayer.push({ page: { title: 'Pricing', lang: 'en' } });

window.adobeDataLayer.push({
  event: 'cta_click',
  eventInfo: { reference: 'component.hero-1' },
});

window.adobeDataLayer.push(function (dl) {
  console.log(dl.getState());
});

window.adobeDataLayer.push({ component: { 'map-1': null } });

Arrays do not merge: pushing an array property overwrites the existing inner array. Push the complete array every time. Mutating the array with anything other than push() (e.g. splice, index assignment) is unsupported.

Reading state

dl.getState();                    // full computed state (merged object)
dl.getState('component.hero-1');  // subtree by dot-notation reference

getState returns the computed result of every data push so far, with event and eventInfo keys excluded. Call it only inside a function push or a listener callback — never on the bare array.

Event listeners

dl.addEventListener(type, listener, options);
dl.removeEventListener(type, listener); // omit listener → removes all for type

Option	Values	Default	Meaning
`scope`	`'past'`, `'future'`, `'all'`	`'all'`	`'past'` replays already-triggered events only; `'future'` = new events only; `'all'` = both
`path`	dot-notation string	—	Only fire when the change touches this state path

Built-in event	Fires when
`adobeDataLayer:change`	Data is pushed (state changed)
`adobeDataLayer:event`	An event object is pushed

The 'all' default means a listener registered late still receives every earlier event — deliberate, to remove race conditions between your script and components that pushed before it loaded.

AEM Core Components events

Core Components populate the data layer automatically once it is enabled via context-aware configuration: a com.adobe.cq.wcm.core.components.internal.DataLayerConfig node with enabled=true under /conf/<site>/sling:configs, referenced by the site’s jcr:content. Confirm it is on by checking <body> for the data-cmp-data-layer-enabled attribute.

Event	Emitted by
`cmp:loaded`	Page, after the data layer is populated
`cmp:show` / `cmp:hide`	Accordion, Tabs, Carousel item changes (`cmp:show` also fires on load)
`cmp:click`	Clickable components

Every cmp: event carries eventInfo.path — the state path of the triggering component — so the handler can look up the component’s full data with getState(event.eventInfo.path).

Tags extension mapping

The Adobe Client Data Layer extension for Tags (Adobe Experience Platform Data Collection) wires ACDL into rules without custom code.

Extension piece	What it gives you
Extension config	Data layer object name (default `adobeDataLayer`, renamable)
Event type	Listen to specific events or any data layer change
Data element: Computed State	Full state, or one configured path
Data element: Size	Number of items pushed to the array
Action: Push to Data Layer	Push JSON (may embed data elements) onto the data layer

Gotchas

adobeDataLayer.getState is not a function — the library has not loaded yet, so the variable is still a plain array. Fix: wrap all API calls in window.adobeDataLayer.push(function (dl) { … }).
Duplicate tracking calls after re-registering a listener — default scope 'all' replays every past event to each new registration (common in SPAs re-running setup on route change). Fix: use scope: 'future', or removeEventListener before adding again.
Items vanish from an array after a partial push — arrays are not merged; the pushed array replaces the stored one. Fix: always push the complete array.
Event data missing from getState() — event and eventInfo are intentionally never persisted to state. Fix: put anything you need later in a normal data key, not inside eventInfo.
No cmp: events on an AEM site — the data layer is disabled for that site. Check <body> for data-cmp-data-layer-enabled; if absent, add the DataLayerConfig context-aware config with enabled=true.

Quick recipes

window.adobeDataLayer.push(function (dl) {
  dl.addEventListener('cmp:click', function (event) {
    var component = dl.getState(event.eventInfo.path);
    // forward component.title / component['@type'] to your endpoint
  });
});

window.adobeDataLayer.push(function (dl) {
  dl.addEventListener('adobeDataLayer:change', onCartChange, {
    path: 'cart',
  });
});

window.adobeDataLayer.push(function (dl) {
  dl.addEventListener('adobeDataLayer:event', forwardEvent, {
    scope: 'future',
  });
});

window.adobeDataLayer.push({ component: { 'form-1': null } });
window.adobeDataLayer.push({ component: { 'form-1': { status: 'reset' } } });

Hub: Adobe guides
Lateral: Consent Mode v2 reference · GA4 event naming cheat sheet
Canonical docs: ACDL wiki (API) · Core Components data layer · Tags extension

Verification notes

API surface checked against the official ACDL wiki and the npm registry (v3.0.1), Core Components behavior against Adobe Experience League, on the date in the header. The library does not document a public version property; read the package version from npm instead.

Changelog

Jul 19, 2026 — Initial version, verified against ACDL 3.0.1 and current Adobe docs.