Manifesto dell’estensione

NOTA

Adobe Experience Platform Launch è stato classificato come una suite di tecnologie di raccolta dati in Adobe Experience Platform. Di conseguenza, sono state introdotte diverse modifiche terminologiche nella documentazione del prodotto. Consulta questo documento come riferimento consolidato delle modifiche terminologiche.

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:

Proprietà Descrizione
name Nome dell’estensione. Deve essere univoco rispetto a tutte le altre estensioni e deve essere conforme alle regole relative alla denominazione. Questo viene utilizzato dai tag come identificatore e non deve essere modificato dopo la pubblicazione dell'estensione.
platform Piattaforma per l’estensione. Al momento l’unico valore accettato è web.
version Versione dell’estensione. Deve seguire il formato di controllo delle versioni semver. È conforme al campo npm version.
displayName Nome leggibile dell’estensione. Questo verrà mostrato agli utenti di Platform. Non è necessario menzionare "tag" o "estensione"; Gli utenti sapranno già che stanno cercando un’estensione di tag.
description Descrizione dell’estensione. Questo verrà mostrato agli utenti di Platform. Se l’estensione consente agli utenti di implementare il prodotto sul loro sito web, descrivi le funzioni del prodotto. Non è necessario menzionare "tag" o "estensione"; Gli utenti sapranno già che stanno cercando un’estensione di tag.
iconPath (Facoltativo) Percorso relativo dell'icona che verrà visualizzata per l'estensione. Non può iniziare con una barra. Deve fare riferimento a un file SVG con estensione .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) URL dell’inserzione relativa all’estensione su Adobe Exchange. Deve corrispondere al pattern https://www.adobeexchange.com/experiencecloud.details.######.html.
viewBasePath Percorso relativo della sottodirectory contenente tutte le viste e le relative risorse (HTML, JavaScript, CSS, immagini). Platform ospita su un server web questa directory, da cui carica i contenuti iframe. Questo campo è obbligatorio e non deve iniziare con una barra. Ad esempio, se tutte le viste sono contenute in src/view/, il valore di viewBasePath sarà src/view/.
hostedLibFiles (Facoltativo) Molti dei nostri utenti preferiscono ospitare tutti i file relativi ai tag sul proprio server. Questo offre agli utenti una maggiore certezza sulla disponibilità dei file in fase di esecuzione e consente loro di analizzare facilmente il codice per individuare eventuali vulnerabilità di sicurezza. Se la porzione libreria dell’estensione deve caricare dei file JavaScript in fase di esecuzione, è consigliabile elencare tali file mediante questa proprietà. I file elencati saranno in hosting accanto alla libreria di runtime di tag. L’estensione può quindi caricare i file tramite un URL recuperato utilizzando il metodo getHostedLibFileUrl.

Questa opzione contiene un array con i percorsi relativi dei file libreria di terze parti che devono essere ospitati.
main (Facoltativo) Percorso relativo di un modulo libreria da eseguire in fase runtime.

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) Descrive la porzione di configurazione dell’estensione. Questa proprietà è necessaria se gli utenti dovranno fornire le impostazioni globali per l’estensione. Per informazioni dettagliate sulla struttura del campo, consulta l’appendice.
events (Facoltativo) Array delle definizioni dei tipi di evento. Per informazioni sulla struttura di ciascun oggetto presente nell’array, consulta la sezione dell’appendice sulle definizioni dei tipi.
conditions (Facoltativo) Array delle definizioni dei tipi di condizione. Per informazioni sulla struttura di ciascun oggetto presente nell’array, consulta la sezione dell’appendice sulle definizioni dei tipi.
actions (Facoltativo) Array delle definizioni dei tipi di azione. Per informazioni sulla struttura di ciascun oggetto presente nell’array, consulta la sezione dell’appendice sulle definizioni dei tipi.
dataElements (Facoltativo) Array delle definizioni dei tipi di elemento dati. Per informazioni sulla struttura di ciascun oggetto presente nell’array, consulta la sezione dell’appendice sulle definizioni dei tipi.
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. Questo viene utilizzato 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

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

L’oggetto di configurazione deve essere strutturato nel modo seguente:

Proprietà Descrizione
viewPath URL relativo della vista di configurazione dell’estensione. Deve essere relativo a 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) Array di oggetti in cui ogni oggetto rappresenta una trasformazione da eseguire su ogni oggetto impostazioni corrispondente quando viene emesso nella libreria runtime. Per ulteriori informazioni sulle ragioni e le modalità di utilizzo di questa proprietà, consulta la sezione relativa alle trasformazioni.

Definizioni dei tipi

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:

Proprietà Descrizione
name Nome del tipo. Deve essere un nome univoco all’interno dell’estensione. Il nome deve essere conforme alle regole di denominazione. Questo viene utilizzato dai tag come identificatore e non deve essere modificato dopo la pubblicazione dell'estensione.
displayName Testo che verrà utilizzato per rappresentare il tipo all’interno dell’interfaccia utente di Raccolta dati. Deve essere leggibile.
categoryName (Facoltativo) Se fornito, il displayName sarà elencato in categoryName nell’interfaccia utente di raccolta dati. 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 Percorso relativo del modulo libreria del tipo. Non può iniziare con una barra. Deve fare riferimento a un file JavaScript con estensione .js.
viewPath (Facoltativo) URL relativo per la vista del tipo. Deve essere relativo a 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 in genere configurate e salvate da un utente che utilizza l’interfaccia utente Raccolta dati. In questi casi, la vista dell’estensione può eseguire i passaggi necessari per convalidare le impostazioni fornite dall’utente. D’altro canto, alcuni utenti scelgono di utilizzare direttamente le API dei tag senza l’aiuto 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": "oggetto",
  "properties": {
    "ritardo": {
      "type": "numero",
      "minimo": 1
    }
  },
  "required": [
    "delay"
  ],
  "additionalProperties": false
}
È consigliabile utilizzare uno strumento come JSON Schema validator per verificare manualmente lo schema.
transforms (Facoltativo) Array di oggetti in cui ogni oggetto rappresenta una trasformazione da eseguire su ogni oggetto impostazioni corrispondente quando viene emesso nella libreria runtime. Per ulteriori informazioni sulle ragioni e sulle modalità di utilizzo, consulta la sezione relativa alle trasformazioni.

Trasformazioni

Per alcuni casi d’uso specifici, le estensioni devono trasformare gli oggetti delle impostazioni salvati da una visualizzazione da Platform prima che vengano emessi nella libreria di runtime di 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. La propertyPath è una stringa delimitata da un punto che indica ai tag dove trovare la proprietà che deve essere modificata all'interno dell'oggetto settings. Di seguito è riportato un oggetto impostazioni di esempio e alcuni propertyPath:

{
  foo: {
    bar: "A string",
    baz: [
      "A",
      "B",
      "C"
    ]
  }
}
  • Se imposti propertyPath su foo.bar, verrà trasformato il valore "A string".
  • Se imposti propertyPath su foo.baz[], verrà trasformato ciascun valore presente nell’array baz.
  • Impostando propertyPath su foo.baz si trasforma l’array baz.

I percorsi delle proprietà possono utilizzare qualsiasi combinazione di array e notazione di oggetto per applicare trasformazioni dell’oggetto impostazioni a qualsiasi livello.

AVVERTENZA

L’utilizzo della notazione dell’array nell’attributo 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 della funzione consente l’esecuzione del codice scritto dagli utenti di Platform da parte di un modulo libreria all’interno della libreria di runtime dei tag emessi.

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 la nostra azione si attiva all'interno della libreria di runtime di tag, vogliamo eseguire il codice dell'utente e passarlo con un nome utente.

Quando l’oggetto impostazioni viene salvato dalla vista del tipo di azione, il codice dell’utente è semplicemente una stringa. Questo è positivo perché può essere serializzato correttamente da e verso JSON; tuttavia, è anche negativo perché in genere viene emesso nella libreria di runtime di tag come stringa e non come 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.

Come soluzione a questa situazione, l’utilizzo della funzione di trasformazione indica a Platform di racchiudere il codice dell’utente in una funzione eseguibile quando viene emessa nella libreria di runtime di 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 settings viene emesso nella libreria di runtime di tag, viene trasformato nel 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 file consente di emettere il codice scritto dagli utenti di Platform in un file separato dalla libreria di runtime di tag. Il file sarà in hosting accanto alla libreria di runtime dei tag e può quindi essere caricato in base alle esigenze dell’estensione in fase di runtime.

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.');"
  }
}

Desideriamo che il codice dell’utente sia inserito in un file separato anziché incluso all’interno della libreria di runtime di tag. Quando una regola che utilizza la nostra azione si attiva all'interno della libreria di runtime di tag, desideri caricare il codice dell'utente 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 settings viene emesso nella libreria di runtime di tag, viene trasformato nel 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 settings vengono emesse nella libreria di runtime di tag . Se alcune proprietà vengono utilizzate solo per la vista delle estensioni, in particolare se contengono informazioni riservate (ad esempio token segreto), utilizza la trasformazione di rimozione per evitare che le informazioni vengano emesse nella libreria di runtime di 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"
  }
}

Desideriamo non includere la proprietà bar all’interno della libreria di runtime di 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 settings viene emesso nella libreria di runtime di tag, viene trasformato nel seguente:

{
  foo: {
  }
}

In questo caso, il valore foo.bar è stato rimosso dall’oggetto delle impostazioni.

In questa pagina