Manifiesto de extensión

NOTA

Adobe Experience Platform Launch se está convirtiendo en un conjunto de tecnologías de recopilación de datos en Experience Platform. Estos cambios se implementarán en toda la documentación del producto en las próximas semanas. Consulte el siguiente documento para obtener una referencia consolidada de los cambios terminológicos.

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 Launch 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:

Propiedad Descripción
name El nombre de la extensión. Debe ser diferente al de todas las demás extensiones de Reactor y debe cumplir con las reglas de nomenclatura. Platform Launch lo utiliza como identificador y no debe cambiarse después de publicar la extensión.
platform La plataforma para la extensión. El único valor aceptado en este momento es web.
version La versión de la extensión. Debe seguir el formato de versión semver. Esto es coherente con npm version field.
displayName El nombre legible en lenguaje natural de su extensión. Se mostrará a los usuarios de Platform Launch. No es necesario mencionar Launch o Extension, pues los usuarios ya sabrán que están viendo una extensión de Launch.
description La descripción de la extensión. Se mostrará a los usuarios de Platform Launch. Si la extensión permite a los usuarios implementar el producto en su sitio web, describa lo que hace el producto. No es necesario mencionar Launch o Extension, pues los usuarios ya sabrán que están viendo una extensión de Platform Launch.
iconPath (Opcional) La ruta relativa al icono que se mostrará para la extensión en Platform Launch. No debe comenzar con una barra oblicua. Debe hacer referencia a un archivo SVG con una extensión .svg. El SVG debe ser cuadrado y escalable por Platform Launch.
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) Dirección URL del listado de la extensión en Adobe Exchange. Debe coincidir con el patrón https://www.adobeexchange.com/experiencecloud.details.######.html.
viewBasePath La ruta relativa al subdirectorio que contiene todas las vistas y los recursos relacionados con la vista (HTML, JavaScript, CSS e imágenes). Platform Launch alojará este directorio en un servidor web y cargará contenido de iframe desde él. Este campo es obligatorio y no debe comenzar con una barra oblicua. Por ejemplo, si todas sus vistas están contenidas en src/view/, el valor de viewBasePath sería src/view/.
hostedLibFiles (Opcional) Muchos de nuestros usuarios prefieren alojar todos los archivos relacionados con Platform Launch en su propio servidor. Esto proporciona a los usuarios un mayor nivel de certeza con respecto a la disponibilidad de archivos en tiempo de ejecución y pueden analizar fácilmente el código para detectar vulnerabilidades de seguridad. Si la parte de biblioteca de la extensión necesita cargar archivos JavaScript en tiempo de ejecución, se recomienda utilizar esta propiedad para la lista de dichos archivos. Los archivos enumerados se alojarán con la biblioteca de tiempo de ejecución de Platform Launch. La extensión puede cargar los archivos mediante una URL recuperada mediante el método getHostedLibFileUrl.

Esta opción contiene una matriz con rutas relativas de archivos de biblioteca de terceros que deben alojarse.
main (Opcional) La ruta relativa de un módulo de biblioteca que debe ejecutarse en tiempo de ejecución.

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) Esto describe la sección configuración de la extensión de la extensión. Es necesario si necesita que los usuarios proporcionen una configuración global para la extensión. Consulte el apéndice para obtener información sobre cómo se debe estructurar este campo.
events (Opcional) Una matriz de definiciones de tipo evento. Consulte la sección del apéndice sobre definiciones de tipo para ver la estructura de cada objeto de la matriz.
conditions (Opcional) Una matriz de definiciones de tipo condición. Consulte la sección del apéndice sobre definiciones de tipo para ver la estructura de cada objeto de la matriz.
actions (Opcional) Una matriz de definiciones de tipo acción. Consulte la sección del apéndice sobre definiciones de tipo para ver la estructura de cada objeto de la matriz.
dataElements (Opcional) Una matriz de definiciones de tipo elemento de datos. Consulte la sección del apéndice sobre definiciones de tipo para ver la estructura de cada objeto de la matriz.
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. Platform Launch lo utiliza 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

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

El objeto de configuración debe estructurarse de la siguiente manera:

Propiedad Descripción
viewPath La dirección URL relativa a la vista de configuración de la extensión. Debe ser relativa a 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 Launch.

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) Una matriz de objetos en la que cada objeto representa una transformación que debe realizarse en cada objeto de configuración correspondiente cuando se emite en la biblioteca de tiempo de ejecución. Consulte la sección transformaciones para obtener más información sobre por qué esto puede ser necesario y cómo se utiliza.

Definiciones de tipo

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:

Propiedad Descripción
name El nombre del tipo. Debe ser un nombre único dentro de la extensión. El nombre debe cumplir con las reglas de nomenclatura. Platform Launch lo utiliza como identificador y no debe cambiarse después de publicar la extensión.
displayName El texto que se utilizará para representar el tipo dentro de la interfaz de usuario de Platform Launch. Debe ser legible en lenguaje natural.
categoryName (Opcional) Cuando se proporcione, displayName se enumerará en categoryName en la interfaz de usuario de inicio de Platform Launch. 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 La ruta relativa al módulo de biblioteca del tipo. No debe comenzar con una barra oblicua. Debe hacer referencia a un archivo JavaScript con una extensión .js.
viewPath (Opcional) La dirección URL relativa a la vista del tipo. Debe ser relativa a 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 Launch 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 mediante la interfaz de usuario de Platform Launch. 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 las API de Platform Launch directamente sin la ayuda de ninguna interfaz de usuario. El propósito de este esquema es permitir que Platform Launch 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",
  "propiedades": {
    "retraso": {
      "type": "número",
      "mínimo": 1
    }
  },
  "obligatorio": [
    "delay"
  ],
  "additionalProperties": false
}
Recomendamos utilizar una herramienta como JSON Schema validator para probar manualmente el esquema.
transforms (Opcional) Una matriz de objetos en la que cada objeto representa una transformación que debe realizarse en cada objeto de configuración correspondiente cuando se emite en la biblioteca de tiempo de ejecución. Consulte la sección sobre transformaciones para obtener más información sobre por qué esto puede ser necesario y cómo se utiliza.

Transforms

En el caso de determinados casos de uso específicos, las extensiones necesitan que Platform Launch transforme los objetos de configuración guardados desde una vista antes de emitirse en la biblioteca de tiempo de ejecución de Platform Launch. 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 Launch de transformación debe aplicarse al objeto de configuración. La propiedad propertyPath es una cadena delimitada por puntos que indica a Platform Launch 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 de foo.bar, transformará el valor "A string".
  • Si establece una propertyPath de foo.baz[], transformará cada valor en la matriz baz.
  • Si establece una propertyPath de foo.baz, transformará la matriz baz.

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.

ADVERTENCIA

El uso de notación de matriz en atributos 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 Launch se ejecute por un módulo de biblioteca dentro de la biblioteca de tiempo de ejecución de Platform Launch 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 Platform Launch, 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 Platform Launch como una cadena, en lugar de una 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 Launch que ajuste el código del usuario en una función ejecutable cuando se emite en la biblioteca de tiempo de ejecución de Platform Launch. 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 Launch dónde encontrar la propiedad que debe modificarse en el 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 Platform Launch, 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 Launch se emita en un archivo independiente de la biblioteca de tiempo de ejecución de Platform Launch. El archivo se alojará junto a la biblioteca de tiempo de ejecución de Platform Launch 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 Platform Launch. Cuando una regla que utiliza nuestra acción se activa en la biblioteca de tiempo de ejecución de Platform Launch, 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 Launch dónde encontrar la propiedad que debe modificarse en el objeto de configuración.

Cuando el objeto de configuración se emite en la biblioteca de tiempo de ejecución de Platform Launch, 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 Platform Launch. 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 Platform Launch.

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 Platform Launch. Para solucionar nuestro problema de ejemplo, definiríamos la transformación en 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 Launch dónde encontrar la propiedad que debe modificarse en el objeto de configuración.

Cuando el objeto de configuración se emite en la biblioteca de tiempo de ejecución de Platform Launch, se transforma en lo siguiente:

{
  foo: {
  }
}

En este caso, el valor de foo.bar se ha eliminado del objeto de configuración.

En esta página