扩展清单

在扩展的基目录中，必须创建一个名为 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 或 Function 构造函数在您的操作类型库模块中执行代码，但是由于内容安全策略可能会阻止代码执行，因此我们强烈建议您不要采取此操作。

作为这种情况的解决方法，当用户的代码发出到标记运行时库时，使用函数转换告知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 资源