安裝Adobe使用者端資料層

安裝Adobe Client Data Layer (ACDL)有兩個部分:

  1. 在推送到它的每個指令碼中建立資料層陣列,如此一來,無論是否已載入ACDL,您的程式碼都能運作。
  2. 使用其中一種安裝方法,每頁載入ACDL程式庫​一次。

建立資料層陣列 initialize

在任何推送至資料層的程式碼前新增下列行:

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

如果陣列不存在,此線條會建立陣列,如果存在,則會保留陣列。 將其納入推送至資料層的每個指令碼中,而不僅僅是第一個指令碼。 指令碼可依任何順序載入,而該行會確保每個指令碼推送至相同的陣列而不覆寫。

在此行之後,使用push()推送資料、事件和函式:

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

在ACDL載入之前,push()是標準的JavaScript陣列方法,而且陣列可作為佇列運作。 ACDL載入時,會依序處理已排入佇列的專案。 請參閱佇列和歷程記錄。

IMPORTANT
ACDL一律使用全域名稱adobeDataLayer。 資料庫不支援其他名稱。 標籤延伸模組可讓第二個名稱參考相同的資料層。

選擇安裝方法 methods

使用下列其中一種方法,在每個頁面上載入ACDL:

方法
使用時機
標籤延伸模組
您可以使用Adobe Experience Platform中的標籤。 擴充功能可載入ACDL。
指令碼標籤
您想要自行託管程式庫檔案,並將其新增至您的頁面範本。
npm
您可以使用套件組合來建置網站的JavaScript。
Adobe Experience Manager
您的網站使用AEM核心元件2.9.0或更新版本。

標籤延伸模組 tags

Adobe Client Data Layer標籤延伸模組會在您的標籤程式庫載入時載入ACDL,除非頁面已載入它。 您不需要將程式庫新增至頁面範本。 您的網站程式碼仍需要建立資料層陣列並推送資料。 請參閱設定Adobe Client Data Layer擴充功能。

指令碼標籤 script

從npm (請參閱npm)下載程式庫,並在您的網站上託管adobe-client-data-layer.min.js。 然後將其載入每個頁面的<head>,其中包含async和defer屬性:

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

支援async的瀏覽器會在下載後立即執行指令碼,而不會封鎖頁面。 由於ACDL會處理所有在載入前已排入佇列的事項,因此即使其他指令碼先推送至資料層,您的資料仍是安全的。

以下範例顯示一個頁面,其中內嵌指令碼和外部指令碼都會在ACDL載入前推送至資料層:

<!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>

外部指令碼/js/myscripts.js也會在推入之前建立陣列:

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

公用npm CDN (例如unpkg和jsDelivr)也提供程式庫檔案。 如果您從協力廠商CDN載入檔案,請在URL中釘選精確版本,這樣檔案就不會在您不知情的情況下變更。

npm npm

安裝套件:

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

套件包含位於dist/adobe-client-data-layer.min.js的瀏覽器指令碼。 請將該檔案複製到您的網站,然後以指令碼標籤載入該檔案,或將檔案匯入您的套件式JavaScript:

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

指令碼不會匯出任何內容。 執行時,它會設定window.adobeDataLayer。

NOTE
在ACDL 3.x中,匯入以上所示的檔案路徑。 3.x套件未定義進入點,因此import "@adobe/adobe-client-data-layer"失敗。

Adobe Experience Manager aem

AEM核心元件2.9.0和更新版本包含ACDL作為使用者端程式庫,以及核心元件推送資料和每個元件的事件。 請參閱搭配核心元件使用Adobe使用者端資料層。

如果您的AEM網站也使用ACDL標籤擴充功能,請關閉擴充功能的​ 載入Adobe使用者端資料層程式庫(如果沒有)選項,以便只有AEM載入程式庫。 ​請參閱設定Adobe Client Data Layer擴充功能。

僅載入程式庫一次 load-once

每頁載入一次ACDL。 如果載入第二個復本,系統會將下列警告記錄至瀏覽器主控台,而不會變更資料層:

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

第一個復本會持續執行,因此您的資料和監聽器仍可運作。 移除重複專案以避免額外下載。 當頁面範本和標籤擴充功能都載入程式庫時,重複專案很常見。

驗證安裝 verify

在載入ACDL的頁面上開啟瀏覽器的開發人員主控台,然後執行下列命令:

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

如果adobeDataLayer.version是undefined,則頁面尚未載入ACDL。 請參閱疑難排解。

從2.x升級至3.x upgrade

Adobe Experience Manager核心元件預設會載入ACDL 2.x,因此許多網站仍執行2.x。 在升級至3.x之前,請檢閱下列變更。 如需所有發行版本,請參閱GitHub 🔗上的發行說明。

ACDL 3.0已使用內建的瀏覽器功能取代其內部公用程式庫。 檔案的大小很多,但需求和某些合併行為已變更:

區域圖
2.x
3.x
瀏覽器需求
支援較舊的瀏覽器
需要structuredClone()和新式JavaScript。 檢視瀏覽器需求。
檔案大小(縮制)
大約33 KB
大約6 KB
將陣列推播至已容納陣列的索引鍵
依位置合併陣列。 正在將["c"]推移到["a", "b"]個結果中,結果為["c", "b"]。
取代陣列。 正在將["c"]推移到["a", "b"]個結果中,結果為["c"]。 請參閱陣列。
將物件推送至包含字串、數字或布林值的索引鍵
以物件取代值。
不會取代值。 請參閱變更值的型別。
getState()個路徑中的方括弧標籤法,例如items[0].sku
支援
不支援。 使用點標籤法,例如items.0.sku。 請參閱getState()。
npm套件進入點
import "@adobe/adobe-client-data-layer"載入程式庫。
匯入檔案路徑。 請參閱npm。

升級後測試實施,尤其是推送陣列或變更值型別的程式碼。

recommendation-more-help
experience-platform-help-collection