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:
name
platform
web
.version
displayName
description
iconPath
(Optional).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)https://www.adobeexchange.com/experiencecloud.details.######.html
entsprechen.viewBasePath
src/view/
befinden, hat viewBasePath
den Wert src/view/
.hostedLibFiles
(Optional)Diese Option enthält ein Array mit relativen Pfaden zu Bibliotheksdateien von Drittanbietern, die gehostet werden müssen.
main
(Optional)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)events
(Optional)conditions
(Optional)actions
(Optional)dataElements
(Optional)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 naming-rules
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 config-object
Das Konfigurationsobjekt sollte wie folgt strukturiert sein:
viewPath
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)Typdefinitionen type-definitions
Eine Typdefinition ist ein Objekt, mit dem ein Ereignis-, Bedingungs-, Aktions- oder Datenelementtyp beschrieben wird. Das Objekt besteht aus folgenden Elementen:
name
displayName
categoryName
(Optional)displayName
in der Benutzeroberfläche unter der 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
.js
verweisen.viewPath
(Optional)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
}
},
"required": [
"delay"
],
"additionalProperties": false
}
Es wird empfohlen, zum manuellen Testen Ihres Schemas ein Tool wie JSON Schema Validator zu verwenden.
transforms
(Optional)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"
]
}
}
- Wenn Sie für
propertyPath
die Zeichenfolgefoo.bar
angeben, wird der Wert"A string"
umgewandelt. - Wenn Sie für
propertyPath
die Zeichenfolgefoo.baz[]
angeben, wird jeder Wert im Arraybaz
umgewandelt. - Wenn Sie für
propertyPath
die Zeichenfolgefoo.baz
angeben, wird das Arraybaz
umgewandelt.
Für Eigenschaftenpfade können beliebige Kombinationen aus Array- und Objektnotation verwendet werden, um Transformationen auf jeder Ebene des Einstellungsobjekts anzuwenden.
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.