SDK のインストール

Adobe Experience Platform Web SDKの使用方法は3つあります。

  1. Adobe Experience Platform Web SDKを使用するには、データ収集UIを使用することをお勧めします。
  2. Adobe Experience Platform Web SDKは、コンテンツ配信ネットワーク(CDN)でも使用できます。
  3. EcmaScript 5およびEcmaScript 2015(ES6)モジュールを書き出すNPMライブラリを使用します。

オプション1:タグ拡張機能のインストール

タグ拡張のドキュメントについては、launchのドキュメントを参照してください。

オプション2:事前にビルドされたスタンドアロンバージョンのインストール

事前にビルドされたバージョンは、CDNで使用できます。 CDN上のライブラリを直接ページで参照することも、独自のインフラストラクチャでダウンロードしてホストすることもできます。 縮小および非縮小形式で使用できます。 非縮小バージョンは、デバッグに役立ちます。

URL構造:https://cdn1.adoberesources.net/alloy/[VERSION]/alloy.min.jsまたはalloy.js (非縮小版)

以下に例を示します。

コードの追加

事前にビルドされたスタンドアロンバージョンには、ページに直接追加された「ベースコード」が必要です。 次の「ベースコード」を、HTMLの<head>タグ内のできる限り上位にコピーして貼り付けます。

<script>
  !function(n,o){o.forEach(function(o){n[o]||((n.__alloyNS=n.__alloyNS||
  []).push(o),n[o]=function(){var u=arguments;return new Promise(
  function(i,l){n[o].q.push([i,l,u])})},n[o].q=[])})}
  (window,["alloy"]);
</script>
<script src="https://cdn1.adoberesources.net/alloy/2.6.4/alloy.min.js" async></script>

「ベースコード」は、alloyという名前のグローバル関数を作成します。 この関数を使用して SDK を操作します。グローバル関数に別の名前を付ける場合は、alloy名前を次のように変更します。

<script>
  !function(n,o){o.forEach(function(o){n[o]||((n.__alloyNS=n.__alloyNS||
  []).push(o),n[o]=function(){var u=arguments;return new Promise(
  function(i,l){n[o].q.push([i,l,u])})},n[o].q=[])})}
  (window,["mycustomname"]);
</script>
<script src="https://cdn1.adoberesources.net/alloy/2.6.4/alloy.min.js" async></script>

この例では、グローバル関数の名前が alloy から mycustomname に変更されています。

重要

潜在的な問題を回避するため、1 文字以上の文字を含み、この名前は、window で既に見つかったプロパティの名前と競合しない名前を使用してください。

このベースコードは、グローバル関数を作成するだけでなく、サーバ上でホストされる外部ファイル(alloy.js)に含まれる追加のコードも読み込みます。デフォルトでは、このコードは非同期で読み込まれ、Web ページのパフォーマンスを可能な限り高めます。これは推奨される実装です。

Internet Explorer のサポート

このSDKは、非同期タスクの完了を伝える方法であるpromiseを使用します。 SDKで使用されるPromise実装は、Internet Explorerを除くすべてのターゲットブラウザーでネイティブにサポートされます。 Internet ExplorerでSDKを使用するには、window.Promise ポリフィルが必要です。

既に window.Promise がポリフィルされているかどうかを判断するには、次の手順を実行します。

  1. Internet ExplorerでWebサイトを開きます。
  2. ブラウザーのデバッグコンソールを開きます。
  3. コンソールに「window.Promise」とに入力し、Enter キーを押します。

undefined 以外が表示された場合は、既に window.Promise がポリフィルされている可能性があります。上記のインストール手順を完了した後に Web サイトを読み込むことで、window.Promise がポリフィルされているかどうかを判断する方法もあります。SDK が promise に関するエラーをスローした場合、window.Promise がポリフィルされていない可能性が高くなります。

window.Promiseのポリフィルが必要と判断した場合は、前述のベースコードの上に次のスクリプトタグを含めます。

<script src="https://cdn.jsdelivr.net/npm/promise-polyfill@8/dist/polyfill.min.js"></script>

このタグは、window.Promiseが有効なPromise実装であることを確認するスクリプトを読み込みます。

メモ

別のPromise実装を読み込む場合は、Promise.prototype.finallyをサポートしていることを確認してください。

JavaScript ファイルの同期読み込み

コードの追加で説明したように、WebサイトのHTMLにコピー&ペーストしたベースコードは、外部ファイルを読み込みます。 外部ファイルには、SDKのコア機能が含まれています。 このファイルの読み込み中に実行しようとしたコマンドは、キューに入れられ、ファイルの読み込み後に処理されます。 ファイルを非同期で読み込むことが、最もパフォーマンスの高いインストール方法です。

ただし、特定の状況では、ファイルを同期的に読み込むことが望ましい場合もあります(これらの状況に関する詳細は後で説明します)。これをおこなうと、外部ファイルが読み込まれて実行されるまで、HTML ドキュメントの残りの部分がブラウザーで解析およびレンダリングされなくなります。通常、プライマリコンテンツをユーザーに表示する前にこの遅延が発生するのはお勧めしませんが、状況によっては合理的な場合もあります。

非同期ではなく同期的にファイルを読み込むには、次に示すように、2 番目の script タグから async 属性を削除します。

<script>
  !function(n,o){o.forEach(function(o){n[o]||((n.__alloyNS=n.__alloyNS||
  []).push(o),n[o]=function(){var u=arguments;return new Promise(
  function(i,l){n[o].q.push([i,l,u])})},n[o].q=[])})}
  (window,["alloy"]);
</script>
<script src="https://cdn1.adoberesources.net/alloy/2.6.4/alloy.min.js"></script>

オプション3:NPMパッケージの使用

Adobe Experience Platform Web SDKは、NPMパッケージとしても使用できます。 🔗 NPMは、JavaScript用パッケージマネージャーです。NPMパッケージをインストールすると、Adobe Experience Platform Web SDK JavaScriptのビルドプロセスを制御できます。 NPMパッケージは、ブラウザーで実行するEcmaScriptバージョン5モジュールまたはEcmaScriptバージョン2015(ES6)モジュールを公開します。

npm install @adobe/alloy

Adobe Experience Platform Web SDKのNPMパッケージは、createInstance関数を公開します。 この関数は、インスタンスの作成に使用されます。 関数に渡されるnameオプションは、ログに使用されるプレフィックスを制御します。 パッケージの使用例を以下に示します。

ECMAScript 2015(ES6)モジュールとしてのパッケージの使用

import { createInstance } from "@adobe/alloy";
const alloy = createInstance({ name: "alloy" });
alloy("config", { ... });
alloy("sendEvent", { ... });
メモ

NPMパッケージは、CommonJSモジュールに依存しています。したがって、bundlerを使用する場合は、bundlerがCommonJSモジュールをサポートしていることを確認してください。 Rollupなど、一部のバンドラーには、CommonJSをサポートするプラグインが必要です。

ECMAScript 5モジュールとしてのパッケージの使用

var alloyLibrary = require("@adobe/alloy");
var alloy = alloyLibrary.createInstance({ name: "alloy" });
alloy("config", { ... });
alloy("sendEvent", { ... });

Internet Explorer のサポート

Adobe Experience Platform SDKは、非同期タスクの完了を伝える方法であるpromiseを使用します。 SDKで使用されるPromise実装は、Internet Explorerを除くすべてのターゲットブラウザーでネイティブにサポートされます。 Internet ExplorerでSDKを使用するには、window.Promise ポリフィルが必要です。

Promiseのポリフィルに使用できるライブラリの1つに、promise-polyfillがあります。 NPMを使用したインストール方法の詳細については、promise-polyfillのドキュメントを参照してください。

メモ

別のPromise実装を読み込む場合は、Promise.prototype.finallyをサポートしていることを確認してください。

このページ