Caricare e implementare test end-to-end

NOTA

Adobe Experience Platform Launch viene riclassificato come una suite di tecnologie di raccolta dati nell’Experience Platform. Queste modifiche verranno implementate in tutta la documentazione del prodotto nelle prossime settimane. Fare riferimento al seguente documento per un riferimento consolidato delle modifiche terminologiche.

Il test delle estensioni prevede l’utilizzo delle API Adobe Experience Platform Launch e/o di strumenti per riga di comando per caricare i pacchetti di estensione, quindi l’utilizzo dell’interfaccia utente di Platform Launch per installare il pacchetto di estensione su una proprietà ed esercitarne le funzionalità all’interno di una libreria e una build di Platform Launch.

Questo documento illustra come implementare test end-to-end per l'estensione.

NOTA

Questa guida presuppone che si stia utilizzando MacOS con Node.js e npm installati e disponibili.

Convalidare l’estensione

Una volta che il team è soddisfatto delle prestazioni dell’estensione e dei risultati visualizzati nello strumento Sandbox, il pacchetto di estensione dovrebbe essere pronto per essere caricato su Platform Launch.

Prima di caricarlo, verifica la presenza di eventuali campi o impostazioni obbligatori. Ad esempio, è consigliabile rivedere (come minimo) il manifesto dell’estensione, la configurazione dell’estensione, le viste e i moduli libreria.

Un esempio specifico è il file del logo: aggiungi una riga "iconPath": "example.svg", al file extension.json e includi il file di immagine del logo nel progetto. Percorso relativo dell’icona che verrà visualizzata per l’estensione all’interno di Platform Launch. Non deve iniziare con una barra. Deve fare riferimento a un file SVG con estensione .svg. Il file SVG deve apparire corretto quando viene riprodotto con proporzioni quadrate e può essere ridimensionato dall’interfaccia utente. Per ulteriori informazioni, consulta l’articolo su come ridimensionare i file SVG.

NOTA

Per le estensioni pubbliche, includi un elemento in extension.json con un collegamento all’inserzione su Exchange. Il manifesto dell’estensione deve includere una voce come questa: "exchangeUrl":"https://www.adobeexchange.com/experiencecloud.details.12345.html" che punta all’URL dell’inserzione su Exchange.

Creare un’integrazione Adobe I/O

Per utilizzare l’API o gli strumenti per riga di comando, è necessario un account tecnico su Adobe I/O. L’account tecnico verrà creato nella console I/O, quindi verrà utilizzato lo strumento Uploader per caricare il pacchetto dell’estensione.

Per informazioni sulla creazione di un account tecnico da utilizzare con Platform Launch, consulta la guida Token di accesso.

IMPORTANTE

Per creare un’integrazione in Adobe I/O è necessario essere un amministratore o uno sviluppatore dell’organizzazione Experience Cloud.

Se non riesci a creare un’integrazione, probabilmente non disponi delle autorizzazioni corrette; in questo caso chiedi a uno degli amministratori dell’organizzazione di completare i passaggi necessari oppure di assegnarti il ruolo di sviluppatore in modo da poterlo fare autonomamente.

Caricare il pacchetto dell’estensione

Con le credenziali corrette, puoi testare il pacchetto dell’estensione end-to-end.

La prima volta che carichi il pacchetto di estensione, questo viene posto in stato development. Ciò significa che è visibile solo per la tua società Platform Launch e solo con una proprietà Platform Launch contrassegnata per lo sviluppo di estensioni (per ulteriori informazioni, vedi più avanti).

Per ora, torna alla riga di comando all’interno della directory che contiene il pacchetto .zip.

npx @adobe/reactor-uploader

npx consente di scaricare ed eseguire un pacchetto npm senza installarlo sul computer. Questo è il modo più semplice per eseguire lo strumento Uploader.

Lo strumento Uploader chiederà di inserire diverse informazioni. L’ID dell’account tecnico, la chiave API e altre informazioni possono essere recuperati dalla console di Adobe I/O. Passa alla pagina Integrations (Integrazioni) nella console di I/O. Seleziona l'organizzazione corretta dal menu a discesa, trova l'integrazione corretta e seleziona Visualizza.

  • Percorso della chiave privata: /path/to/private.key. Si tratta del luogo in cui è stata salvata la chiave privata di cui al punto 2 qui sopra.
  • ID dell’organizzazione: è disponibile nella pagina di panoramica della console di I/O lasciata aperta in precedenza; usa Copia/Incolla.
  • ID account tecnico: è disponibile nella console I/O; usa Copia/Incolla.
  • Chiave API: è disponibile nella console I/O; usa Copia/Incolla.
  • Segreto cliente: è disponibile nella console I/O; usa Copia/Incolla.
  • Percorso del file extension_package da caricare: /path/to/extension_package.zip. Se richiami lo strumento Uploader dalla directory che contiene il pacchetto .zip, non occorre digitarne il persorso: è sufficiente selezionarlo dall’elenco.

Il pacchetto dell’estensione verrà quindi caricato e lo strumento Uploader ti fornirà l’ID del file extension_package.

NOTA

Durante il caricamento o l'applicazione di patch, il pacchetto dell'estensione viene posto in uno stato "in sospeso" mentre il sistema lo estrae in modo asincrono e lo implementa. Durante questo processo, è possibile eseguire il polling dell’ID di extension_package per il relativo stato utilizzando l’API e, all’interno di Platform Launch, nel catalogo viene visualizzata la scheda dell’estensione contrassegnata “In sospeso”.

NOTA

Se pensi di dover eseguire spesso lo strumento di caricamento, inserire tutte queste informazioni ogni volta può risultare laborioso. È possibile trasmettere questi elementi anche come argomenti dalla riga di comando. Per ulteriori informazioni, consulta la sezione sugli argomenti della riga di comando nella documentazione NPM.

Creare una proprietà di sviluppo

Quando accedi a Platform Launch, viene visualizzata innanzitutto la schermata Proprietà. Una proprietà è un contenitore per i tag da distribuire e può essere utilizzata in uno o più siti.

Qui puoi vedere la proprietà “test”; tuttavia la prima volta che esegui l’accesso non sarà visibile alcuna proprietà. Per crearne una, fai clic su Nuova proprietà. Immetti un nome e un URL. Puoi utilizzare l’URL del sito di prova o della pagina in cui intendi testare l’estensione. Questo campo di dominio può essere utilizzato da alcune estensioni o da una condizione tramite l’estensione Core (che verrà trattata più avanti). Tieni presente che localhost qui non funziona, quindi se usi un URL localhost, ai fini di questo test utilizza un valore qualsiasi, ad esempio example.com.

Poiché vuoi utilizzare questa proprietà per il test di sviluppo delle estensioni, espandi le Opzioni avanzate e assicurati di selezionare la casella “Configure for extension development” (Configura per sviluppo estensioni).

Seleziona Salva in basso per salvare la nuova proprietà.

Viene visualizzata di nuovo la schermata Proprietà. Fai clic sul nome della proprietà appena creata. Questa è la schermata Panoramica di una proprietà. Questa schermata contiene i collegamenti di navigazione globale, in alto, e altri collegamenti per accedere a ogni area del sistema.

Installare l’estensione

Per installare l'estensione in questa proprietà, fai clic sul collegamento Estensioni, nell'area di navigazione principale in alto.

Nella schermata delle estensioni installate, è visualizzata l’estensione Core. L’estensione Core contiene tutte le funzionalità per la gestione dei tag disponibili in Platform Launch. Per aggiungere la tua estensione, fai clic su Catalogo:

Il catalogo presenta le icone delle schede di ogni estensione disponibile. Se la tua estensione non viene visualizzata nel catalogo, assicurati di aver completato i passaggi descritti nelle sezioni precedenti sull’impostazione di Adobe Admin Console e sulla creazione del pacchetto di estensione. Se Platform Launch non ha completato l’elaborazione iniziale, il pacchetto di estensione potrebbe essere visualizzato come In sospeso.

Se tutta la procedura è stata eseguita correttamente ma nel catalogo non si vede ancora un pacchetto di estensione In sospeso o Non riuscito, puoi provare a usare direttamente le API per verificare lo stato del pacchetto di estensione. Per ulteriori informazioni, consulta Get an ExtensionPackage (Ottenere un pacchetto estensione) nella documentazione delle API.

Se l'elaborazione del pacchetto di estensione è stata completata, sulla scheda sarà presente un pulsante Installa su cui fare clic:

Viene visualizzata l’eventuale schermata di configurazione creata per l’estensione. Aggiungi le informazioni necessarie per configurare l'estensione e fai clic sul collegamento blu Salva, in basso. Se l'estensione non prevede alcuna configurazione, verrà installata non appena fai clic su Installa.

Ecco un esempio con l’estensione Facebook:

A questo punto viene visualizzata a schermata delle estensioni installate, con l’estensione Core e l’estensione personalizzata.

Creare risorse per testare l’estensione

Le estensioni forniscono nuove funzionalità agli utenti di Platform Launch. Queste vengono quasi sempre visualizzate in Elementi dati o nel Generatore regole. Esaminiamo ora queste due aree.

Elementi dati

Elementi dati : in Platform Launch, questi permettono agli utenti di riutilizzare valori esistenti. Ogni elemento dati rappresenta una mappatura o un puntatore verso dati sorgente. Un singolo elemento dati è una variabile che può essere mappata su stringhe di query, URL, valori di cookie, variabili JavaScript e così via.

Le estensioni possono definire i tipi di elementi dati necessari per il funzionamento dell’estensione o semplicemente per comodità degli utenti. Quando un’estensione fornisce tipi di elementi dati, questi vengono visualizzati agli utenti in un elenco a discesa nella schermata Crea nuovo elemento dati:

Quando un utente seleziona l’estensione dal menu a discesa Estensione, il menu a discesa Tipo di elemento dati viene compilato con i tipi di elemento dati fornito dall’estensione. L’utente può quindi mappare ogni elemento dati al relativo valore sorgente. Gli elementi dati possono essere utilizzati quando si creano regole nell’evento di modifica dell’elemento dati o nell’evento Codice personalizzato per attivare una regola da eseguire. Un elemento dati può essere utilizzato anche nella Condizione elemento dati o in altre Condizioni, Eccezioni o Azioni in una regola.

Una volta creato l’elemento dati (impostandone la mappatura), gli utenti possono fare riferimento ai dati sorgente semplicemente facendo riferimento a tale elemento dati. Se la sorgente del valore cambia (in seguito alla riprogettazione del sito, ecc.) gli utenti dovranno aggiornare la mappatura solo una volta in Platform Launch e tutti gli elementi dati riceveranno automaticamente il nuovo valore sorgente.

Regole

Seleziona il collegamento Regole nell’area di navigazione superiore, quindi Aggiungi regola:

Prima di tutto, assegna un nome alla regola. La schermata Crea nuova regola è impostata come un’istruzione if-then:

Se si verifica un evento, le condizioni vengono rispettate e non ci sono eccezioni, l’azione viene attivata. Lo stesso flusso esiste nelle estensioni in cui è possibile creare o riutilizzare eventi, condizioni, eccezioni, elementi dati o azioni.

Continuando con l’esempio di Facebook, aggiungiamo un evento per ogni volta che una pagina viene caricata sul nostro sito:

Con il tipo di evento Window Loaded, la regola viene attivata ogni volta che una pagina viene caricata sul sito. Seleziona Salva. Per questo esempio, saltiamo Condizioni ed Eccezioni perché vogliamo che la regola venga attivata per qualsiasi pagina del sito, che sia quindi una regola “globale” da attivare sempre al caricamento.

In Azioni, fai clic su Aggiungi. Nella schermata Configurazione azione è possibile scegliere l’estensione con cui lavorare e l’azione che si desidera eseguire quando la regola viene attivata. Scegli Facebook Pixel in Estensione e Invia vista pagina in Tipo azione:

Fai clic sul pulsante blu Mantieni modifiche, in basso, e quindi su Salva regola nella schermata successiva. Durante il test dell’estensione, è possibile selezionare qualsiasi evento, condizione ecc. fornito dall’estensione in un numero qualsiasi di regole.

Pubblicare le modifiche

Nell'area di navigazione principale, fai clic su Pubblicazione, quindi sul collegamento Aggiungi nuova libreria:

Una libreria è un insieme di istruzioni che definiscono il modo in cui estensioni, elementi dati e regole interagiscono tra loro e con il sito web. Le librerie vengono compilate in build. Una libreria può contenere tutte le modifiche che l’utente potrà fare o testare contemporaneamente.

Nella schermata Crea nuova libreria, aggiungi un nome e scegli un ambiente. Platform Launch fornisce un ambiente di sviluppo predefinito chiamato Development, quindi selezionalo dall’elenco Ambiente. Per ora, aggiungeremo tutte le risorse disponibili, quindi fai clic su Aggiungi tutte le risorse modificate.

NOTA

Quando si aggiunge una risorsa a una libreria, viene creata un'istantanea della risorsa nel momento esatto e viene aggiunta alla libreria. Quando si apportano modifiche alle risorse in un secondo momento (ad esempio, a seguito di correzioni da apportare), si deve anche aggiornare la libreria per includere le modifiche più recenti alle risorse. Il pulsante Aggiungi tutte le risorse modificate è utile anche a questo scopo.

Seleziona quindi Salva in basso. Ora che tutte le modifiche sono state incluse in questa libreria dev, possiamo procedere alla sua generazione:

Al termine del processo di generazione, accanto al nome della libreria compare un indicatore verde di operazione riuscita:

La libreria di Platform Launch ora è pubblicata e in attesa di essere utilizzata. Ora è necessario far sì che la pagina di test trovi la libreria, in modo da verificarne il comportamento in un browser per l’utente finale.

Installa Platform Launch in un sito di test

Passiamo alla scheda Ambienti, dove sono disponibili le istruzioni di installazione.

In questa pagina, sono visibili tutti gli ambienti disponibili e se ne possono creare altri. Abbiamo pubblicato la libreria nell'ambiente di sviluppo; pertanto, per ottenere le istruzioni di installazione per tale ambiente, fai clic sull'icona della casella nella colonna Installa alla riga Sviluppo.

Vengono visualizzate le istruzioni di installazione per l’ambiente di sviluppo. Fai clic sul pulsante Copia per copiare il tag <script> nella casella.

L’installazione viene completata inserendo questo singolo tag <script> nella sezione <head> del documento o del modello del sito. Ora visita il sito di prova per verificare il comportamento della libreria Platform Launch pubblicata.

Test

Durante la convalida dell’estensione sulla pagina o sul sito di prova, sono disponibili alcuni utili comandi della console:

  • _satellite.setDebug(true); imposta Platform Launch in modalità di debug e fornisce istruzioni di registrazione alla console.
  • L’oggetto _satellite._container contiene tutti i tipi di informazioni utili sulla libreria implementata, inclusi i dettagli relativi a build, elementi dati, regole ed estensioni.

In pratica, dobbiamo verificare la funzionalità della libreria implementata, per essere certi che il codice scritto nel pacchetto di estensione si comporti come previsto dopo che Platform Launch ha generato la libreria.

Se occorre apportare delle modifiche al pacchetto di estensione, il processo di iterazione è simile a quello di sviluppo.

  1. Apporta le modifiche al codice nel progetto.
  2. Convalida le modifiche con lo strumento Sandbox.
  3. Utilizza lo strumento Packager per creare un nuovo pacchetto .zip.
  4. Usa lo strumento di caricamento per caricare il nuovo pacchetto .zip. Puoi seguire le stesse istruzioni riportate sopra per il caricamento iniziale, con una differenza: poiché ora esiste già un pacchetto di estensione con lo stesso nome in modalità di sviluppo, il nuovo pacchetto sovrascriverà quello esistente. Per risparmiare tempo evitando di immettere di volta in volta le credenziali, consulta la documentazione di reactor-uploader e trasmetti gli argomenti necessari alla riga di comando.
  5. Questa volta è possibile saltare la fase di installazione.
  6. Modifica le risorse: se hai già modificato la configurazione di uno dei componenti dell’estensione, occorre aggiornare tali risorse nell’interfaccia utente di Platform Launch.
  7. Aggiungi le modifiche più recenti alla libreria e procedi di nuovo alla sua generazione.
  8. Effettua ulteriori verifiche.

In questa pagina