拡張機能マニフェスト

拡張機能の基本ディレクトリには、extension.json という名前のファイルを作成する必要があります。 このファイルには、Adobe Experience Platform が拡張機能を適切に使用できるようにするための重要な詳細が含まれています。 内容の一部は、npm のpackage.json の形式に従って構成されます。

extension.json の例は、Hello World 拡張機能 の GitHub リポジトリにあります。

拡張機能マニフェストは、次のプロパティで構成する必要があります。

付録

命名規則 naming-rules

extension.json 内の name フィールドの値は、次のルールに従う必要があります。

これらのルールは、npm パッケージ名ルールと一致します。

設定オブジェクトのプロパティ config-object

設定オブジェクトは、次のように構造化する必要があります。

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delay": {
      "type": "number",
      "minimum": 1
    }
  },
  "required": [
    "delay"
  ],
  "additionalProperties": false
}

タイプの定義 type-definitions

タイプの定義とは、イベント、条件、アクションまたはデータ要素の各タイプを記述するために使用されるオブジェクトです。 このオブジェクトは、次の内容で構成されます。

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delay": {
      "type": "number",
      "minimum": 1
    }
  },
  "required": [
    "delay"
  ],
  "additionalProperties": false
}

変換 transforms

特定のユースケースでは、拡張機能を使用するには、ビューから保存した settings オブジェクトを Platform で変換してから、タグのランタイムライブラリに発行する必要があります。 extension.json 内でタイプ定義を定義する際に、transforms プロパティを設定することで、これらの 1 つ以上の変換を実行するように要求できます。 transforms プロパティはオブジェクトの配列です。各オブジェクトは、実行する必要のある変換を表します。

すべての変換には type と propertyPath が必要です。 type は、function、remove、file のいずれかである必要があり、Platform が settings オブジェクトに適用する必要がある変換を示します。propertyPath はピリオドで区切られた文字列で、変更が必要なプロパティが settings オブジェクト内のどこにあるかをタグに伝えます。次に、設定オブジェクトと propertyPath の例を示します。

{
  foo: {
    bar: "A string",
    baz: [
      "A",
      "B",
      "C"
    ]
  }
}

プロパティパスは、配列とオブジェクト表記の組み合わせを使用して、 設定オブジェクトの任意のレベルで変換を適用できます。

以下の節では、利用可能な変換とその使用方法について説明します。

関数変換

関数変換を使用すると、Platform ユーザーが記述したコードを、発行されたタグのランタイムライブラリ内のライブラリモジュールによって実行できます。

「カスタムスクリプト」アクションタイプを指定するとします。 「カスタムスクリプト」アクションビューには、ユーザーがコードを入力できるテキスト領域があります。ユーザーがテキスト領域に次のコードを入力したとします。

console.log('Welcome, ' + username +'. This is ZomboCom.');

ユーザーがルールを保存すると、表示で保存される設定オブジェクトは次のようになります。

{
  foo: {
    bar: "console.log('Welcome, ' + username +'. This is ZomboCom.');"
  }
}

タグのランタイムライブラリ内でアクションを使用するルールが起動した場合、ユーザーのコードを実行し、ユーザー名を渡します。

設定オブジェクトがアクションタイプのビューから保存された時点で、ユーザーのコードは単なる文字列になります。 この動作には、JSON との間でコードを適切にシリアル化できるため利点もありますが、通常、コードは実行可能な関数ではなく、文字列としてタグのランタイムライブラリに発行されるため、欠点もあります。eval または Function コンストラクターを使用して、アクションタイプのライブラリモジュール内のコードを実行しようとしても、コンテンツのセキュリティポリシーによって実行がブロックされる可能性があるので、この操作は推奨されません。

この状況の回避策として、タグのランタイムライブラリでユーザーのコードが発行されたときに、関数変換を使用して、そのコードを実行可能な関数に含めるよう Platform に指示します。 この例の問題を解決するには、extension.json でタイプの定義の変換を次のように定義します。

{
  "transforms": [
    {
      "type": "function",
      "propertyPath": "foo.bar",
      "parameters": ["username"]
    }
  ]
}

settings オブジェクトがタグのランタイムライブラリで発行されると、次のように変換されます。

{
  foo: {
    bar: function(username) {
      console.log('Welcome, ' + username +'. This is ZomboCom.');
    }
  }
}

その後、ライブラリモジュールは、ユーザーのコードを含む関数を呼び出し、username 引数に渡すことができます。

ファイル変換

ファイル変換を使用すると、Platform ユーザーが記述したコードを、タグのランタイムライブラリとは別のファイルに発行できます。このファイルは、タグのランタイムライブラリと共にホストされ、必要に応じて、実行時に拡張機能で読み込むことができます。

「カスタムスクリプト」アクションタイプを指定するとします。 アクションタイプのビューには、ユーザーがコードを入力できるテキスト領域が表示される場合があります。 ユーザーがテキスト領域に次のコードを入力したとします。

console.log('This is ZomboCom.');

ユーザーがルールを保存すると、表示で保存される設定オブジェクトは次のようになります。

{
  foo: {
    bar: "console.log('This is ZomboCom.');"
  }
}

ユーザーのコードを、タグのランタイムライブラリ内ではなく別のファイルに配置する必要があります。 タグのランタイムライブラリ内でアクションを使用するルールが起動する場合、ドキュメントの本文にスクリプト要素を追加して、ユーザーのコードを読み込みます。この例の問題を解決するには、extension.json のアクションタイプの定義の変換を次のように定義します。

{
  "transforms": [
    {
      "type": "file",
      "propertyPath": "foo.bar"
    }
  ]
}

settings オブジェクトがタグのランタイムライブラリで発行されると、次のように変換されます。

{
  foo: {
    bar: "//launch.cdn.com/path/abc.js"
  }
}

この場合、foo.bar の値は URL に変換されています。 正確な URL は、ライブラリの構築時に決定されます。 ファイルには常に拡張子 .js が付き、JavaScript 対応の MIME タイプを使用して配信されます。 将来、他の MIME タイプのサポートが追加される可能性があります。

変換の削除

デフォルトでは、settings オブジェクトのすべてのプロパティは、タグのランタイムライブラリに発行されます。特定のプロパティが拡張機能の表示のみに使用される場合、特に機密情報（ 例：シークレットトークン）が含まれる場合は、変換の削除を使用して、情報がタグのランタイムライブラリに発行されないようにする必要があります。

新しいアクションタイプを指定するとします。 アクションタイプのビューでは、特定の API への接続を許可する秘密キーをユーザーが入力できる場合があります。 ユーザーが次のテキストを入力したとします。

ABCDEFG

ユーザーがルールを保存すると、表示で保存される設定オブジェクトは次のようになります。

{
  foo: {
    bar: "ABCDEFG"
  }
}

タグのランタイムライブラリ内に bar プロパティを含めないでください。 この例の問題を解決するには、extension.json のアクションタイプの定義の変換を次のように定義します。

{
  "transforms": [
    {
      "type": "remove",
      "propertyPath": "foo.bar"
    }
  ]
}

settings オブジェクトがタグのランタイムライブラリで発行されると、次のように変換されます。

{
  foo: {
  }
}

この場合、foo.bar の値は設定オブジェクトから削除されています。