Web 拡張機能のビュー
イベント、条件、アクション、データ要素の各タイプには、ユーザーが設定を指定できる表示が用意されています。 また、この拡張機能には最上位の拡張機能設定表示が含まれていて、拡張機能全体に対してグローバル設定を指定できます。表示の構築プロセスは、すべてのタイプの表示で同じです。
文書タイプの追加
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）が渡されます。この引数は、次のプロパティを含むオブジェクトである必要があります。
settingssettings が null の場合は、ユーザーが保存されたバージョンを読み込むのではなく、初期設定を作成していることを示しています。settings がオブジェクトの場合、ユーザーは以前に保持された設定の編集を選択しているので、これを使用して表示に入力する必要があります。extensionSettingssettings を使用します。propertySettingstokenstokens.imsAccess 下の IMS トークンを使用する必要があります。このトークンは、アドビが開発した拡張機能に対してのみ使用できます。アドビが作成した拡張機能をアドビ従業員が代表する場合は、データ収集エンジニアリングチームにメールを送信し、許可リストに追加できるように拡張機能の名前を指定してください。companyorgId を含むオブジェクトです。これ自体は、Adobe Experience Cloud ID（24 文字の英数字文字列）を表します。schema表示は、この情報を使用してフォームのレンダリングと管理をおこなう必要があります。 info.settings を扱うだけで済むこともありますが、場合によってはその他の情報も指定する必要があります。
validate
validate メソッドは、ユーザーが「保存」ボタンを押した後に呼び出されます。次のいずれかが返されます。
- ユーザーの入力が有効かどうかを示すブール値。
- ユーザーの入力が有効かどうかを示すブール値を使用して後で解決されるプロミス。
ライブラリモジュールがその入力に影響を与えるので、有効な入力であるかどうかを判断するのは、拡張機能開発者の責任です。
ユーザーの入力が無効な場合は、何を修正したらよいかをユーザーに知らせるために、表示内に入力した内容が無効であることを示します。
getSettings
getSettings メソッドは、ユーザーが「保存」ボタンを押し、ビューの検証が完了した後に呼び出されます。この関数によって、次のいずれかの値が返されます。
- ユーザー入力に基づく設定を含むオブジェクト。
- ユーザー入力に基づく設定を含むオブジェクトを使用して後で解決されるプロミス。
この設定オブジェクトは、後でタグランタイムライブラリに発行されます。このオブジェクトの内容は自由に指定できます。オブジェクトは、JSON との間でシリアル化およびデシリアル化が可能である必要があります。関数や RegExp インスタンスなどの値はこれらの条件を満たさないので、使用できません。
共有表示の活用
window.extensionBridge オブジェクトには、タグを通じて使用可能な既存のビューを利用できるメソッドがいくつかあるので、ビュー内で再現する必要はありません。利用可能なメソッドを次に示します。
openCodeEditor
window.extensionBridge.openCodeEditor().then(function(code) {
console.log(code);
});
このメソッドを呼び出すと、ユーザーがコードのスニペットを編集できるモーダルが表示されます。ユーザーがコードの編集を終了すると、プロミスは更新されたコードを使用して解決されます。ユーザーが変更の保存を選択せずにコードエディターを閉じると、プロミスは解決されません。options オブジェクトは、次のような構造にする必要があります。
codelanguagejavascript、html、css、json、および plaintext です。これを指定しない場合、javascript と見なされます。openRegexTester
window.extensionBridge.openRegexTester().then(function(pattern) {
console.log(pattern);
});
このメソッドを呼び出すとモーダルが表示され、ユーザーはそこで正規表現パターンのテストと変更をおこなうことができます。ユーザーが正規表現の編集を終了すると、プロミスは更新された正規表現パターンで解決されます。ユーザーが変更の保存を選択せずに正規表現テスターを閉じた場合、プロミスは解決されません。options オブジェクトには次のプロパティが含まれている必要があります。
patternflagsgi はグローバル一致フラグ、および大文字と小文字を区別しないフラグを示します。ユーザーは、これらのフラグをテスター内で変更することはできません。ただし、これらのフラグは、正規表現の実行時に拡張機能が使用する特定のフラグを示すために使用されます。これを指定しない場合、テスター内でフラグは使用されません。正規表現のフラグの詳細については、MDN の RegExp に関するドキュメントを参照してください。一般的なシナリオとしては、ユーザーが正規表現の大文字と小文字の区別を切り替えることができる拡張機能があります。これをサポートするために、通常、拡張機能の拡張機能表示内にチェックボックスが表示されます。このチェックボックスをオンにすると、大文字と小文字の区別が無効になります（
i フラグで表されます）。表示で保存される設定オブジェクトでは、正規表現を実行するライブラリモジュールが i フラグを使用する必要があるかどうかを知ることができるように、チェックボックスがオンになっているかどうかを表す必要があります。また、拡張機能表示で正規表現テスターを開く際に、大文字と小文字の区別をしないチェックボックスがオンになっていれば、i フラグを渡す必要があります。これにより、大文字と小文字の区別を無効にして、正規表現を適切にテストできます。openDataElementSelector open-data-element
window.extensionBridge.openDataElementSelector().then(function(dataElement) {
console.log(dataElement);
});
このメソッドを呼び出すと、ユーザーがデータ要素を選択できるモーダルが表示されます。ユーザーがデータ要素の選択を完了すると、選択したデータ要素の名前でプロミスが解決されます（デフォルトでは、名前はパーセント記号で囲まれます）。ユーザーが変更の保存を選択せずに要素セレクターを閉じた場合、プロミスは解決されません。
options オブジェクトには、1 つのブール値プロパティ tokenize を含める必要があります。このプロパティは、プロミスを解決する前に、選択したデータ要素の名前をパーセント記号で囲む必要があるかどうかを示します。これが有用な理由については、サポートされているデータ要素に関するセクションを参照してください。このオプションのデフォルト値は true です。
サポートされているデータ要素 supporting-data-elements
ビューには、ユーザーがデータ要素を活用するためのフォームフィールドが含まれている可能性があります。例えば、ユーザーが製品名を入力する必要があるテキストフィールドがビューに含まれている場合、ユーザーがフィールドにハードコードされた値を入力しても意味がない場合があります。代わりに、フィールドの値を動的にする（実行時に判断する）ことができますが、それにはデータ要素を使用します。
例えば、コンバージョンを追跡するビーコンを送信する拡張機能を構築するとします。また、ビーコンが送信するデータの 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（文字列）で modelnumber が 2000（数値）の場合、ライブラリモジュールに渡される結果の設定オブジェクトは次のようになります。
{
productName: 'Ceiling Medallion Pro - 2000'
}
ナビゲーションの回避
拡張機能ビューと、その拡張機能ビュー内でナビゲーションが発生していない場合、拡張機能ビューとそのデータ収集ユーザーインターフェイスとの間の通信は実行されます。このため、拡張機能ビューには、ユーザーが拡張機能ビューの HTML ページから移動できる要素を追加しないでください。例えば、拡張機能ビュー内にリンクを指定する場合は、新しいブラウザーウィンドウが開くようにします（通常は、アンカータグに target="_blank" を追加します）。拡張機能ビュー内で form 要素を使用する場合は、フォームが送信されないことを確認します。フォーム内に button 要素があり、その要素に type="button" を追加しなかった場合、誤ってフォームが送信される可能性があります。 拡張機能ビュー内でフォームを送信すると、HTML ドキュメントが更新され、ユーザーエクスペリエンスが損なわれます。