Erweiterungsmanifest

HINWEIS

Adobe Experience Platform Launch wurde als eine Suite von Datenerfassungstechnologien in Adobe Experience Platform umbenannt. Infolgedessen wurden in der gesamten Produktdokumentation mehrere terminologische Änderungen eingeführt. Eine konsolidierte Übersicht der terminologischen Änderungen finden Sie im folgenden Dokument.

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:

Eigenschaft Beschreibung
name Name der Erweiterung. Dies muss sich von allen anderen Erweiterungen unterscheiden und den Benennungsregeln entsprechen. Er wird von Tags als Kennung verwendet und sollte nach der Veröffentlichung der Erweiterung nicht geändert werden.
platform Die Plattform für die Erweiterung. Der einzige Wert, der im Moment akzeptiert wird, lautet web.
version Die Version der Erweiterung. Sie muss dem Versionierungsformat semver entsprechen. Dies entspricht dem npm-Feld version.
displayName Der für Menschen lesbare Name der Erweiterung. Er wird Platform-Benutzern angezeigt. Es ist nicht erforderlich, „Tags“ oder „Erweiterung“ zu erwähnen, da die Benutzer bereits wissen, dass sie eine Tag-Erweiterung vor sich haben.
description Die Beschreibung der Erweiterung. Er wird Platform-Benutzern angezeigt. Wenn Benutzer mit Ihrer Erweiterung Ihr Produkt auf ihrer Website implementieren können, beschreiben Sie die Funktionen Ihres Produkts. Es ist nicht erforderlich, „Tags“ oder „Erweiterung“ zu erwähnen, da die Benutzer bereits wissen, dass sie eine Tag-Erweiterung vor sich haben.
iconPath (Optional) Der relative Pfad zu dem Symbol, das für die Erweiterung angezeigt wird. Er sollte nicht mit einem Schrägstrich beginnen. Er muss auf eine SVG-Datei mit der Erweiterung .svg verweisen. Das SVG-Symbol sollte quadratisch sein und sich von Platform skalieren lassen.
author „author“ ist ein Objekt, das wie folgt strukturiert sein sollte:
  • name: Der Name des Autors der Erweiterung. Alternativ kann hier der Name der Firma angegeben werden.
  • url (Optional): Eine URL, die weitere Informationen zum Autor der Erweiterung bietet.
  • email (Optional): Die E-Mail-Adresse des Autors der Erweiterung.
Dies entspricht den Regeln des npm-Felds author.
exchangeUrl (Erforderlich für öffentliche Erweiterungen) Die URL zum Listeneintrag Ihrer Erweiterung auf Adobe Exchange. Sie muss dem Muster https://www.adobeexchange.com/experiencecloud.details.######.html entsprechen.
viewBasePath Der relative Pfad zu dem Unterverzeichnis, das alle Ihre Ansichten und ansichtsbezogenen Ressourcen (HTML, JavaScript, CSS, Bilder) enthält. Platform hostet dieses Verzeichnis auf einem Webserver und lädt iframe-Inhalte daraus. Dies ist ein erforderliches Feld und darf nicht mit einem Schrägstrich beginnen. Wenn sich beispielsweise alle Ihre Ansichten im Verzeichnis src/view/ befinden, hat viewBasePath den Wert src/view/.
hostedLibFiles (Optional) Viele Benutzer bevorzugen es, alle Tag-bezogenenen Dateien auf ihrem eigenen Server zu hosten. Dies bietet den Benutzern höhere Sicherheit in Bezug auf die Dateiverfügbarkeit zur Laufzeit und sie können den Code einfach auf Sicherheitslücken überprüfen. Wenn die Bibliothekskomponente der Erweiterung zur Laufzeit JavaScript-Dateien laden muss, sollten Sie diese Eigenschaft verwenden, um die betreffenden Dateien aufzulisten. Die aufgelisteten Dateien werden zusammen mit der Tag-Laufzeitbibliothek gehostet. Ihre Erweiterung kann die Dateien dann über eine URL laden, die mit der getHostedLibFileUrl-Methode abgerufen wird.

Diese Option enthält ein Array mit relativen Pfaden zu Bibliotheksdateien von Drittanbietern, die gehostet werden müssen.
main (Optional) Der relative Pfad eines Bibliotheksmoduls, das zur Laufzeit ausgeführt werden soll.

Dieses Modul wird immer in die Laufzeitbibliothek eingebunden und ausgeführt. Weil das Modul immer in die Laufzeitbibliothek eingebunden wird, empfehlen wir, nur dann ein „main“-Modul zu verwenden, wenn es unbedingt erforderlich ist, und seine Code-Größe minimal zu halten.

Es ist nicht garantiert, dass dieses Modul zuerst ausgeführt wird. Andere Module können davor ausgeführt werden.
configuration (Optional) Dies beschreibt den Abschnitt mit der Erweiterungskonfiguration der Erweiterung. Dies ist erforderlich, wenn Benutzer globale Einstellungen für die Erweiterung angeben müssen. Weitere Informationen dazu, wie dieses Feld aufgebaut sein soll, finden Sie im Anhang.
events (Optional) Ein Array von Typdefinitionen für Ereignisse. Die Struktur der einzelnen Objekte im Array finden Sie im Anhang unter Typdefinitionen.
conditions (Optional) Ein Array von Typdefinitionen für Bedingungen. Die Struktur der einzelnen Objekte im Array finden Sie im Anhang unter Typdefinitionen.
actions (Optional) Ein Array von Typdefinitionen für Aktionen. Die Struktur der einzelnen Objekte im Array finden Sie im Anhang unter Typdefinitionen.
dataElements (Optional) Ein Array von Typdefinitionen für Datenelemente. Die Struktur der einzelnen Objekte im Array finden Sie im Anhang unter Typdefinitionen.
sharedModules (Optional) Ein Array von gemeinsamen Moduldefinitionsobjekten. Jedes gemeinsame Modulobjekt im Array sollte wie folgt aufgebaut sein:
  • name: Der Name des gemeinsamen Moduls. Beachten Sie, dass dieser Name verwendet wird, wenn von anderen Erweiterungen auf gemeinsame Module verwiesen wird, wie unter Gemeinsame Module beschrieben. Dieser Name wird in keiner Benutzeroberfläche angezeigt. Er sollte sich von den Namen anderer gemeinsamer Module in Ihrer Erweiterung unterscheiden und muss den Benennungsregeln entsprechen. Er wird von Tags als Kennung verwendet und sollte nach der Veröffentlichung der Erweiterung nicht geändert werden.
  • libPath: Der relative Pfad zum gemeinsamen Modul. Er sollte nicht mit einem Schrägstrich beginnen. Er muss auf eine JavaScript-Datei mit der Erweiterung .js verweisen.

Anhang

Benennungsregeln

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

  • Darf höchstens 214 Zeichen lang sein
  • Darf nicht mit einem Punkt oder Unterstrich beginnen
  • Darf keine Großbuchstaben enthalten
  • Darf nur Zeichen enthalten, die in einer URL zulässig sind

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

Eigenschaften von Konfigurationsobjekten

Das Konfigurationsobjekt sollte wie folgt strukturiert sein:

Eigenschaft Beschreibung
viewPath Die relative URL zur Erweiterungskonfigurationsansicht. Sie sollte relativ zu viewBasePath sein und nicht mit einem Schrägstrich beginnen. Sie muss auf eine HTML-Datei mit der Erweiterung .html verweisen. Abfragezeichenfolgen- und Fragmentbezeichner-Suffixe (Hashes) sind zulässig.
schema Ein Objekt vom Typ JSON-Schema, das das Format eines gültigen Objekts beschreibt, das in der Erweiterungskonfigurationsansicht gespeichert wird. Da Sie der Entwickler der Konfigurationsansicht sind, müssen Sie sicherstellen, dass alle gespeicherten Einstellungsobjekte diesem Schema entsprechen. Dieses Schema wird auch für die Validierung verwendet, wenn Benutzer versuchen, Daten mit den Platform-Services zu speichern.

Beispiel für ein schema-Objekt:
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delay": {
      "type": "number",
      "minimum": 1
    }
  },
  "required": [
    "delay"
  ],
  "additionalProperties": false
}
Es wird empfohlen, zum manuellen Testen Ihres Schemas ein Tool wie JSON Schema Validator zu verwenden.
transforms (Optional) Ein Array von Objekten, wobei jedes Objekt eine Transformation darstellt, die bei der Ausgabe in die Laufzeitbibliothek an jedem entsprechenden Einstellungsobjekt durchgeführt werden soll. Weitere Informationen dazu, warum dies erforderlich ist und wie es verwendet wird, finden Sie im Abschnitt Transformationen.

Typdefinitionen

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

Eigenschaft Beschreibung
name Name des Typs. Dies muss ein eindeutiger Name innerhalb der Erweiterung sein. Der Name muss den Benennungsregeln entsprechen. Er wird von Tags als Kennung verwendet und sollte nach der Veröffentlichung Ihrer Erweiterung nicht geändert werden.
displayName Der Text, der zur Darstellung des Typs in der Datenerfassungs-Benutzeroberfläche verwendet wird. Er sollte für Menschen lesbar sein.
categoryName (Optional) Wenn zur Verfügung gestellt, wird der displayName in der Datenerfassungs-Benutzeroberfläche unter categoryName aufgeführt. Alle Typen mit dem gleichen categoryName-Wert werden unter der gleichen Kategorie aufgeführt. Wenn Ihre Erweiterung beispielsweise den Ereignistyp keyUp und den Ereignistyp keyDown bereitstellt und beide Ereignistypen einen categoryName-Wert von Keyboard aufweisen, werden beide Ereignistypen unter der Kategorie „Keyboard“ aufgelistet, während der Benutzer beim Erstellen einer Regel einen Eintrag aus der Liste der verfügbaren Ereignistypen auswählt. Der Wert von categoryName sollte für Menschen lesbar sein.
libPath Der relative Pfad zum Bibliotheksmodul des Typs. Er sollte nicht mit einem Schrägstrich beginnen. Er muss auf eine JavaScript-Datei mit der Erweiterung .js verweisen.
viewPath (Optional) Die relative URL zur Ansicht des Typs. Sie sollte relativ zu viewBasePath sein und nicht mit einem Schrägstrich beginnen. Sie muss auf eine HTML-Datei mit der Erweiterung .html verweisen. Abfragezeichenfolgen und Fragmentbezeichner (Hashes) sind zulässig. Wenn das Bibliotheksmodul Ihres Typs keine Einstellungen von Benutzern verwendet, können Sie diese Eigenschaft ausschließen. Platform wird dann stattdessen einen Platzhalter anzeigen, der angibt, dass keine Konfiguration erforderlich ist.
schema Ein Objekt vom Typ JSON-Schema, das das Format eines gültigen Einstellungsobjekts beschreibt, das vom Benutzer gespeichert werden kann. Die Einstellungen werden normalerweise von einem Benutzer über die Datenerfassungs-Benutzeroberfläche konfiguriert und gespeichert. In diesen Fällen kann die Ansicht der Erweiterung die erforderlichen Schritte zur Überprüfung der vom Benutzer bereitgestellten Einstellungen durchführen. Auf der anderen Seite entscheiden sich einige Benutzer dafür, Tag-APIs direkt ohne die Hilfe einer Benutzeroberfläche zu verwenden. Mit diesem Schema wird Platform in die Lage versetzt, genau zu überprüfen, ob die von den Benutzern gespeicherten settings-Objekte unabhängig davon, ob eine Benutzeroberfläche verwendet wird, in einem Format vorliegen, das mit dem Bibliotheksmodul kompatibel ist, das zur Laufzeit das settings-Objekt verarbeitet.

Ein Beispiel für ein schema-Objekt:
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delay": {
      "type": "number",
      "minimum": 1
    }
  },
  "erforderlich": [
    "delay"
  ],
  "additionalProperties": false
}
Es wird empfohlen, zum manuellen Testen Ihres Schemas ein Tool wie JSON Schema Validator zu verwenden.
transforms (Optional) Ein Array von Objekten, wobei jedes Objekt eine Transformation darstellt, die bei der Ausgabe in die Laufzeitbibliothek an jedem entsprechenden Einstellungsobjekt durchgeführt werden soll. Weitere Informationen dazu, warum dies erforderlich ist und wie es verwendet wird, finden Sie im Abschnitt zu Transformationen.

Transformationen

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"
    ]
  }
}
  • Wenn Sie für propertyPath die Zeichenfolge foo.bar angeben, wird der Wert "A string" umgewandelt.
  • Wenn Sie für propertyPath die Zeichenfolge foo.baz[] angeben, wird jeder Wert im Array baz umgewandelt.
  • Wenn Sie für propertyPath die Zeichenfolge foo.baz angeben, wird das Array baz umgewandelt.

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

WARNUNG

Die Verwendung der Array-Notation im propertyPath-Attribut (z. B. foo.baz[]) wird im Sandboxtool für Erweiterungen noch nicht unterstützt.

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"]
    }
  ]
}
  • type definiert den Typ der Transformation, die auf das Einstellungsobjekt angewendet werden soll.
  • propertyPath ist eine Zeichenfolge mit Punkt als Trennzeichen, die Platform angibt, wo sich die Eigenschaft befindet, die im settings-Objekt geändert werden muss.
  • parameters ist ein Array von Parameternamen, die in die Signatur der Wrapping-Funktion aufgenommen werden sollen.

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"
    }
  ]
}
  • type definiert den Typ der Transformation, die auf das Einstellungsobjekt angewendet werden soll.
  • propertyPath ist eine Zeichenfolge mit Punkt als Trennzeichen, die Platform angibt, wo sich die Eigenschaft befindet, die im settings-Objekt geändert werden muss.

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"
    }
  ]
}
  • type definiert den Typ der Transformation, die auf das Einstellungsobjekt angewendet werden soll.
  • propertyPath ist eine Zeichenfolge mit Punkt als Trennzeichen, die Platform angibt, wo sich die Eigenschaft befindet, die im settings-Objekt geändert werden muss.

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.

Auf dieser Seite