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:

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:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delay": {
      "type": "number",
      "minimum": 1
    }
  },
  "required": [
    "delay"
  ],
  "additionalProperties": false
}

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:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delay": {
      "type": "number",
      "minimum": 1
    }
  },
  "required": [
    "delay"
  ],
  "additionalProperties": false
}

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 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.

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.

Recursos de Business.Adobe.com