Erweiterungsmanifest

Im Basisverzeichnis der Erweiterung müssen Sie eine Datei mit dem Namen extension.json erstellen. Sie enthält wichtige Details zu Ihrer Erweiterung, die es Adobe Experience Platform ermöglichen, diese ordnungsgemäß zu nutzen. Einige Inhalte sind nach dem Vorbild von npm package.json gestaltet.

Ein Beispiel für extension.json finden Sie im GitHub-Repository Hello World Extension.

Ein Erweiterungsmanifest muss Folgendes enthalten:

Anhang

Benennungsregeln naming-rules

Der Wert eines jeden Felds name in extension.json muss den folgenden Regeln entsprechen:

Diese Regeln entsprechen den Regeln für npm-Paketnamen.

Eigenschaften von Konfigurationsobjekten config-object

Das Konfigurationsobjekt sollte wie folgt strukturiert sein:

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

Typdefinitionen type-definitions

Eine Typdefinition ist ein Objekt, mit dem ein Ereignis-, Bedingungs-, Aktions- oder Datenelementtyp beschrieben wird. Das Objekt besteht aus folgenden Elementen:

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

Transformationen transforms

Für bestimmte spezifische Anwendungsfälle müssen für Erweiterungen die in einer Ansicht gespeicherten Einstellungsobjekte aus Platform transformiert werden, bevor sie in die Tag-Laufzeitbibliothek ausgegeben werden. Sie können anfordern, dass eine oder mehrere dieser Transformationen durchgeführt werden, indem Sie die transforms-Eigenschaft beim Definieren einer Typdefinition in extension.json festlegen. Die transforms-Eigenschaft ist ein Array von Objekten, wobei jedes Objekt eine auszuführende Transformation darstellt.

Alle Transformationen benötigen einen type-Wert und einen propertyPath-Wert. Der Wert von type muss function, remove oder file lauten. Er beschreibt, welche Transformation von Platform auf das settings-Objekt angewendet werden soll. Der propertyPath ist eine durch Punkte getrennte Zeichenfolge, die Tags mitteilt, wo die zu ändernde Eigenschaft im Einstellungsobjekt zu finden ist. Es folgen ein Beispiel für ein Einstellungsobjekt und einige Angaben für propertyPath:

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

Für Eigenschaftenpfade können beliebige Kombinationen aus Array- und Objektnotation verwendet werden, um Transformationen auf jeder Ebene des Einstellungsobjekts anzuwenden.

In den folgenden Abschnitten werden die verfügbaren Transformationstypen und ihre Verwendung beschrieben.

Transformationstyp „function“

Die Funktionstransformation ermöglicht, dass von Platform-Benutzern geschriebener Code von einem Bibliotheksmodul in der ausgegebenen Tag-Laufzeitbibliothek ausgeführt wird.

Angenommen, wir möchten einen Aktionstyp für ein „benutzerdefiniertes Skript“ bereitstellen. Die Aktionsansicht „benutzerdefiniertes Skript“ bietet vielleicht einen Textbereich, in dem der Benutzer Code eingeben kann. Nehmen wir an, ein Benutzer hat den folgenden Code in den Textbereich eingegeben:

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

Wenn der Benutzer die Regel speichert, kann das von der Ansicht gespeicherte Einstellungsobjekt wie folgt aussehen:

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

Wenn eine Regel, die unsere Aktion verwendet, in der Tag-Laufzeitbibliothek ausgelöst wird, soll der Code des Benutzers ausgeführt und ihm ein Benutzername übergeben werden.

Wenn das settings-Objekt aus der Ansicht des Aktionstyps gespeichert wird, ist der Benutzercode einfach eine Zeichenfolge. Dies ist gut, da es ordnungsgemäß zu und von JSON serialisiert werden kann. Es ist jedoch auch schlecht, da es in der Tag-Laufzeitbibliothek normalerweise auch als Zeichenfolge und nicht als ausführbare Funktion ausgegeben wird. Obwohl Sie versuchen könnten, den Code innerhalb des Bibliotheksmoduls Ihres Aktionstyps mit eval oder einem Function-Konstruktor auszuführen, wird davon dringend abgeraten, weil Sicherheitsrichtlinien für Inhalte die Ausführung potenziell blockieren können.

Um diese Situation zu umgehen, erhält Platform bei Verwendung der Funktionstransformation die Anweisung, den Code des Benutzers in eine ausführbare Funktion einzuschließen, wenn er in der Tag-Laufzeitbibliothek ausgegeben wird. Zur Lösung unseres Beispielproblems würden wir die Transformation in der Typdefinition in extension.json wie folgt definieren:

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

Wenn das Einstellungsobjekt in der Tag-Laufzeitbibliothek ausgegeben wird, wird es wie folgt umgewandelt:

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

Ihr Bibliotheksmodul kann dann die Funktion aufrufen, die den Code des Benutzers enthält, und das Argument username übergeben.

Transformationstyp „file“

Die Dateitransformation ermöglicht die Ausgabe von Code, der von Platform-Benutzern geschrieben wurde, in eine Datei, die von der Tag-Laufzeitbibliothek getrennt ist. Die Datei wird zusammen mit der Tag-Laufzeitbibliothek gehostet und kann dann von der Erweiterung zur Laufzeit nach Bedarf geladen werden.

Angenommen, wir möchten einen Aktionstyp für ein „benutzerdefiniertes Skript“ bereitstellen. Die Ansicht des Aktionstyps kann einen Textbereich bereitstellen, in dem der Benutzer Code eingeben kann. Nehmen wir an, ein Benutzer hat den folgenden Code in den Textbereich eingegeben:

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

Wenn der Benutzer die Regel speichert, kann das von der Ansicht gespeicherte Einstellungsobjekt wie folgt aussehen:

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

Wir möchten, dass der Code des Benutzers in einer separaten Datei platziert wird, anstatt in die Tag-Laufzeitbibliothek aufgenommen zu werden. Wenn eine Regel, die unsere Aktion verwendet, in der Tag-Laufzeitbibliothek ausgelöst wird, soll der Code des Benutzers geladen werden, indem ein Skriptelement an den Dokument-Textkörper angehängt wird. Zur Lösung unseres Beispielproblems würden wir die Transformation in der Aktionstypdefinition in extension.json wie folgt definieren:

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

Wenn das Einstellungsobjekt in der Tag-Laufzeitbibliothek ausgegeben wird, wird es wie folgt umgewandelt:

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

In diesem Fall wurde der Wert von foo.bar in eine URL transformiert. Die genaue URL wird zum Zeitpunkt der Erstellung der Bibliothek bestimmt. Die Datei erhält immer die Erweiterung .js und wird mit einem JavaScript-orientierten MIME-Typ bereitgestellt. Möglicherweise werden in Zukunft weitere MIME-Typen unterstützt.

Transformationstyp „remove“

Standardmäßig werden alle Eigenschaften des Einstellungsobjekts in der Tag-Laufzeitbibliothek ausgegeben. Wenn bestimmte Eigenschaften nur für die Erweiterungsansicht verwendet werden, insbesondere wenn sie vertrauliche Informationen enthalten (z. B. geheime Token), sollten Sie den Transformationstyp „remove“ verwenden, um zu verhindern, dass diese Informationen in die Tag-Laufzeitbibliothek ausgegeben werden.

Angenommen wir möchten einen neuen Aktionstyp bereitstellen. Die Ansicht des Aktionstyps kann ein Eingabefeld enthalten, in das der Benutzer einen geheimen Schlüssel eingeben kann, um eine Verbindung mit einer bestimmten API herzustellen. Nehmen wir an, ein Benutzer hat den folgenden Text in das Eingabefeld eingegeben:

ABCDEFG

Wenn der Benutzer die Regel speichert, kann das von der Ansicht gespeicherte Einstellungsobjekt wie folgt aussehen:

{
  foo: {
    bar: "ABCDEFG"
  }
}

Wir möchten die Eigenschaft bar nicht in die Tag-Laufzeitbibliothek einschließen. Zur Lösung unseres Beispielproblems würden wir die Transformation in der Aktionstypdefinition in extension.json wie folgt definieren:

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

Wenn das Einstellungsobjekt in der Tag-Laufzeitbibliothek ausgegeben wird, wird es wie folgt umgewandelt:

{
  foo: {
  }
}

In diesem Fall wurde der Wert von foo.bar aus dem settings-Objekt entfernt.