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