Manifiesto de extensión
En el directorio base de la extensión debe crear un archivo llamado extension.json
. Contiene detalles esenciales sobre su extensión que permiten a Adobe Experience Platform consumirla correctamente. Algunos de los contenidos se forman siguiendo npm package.json
.
Se puede encontrar un ejemplo extension.json
en el repositorio Hello World extension de GitHub.
Un manifiesto de extensión debe constar de lo siguiente:
name
platform
web
.version
displayName
description
iconPath
(Opcional).svg
. El SVG debe ser cuadrado y escalable por Platform.author
El autor es un objeto que debe estructurarse de la siguiente manera:
name
: nombre del autor de la extensión. También puede utilizar el nombre de la compañía aquí.url
(opcional): dirección URL donde puede obtener más información sobre el autor de la extensión.email
(opcional): dirección de correo electrónico del autor de la extensión.
Esto es coherente con las reglas de npm author field.
exchangeUrl
(necesario para extensiones públicas)https://www.adobeexchange.com/experiencecloud.details.######.html
.viewBasePath
src/view/
, el valor de viewBasePath
sería src/view/
.hostedLibFiles
(Opcional)Esta opción contiene una matriz con rutas relativas de archivos de biblioteca de terceros que deben alojarse.
main
(Opcional)Este módulo siempre se incluirá en la biblioteca de tiempo de ejecución y se ejecutará. Debido a que el módulo siempre se incluye en la biblioteca de tiempo de ejecución, recomendamos utilizar únicamente un módulo "principal" cuando sea absolutamente necesario y mantener un código mínimo.
No se garantiza que este módulo se ejecute primero, ya que otros módulos pueden ejecutarse antes.
configuration
(Opcional)events
(Opcional)conditions
(Opcional)actions
(Opcional)dataElements
(Opcional)sharedModules
(Opcional)Una matriz de objetos de definición de módulo compartidos. Cada objeto de módulo compartido de la matriz debe estructurarse de la siguiente manera:
name
: nombre del módulo compartido. Tenga en cuenta que este nombre se utilizará al hacer referencia a módulos compartidos de otras extensiones como se describe en Módulos compartidos. Este nombre nunca se muestra en ninguna interfaz de usuario. Debe ser diferente a los nombres de otros módulos compartidos en la extensión y debe cumplir con las reglas de nomenclatura. Las etiquetas lo utilizan como identificador y no debe cambiarse después de publicar la extensión.libPath
: ruta relativa al módulo compartido. No debe comenzar con una barra oblicua. Debe hacer referencia a un archivo JavaScript con una extensión.js
.
Apéndice
Reglas de nomenclatura naming-rules
El valor de cualquier name
campo interno extension.json
debe cumplir con las siguientes reglas:
- Debe tener un máximo de 214 caracteres
- No debe comenzar con punto o guion bajo.
- No debe contener letras mayúsculas.
- Solo debe contener caracteres seguros para URL.
Satisfacen las reglas de npm package name.
Propiedades del objeto de configuración config-object
El objeto de configuración debe estructurarse de la siguiente manera:
viewPath
viewBasePath
y no debe comenzar con una barra oblicua. Debe hacer referencia a un archivo HTML con una extensión .html
. Se aceptan los sufijos de cadena de consulta y de identificador de fragmento (hashes).schema
Un objeto de esquema JSON que describe el formato de un objeto válido que se está guardando desde la vista de configuración de la extensión. Dado que usted es el desarrollador de la vista de configuración, es su responsabilidad asegurarse de que cualquier objeto de configuración guardado coincida con este esquema. Este esquema también se utilizará para la validación cuando los usuarios intenten guardar datos mediante los servicios de Platform
A continuación, se muestra un objeto de esquema de ejemplo:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"delay": {
"type": "number",
"minimum": 1
}
},
"required": [
"delay"
],
"additionalProperties": false
}
Recomendamos utilizar una herramienta como JSON Schema validator para probar manualmente el esquema.
transforms
(Opcional)Definiciones de tipo type-definitions
Una definición de tipo es un objeto que se utiliza para describir un evento, una condición, una acción o un tipo de elemento de datos. El objeto consta de lo siguiente:
name
displayName
categoryName
(Opcional)displayName
se enumerará en categoryName
en la interfaz de usuario de inicio de Todos los tipos que tengan el mismo categoryName
se enumerarán en la misma categoría. Por ejemplo, si la extensión proporcionaba un tipo de evento keyUp
y un tipo de evento keyDown
y ambos tenían un categoryName
de Keyboard
, ambos tipos de evento se enumerarían en la categoría de teclado mientras el usuario seleccionaba entre la lista de tipos de evento disponibles al crear una regla. El valor de categoryName
debe ser legible en lenguaje natural.libPath
.js
.viewPath
(Opcional)viewBasePath
y no debe comenzar con una barra oblicua. Debe hacer referencia a un archivo HTML con una extensión .html
. Se aceptan cadenas de consulta e identificadores de fragmento (hashes). Si el módulo de biblioteca del tipo no utiliza ninguna configuración de usuario, puede excluir esta propiedad y, en su lugar, Platform mostrará un marcador de posición que indique que no es necesaria ninguna configuración.schema
Un objeto de esquema JSON que describe el formato de un objeto de configuración válido que el usuario puede guardar. Por lo general, el usuario configura y guarda la configuración a través de la interfaz de usuario de recopilación de datos. En estos casos, la vista de la extensión puede realizar los pasos necesarios para validar la configuración proporcionada por el usuario. Por otro lado, algunos usuarios eligen utilizar API de etiquetas directamente sin la ayuda de ninguna interfaz de usuario. El propósito de este esquema es permitir que Platform valide correctamente que los objetos de configuración guardados por los usuarios, independientemente de si se utiliza una interfaz de usuario, están en un formato compatible con el módulo de biblioteca que actuará en el objeto de configuración durante la ejecución.
A continuación, se muestra un objeto de esquema de ejemplo:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"delay": {
"type": "number",
"minimum": 1
}
},
"required": [
"delay"
],
"additionalProperties": false
}
Recomendamos utilizar una herramienta como JSON Schema validator para probar manualmente el esquema.
transforms
(Opcional)Transforms transforms
En el caso de determinados casos de uso específicos, las extensiones necesitan que Platform transforme los objetos de configuración guardados desde una vista antes de emitirse en la biblioteca de tiempo de ejecución de etiqueta. Puede solicitar que una o más de estas transformaciones se realicen configurando la propiedad transforms
al definir una definición de tipo dentro de su extension.json
. La propiedad transforms
es una matriz de objetos en la que cada objeto representa una transformación que debe tener lugar.
Todas las transformaciones requieren un type
y una propertyPath
. El type
debe ser una function
, un remove
y un file
, y describir qué Platform de transformación debe aplicarse al objeto de configuración. La propiedad propertyPath
es una cadena delimitada por puntos que indica a las etiquetas dónde encontrar la propiedad que debe modificarse en el objeto de configuración. Este es un objeto de configuración de ejemplo y propertyPath
:
{
foo: {
bar: "A string",
baz: [
"A",
"B",
"C"
]
}
}
- Si establece una
propertyPath
defoo.bar
, transformará el valor"A string"
. - Si establece una
propertyPath
defoo.baz[]
, transformará cada valor en la matrizbaz
. - Si establece una
propertyPath
defoo.baz
, transformará la matrizbaz
.
Las rutas de propiedades pueden utilizar cualquier combinación de notación de objetos y matrices para aplicar transformaciones en cualquier nivel del objeto de configuración.
propertyPath
(por ejemplo, foo.baz[]
) todavía no se admite en la extensión sandbox*tool.Las secciones siguientes describen las transformaciones disponibles y cómo utilizarlas.
Transformación de funciones
La transformación de funciones permite que el código escrito por los usuarios de Platform lo ejecute un módulo de biblioteca dentro de la biblioteca de tiempo de ejecución de la etiqueta emitida.
Supongamos que queremos proporcionar un tipo de acción de "secuencia de comandos personalizada". La vista de acción "script personalizado" puede proporcionar un área de texto en la que el usuario puede introducir código. Supongamos que un usuario ha introducido el siguiente código en el área de texto:
console.log('Welcome, ' + username +'. This is ZomboCom.');
Cuando el usuario guarda la regla, el objeto de configuración guardado por la vista puede tener este aspecto:
{
foo: {
bar: "console.log('Welcome, ' + username +'. This is ZomboCom.');"
}
}
Cuando una regla que utiliza nuestra acción se activa dentro de la biblioteca de tiempo de ejecución de etiqueta, queremos ejecutar el código del usuario y pasarle un nombre de usuario.
En el momento en que el objeto de configuración se guarda desde la vista del tipo de acción, el código del usuario es simplemente una cadena. Esto es positivo porque se puede serializar correctamente desde JSON y hacia JSON; sin embargo, también es malo porque, por lo general, se emitiría en la biblioteca de tiempo de ejecución de etiqueta como cadena, en lugar de como función ejecutable. Aunque podría intentar ejecutar el código en el módulo de biblioteca del tipo de acción mediante eval
o un constructor de funciones, se desaconseja porque las políticas de seguridad de contenido podrían bloquear la ejecución.
Como solución alternativa a esta situación, el uso de la transformación de funciones indica a Platform que ajuste el código del usuario en una función ejecutable cuando se emite en la biblioteca de tiempo de ejecución de etiqueta. Para solucionar el problema del ejemplo, definiríamos la transformación de la definición de tipo en extension.json
de la siguiente manera:
{
"transforms": [
{
"type": "function",
"propertyPath": "foo.bar",
"parameters": ["username"]
}
]
}
type
define el tipo de transformación que debe aplicarse al objeto de configuración.propertyPath
es una cadena delimitada por puntos que indica a Platform dónde encontrar la propiedad que debe modificarse dentro del objeto de configuración.parameters
es una matriz de nombres de parámetros que deben incluirse en la firma de la función de ajuste.
Cuando el objeto de configuración se emite en la biblioteca de tiempo de ejecución de etiqueta, se transforma en lo siguiente:
{
foo: {
bar: function(username) {
console.log('Welcome, ' + username +'. This is ZomboCom.');
}
}
}
El módulo de biblioteca puede, así, llamar a la función que contiene el código del usuario y pasar el argumento username
.
Transformación de archivos
La transformación de archivos permite que el código escrito por los usuarios de Platform se emita en un archivo independiente de la biblioteca de tiempo de ejecución de etiqueta. El archivo se alojará junto a la biblioteca de tiempo de ejecución de etiqueta y, a continuación, se podrá cargar según sea necesario en la extensión durante el tiempo de ejecución.
Supongamos que queremos proporcionar un tipo de acción de "secuencia de comandos personalizada". La vista del tipo de acción puede proporcionar un área de texto donde el usuario puede introducir código. Supongamos que un usuario ha introducido el siguiente código en el área de texto:
console.log('This is ZomboCom.');
Cuando el usuario guarda la regla, el objeto de configuración guardado por la vista puede tener este aspecto:
{
foo: {
bar: "console.log('This is ZomboCom.');"
}
}
Queremos que el código del usuario se coloque en un archivo independiente en lugar de incluirse en la biblioteca de tiempo de ejecución de etiqueta. Cuando una regla que utiliza nuestra acción se activa en la biblioteca de tiempo de ejecución de etiqueta, nos gustaría cargar el código del usuario añadiendo un elemento de secuencia de comandos al cuerpo del documento. Para solucionar el problema de ejemplo, definiríamos la transformación de la definición de tipo de acción en extension.json
de la siguiente manera:
{
"transforms": [
{
"type": "file",
"propertyPath": "foo.bar"
}
]
}
type
define el tipo de transformación que debe aplicarse al objeto de configuración.propertyPath
es una cadena delimitada por puntos que indica a Platform dónde encontrar la propiedad que debe modificarse dentro del objeto de configuración.
Cuando el objeto de configuración se emite en la biblioteca de tiempo de ejecución de etiqueta, se transforma en lo siguiente:
{
foo: {
bar: "//launch.cdn.com/path/abc.js"
}
}
En este caso, el valor de foo.bar
se ha transformado en una dirección URL. La dirección URL exacta se determinará en el momento de crear la biblioteca. El archivo siempre recibirá una extensión .js
y se enviará con un tipo MIME orientado a JavaScript. Podemos añadir compatibilidad con otros tipos MIME en el futuro.
Eliminación de la transformación
De forma predeterminada, todas las propiedades del objeto de configuración se emiten en la biblioteca de tiempo de ejecución de etiqueta. Si determinadas propiedades solo se utilizan para la vista de extensión, especialmente si contienen información confidencial (por ejemplo, un token secreto), debe utilizar la transformación de eliminación para evitar que la información se emita en la biblioteca de tiempo de ejecución de etiqueta.
Supongamos que queremos proporcionar un nuevo tipo de acción. La vista del tipo de acción puede proporcionar una entrada en la que el usuario puede introducir una clave secreta que permita la conexión a una API específica. Supongamos que un usuario ha introducido el siguiente texto en la entrada:
ABCDEFG
Cuando el usuario guarda la regla, el objeto de configuración guardado por la vista puede tener este aspecto:
{
foo: {
bar: "ABCDEFG"
}
}
No queremos incluir la propiedad bar
en la biblioteca de tiempo de ejecución de etiquetas. Para solucionar el problema de ejemplo, definiríamos la transformación de la definición de tipo de acción en extension.json
de la siguiente manera:
{
"transforms": [
{
"type": "remove",
"propertyPath": "foo.bar"
}
]
}
type
define el tipo de transformación que debe aplicarse al objeto de configuración.propertyPath
es una cadena delimitada por puntos que indica a Platform dónde encontrar la propiedad que debe modificarse dentro del objeto de configuración.
Cuando el objeto de configuración se emite en la biblioteca de tiempo de ejecución de etiqueta, se transforma en lo siguiente:
{
foo: {
}
}
En este caso, el valor de foo.bar
se ha eliminado del objeto de configuración.