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:

Appendice

Regole di denominazione naming-rules

Il valore di qualsiasi campo name all’interno di extension.json deve essere conforme alle regole seguenti:

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:

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

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:

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

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"
    ]
  }
}

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

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"]
    }
  ]
}

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"
    }
  ]
}

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"
    }
  ]
}

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.