push()

push()方法将项目添加到Adobe客户端数据层(ACDL)。 这是在加载库之前唯一可以调用的方法,因此它是网站代码与数据层交互的主要方式。

adobeDataLayer.push(...items: (object | Function)[]): number | undefined

在ACDL加载之前,push()是标准Array.prototype.push()方法,项目在数组中等待库加载。 加载ACDL后,其push()版本会立即处理每个项。 请参阅队列和历史记录。

始终在推送前创建数组:

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

项目类型 item-types

您可以推送三种类型的项目:

项目
ACDL的功能
数据对象
将对象合并到计算状态并触发adobeDataLayer:change。
事件对象
触发命名事件和adobeDataLayer:event。 将对象中的任何数据合并到计算状态。
函数
调用函数并将数据层传递到函数。

数据对象 data

没有event密钥的纯对象。 ACDL将其合并到计算状态:

window.adobeDataLayer.push({
  page: { title: "Products", language: "en" },
  user: { loggedIn: true }
});

要删除键,请将null推送为其值。 查看删除数据。

事件对象 event

具有event键的纯对象,包含非空字符串。 该对象还可以包含要合并到计算状态中的eventInfo键和数据:

window.adobeDataLayer.push({
  event: "cart add",
  eventInfo: { sku: "a-100" },
  cart: { itemCount: 3 }
});

ACDL将本例中的数据cart合并到计算状态,然后调用该事件的侦听器。 查看活动。

函数 function

库就绪时ACDL调用的函数。 使用它可安全地调用其他ACDL方法,即使库尚未加载:

window.adobeDataLayer.push(function(dl) {
  dl.addEventListener("cart add", function(event) {
    console.log("Added to cart:", event.eventInfo.sku);
  });
});

ACDL调用函数时,将数据层作为其参数,并将数据层作为this。 它不会将函数保留在数组中。 如果函数引发错误,则该错误会传播到调用push()的代码。 在加载库之前,还会出现错误,阻止ACDL处理队列的其余部分。 查看ACDL就绪时运行代码。

返回值 return

加载ACDL后,push()在将项添加到历史记录时返回数组的新长度。 当它不添加项时,例如当您只推送函数或无效项时,它返回undefined。

每次调用推送一个项目 one-item

您可以将多个项传递到一个push()调用,ACDL会按顺序处理它们。 但是,当一个调用组合了不同类型的项目时,历史记录可能会变得不一致。 例如,如果第一项是一个函数,ACDL会处理它后面的数据对象,但不会将其添加到历史记录中。 在单独的调用中推送每个项目。

项目无效 invalid

ACDL仅接受纯对象和函数。 如果推送任何其他值(例如字符串、数字、布尔值或数组),ACDL不会处理它并将以下错误记录到浏览器控制台:

The following item cannot be handled by the data layer because it does not have a valid format: "example"

推送null或undefined会引发TypeError。

NOTE
具有on和handler键或具有off键的对象不是数据。 ACDL会忽略它们,并且不会将它们添加到历史记录中。 要添加或删除侦听器,请使用addEventListener()和removeEventListener()。
recommendation-more-help
experience-platform-help-collection