Web 拡張機能のビュー

メモ

Adobe Experience Platform Launch は、Adobe Experience Platform のデータ収集テクノロジースイートとしてリブランドされています。 その結果、製品ドキュメント全体でいくつかの用語の変更がロールアウトされました。用語の変更点の一覧については、次のドキュメントを参照してください。

イベント、条件、アクション、データ要素の各タイプには、ユーザーが設定を指定できる表示が用意されています。 また、この拡張機能には最上位の拡張機能設定表示が含まれていて、拡張機能全体に対してグローバル設定を指定できます。表示の構築プロセスは、すべてのタイプの表示で同じです。

文書タイプの追加

HTML ファイルには doctype タグを必ず含めてください。 通常、これは、HTML ファイルを次で開始することを意味します。

<!DOCTYPE html>

タグ iframe スクリプトを含む

ビューの HTML に、次のタグ iframe スクリプトを含めます。

<script src="https://assets.adobedtm.com/activation/reactor/extensionbridge/extensionbridge.min.js"></script>

このスクリプトは、ビューがタグアプリケーションと通信できるようにする通信 API を提供します。

拡張ブリッジ通信 API での登録

iframe スクリプトが読み込まれたら、通信に使用するタグにいくつかのメソッドを指定する必要があります。window.extensionBridge.register を呼び出し、次のようにオブジェクトを渡します。

window.extensionBridge.register({
  init: function(info) {
    // Populate view with info.settings which will exist if the user is editing something
    // that was previously saved.
    if (info.settings) {
      document.getElementById('name').value = info.settings.name;
    }
  },
  validate: function() {
    // Return whether the view is valid.
    return document.getElementById('name').value.length > 0;
  },
  getSettings: function() {
    // Return user-provided settings.
    return {
      name: document.getElementById('name').value
    };
  }
});

各メソッドの内容は、特定の表示要件に合わせて変更する必要があります。

init

init メソッドは、ビューが iframe に読み込まれるとすぐに、タグによって呼び出されます。これには 1 つの引数(info)が渡されます。この引数は、次のプロパティを含むオブジェクトである必要があります。

プロパティ 説明
settings この表示で以前に保存された設定を含むオブジェクトです。 settingsnull の場合は、ユーザーが保存されたバージョンを読み込むのではなく、初期設定を作成していることを示しています。settings がオブジェクトの場合、ユーザーは以前に保持された設定の編集を選択しているので、これを使用して表示に入力する必要があります。
extensionSettings 拡張機能の設定表示から保存された設定です。これは、拡張機能の設定表示以外の表示の拡張機能設定にアクセスする場合に便利です。現在の表示が拡張機能の設定表示の場合は、settings を使用します。
propertySettings プロパティの設定を含むオブジェクトです。 このオブジェクトに何が含まれるかについて詳しくは、 turbine オブジェクトのガイド を参照してください。
tokens API トークンを含むオブジェクトです。 表示内から Adobe API にアクセスするには、通常 tokens.imsAccess 下の IMS トークンを使用する必要があります。このトークンは、アドビが開発した拡張機能に対してのみ使用できます。アドビが作成した拡張機能を代表するアドビの従業員の場合は、データ収集エンジニアリングチームにメールを送信し、拡張機能の名前を入力して、許可リストに追加できるようにしてください。
company 1 つのプロパティ orgId を含むオブジェクトです。これ自体は、Adobe Experience Cloud ID(24 文字の英数字文字列)を表します。
schema JSON スキーマ形式のオブジェクトです。このオブジェクトは拡張機能マニフェストから取得され、フォームの検証に役立つ場合があります。

表示は、この情報を使用してフォームのレンダリングと管理をおこなう必要があります。 info.settings を扱うだけで済むこともありますが、場合によってはその他の情報も指定する必要があります。

validate

validate メソッドは、ユーザーが 「保存」ボタンを押した後に呼び出されます。次のいずれかが返されます。

  • ユーザーの入力が有効かどうかを示すブール値。
  • ユーザーの入力が有効かどうかを示すブール値を使用して後で解決されるプロミス。

ライブラリモジュールがその入力に影響を与えるので、有効な入力であるかどうかを判断するのは、拡張機能開発者の責任です。

ユーザーの入力が無効な場合は、何を修正したらよいかをユーザーに知らせるために、表示内に入力した内容が無効であることを示します。

getSettings

getSettings メソッドは、ユーザーが 「保存」ボタンを押し、ビューの検証が完了した後に呼び出されます。この関数によって、次のいずれかの値が返されます。

  • ユーザー入力に基づく設定を含むオブジェクト。
  • ユーザー入力に基づく設定を含むオブジェクトを使用して後で解決されるプロミス。

この設定オブジェクトは、後でタグランタイムライブラリに発行されます。このオブジェクトの内容は自由に指定できます。オブジェクトは、JSON との間でシリアル化およびデシリアル化が可能である必要があります。関数や RegExp インスタンスなどの値はこれらの条件を満たさないので、使用できません。

共有表示の活用

window.extensionBridge オブジェクトには、タグで使用可能な既存のビューを利用するためのメソッドがいくつかあるので、ビュー内で再現する必要はありません。利用可能なメソッドを次に示します。

openCodeEditor

window.extensionBridge.openCodeEditor().then(function(code) { 
  console.log(code);
});

このメソッドを呼び出すと、ユーザーがコードのスニペットを編集できるモーダルが表示されます。ユーザーがコードの編集を終了すると、プロミスは更新されたコードを使用して解決されます。ユーザーが変更の保存を選択せずにコードエディターを閉じると、プロミスは解決されません。options オブジェクトは、次のような構造にする必要があります。

プロパティ 説明
code エディターに表示する必要があるコード。これは、通常、ユーザーが既存のコードを編集する際に表示されます。これを指定しない場合、コードエディターを開くと空の状態で表示されます。
language 編集するコードの言語。有効なオプションは javascripthtmlcssjson、および plaintext です。これを指定しない場合、javascript と見なされます。

openRegexTester

window.extensionBridge.openRegexTester().then(function(pattern) { 
  console.log(pattern);
});

このメソッドを呼び出すとモーダルが表示され、ユーザーはそこで正規表現パターンのテストと変更をおこなうことができます。ユーザーが正規表現の編集を終了すると、プロミスは更新された正規表現パターンで解決されます。ユーザーが変更の保存を選択せずに正規表現テスターを閉じた場合、プロミスは解決されません。options オブジェクトには次のプロパティが含まれている必要があります。

プロパティ 説明
pattern テスター内のパターンフィールドの初期値として使用する必要がある正規表現パターン。これは、通常、ユーザーが既存の正規表現を編集する際に表示されます。これを指定しない場合、パターンフィールドは最初、空の状態になります。
flags テスターで使用する必要がある正規表現フラグ。例えば、gi はグローバル一致フラグ、および大文字と小文字を区別しないフラグを示します。ユーザーは、これらのフラグをテスター内で変更することはできません。ただし、これらのフラグは、正規表現の実行時に拡張機能が使用する特定のフラグを示すために使用されます。これを指定しない場合、テスター内でフラグは使用されません。正規表現のフラグの詳細については、MDN の RegExp に関するドキュメントを参照してください。

一般的なシナリオとしては、ユーザーが正規表現の大文字と小文字の区別を切り替えることができる拡張機能があります。これをサポートするために、通常、拡張機能の拡張機能表示内にチェックボックスが表示されます。このチェックボックスをオンにすると、大文字と小文字の区別が無効になります(i フラグで表されます)。表示で保存される設定オブジェクトでは、正規表現を実行するライブラリモジュールが i フラグを使用する必要があるかどうかを知ることができるように、チェックボックスがオンになっているかどうかを表す必要があります。また、拡張機能ビューで正規表現テスターを開く際に、大文字と小文字の区別をしないチェックボックスがオンになっていれば、i フラグを渡す必要があります。これにより、ユーザーは、大文字と小文字を区別しないようにして正規表現を適切にテストできます。

openDataElementSelector

window.extensionBridge.openDataElementSelector().then(function(dataElement) { 
  console.log(dataElement);
});

このメソッドを呼び出すと、ユーザーがデータ要素を選択できるモーダルが表示されます。ユーザーがデータ要素の選択を完了すると、選択したデータ要素の名前でプロミスが解決されます(デフォルトでは、名前はパーセント記号で囲まれます)。ユーザーが変更の保存を選択せずに要素セレクターを閉じた場合、プロミスは解決されません。

options オブジェクトには、単一のブール値プロパティ(tokenize)を含める必要があります。このプロパティは、プロミスを解決する前に、選択したデータ要素の名前をパーセント記号で囲む必要があるかどうかを示します。これが有用な理由については、サポートされているデータ要素に関するセクションを参照してください。このオプションのデフォルト値は true です。

サポートされているデータ要素

ビューには、ユーザーがデータ要素を活用したいフォームフィールドが含まれている可能性があります。例えば、ユーザーが製品名を入力する必要があるテキストフィールドがビューに含まれている場合、ユーザーがフィールドにハードコードされた値を入力しても意味がない場合があります。代わりに、フィールドの値を動的にする(実行時に判断する)ことができますが、それにはデータ要素を使用します。

例えば、コンバージョンを追跡するビーコンを送信する拡張機能を構築するとします。また、ビーコンが送信するデータの 1 つが製品名であるとします。ユーザーがビーコンを設定できる拡張機能ビューには、製品名のテキストフィールドがありそうです。製品名はビーコンの送信元ページに依存する可能性が高いので、通常、Platform ユーザーが「Calzone Oven XL」のような静的な製品名を入力してもあまり意味はありません。これは、データ要素にとって重要です。

製品名の値に productname という名前のデータ要素を使用したい場合、ユーザーは両側にパーセント記号を付けてデータ要素名を入力できます(%productname%)。パーセンテージ(%)記号で囲まれたデータ要素名は、「データ要素トークン」と呼ばれます。Platform ユーザーは、この構成に精通していることがよくあります。さらに、拡張機能は、書き出す settings オブジェクト内にデータ要素トークンを保存します。設定オブジェクトは次のようになります。

{
  productName: '%productname%'
}

実行時に、設定オブジェクトをライブラリモジュールに渡す前に、設定オブジェクトがスキャンされ、データ要素トークンがそれぞれの値に置き換えられます。実行中、productname データ要素の値が Ceiling Medallion Pro 2000 であった場合、ライブラリモジュールに渡される設定オブジェクトは次のようになります。

{
  productName: 'Ceiling Medallion Pro 2000'
}

ユーザーがデータ要素を使用できる場所を示すために、またデータ要素を簡単に入力できるように、フィールドの横に次のようなアイコンボタンを追加することを強くお勧めします。

データ要素フィールド

ユーザーがテキストフィールドの横のボタンを選択すると、前述のようにwindow.extensionBridge.openDataElementSelector が呼び出されます。こうすることで、ユーザーは、名前とパーセント記号を入力する代わりに、表示されたデータ要素のリストから選択することができます。ユーザーがデータ要素を選択すると、選択したデータ要素の名前がパーセント記号で囲まれて表示されます(tokenize オプションを false に設定していない場合)。 その後、テキストフィールドに結果を入力するよう勧められます。

データ要素トークンの置き換え

前述のとおり、持続的な設定オブジェクトが次のように構成されている場合:

{
  productName: '%productname%'
}

また、実行時のproductname データ要素の値が Ceiling Medallion Pro 2000 の場合、ライブラリモジュールに渡される設定オブジェクトは次のようになります。

{
  productName: 'Ceiling Medallion Pro 2000'
}

設定オブジェクト内の値がパーセント記号 + 文字列 + パーセント記号​だけ​で構成されている場合、データ要素の値に置き換えられ、データ要素の値の型は変更されません

例えば、実行時のproductname の値が文字列ではなく数値 538 であった場合、ライブラリモジュールに渡される settings オブジェクトは次のようになります。

{
  productName: 538
}

ここでは、結果の 538 は数値で、文字列ではありません。同様に、実行時のデータ要素の値が関数であった場合(まれにですが使用されることがあります)、結果の設定オブジェクトは次のようになります。

{
  productName: function() { … }
}

一方、持続的な設定オブジェクトが次のような場合について考えてみます。

{
  productName: '%productname% - %modelnumber%'
}

この場合、productName の値は単一のデータ要素トークンではないので、結果は常に文字列になります。各データ要素トークンは、文字列にキャストされた後、それぞれの値に置き換えられます。実行時、productname の値が Ceiling Medallion Pro(文字列)で modelnumber2000(数値)であった場合、ライブラリモジュールに渡される結果の設定オブジェクトは次のようになります。

{
  productName: 'Ceiling Medallion Pro - 2000'
}

ナビゲーションの回避

拡張機能ビューとそれに含まれるデータ収集ユーザーインターフェイス間の通信は、拡張機能ビュー内でナビゲーションが発生していないことを条件としています。このため、拡張機能ビューには、ユーザーが拡張機能ビューの HTML ページから移動できる要素を追加しないでください。例えば、拡張機能ビュー内にリンクを指定する場合は、新しいブラウザーウィンドウが開くようにします(通常は、アンカータグに target="_blank" を追加します)。拡張機能ビュー内で form 要素を使用する場合は、フォームが送信されないことを確認します。フォーム内に button 要素があり、その要素に type="button" を追加しなかった場合、誤ってフォームが送信される可能性があります。 拡張機能ビュー内でフォームを送信すると、HTML ドキュメントが更新され、ユーザーエクスペリエンスが損なわれます。

このページ