扩展清单

注意

Adobe Experience Platform Launch已在Adobe Experience Platform中重新命名为一套数据收集技术。 因此,在产品文档中推出了一些术语更改。 有关术语更改的统一参考,请参阅以下文档

在扩展的基目录中,必须创建一个名为 extension.json 的文件。该文件包含有关扩展的重要详细信息,借助该信息,Adobe Experience Platform 可以正确使用扩展。其中的部分内容采用 npm 的 package.json 方式构成。

Hello World 扩展 GitHub 存储库中提供了 extension.json 示例。

扩展清单必须包含以下属性:

属性 描述
name 扩展的名称。此名称必须唯一,不同于所有其他 扩展,且必须符合命名规则标记将用作标识符,在发布扩展后不应更改此设置。
platform 用于此扩展的平台。目前唯一接受的值是 web
version 此扩展的版本。必须遵循 semver 版本控制格式。与 npm 版本字段规则相一致。
displayName 用户可读的扩展名称。这将向Platform用户显示。 无需提及“标记”或“扩展”;用户已经知道他们正在查看标记扩展。
description 有关扩展的描述。这将向Platform用户显示。 如果您的扩展使用户能够在其网站上实施您的产品,请说明产品的功能。无需提及“标记”或“扩展”;用户已经知道他们正在查看标记扩展。
iconPath(可选) 将为扩展显示的图标的相对路径。 不应以斜杠开头。必须引用一个扩展名为 .svg 的 SVG 文件。SVG应为正方形,并可以由Platform缩放。
author “author”是一个对象,其结构应如下所示:
  • name:扩展的作者姓名。或者,也可以在此使用公司名称。
  • url(可选):一个 URL,可以从中了解有关扩展作者的更多信息。
  • email(可选):扩展作者的电子邮件地址。
npm 作者字段规则相一致。
exchangeUrl(公共扩展的必需属性) 指向 Adobe Exchange 上列出的扩展的 URL。必须匹配以下模式:https://www.adobeexchange.com/experiencecloud.details.######.html
viewBasePath 包含您的所有视图及视图相关资源(HTML、JavaScript、CSS、图像)的子目录的相对路径。Platform 将在 Web 服务器上托管此目录,并从中加载 iframe 内容。这是必填字段,且不应以斜杠开头。例如,如果您的所有视图都包含在 src/view/ 中,则 viewBasePath 的值为 src/view/
hostedLibFiles(可选) 我们的许多用户更喜欢在自己的服务器上托管所有与标记相关的文件。 这可以提高用户在运行时对文件可用性的确定级别,而且用户可以轻松扫描代码以发现安全漏洞。如果扩展的库部分需要在运行时加载 JavaScript 文件,则建议使用此属性来列出这些文件。列出的文件将与标记运行时库一起托管。 随后,您的扩展将可以通过使用 getHostedLibFileUrl 方法检索到的 URL 来加载文件。

此选项包含一个数组,其中含有需托管的第三方库文件的相对路径。
main(可选) 运行时应执行的库模块的相对路径。

此模块将始终包含在运行时库中并得以执行。由于此模块始终包含在运行时库中,因此建议仅在绝对有必要的情况下才使用“main”模块,并保持其代码大小最小。

我们并不保证会首先执行此模块,其他模块有可能会在其之前执行。
configuration(可选) 此字段描述扩展的扩展配置部分。如果要求用户提供扩展的全局设置,则需要使用此字段。有关应当如何构建此字段的详细信息,请参阅附录
events(可选) 事件类型定义的数组。请参阅附录中的类型定义部分,以了解数组中每个对象的结构。
conditions(可选) 条件类型定义的数组。请参阅附录中的类型定义部分,以了解数组中每个对象的结构。
actions(可选) 操作类型定义的数组。请参阅附录中的类型定义部分,以了解数组中每个对象的结构。
dataElements(可选) 数据元素类型定义的数组。请参阅附录中的类型定义部分,以了解数组中每个对象的结构。
sharedModules(可选) 共享模块定义对象的数组。数组中的每个共享模块对象应当具有以下结构:
  • name:共享模块的名称。请注意,当从其他扩展引用共享模块时,将使用此名称,如共享模块中所述。此名称从不显示在任何用户界面中。此名称应当唯一,不同于扩展中其他共享模块的名称,且必须符合命名规则标记将用作标识符,在发布扩展后不应更改此设置。
  • libPath:共享模块的相对路径。不应以斜杠开头。必须引用一个扩展名为 .js 的 JavaScript 文件。

附录

命名规则

extension.json 中任意 name 字段的值必须符合以下规则:

  • 不得超过 214 个字符
  • 不得以点或下划线开头
  • 不能包含大写字母
  • 只能包含 URL 安全字符

npm 包名称规则相一致。

配置对象属性

配置对象应当具有以下结构:

属性 描述
viewPath 扩展配置视图的相对 URL。应当相对于 viewBasePath,且不应以斜杠开头。必须引用一个扩展名为 .html 的 HTML 文件。可接受查询字符串和片段标识符(哈希)后缀。
schema JSON 模式的对象,用来描述从扩展配置视图中保存的有效对象的格式。由于您是配置视图的开发者,因此您有责任确保所有保存的设置对象都与此模式匹配。当用户尝试使用 Platform 服务保存数据时,此模式还将用于执行验证。

模式对象的示例如下所示:
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delay": {
      "type": "number",
      "minimum": 1
    }
  },
  "required": [
    "delay"
  ],
  "additionalProperties": false
}
我们建议使用诸如 JSON 模式验证器之类的工具,手动测试您的模式。
transforms (可选) 一个对象数组,其中的每个对象表示当每个相应的设置对象发出到运行时库时所应执行的转换。有关为何需要转换以及如何使用转换的更多信息,请参阅转换部分。

类型定义

类型定义是用于描述事件、条件、操作或数据元素类型的对象。该对象包含以下属性:

属性 描述
name 类型的名称。此名称必须是扩展中的唯一名称。此名称必须符合命名规则标记将用作标识符,在发布扩展后不应更改此设置。
displayName 用于在数据收集用户界面中表示类型的文本。 该文本应当可供用户读取。
categoryName (可选) 提供后,displayName将列在数据收集UI的categoryName下。 所有具有相同 categoryName 的类型都将列在同一类别下。例如,如果您的扩展提供了 keyUp 事件类型和 keyDown 事件类型,并且它们都具有 categoryName Keyboard,那么当用户在构建规则时从可用事件类型列表中进行选择时,这两个事件类型都会列在 Keyboard 类别下。categoryName 的值应当可供用户读取。
libPath 类型库模块的相对路径。不应以斜杠开头。必须引用一个扩展名为 .js 的 JavaScript 文件。
viewPath (可选) 类型视图的相对 URL。应当相对于 viewBasePath,且不应以斜杠开头。必须引用一个扩展名为 .html 的 HTML 文件。可接受查询字符串和片段标识符(哈希)。如果您的类型库模块不使用用户的任何设置,则可以排除此属性,Platform 将改为显示一个占位符,以说明无需任何配置。
schema JSON 模式的对象,用来描述用户可保存的有效设置对象的格式。设置通常由用户使用数据收集用户界面来配置和保存。 在这些用例中,扩展的视图可采取必要步骤来验证用户提供的设置。另一方面,某些用户选择直接使用标记API,而无需任何用户界面的帮助。 此模式用于允许 Platform 正确验证用户保存的设置对象(不管是否使用了用户界面)是否采用了与运行时基于该设置对象执行操作的库模块相兼容的格式。

模式对象的示例如下所示:
{
  "$schema":"http://json-schema.org/draft-04/schema#"
  "type":"object",
  "properties":{
    "delay":{
      "type":"number",
      "minimum":1
    }
  },
  “必需”:[
    "delay"
  ],
  "additionalProperties":false
}
我们建议使用诸如 JSON 模式验证器之类的工具,手动测试您的模式。
transforms (可选) 一个对象数组,其中的每个对象表示当每个相应的设置对象发出到运行时库时所应执行的转换。有关为何需要转换以及如何使用转换的更多信息,请参阅转换部分。

转换

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

所有转换都需要一个 typepropertyPathtype 必须是 functionremovefile 之一,用于说明 Platform 应当对设置对象执行的转换。propertyPath是一个以句点分隔的字符串,用于告知标记在何处查找设置对象中需要修改的属性。 下面是一个设置对象及部分 propertyPath 的示例:

{
  foo: {
    bar: "A string",
    baz: [
      "A",
      "B",
      "C"
    ]
  }
}
  • 如果设置 propertyPathfoo.bar,则转换 "A string" 值。
  • 如果设置 propertyPathfoo.baz[],则转换 baz 数组中的每个值。
  • 如果设置 propertyPathfoo.baz,则转换 baz 数组。

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

警告

扩展 sandbox*tool 尚不支持在 propertyPath 属性中使用数组符号(例如,foo.baz[])。

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

函数转换

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

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

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

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

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

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

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

作为这种情况的解决方法,当用户代码发出到标记运行时库时,使用函数转换告知平台将用户代码包含在可执行函数中。 为了解决我们的示例问题,我们将在 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 的值已从设置对象中移除。

在此页面上