Install the Adobe Client Data Layer

Installing the Adobe Client Data Layer (ACDL) involves two parts:

Create the data layer array initialize

Add the following line before any code that pushes to the data layer:

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

This line creates the array if it doesn’t exist and keeps it if it does. Include it in every script that pushes to the data layer, not just the first one. Scripts can load in any order, and the line makes sure that each script pushes to the same array without overwriting it.

After this line, push data, events, and functions with push():

window.adobeDataLayer = window.adobeDataLayer || [];
window.adobeDataLayer.push({ page: { title: "Home" } });

Until ACDL loads, push() is the standard JavaScript array method, and the array works as a queue. When ACDL loads, it processes the queued items in order. See Queue and history.

Choose an installation method methods

Load ACDL on each page with one of the following methods:

Tag extension tags

The Adobe Client Data Layer tag extension loads ACDL when your tag library loads, unless the page already loads it. You don’t need to add the library to your page templates. Your site code still needs to create the data layer array and push data. See Configure the Adobe Client Data Layer extension.

Script tag script

Download the library from npm (see npm) and host adobe-client-data-layer.min.js on your site. Then load it in the <head> of each page with both the async and defer attributes:

<script src="/js/adobe-client-data-layer.min.js" async defer></script>

Browsers that support async run the script as soon as it downloads, without blocking the page. Because ACDL processes everything that was queued before it loaded, your data is safe even if other scripts push to the data layer first.

The following example shows a page where an inline script and an external script both push to the data layer before ACDL loads:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>My page</title>
    <script src="/js/myscripts.js" defer></script>
    <script>
      window.adobeDataLayer = window.adobeDataLayer || [];
      window.adobeDataLayer.push({ page: { title: "My page" } });
    </script>
    <script src="/js/adobe-client-data-layer.min.js" async defer></script>
  </head>
  <body>
    <h1>My page</h1>
  </body>
</html>

The external script, /js/myscripts.js, also creates the array before it pushes:

window.adobeDataLayer = window.adobeDataLayer || [];
window.adobeDataLayer.push({ user: { loggedIn: false } });

Public npm CDNs, such as unpkg and jsDelivr, also serve the library file. If you load it from a third-party CDN, pin an exact version in the URL so that the file doesn’t change without your knowledge.

npm npm

Install the package:

npm install @adobe/adobe-client-data-layer

The package contains a browser script at dist/adobe-client-data-layer.min.js. Either copy that file to your site and load it with a script tag, or import the file in your bundled JavaScript:

import "@adobe/adobe-client-data-layer/dist/adobe-client-data-layer.min.js";

The script doesn’t export anything. When it runs, it sets up window.adobeDataLayer.

Adobe Experience Manager aem

AEM Core Components 2.9.0 and later include ACDL as a client library, and Core Components push data and events for each component. See Using the Adobe Client Data Layer with the Core Components.

If your AEM site also uses the ACDL tag extension, turn off the extension’s Load the Adobe Client Data Layer library if absent option so that only AEM loads the library. See Configure the Adobe Client Data Layer extension.

Load the library only once load-once

Load ACDL once per page. If a second copy loads, it logs the following warning to the browser console and doesn’t change the data layer:

Adobe Client Data Layer v3.0.1 has already been imported/initialized on this page. You may be erroneously loading it a second time.

The first copy keeps running, so your data and listeners still work. Remove the duplicate to avoid the extra download. Duplicates are common when both a page template and the tag extension load the library.

Verify the installation verify

Open your browser’s developer console on a page that loads ACDL and run the following commands:

adobeDataLayer.version     // For example, "3.0.1"
adobeDataLayer.getState()  // The computed state of everything pushed so far

If adobeDataLayer.version is undefined, ACDL hasn’t loaded on the page. See Troubleshooting.

Upgrade from 2.x to 3.x upgrade

Adobe Experience Manager Core Components load ACDL 2.x by default, so many sites still run 2.x. Review the following changes before you upgrade to 3.x. For all releases, see the release notes on GitHub.

ACDL 3.0 replaced its internal utility library with built-in browser features. The file is much smaller, but the requirements and some merge behavior changed:

Test your implementation after you upgrade, especially code that pushes arrays or changes the type of a value.