扩展清单
在扩展的基目录中,必须创建一个名为 extension.json
的文件。其中包含有关扩展的重要详细信息,借助这些信息,Adobe Experience Platform可以正确使用扩展。 其中的部分内容采用 npm 的 package.json
方式构成。
Hello World 扩展 GitHub 存储库中提供了 extension.json
示例。
扩展清单必须包含以下属性:
name
platform
web
。displayName
description
iconPath
(可选).svg
的 SVG 文件。SVG应为正方形,并且可以由Platform缩放。author
“author”是一个对象,其结构应如下所示:
name
:扩展的作者姓名。或者,也可以在此使用公司名称。url
(可选):一个 URL,可以从中了解有关扩展作者的更多信息。email
(可选):扩展作者的电子邮件地址。
与 npm 作者字段规则相一致。
exchangeUrl
(公共扩展的必需属性)https://www.adobeexchange.com/experiencecloud.details.######.html
。viewBasePath
src/view/
中,则 viewBasePath
的值为 src/view/
。hostedLibFiles
(可选)此选项包含一个数组,其中含有需托管的第三方库文件的相对路径。
main
(可选)此模块将始终包含在运行时库中并得以执行。由于此模块始终包含在运行时库中,因此建议仅在绝对有必要的情况下才使用“main”模块,并保持其代码大小最小。
我们并不保证会首先执行此模块,其他模块有可能会在其之前执行。
附录
命名规则 naming-rules
extension.json
中任意 name
字段的值必须符合以下规则:
- 不得超过 214 个字符
- 不得以点或下划线开头
- 不能包含大写字母
- 只能包含 URL 安全字符
与 npm 包名称规则相一致。
配置对象属性 config-object
配置对象应当具有以下结构:
viewPath
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
(可选)类型定义 type-definitions
类型定义是用于描述事件、条件、操作或数据元素类型的对象。该对象包含以下属性:
name
displayName
categoryName
(可选)displayName
将列在UI中的categoryName
下。 所有具有相同 categoryName
的类型都将列在同一类别下。例如,如果您的扩展提供了 keyUp
事件类型和 keyDown
事件类型,并且它们都具有 categoryName
Keyboard
,那么当用户在构建规则时从可用事件类型列表中进行选择时,这两个事件类型都会列在 Keyboard 类别下。categoryName
的值应当可供用户读取。libPath
.js
的 JavaScript 文件。viewPath
(可选)viewBasePath
,且不应以斜杠开头。必须引用一个扩展名为 .html
的 HTML 文件。可接受查询字符串和片段标识符(哈希)。如果您的类型库模块不使用用户的任何设置,则可以排除此属性,Platform将改为显示一个占位符,以说明无需任何配置。schema
JSON 模式的对象,用来描述用户可保存的有效设置对象的格式。设置通常由用户使用数据收集用户界面进行配置和保存。 在这些用例中,扩展的视图可采取必要步骤来验证用户提供的设置。另一方面,有些用户选择直接使用标记API,而不借助任何用户界面。 此架构的目的是允许Platform正确验证用户保存的设置对象(无论是否使用用户界面)是否采用了与运行时基于该设置对象执行操作的库模块兼容的格式。
模式对象的示例如下所示:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"delay": {
"type": "number",
"minimum": 1
}
},
"required": [
"delay"
],
"additionalProperties": false
}
我们建议使用诸如 JSON 模式验证器之类的工具,手动测试您的模式。
transforms
(可选)转换 transforms
对于某些特定用例,扩展要求在将从视图保存的设置对象发出到标记运行时库之前,先由Platform转换这些设置对象。 您可以通过在 extension.json
中定义类型定义时设置 transforms
属性,来要求执行一个或多个此类转换。transforms
属性是一个对象数组,其中的每个对象表示应当执行的转换。
所有转换都需要一个 type
和 propertyPath
。type
必须为function
、remove
和file
之一,并描述应将哪个转换平台应用于设置对象。 propertyPath
是一个以句点分隔的字符串,它告知标记在何处查找设置对象中需要修改的属性。 下面是一个设置对象及部分 propertyPath
的示例:
{
foo: {
bar: "A string",
baz: [
"A",
"B",
"C"
]
}
}
- 如果设置
propertyPath
为foo.bar
,则转换"A string"
值。 - 如果设置
propertyPath
为foo.baz[]
,则转换baz
数组中的每个值。 - 如果设置
propertyPath
为foo.baz
,则转换baz
数组。
属性路径可使用数组和对象符号的任意组合,在设置对象的任意级别应用转换。
propertyPath
属性中使用数组符号(例如,foo.baz[]
)。以下各部分介绍了一些可用的转换和使用这些转换的方式。
函数转换
函数转换允许库模块在所发出的标记运行时库中执行由Platform用户编写的代码。
假设我们希望提供一个“自定义脚本”操作类型。“自定义脚本”操作视图可能提供一个文本区域,用户可在其中输入一些代码。假设用户在该文本区域中输入了以下代码:
console.log('Welcome, ' + username +'. This is ZomboCom.');
当用户保存规则后,视图所保存的设置对象可能如下所示:
{
foo: {
bar: "console.log('Welcome, ' + username +'. This is ZomboCom.');"
}
}
当使用我们的操作的规则在标记运行时库中触发时,我们希望执行用户的代码并为其传递一个用户名。
在从操作类型的视图保存设置对象时,用户的代码仅为一个字符串。其好处是可以与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
的值已从设置对象中移除。