扩展清单

在扩展的基目录中，必须创建一个名为 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

对于某些特定用例，扩展要求在将从视图保存的设置对象发出到标记运行时库之前，先由Experience Platform转换这些设置对象。 您可以通过在 extension.json 中定义类型定义时设置 transforms 属性，来要求执行一个或多个此类转换。 transforms 属性是一个对象数组，其中的每个对象表示应当执行的转换。

所有转换都需要一个 type 和 propertyPath。 type必须为function、remove和file之一，并说明Experience Platform应将哪个转换应用于设置对象。 propertyPath是一个以句点分隔的字符串，它告知标记在何处查找设置对象中需要修改的属性。 下面是一个设置对象及部分 propertyPath 的示例：

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

属性路径可使用数组和对象符号的任意组合，在设置对象的任意级别应用转换。

以下各部分介绍了一些可用的转换和使用这些转换的方式。

函数转换

函数转换允许库模块在所发出的标记运行时库中执行由Experience Platform用户编写的代码。

假设我们希望提供一个“自定义脚本”操作类型。 “自定义脚本”操作视图可能提供一个文本区域，用户可在其中输入一些代码。 假设用户在该文本区域中输入了以下代码：

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

当用户保存规则后，视图所保存的设置对象可能如下所示：

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

当使用我们的操作的规则在标记运行时库中触发时，我们希望执行用户的代码并为其传递一个用户名。

在从操作类型的视图保存设置对象时，用户的代码仅为一个字符串。 其好处是可以与JSON正确进行双向序列化；不过，这种类型也存在弊端，因为它通常会作为字符串而非可执行函数发出到标记运行时库中。 尽管您可以尝试使用 eval 或 Function 构造函数在您的操作类型库模块中执行代码，但是由于内容安全策略可能会阻止代码执行，因此我们强烈建议您不要采取此操作。

作为这种情况的临时应对方法，当用户代码发出到标记运行时库时，使用函数转换告知Experience Platform将用户代码包含在可执行函数中。 为了解决我们的示例问题，我们将在 extension.json 的类型定义中定义转换，如下所示：

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

当设置对象发出到标记运行时库时，它将转换为以下内容：

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

接下来，您的库模块可调用包含用户代码的函数，并在 username 参数中传递。

文件转换

文件转换允许将Experience 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 的值已从设置对象中移除。