擴充功能資訊清單

在擴充功能的基礎目錄中，您必須建立名為 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正確序列化為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 的值已從設定物件中移除。

Business.Adobe.com 資源