Manifesto dell’estensione
Nella directory di base dell’estensione è necessario creare un file denominato extension.json
. Contiene informazioni critiche sull’estensione che consentono a Adobe Experience Platform di utilizzarla correttamente. Alcuni contenuti sono creati secondo le regole npm per package.json
.
Un esempio di extension.json
è disponibile nell’archivio GitHub dell’estensione Hello World.
Un manifesto dell’estensione deve essere costituito dai seguenti elementi:
name
platform
web
.version
displayName
description
iconPath
(Facoltativo).svg
. Il file SVG deve essere quadrato e può essere ridimensionato da Platform.author
L’oggetto “author” deve essere strutturato nel modo seguente:
name
: nome dell’autore dell’estensione. In alternativa, qui è possibile utilizzare il nome della società.url
(facoltativo): URL in cui si possono trovare ulteriori informazioni sull’autore dell’estensione.email
(facoltativo): indirizzo e-mail dell’autore dell’estensione.
È conforme alle regole npm per il campo author.
exchangeUrl
(richiesto per le estensioni pubbliche)https://www.adobeexchange.com/experiencecloud.details.######.html
.viewBasePath
src/view/
, il valore di viewBasePath
sarà src/view/
.hostedLibFiles
(Facoltativo)Questa opzione contiene un array con i percorsi relativi dei file libreria di terze parti che devono essere ospitati.
main
(Facoltativo)Questo modulo sarà sempre incluso nella libreria runtime ed eseguito. Poiché il modulo verrà sempre incluso nella libreria runtime, si consiglia di utilizzare un modulo “main” solo se è assolutamente necessario e di mantenerne minima la dimensione del codice.
Non è garantito che questo modulo sia eseguito per primo; è possibile che altri moduli vengano eseguiti prima di esso.
configuration
(Facoltativo)events
(Facoltativo)conditions
(Facoltativo)actions
(Facoltativo)dataElements
(Facoltativo)sharedModules
(Facoltativo)Array degli oggetti di definizione dei moduli condivisi. Ciascun oggetto di modulo condiviso presente nell’array deve essere strutturato nel modo seguente:
name
: nome del modulo condiviso. Questo nome verrà utilizzato quando si fa riferimento a moduli condivisi da altre estensioni, come descritto in Moduli condivisi. Questo nome non viene mai visualizzato in alcuna area dell’interfaccia utente. Deve essere univoco rispetto ai nomi di altri moduli condivisi all’interno dell’estensione e deve essere conforme alle regole di denominazione. Viene usato dai tag come identificatore e non deve essere modificato dopo la pubblicazione dell’estensione.libPath
: percorso relativo del modulo condiviso. Non può iniziare con una barra. Deve fare riferimento a un file JavaScript con estensione.js
.
Appendice
Regole di denominazione naming-rules
Il valore di qualsiasi campo name
all’interno di extension.json
deve essere conforme alle regole seguenti:
- Può contenere un massimo 214 caratteri.
- Non deve iniziare con un punto o un carattere di sottolineatura.
- Non deve contenere lettere maiuscole.
- Deve contenere solo caratteri sicuri per gli URL.
Queste regole sono conformi alle regole npm per il nome del pacchetto.
Proprietà dell’oggetto di configurazione config-object
L’oggetto di configurazione deve essere strutturato nel modo seguente:
viewPath
viewBasePath
e non deve iniziare con una barra. Deve fare riferimento a un file HTML con estensione .html
. È possibile utilizzare suffissi per stringhe di query e identificatori di frammento (hash).schema
Oggetto dello schema JSON che descrive il formato di un oggetto valido salvato dalla vista di configurazione dell’estensione. In quanto sviluppatore della vista di configurazione, devi assicurarti che tutti gli oggetti impostazioni salvati siano conformi a questo schema. Questo schema verrà utilizzato anche per la convalida quando gli utenti tenteranno di salvare i dati tramite i servizi di Platform
Esempio di un oggetto schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"delay": {
"type": "number",
"minimum": 1
}
},
"required": [
"delay"
],
"additionalProperties": false
}
È consigliabile utilizzare uno strumento come JSON Schema validator per verificare manualmente lo schema.
transforms
(Facoltativo)Definizioni dei tipi type-definitions
La definizione di un tipo è un oggetto utilizzato per descrivere un tipo di evento, di condizione, di azione o di elemento dati. L’oggetto è costituito dai seguenti elementi:
name
displayName
categoryName
(Facoltativo)displayName
verrà elencato in categoryName
nell'interfaccia utente. Tutti i tipi con lo stesso categoryName
saranno elencati nella stessa categoria. Ad esempio, se l’estensione ha fornito un tipo di evento keyUp
e un tipo di evento keyDown
, entrambi con categoryName
impostato su Keyboard
, entrambi i tipi di evento sono elencati nella categoria Keyboard quando l’utente seleziona una voce dall’elenco dei tipi di evento disponibili per creare una regola. Il valore di categoryName
deve essere leggibile.libPath
.js
.viewPath
(Facoltativo)viewBasePath
e non deve iniziare con una barra. Deve fare riferimento a un file HTML con estensione .html
. È possibile utilizzare identificatori di stringhe di query e frammenti (hash). Se il modulo libreria del tipo non utilizza impostazioni configurate da un utente, è possibile escludere questa proprietà e Platform al suo posto mostrerà un segnaposto che informa che non è necessaria alcuna configurazione.schema
Oggetto con schema JSON che descrive il formato di un oggetto impostazioni valido che può essere salvato dall’utente. Le impostazioni vengono generalmente configurate e salvate da un utente che utilizza l’interfaccia di Data Collection. In questi casi, la vista dell’estensione può eseguire i passaggi necessari per convalidare le impostazioni fornite dall’utente. Alcuni utenti preferiscono invece utilizzare direttamente le API dei tag senza l’ausilio di alcuna interfaccia utente. Lo scopo di questo schema è consentire a Platform di convalidare correttamente che gli oggetti impostazioni salvati dagli utenti siano in un formato compatibile con il modulo libreria che agirà in base all’oggetto impostazioni stesso in fase di esecuzione, indipendentemente dall’utilizzo o meno di un'interfaccia utente.
Esempio di oggetto schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"delay": {
"type": "number",
"minimum": 1
}
},
"required": [
"delay"
],
"additionalProperties": false
}
È consigliabile utilizzare uno strumento come JSON Schema validator per verificare manualmente lo schema.
transforms
(Facoltativo)Trasformazioni transforms
Per alcuni casi d’uso specifici, le estensioni richiedono che gli oggetti impostazioni salvati da una vista siano trasformati da Platform prima che vengano emessi nella relativa libreria runtime dei tag. È possibile richiedere che una o più di queste trasformazioni siano effettuate impostando la proprietà transforms
quando si imposta la definizione di un tipo all’interno di extension.json
. La proprietà transforms
è un array di oggetti in cui ogni oggetto rappresenta una trasformazione che deve essere eseguita.
Tutte le trasformazioni richiedono type
e propertyPath
. Il valore di type
può essere function
, remove
o file
e descrive il tipo di trasformazione che verrà applicata da Platform all’oggetto impostazioni. Il valore di propertyPath
è una stringa delimitata da punti che indica ai tag dove trovare la proprietà da modificate all’interno dell’oggetto impostazioni. Di seguito è riportato un oggetto impostazioni di esempio e alcuni propertyPath
:
{
foo: {
bar: "A string",
baz: [
"A",
"B",
"C"
]
}
}
- Se imposti
propertyPath
sufoo.bar
, verrà trasformato il valore"A string"
. - Se imposti
propertyPath
sufoo.baz[]
, verrà trasformato ciascun valore presente nell’arraybaz
. - Impostando
propertyPath
sufoo.baz
si trasforma l’arraybaz
.
I percorsi delle proprietà possono utilizzare qualsiasi combinazione di array e notazione di oggetto per applicare trasformazioni dell’oggetto impostazioni a qualsiasi livello.
propertyPath
(ad esempio foo.baz[]
) non è ancora supportato nello strumento sandbox dell’estensione.Le sezioni seguenti descrivono le trasformazioni disponibili e come utilizzarle.
Trasformazione tramite funzione
La trasformazione tramite funzione consente di eseguire il codice scritto dagli utenti di Platform tramite un modulo libreria all’interno della libreria runtime di tag emessa.
Supponiamo di voler fornire un tipo di azione “script personalizzato”. La visualizzazione dell’azione “script personalizzato” potrebbe fornire un’area di testo in cui l’utente potrà immettere il codice. Supponiamo che un utente abbia immesso il seguente codice nell’area di testo:
console.log('Welcome, ' + username +'. This is ZomboCom.');
Quando l’utente salva la regola, l’oggetto impostazioni salvato dalla vista potrebbe essere simile al seguente:
{
foo: {
bar: "console.log('Welcome, ' + username +'. This is ZomboCom.');"
}
}
Quando una regola che utilizza questa azione viene attivata nella libreria runtime dei tag, dovrà essere eseguito il codice dell’utente per trasmettervi un nome utente.
Quando l’oggetto impostazioni viene salvato dalla vista del tipo di azione, il codice dell’utente è semplicemente una stringa. Questo va bene perché può essere correttamente serializzato da e verso JSON; tuttavia, si tratta anche di un problema perché generalmente viene emesso nella libreria runtime dei tag anche come una stringa, anziché come una funzione eseguibile. Anche se è possibile tentare di eseguire il codice all’interno del modulo libreria del tipo di azione utilizzando eval
o un costruttore di funzione, è altamente sconsigliato a causa di criteri per la sicurezza dei contenuti che potrebbero bloccare l’esecuzione.
Per ovviare a questa situazione, l’utilizzo della trasformazione tramite funzione indica a Platform di racchiudere il codice dell’utente in una funzione eseguibile quando viene emesso nella libreria runtime dei tag. Per risolvere il problema di questo esempio, definiamo la trasformazione sulla definizione del tipo in extension.json
nel modo seguente:
{
"transforms": [
{
"type": "function",
"propertyPath": "foo.bar",
"parameters": ["username"]
}
]
}
type
definisce il tipo di trasformazione da applicare all’oggetto impostazioni.propertyPath
è una stringa delimitata da punti che indica a Platform dove trovare la proprietà da modificare all’interno dell’oggetto delle impostazioni.parameters
è un array di nomi dei parametri da includere nella firma della funzione di wrapping.
Quando l’oggetto impostazioni viene emesso nella libreria runtime dei tag, verrà trasformato nel modo seguente:
{
foo: {
bar: function(username) {
console.log('Welcome, ' + username +'. This is ZomboCom.');
}
}
}
Il modulo libreria può quindi richiamare la funzione contenente il codice dell’utente e trasmetterlo nell’argomento username
.
Trasformazione tramite file
La trasformazione tramite file consente di emettere il codice scritto dagli utenti di Platform in un file separato dalla libreria runtime dei tag. Il file sarà ospitato accanto alla libreria runtime dei tag e, se necessario, può essere caricato dall’estensione in fase di esecuzione.
Supponiamo di voler fornire un tipo di azione “script personalizzato”. La visualizzazione del tipo di azione potrebbe fornire un’area di testo in cui l’utente può immettere alcuni codici. Supponiamo che un utente abbia immesso il seguente codice nell’area di testo:
console.log('This is ZomboCom.');
Quando l’utente salva la regola, l’oggetto impostazioni salvato dalla vista potrebbe essere simile al seguente:
{
foo: {
bar: "console.log('This is ZomboCom.');"
}
}
Il codice dell’utente dovrebbe essere inserito in un file separato, invece di essere incluso nella libreria runtime dei tag. Quando una regola che utilizza la nostra azione viene attivata nella libreria runtime dei tag, il codice dell’utente dovrà essere caricato aggiungendo un elemento script al corpo del documento. Per risolvere il problema di questo esempio, definiamo la trasformazione nella definizione del tipo di azione in extension.json
nel modo seguente:
{
"transforms": [
{
"type": "file",
"propertyPath": "foo.bar"
}
]
}
type
definisce il tipo di trasformazione da applicare all’oggetto impostazioni.propertyPath
è una stringa delimitata da punti che indica a Platform dove trovare la proprietà da modificare all’interno dell’oggetto delle impostazioni.
Quando l’oggetto impostazioni viene emesso nella libreria runtime dei tag, verrà trasformato nel modo seguente:
{
foo: {
bar: "//launch.cdn.com/path/abc.js"
}
}
In questo caso, il valore di foo.bar
è stato trasformato in un URL. L’URL esatto verrà determinato al momento della creazione della libreria. Il file riceverà sempre l’estensione .js
e verrà distribuito utilizzando un tipo MIME orientato a JavaScript. In futuro potrebbe venir aggiunto il supporto di altri tipi MIME.
Trasformazione di rimozione
Per impostazione predefinita, tutte le proprietà dell’oggetto impostazioni sono emesse nella libreria runtime dei tag. Se alcune proprietà vengono utilizzate solo per la vista delle estensioni, in particolare se contengono informazioni riservate (ad esempio un token segreto), è necessario usare la trasformazione di rimozione per impedire che le informazioni vengano emesse nella libreria runtime dei tag.
Supponiamo di voler fornire un nuovo tipo di azione. La vista del tipo di azione potrebbe fornire un campo di input in cui l’utente può immettere una chiave segreta che consentirà la connessione a una API specifica. Supponiamo che un utente abbia immesso il testo seguente:
ABCDEFG
Quando l’utente salva la regola, l’oggetto impostazioni salvato dalla vista potrebbe essere simile al seguente:
{
foo: {
bar: "ABCDEFG"
}
}
La proprietà bar
non dovrebbe essere inclusa nella libreria runtime dei tag. Per risolvere il problema di questo esempio, definiamo la trasformazione nella definizione del tipo di azione in extension.json
nel modo seguente:
{
"transforms": [
{
"type": "remove",
"propertyPath": "foo.bar"
}
]
}
type
definisce il tipo di trasformazione da applicare all’oggetto impostazioni.propertyPath
è una stringa delimitata da punti che indica a Platform dove trovare la proprietà da modificare all’interno dell’oggetto delle impostazioni.
Quando l’oggetto impostazioni viene emesso nella libreria runtime dei tag, verrà trasformato nel modo seguente:
{
foo: {
}
}
In questo caso, il valore foo.bar
è stato rimosso dall’oggetto delle impostazioni.