擴充功能資訊清單

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

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

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

附錄

命名規則

extension.json 內任何 name 欄位的值皆必須符合下列規則：

• 必須小於或等於 214 個字元
• 不得以點或底線開頭
• 不可包含大寫字母
• 只能包含適用於 URL 的字元

這些規則與 npm 套件名稱規則一致。

組態物件屬性

組態物件應有如下的結構：

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

類型定義

類型定義是物件，可用來說明事件、條件、動作或資料元素類型。此物件包含下列項目：

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

轉換

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

所有轉換都需要 type 和 propertyPath。type 必須是 function、remove 和 file 的其中之一，並說明 Platform 應將哪個轉換套用至設定物件。此 propertyPath 是以句點分隔的字串，用來告知標籤應在何處尋找需要在設定物件中修改的屬性。 以下是設定物件和某些 propertyPath 的範例：

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

• 如果您將 propertyPath 設為 foo.bar，則會轉換 "A string" 值。
• 如果您將 propertyPath 設為 foo.baz[]，則會轉換 baz 陣列中的每個值。
• 如果您將 propertyPath 設為 foo.baz，則會轉換 baz 陣列。

屬性路徑可使用陣列和物件標記法的任意組合，以在設定物件的任何層級套用轉換。

以下幾節將說明可用的轉換及其使用方式。

函數轉換

函式轉換可讓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"]
    }
  ]
}

• type 會定義應套用至設定物件的轉換類型。
• propertyPath 是以句點分隔的字串，用來向 Platform 指出應在何處尋找需要在設定物件中修改的屬性。
• parameters 是一個陣列，內含應包含在包裝函數簽章中的參數名稱。

當設定物件在標籤執行階段程式庫中發出時，它會轉換為以下內容：

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

• type 會定義應套用至設定物件的轉換類型。
• propertyPath 是以句點分隔的字串，用來向 Platform 指出應在何處尋找需要在設定物件中修改的屬性。

當設定物件在標籤執行階段程式庫中發出時，它會轉換為以下內容：

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

• type 會定義應套用至設定物件的轉換類型。
• propertyPath 是以句點分隔的字串，用來向 Platform 指出應在何處尋找需要在設定物件中修改的屬性。

當設定物件在標籤執行階段程式庫中發出時，它會轉換為以下內容：

{
  foo: {
  }
}

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