擴充功能資訊清單

在擴充功能的基礎目錄中，您必須建立名為 extension.json 的檔案。此部分包含有關擴充功能的重要詳細資訊，可讓Adobe Experience Platform正確加以使用。 部分內容是以 npm package.json 的形式構成的。

例如，您可以在 Hello World 擴充功能 GitHub 存放庫中找到 extension.json。

擴充功能資訊清單必須包含下列項目：

附錄

命名規則 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

針對特定使用案例，擴充功能從檢視儲存的設定物件必須先由Platform進行轉換，才能發出至標籤執行階段程式庫中。 在 extension.json 中定義類型定義時，您可以設定 transforms 屬性，以要求進行一或多個這類轉換。transforms 屬性是一個物件陣列，其中每個物件分別代表應進行的轉換。

所有轉換都需要 type 和 propertyPath。type必須是function、remove和file其中之一，並說明Platform應將哪個轉換套用至設定物件。 propertyPath是以句點分隔的字串，用來告知標籤應在何處尋找需要在設定物件中修改的屬性。 以下是設定物件和某些 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 或函數建構函式在您動作類型的程式庫模組中執行程式碼，但由於內容安全性原則可能會阻礙執行，強烈建議不要採用此方式。

為因應此情況，請使用函式轉換，指示Platform在標籤執行階段程式庫內發出使用者的程式碼時，將其包裝在可執行的函式中。 為了解決此範例的問題，我們將在 extension.json 中定義類型定義的轉換，如下所示：

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

當設定物件在標籤執行階段程式庫中發出時，將會轉換為下列專案：

{
  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"
    }
  ]
}

當設定物件在標籤執行階段程式庫中發出時，將會轉換為下列專案：

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

在此案例中，foo.bar 的值已轉換為 URL。確切的 URL 將在建置程式庫時決定。檔案的副檔名將一律指定為 .js，且會使用 JavaScript 導向的 MIME 類型進行傳遞。未來我們可能會新增其他 MIME 類型的支援。

移除轉換

依預設，設定物件的所有屬性都會在標籤執行階段程式庫中發出。 如果某些屬性僅用於擴充功能檢視，尤其是其中包含敏感資訊時 (例如秘密代號)，您應該使用移除轉換來防止資訊發出至標籤執行階段程式庫中。

假設我們想要提供新的動作類型。動作類型的檢視可提供輸入區，讓使用者可在其中輸入允許連線至特定 API 的密鑰。我們假設使用者在輸入區中輸入了下列文字：

ABCDEFG

當使用者儲存規則時，檢視儲存的設定物件可能顯示如下：

{
  foo: {
    bar: "ABCDEFG"
  }
}

我們不想在標籤執行階段程式庫中包含屬性bar。 為了解決此範例的問題，我們將在 extension.json 中定義動作類型定義的轉換，如下所示：

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

當設定物件在標籤執行階段程式庫中發出時，將會轉換為下列專案：

{
  foo: {
  }
}

在此案例中，foo.bar 的值已從設定物件中移除。