エンドツーエンドテストのアップロードと実装

メモ

Adobe Experience Platform Launchは、Experience Platformのデータ収集テクノロジーのスイートとしてリブランドされています。 これらの変更は、今後数週間以内にすべての製品ドキュメントで公開される予定です。 用語の変更点の統合的な参照については、次のドキュメントを参照してください。

拡張機能のテストでは、Adobe Experience Platform Launch API やコマンドラインツールを使用して拡張機能パッケージをアップロードし、Platform Launch UI を使用して拡張機能パッケージをプロパティにインストールして、Platform Launch ライブラリとビルド内でその機能を確認します。

このドキュメントでは、拡張機能のエンドツーエンドテストの実装方法について説明します。

メモ

このガイドは、Node.jsおよびnpmがインストールされ使用可能な状態でMacOSを使用していることを前提としています。

拡張機能の検証

チームが拡張機能のパフォーマンスと Sandbox ツールに表示される結果に満足したら、拡張機能パッケージを Platform Launch にアップロードする準備は完了です。

アップロードする前に、必須フィールドまたは設定が存在することを確認してください。例えば、最低でも拡張機能マニフェスト拡張機能の設定表示ライブラリモジュールを確認することをお勧めします。

具体的な例としては、ロゴファイルが挙げられます。extension.json ファイルに "iconPath": "example.svg", 行を追加して、そのロゴ画像ファイルをプロジェクトに含めます。これは、Platform Launch 内の拡張機能に表示されるアイコンへの相対パスです。先頭にスラッシュを配置することはできません。拡張子が .svg の SVG ファイルを参照する必要があります。SVG は、正方形にレンダリングされると通常どおりに表示され、ユーザーインターフェイスで拡大縮小できます。詳しくは、「How to Scale SVG(SVG の拡大・縮小方法)」を参照してください。

メモ

公開拡張機能の場合は、項目と Exchange 用リストへのリンクを extension.json に含めてください。拡張機能マニフェストには、Exchange 用リストの URL を指す "exchangeUrl":"https://www.adobeexchange.com/experiencecloud.details.12345.html" のようなエントリを含める必要があります。

Adobe I/O 統合環境の作成

API またはコマンドラインツールを使用するには、Adobe I/O のテクニカルアカウントが必要です。I/O コンソールでテクニカルアカウントが作成され、アップローダツールを使用して拡張機能パッケージがアップロードされます。

Platform Launch で使用するテクニカルアカウントの作成については、アクセストークンのガイドを参照してください。

重要

Adobe I/O で統合を作成するには、Experience Cloud 組織管理者または Experience Cloud 組織開発者である必要があります。

統合を作成できない場合は、適切な権限を持っていない可能性があります。その場合は、組織管理者に手順を完了してもらうか、自身で手順を実行できるよう開発者として割り当ててもらうように依頼します。

拡張機能パッケージのアップロード

資格情報の問題を解決したら、エンドツーエンドで拡張機能パッケージのテストを行うことができます。

拡張機能パッケージを初めてアップロードすると、development の状態になります。つまり、自身の Platform Launch の会社と、拡張機能の開発用とマークされた Platform Launch プロパティでのみ表示できます(詳細については後述)。

ここでは、.zip パッケージが含まれているディレクトリ内のコマンドラインに戻ります。

npx @adobe/reactor-uploader

npx:npm パッケージをダウンロードして実行できます。実際にはこのパッケージをコンピューターにインストールする必要はありません。これは、アップローダを実行する最も簡単な方法です。

アップローダでは、いくつかの情報を入力するように求められます。テクニカルアカウント ID、API キー、およびその他の情報は、Adobe I/O コンソールから取得できます。I/O コンソールの統合ページに移動します。ドロップダウンから正しい組織を選択し、適切な統合を見つけて、「表示」を選択します。

  • 秘密鍵へのパス:/path/to/private.keyこれは、前述の手順 2 で秘密鍵を保存した場所です。
  • 組織 ID:先ほど開いた I/O コンソールの概要ページからコピーして貼り付けます。
  • テクニカルアカウント ID:I/O コンソールからコピーして貼り付けます。
  • API キー:I/O コンソールからコピーして貼り付けます。
  • クライアント暗号鍵:I/O コンソールからコピーして貼り付けます。
  • アップロードする拡張機能パッケージへのパス:/path/to/extension_package.zip.zip パッケージを含むディレクトリ内からアップローダを呼び出す場合は、パスを入力する代わりに、リストからアップローダを選択するだけで済みます。

拡張機能パッケージがアップロードされ、アップローダによって拡張パッケージの ID が提供されます。

メモ

アップロード時またはパッチ適用時に、拡張機能パッケージは保留状態になりますが、システムによりパッケージが非同期で抽出されデプロイされます。この処理がおこなわれている間に、API を使用してその状態の extension_package ID をポーリングできます。Platform Launch 内では、カタログ内の拡張機能カードが「保留」とマークされます。

メモ

アップローダを頻繁に実行する予定がある場合、毎回これらの情報を入力するのが負担になる場合があります。これらは、コマンドラインから引数として渡すこともできます。詳細については、NPM ドキュメントのコマンドラインの引数に関する節を参照してください。

開発プロパティの作成

Platform Launch にログインすると、最初にプロパティ画面が表示されます。プロパティは、デプロイするタグのコンテナであり、1 つまたは複数のサイトで使用できます。

ここには「test」プロパティが表示されていますが、初めてログインしたときには、画面にプロパティは表示されません。新しいプロパティを作成するには、「新規プロパティ」をクリックします。名前と URL を入力します。拡張機能をテストするテストサイトまたはページの URL を使用したい場合があります。このドメインフィールドは、一部の拡張機能や、コア拡張機能を使用した条件で使用できます(詳細については後述)。 localhost は動作しないので、localhost URL を使用している場合は、このテストに example.com のような任意の値を使用してください。

このプロパティを拡張機能の開発テストに使用するので、「詳細オプション」を展開して「拡張機能の開発用に設定」チェックボックスをオンにする必要があります。

下部の「保存」を選択して、新しいプロパティを保存します。

プロパティ画面に戻ります。作成したプロパティの名前を選択します。これは、プロパティの概要画面です。ここでは多くの作業はおこないませんが、システムの各領域へのリンクがあり、上部にグローバルナビゲーションリンクがあります。

拡張機能のインストール

このプロパティに拡張機能をインストールするには、上部のメインナビゲーションリンクにある「 拡張機能」リンクをクリックします。

この​インストール済み​画面に、コア​拡張機能が表示されます。コア拡張機能には、Platform Launch 内のすべてのタグ管理機能が含まれています。拡張機能を追加するには、「 カタログ」を選択します。

カタログには、使用可能な各拡張機能に対応するカードアイコンが表示されます。拡張機能がカタログに表示されない場合は、前述のアドビ管理コンソールの設定の節と、拡張機能パッケージの作成の節の手順を最初に実行してください。また、Platform Launch が初期処理を完了していない場合は、拡張機能パッケージが「保留」と表示される場合があります。

すべての操作を正しく実行したと確信しているにもかかわらず、カタログに「保留」または「失敗」の拡張機能パッケージが表示されない場合は、API を直接実行して拡張機能パッケージのステータスを確認できます。 詳しくは、API ドキュメントの ExtensionPackage の取得に関する記事を参照してください。

拡張機能パッケージの処理が完了すると、このカードには「インストール」ボタンが表示され、選択できるようになります。

クリックすると、拡張機能のために構築した設定画面が表示されます(ある場合)。 拡張機能の設定に必要な情報を追加し、下部にある「保存」を選択します。拡張機能に設定がない場合は、「インストール」を選択するとすぐにインストールされます。

以下は、Facebook の拡張機能の例です。

これで、コア拡張機能と拡張機能が設定された「インストール済み」拡張機能の画面が表示されます。

拡張機能をテストするためのリソースを作成する

拡張機能は、Platform Launch でユーザーに新しい機能を提供します。 これらの機能は、ほとんどの場合、データ要素やルールビルダーに表示されます。 次に、これらの両方の領域について説明します。

データ要素

データ要素が Platform Launch に存在し、ユーザーが値を永続化できるようにします。 各データ要素は、ソースデータへのマッピングまたはポインターです。 単一のデータ要素は、クエリ文字列、URL、Cookie 値、JavaScript 変数などにマッピングできる変数です。

拡張機能では、必要に応じてデータ要素タイプを定義し、拡張機能を動作させることも、ユーザーにとっての利便性を考慮して定義することもできます。 拡張機能でデータ要素タイプが指定されると、新しいデータ要素を作成画面のユーザー用のドロップダウンリストに表示されます。

ユーザーが「拡張機能」ドロップダウンから拡張機能を選択すると、「データ要素タイプ」ドロップダウンに、拡張機能から提供されたデータ要素タイプが入力されます。 次に、ユーザーは各データ要素をソース値にマップできます。その後、データ要素の変更イベントまたはカスタムコードイベントでルールを作成する際にデータ要素を使用して、ルールの実行をトリガーできます。 データ要素は、データ要素の条件や、ルール内の他の条件、例外、アクションでも使用できます。

データ要素を作成したら(マッピングを設定します)、ユーザーは、データ要素を参照するだけでソースデータを参照できます。 値のソースが変更された場合(サイトの再設計など)、ユーザーは Platform Launch で 1 回のみマッピングを更新する必要があり、すべてのデータ要素が新しいソース値を自動的に受け取ります。

ルール

上部のナビゲーションで「ルール」リンクを選択し、「ルールを追加」を選択します。

まず、ルールに名前を付けます。どのような名前でもかまいません。新しいルールを作成画面は、if-then ステートメントのように設定されます。

イベントが発生し、条件が満たされて例外がない場合は、アクションがトリガーされます。このようなフローは、イベント、条件、例外、データ要素、またはアクションを作成または活用できる拡張機能にも存在します。

Facebook の例を続けて、サイトでページが読み込まれるたびにイベントを追加します。

Window Loaded イベントタイプを使用すると、サイトでページが読み込まれたときに、このルールがトリガーされます。 「保存」を選択します。この例では、サイト上の任意のページに対してこのルールをトリガーしたい場合、「条件」と「例外」をスキップします。これは、「グローバル」な読み込み時のルールのようなものです。

「アクション」の下にある「追加」を選択します。アクションの設定画面では、操作する拡張機能と、このルールがトリガーされたときに実行するアクションを選択できます。 「拡張機能」の下の「Facebook ピクセル」を選択し、「アクションタイプ」の下の「ページ表示を送信」を選択します。

下部の「 変更を保持」を選択し、次の画面で「ルールを保存」を選択します。拡張機能をテストする場合、拡張機能によって提供される任意のイベントや条件などを任意の数のルールで選択できます。

変更を公開する

メインナビゲーションで「公開」を選択し、「新しいライブラリを追加」リンクを選択します。

ライブラリは、拡張機能、データ要素、ルールの相互のやり取り、およびWeb サイトとやり取りする方法を示す命令のセットです。ライブラリはビルドにコンパイルされます。ライブラリには、必要に応じて、一度に作成またはテストできる数の変更を含めることができます。

新しいライブラリを作成画面で、名前を追加し、環境を選択します。 Platform Launch は、Development というわかりやすい名前のデフォルトの開発環境を提供しているので、その環境を環境リストから選択します。 ここでは、利用可能なすべてのリソースを追加するので、「変更したすべてのリソースを追加」をクリックします。

メモ

リソースをライブラリに追加する場合、追加時点のそのリソースのスナップショットが作成され、ライブラリに追加されます。後でリソースに変更を加える場合(必要な修正の結果など)は、ライブラリを更新して、リソースに対する最新の変更を含める必要もあります。「変更したすべてのリソースを追加」ボタンもこの操作に役立ちます。

次に、下部の「保存」を選択します。この dev ライブラリにすべての変更が加えられたので、ビルドを開始します。

ビルドプロセスが完了すると、ライブラリ名の横に緑色の​成功​インジケーターが表示されます。

これで、Platform Launch ライブラリが公開され、使用可能な状態になりました。次に、テストページでこのライブラリを探すように指示して、ブラウザーでエンドユーザーの動作をテストできるようにする必要があります。

テストサイトに Platform Launch をインストールする

インストール手順は「環境」タブで利用できるので、そこに移動します。

このページには、利用可能なすべての環境が表示され、さらに多くの環境を作成できます。 ライブラリを開発環境に公開したので、「開発」行の「インストール」列のボックスアイコンを選択して、その環境のインストール手順を取得します。

開発環境のインストール手順を表示しています。ここで必要なことは、ボックスの <script> タグをコピーするだけなので、「コピー」ボタンを選択します。

この単一の <script> タグをドキュメントまたはサイトテンプレートの <head> セクション内に配置すると、インストールが完了します。 次に、テストサイトにアクセスして、公開済みの Platform Launch ライブラリの動作をテストします。

テスト

テストページまたはサイトで拡張機能を検証する際に役立つコンソールコマンドがいくつかあります。

  • _satellite.setDebug(true); により Platform Launch がデバッグモードになり、有用なログステートメントがコンソールに出力されます。
  • _satellite._container オブジェクトには、ビルド、データ要素、ルール、拡張機能に関する詳細など、デプロイ済みのライブラリに関するあらゆる有用な情報が含まれています。

最終的には、デプロイ済みライブラリの機能をテストし、拡張機能パッケージ内に記述したコードが Platform Launch によってライブラリにコンパイルされたときに、期待どおりに動作することを確認します。

拡張機能パッケージに加える必要のある変更を見つけた場合、その繰り返し処理は開発プロセスと似ています。

  1. プロジェクト内のコードに変更を加えます。
  2. サンドボックスツールを使用して変更を検証します。
  3. Packager ツールを使用して新しい .zip パッケージを作成します。
  4. アップローダツールを使用して新しい .zip パッケージをアップロードします。最初のアップロードでは、上記と同じ手順に従うことができますが、今回は開発モードで同じ名前の拡張機能パッケージが既に存在するため、新しいパッケージを作成する代わりに、このパッケージがもう 1 つのパッケージを上書きします。資格情報を何度も繰り返し入力しないようにして時間を節約したい場合は、reactor-uploader のドキュメントを参照して、コマンドラインで引数を渡すことができます。
  5. 今回はインストール手順をスキップできます。
  6. リソースを変更します。拡張機能コンポーネントの設定を変更した場合は、Platform Launch UI でこれらのリソースを更新する必要があります。
  7. ライブラリに最新の変更を追加して、ビルドを再度実行する。
  8. さらにテストを実行する。

このページ