Manifiesto de extensión

NOTA

Adobe Experience Platform Launch se ha convertido en un conjunto de tecnologías de recopilación de datos en Adobe Experience Platform. Como resultado, se han implementado varios cambios terminológicos en la documentación del producto. 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 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 y debe cumplir con las reglas de nomenclatura. Las etiquetas lo utilizan como identificador y no se debe cambiar 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. Esto se mostrará a los usuarios de Platform. No es necesario mencionar "etiquetas" o "extensión"; los usuarios ya sabrán que están viendo una extensión de etiqueta.
description La descripción de la extensión. Esto se mostrará a los usuarios de Platform. 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 "etiquetas" o "extensión"; los usuarios ya sabrán que están viendo una extensión de etiqueta.
iconPath (Opcional) Ruta relativa al icono que se mostrará para la extensión. 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.
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 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 etiquetas 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 junto con la biblioteca de tiempo de ejecución de etiquetas. 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. Las etiquetas lo utilizan como identificador y no se debe cambiar 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

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. Las etiquetas lo utilizan como identificador y no se debe cambiar después de publicar la extensión.
displayName Texto que se utilizará para representar el tipo en la interfaz de usuario de la recopilación de datos. Debe ser legible en lenguaje natural.
categoryName (Opcional) Cuando se proporciona, el displayName se enumera en el categoryName dentro de la interfaz de usuario de recopilación de datos. 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 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. Normalmente, un usuario configura y guarda la configuración mediante 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 las 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",
  "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

Para determinados casos de uso específicos, las extensiones necesitan que Platform transforme los objetos de configuración guardados desde una vista antes de que se emitan en la biblioteca de tiempo de ejecución de etiquetas. 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. El propertyPath es una cadena delimitada por períodos que indica a las etiquetas dónde encontrar la propiedad que debe modificarse dentro del 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 un módulo de biblioteca ejecute el código escrito por los usuarios de Platform dentro de la biblioteca de tiempo de ejecución de etiquetas emitidas.

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 etiquetas, nos gustaría 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 bueno porque puede serializarse correctamente desde y hacia JSON; sin embargo, también es malo porque normalmente se emitía en la biblioteca de tiempo de ejecución de etiquetas como una cadena también 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 para 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 etiquetas. 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 etiquetas, se transforma en el 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 etiquetas. El archivo se alojará junto a la biblioteca de tiempo de ejecución de etiquetas y se podrá cargar según sea necesario en la extensión durante la 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 dentro de la biblioteca de tiempo de ejecución de etiquetas. Cuando una regla que utiliza nuestra acción se activa dentro de la biblioteca de tiempo de ejecución de etiquetas, nos gustaría cargar el código del usuario adjuntando 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 etiquetas, se transforma en el 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 settings se emiten en la biblioteca de tiempo de ejecución de etiquetas. Si determinadas propiedades solo se utilizan para la vista de extensión, especialmente si contienen información confidencial (por ejemplo, token secreto), debe utilizar la transformación remove para evitar que la información se emita en la biblioteca de tiempo de ejecución de etiquetas.

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"
  }
}

Nos gustaría no incluir la propiedad bar dentro de 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 etiquetas, se transforma en el siguiente:

{
  foo: {
  }
}

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

En esta página