Adobe Client Data Layerのインストール

Adobe Client Data Layer (ACDL)のインストールには、次の2つの部分があります。

  1. ACDLがまだ読み込まれていなくてもコードが機能するように、プッシュするすべてのスクリプトでデータ レイヤー配列​を作成します。
  2. ACDL ライブラリ​をページごとに1回、いずれかの​ インストール方法を使用して読み込みます。

データレイヤー配列の作成 initialize

データレイヤーにプッシュするコードの前に次の行を追加します。

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

この行は、存在しない場合は配列を作成し、存在する場合は保持します。 最初のレイヤーだけでなく、データレイヤーにプッシュするすべてのスクリプトに含めます。 スクリプトは任意の順序で読み込むことができ、行は各スクリプトが上書きすることなく同じ配列にプッシュすることを確認します。

この行の後、データ、イベント、および関数をpush()でプッシュします。

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

ACDLが読み込まれるまで、push()は標準のJavaScript配列方式であり、配列はキューとして機能します。 ACDLが読み込まれると、キューに入った項目が順番に処理されます。 ​ キューと履歴を参照してください。

IMPORTANT
ACDLは常にグローバル名adobeDataLayerを使用します。 ライブラリは他の名前をサポートしていません。 ​ タグ拡張機能は、2番目の名前を同じデータレイヤーを参照するように設定できます。

インストール方法の選択 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をホストします。 次に、asyncとdeferの両方の属性を持つ各ページの<head>に読み込みます。

<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 } });

unpkgやjsDelivrなどのパブリック npm CDNは、ライブラリファイルも提供します。 サードパーティの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 Client Data Layerの使用を参照してください。

AEM サイトでACDL タグ拡張機能も使用している場合は、拡張機能の「不在の場合はAdobe クライアントデータレイヤーライブラリを読み込む」オプションをオフにして、AEMのみがライブラリを読み込めるようにします。 Adobe Client Data Layer拡張機能の設定を参照してください。

ライブラリを1回だけ読み込む load-once

ページごとに1回ACDLを読み込みます。 2番目のコピーが読み込まれた場合、ブラウザーコンソールに次の警告が記録され、データレイヤーは変更されません。

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"]になります。 配列を参照してください。
文字列、数値、またはブール値を保持するキーにオブジェクトをプッシュする
値をオブジェクトに置き換えます。
は値を置き換えません。 値の型の変更を参照してください。
items[0].skuなど、getState() パスの角括弧の表記法
対応
サポートされていません。 items.0.skuなどのドット表記法を使用します。 getState()を参照してください。
npm パッケージエントリポイント
import "@adobe/adobe-client-data-layer"がライブラリを読み込みます。
ファイルパスを読み込みます。 npmを参照してください。

アップグレード後に実装をテストします。特に、配列をプッシュしたり、値のタイプを変更したりするコードをテストします。

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