Manifeste d’extensions

Dans le répertoire de base de votre extension, vous devez créer un fichier appelé extension.json. Cette section contient des détails importants sur votre extension, ce qui permet à Adobe Experience Platform de l’utiliser correctement. Certains contenus sont formés à l’instar du npm package.json de npm.

Vous trouverez un exemple d’extension extension.json dans le référentiel GitHub de l’extension Hello World.

Un manifeste d’extensions doit être constitué des éléments suivants :

Annexe

Règles d’attribution de noms naming-rules

La valeur de tout champ name dans extension.json doit respecter les règles suivantes :

Ces règles sont conformes aux règles npm package name.

Propriétés de l’objet de configuration config-object

L’objet de configuration doit être structuré comme suit :

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

Définitions de type type-definitions

Une définition de type est un objet utilisé pour décrire un type d’événement, de condition, d’action ou d’élément de données. L’objet se compose des éléments suivants :

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

Transformations transforms

Pour certains cas d’utilisation spécifiques, les extensions ont besoin que les objets settings enregistrés à partir d’une vue soient transformés par Experience Platform avant d’être émis dans la bibliothèque d’exécution des balises. Vous pouvez demander qu’une ou plusieurs de ces transformations se produisent en définissant la propriété transforms lors de la définition d’une définition de type dans votre extension.json. La propriété transforms est un tableau d’objets où chaque objet représente une transformation qui doit avoir lieu.

Toutes les transformations nécessitent un type et un propertyPath. Le type doit être l’un des function, remove et file et décrit la transformation qu’Experience Platform doit appliquer à l’objet settings. Le champ propertyPath est une chaîne délimitée par des points qui indique aux balises où trouver la propriété qui doit être modifiée dans lʼobjet settings. Voici un exemple d’objet settings et quelques propertyPath :

{
  foo: {
    bar: "A string",
    baz: [
      "A",
      "B",
      "C"
    ]
  }
}

Les chemins d’accès aux propriétés peuvent utiliser n’importe quelle combinaison de notation de tableau et d’objet pour appliquer des transformations à n’importe quel niveau de l’objet settings.

Les sections ci-dessous décrivent les transformations disponibles et comment les utiliser.

Transformation de fonction

La transformation de fonction permet à un module Bibliothèque d’exécuter le code écrit par les utilisateurs d’Experience Platform dans la bibliothèque d’exécution de balise émise.

Supposons que nous souhaitions fournir un type d’action « script personnalisé ». La vue d’action « script personnalisé » peut fournir une zone de texte dans laquelle l’utilisateur peut entrer du code. Supposons qu’un utilisateur ait saisi le code suivant dans la zone de texte :

console.log('Welcome, ' + username +'. This is ZomboCom.');

Lorsque l’utilisateur enregistre la règle, l’objet settings enregistré par la vue peut se présenter comme suit :

{
  foo: {
    bar: "console.log('Welcome, ' + username +'. This is ZomboCom.');"
  }
}

Lorsquʼune règle utilisant notre action se déclenche dans la bibliothèque dʼexécution des balises, nous souhaitons exécuter le code de lʼutilisateur et lui transmettre un nom dʼutilisateur.

Au moment où l’objet settings est enregistré à partir de la vue du type d’action, le code de l’utilisateur est simplement une chaîne. Ceci est utile car il peut être correctement sérialisé vers et à partir de JSON. Cependant, cʼest également un inconvénient, car il serait généralement émis dans la bibliothèque dʼexécution des balises sous la forme dʼune chaîne et non dʼune fonction exécutable. Bien que vous puissiez tenter d’exécuter le code dans le module Bibliothèque de votre type d’action à l’aide de eval ou d’une fonction constructeur, cela est fortement déconseillé en raison de politiques de sécurité de contenu susceptibles de bloquer l’exécution.

Pour pallier cette situation, l’utilisation de la transformation de fonction indique à Experience Platform d’encapsuler le code de l’utilisateur dans une fonction exécutable lorsqu’il est émis dans la bibliothèque d’exécution de balise. Pour résoudre le problème de notre exemple, nous définirions la transformation sur la définition de type dans extension.json comme suit :

{
  "transforms": [
    {
      "type": "function",
      "propertyPath": "foo.bar",
      "parameters": ["username"]
    }
  ]
}

Lorsque lʼobjet settings est émis dans la bibliothèque dʼexécution des balises, il est transformé comme suit :

{
  foo: {
    bar: function(username) {
      console.log('Welcome, ' + username +'. This is ZomboCom.');
    }
  }
}

Votre module Bibliothèque peut alors appeler la fonction contenant le code de l’utilisateur et transmettre l’argument username.

Transformation de fichier

La transformation de fichier permet d’émettre le code écrit par les utilisateurs d’Experience Platform dans un fichier distinct de la bibliothèque d’exécution des balises. Le fichier sera hébergé en même temps que la bibliothèque dʼexécution des balises et pourra ensuite être chargé selon les besoins de votre extension au moment de lʼexécution.

Supposons que nous souhaitions fournir un type d’action « script personnalisé ». La vue du type d’action peut fournir un champ de texte dans lequel l’utilisateur peut saisir du code. Supposons qu’un utilisateur ait saisi le code suivant dans la zone de texte :

console.log('This is ZomboCom.');

Lorsque l’utilisateur enregistre la règle, l’objet settings enregistré par la vue peut se présenter comme suit :

{
  foo: {
    bar: "console.log('This is ZomboCom.');"
  }
}

Nous souhaitons que le code de lʼutilisateur soit placé dans un fichier distinct au lieu dʼêtre inclus dans la bibliothèque dʼexécution des balises. Lorsquʼune règle utilisant notre action se déclenche dans la bibliothèque dʼexécution des balises, nous souhaitons charger le code de lʼutilisateur en ajoutant un élément de script au corps du document. Pour résoudre le problème de notre exemple, nous définirions la transformation sur la définition de type d’action dans extension.json comme suit :

{
  "transforms": [
    {
      "type": "file",
      "propertyPath": "foo.bar"
    }
  ]
}

Lorsque lʼobjet settings est émis dans la bibliothèque dʼexécution des balises, il est transformé comme suit :

{
  foo: {
    bar: "//launch.cdn.com/path/abc.js"
  }
}

Dans ce cas, la valeur de foo.bar a été transformée en URL. L’URL exacte sera déterminée au moment de la génération de la bibliothèque. Le fichier reçoit toujours une extension .js et est livré avec un type MIME orienté JavaScript. Nous pourrions à l’avenir ajouter la prise en charge d’autres types MIME.

Transformation remove

Par défaut, toutes les propriétés de lʼobjet settings sont émises dans la bibliothèque dʼexécution des balises. Si certaines propriétés ne sont utilisées que pour la vue d’extension, en particulier si elles contiennent des informations sensibles (par exemple un jeton secret), vous devez utiliser la transformation remove pour empêcher lʼémission des informations dans la bibliothèque dʼexécution des balises.

Supposons que nous voudrions fournir un nouveau type d’action. La vue du type d’action peut fournir une entrée à partir de laquelle l’utilisateur peut saisir une clé secrète permettant la connexion à une API spécifique. Supposons qu’un utilisateur ait saisi le texte suivant :

ABCDEFG

Lorsque l’utilisateur enregistre la règle, l’objet settings enregistré par la vue peut se présenter comme suit :

{
  foo: {
    bar: "ABCDEFG"
  }
}

Nous aimerions ne pas inclure la propriété bar dans la bibliothèque dʼexécution des balises. Pour résoudre le problème de notre exemple, nous définirions la transformation sur la définition de type d’action dans extension.json comme suit :

{
  "transforms": [
    {
      "type": "remove",
      "propertyPath": "foo.bar"
    }
  ]
}

Lorsque lʼobjet settings est émis dans la bibliothèque dʼexécution des balises, il est transformé comme suit :

{
  foo: {
  }
}

Dans ce cas, la valeur de foo.bar a été supprimée de l’objet settings.