Come aggiornare la tua cartuccia Salesforce Commerce Cloud

Cosa imparerai

Scopri come eseguire l'upgrade della tua cartuccia Klaviyo per Salesforce Commerce Cloud.

Stai utilizzando una versione della cartuccia precedente alla 23.7.0? Ti consigliamo di aggiornare immediatamente alla versione 23.7.0 o successive. Le versioni precedenti della cartuccia utilizzano le API v1 e v2 di Klaviyo, che sono state ritirate dal mercato e non funzionano più come previsto. Consigliamo sempre di aggiornare alla nostra versione più recente (attualmente, 25.7.0).

Prima di iniziare

La versione 23.7.0 include una serie di miglioramenti significativi, alcuni dei quali sono modifiche architetturali relative a come vengono attivati gli eventi. Di seguito sono descritte considerazioni particolari per l'aggiornamento da qualsiasi versione precedente alla 23.70 a qualsiasi versione successiva.

Comprendi le integrazioni attuali

È importante conoscere la tua attuale integrazione SFCC e quali modifiche o personalizzazioni potrebbero essere state apportate specificamente per il tuo sito web. Soprattutto, dovresti valutare se i dati evento specifici che invii a Klaviyo sono stati modificati o ampliati e se hai aggiunto eventuali eventi personalizzati.

Ti consigliamo di confrontare il tuo codice che assembla i dati degli eventi con la versione precedente della cartuccia Klaviyo, disponibile su Github di Klaviyo. Supponendo che la tua integrazione non sia stata pesantemente personalizzata, troverai le funzioni di assemblaggio dei dati attuali in int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js e, per Order Confirmation, in int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js.

Annota eventuali personalizzazioni in modo da poterle applicare di nuovo una volta installata la nuova cartuccia.

Collega una sandbox SFCC a un account di test Klaviyo

Se non hai ancora creato un account Klaviyo secondario per i test, separato dall’account collegato al tuo ambiente di produzione SFCC, ti consigliamo di farlo. Poi collega il tuo ambiente sandbox SFCC al nuovo account. Ti consigliamo di completare questo passaggio usando la tua versione precedente della cartuccia Klaviyo, così puoi verificare che gli eventi vengano inviati e ricevuti correttamente dal tuo account Klaviyo secondario prima di procedere con l’aggiornamento del codebase con la nuova cartuccia Klaviyo.

Rimuovi il codice del cartridge Klaviyo precedente

Se la tua integrazione non è stata pesantemente personalizzata, potrai rimuovere la maggior parte della precedente integrazione Klaviyo semplicemente eliminando le due cartelle del cartridge Klaviyo: int_klaviyo_core e int_klaviyo (per Site Genesis) oppure int_klaviyo_sfra (per SFRA) dal codebase. Tuttavia, dovrai anche rimuovere qualsiasi codice specifico di Klaviyo che potrebbe essere stato aggiunto ai file del modello e, potenzialmente, ai file JavaScript.

Per Site Genesis

Le integrazioni Standard per Site Genesis avranno il seguente codice aggiunto a footer_UI.isml:

<isinclude template="components/footer/klaviyoFooter"/>

Verrà anche aggiunto il seguente blocco a minicart.isml, cart.isml e a tutti gli altri file isml “cart”:

<isif condition="${pdict.CurrentHttpParameterMap.cartAction == 'add' || pdict.CurrentHttpParameterMap.cartAction
  == 'update'}">
   <isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyoAddToCart')}"/>
</isif>

Per SFRA

Le integrazioni Standard per SFCC avranno il seguente codice aggiunto a pageFooter.isml:

<isinclude template="klaviyo/klaviyoFooter"/>

Verrà inoltre aggiunto il seguente codice alla route AddProduct nel controller Cart.js:

 if(dw.system.Site.getCurrent().getCustomPreferenceValue('klaviyo_enabled')){
   var KlaviyoUtils = require('*/cartridge/scripts/utils/klaviyo/klaviyoUtils');
 KlaviyoUtils.trackAddToCart();
}

Sia per Site Genesis che per SFRA, dopo che le cartelle del cartridge e gli snippet di codice sopra menzionati sono stati rimossi, è consigliabile cercare nella codebase la parola "Klaviyo". Assicurati di sapere cosa fa qualsiasi codice relativo a Klaviyo che rimane nella tua base di codice prima di rimuoverlo, poiché questi blocchi potrebbero rappresentare personalizzazioni che dovrai ripristinare dopo l’installazione della nuova cartuccia.

Rimuovi servizi

La precedente integrazione avrà creato un KlaviyoTrackService, KlaviyoTrackProfile e KlaviyoTrackCredentials in Amministrazione > Operazioni > Servizio. Tutti e tre possono essere rimossi in sicurezza, poiché il processo di integrazione della nuova cartuccia Klaviyo creerà nuovi servizi con nomi diversi.

Non è fondamentale rimuovere i servizi precedenti, ma è consigliabile eliminarli per evitare confusione in futuro.

Rivedi le preferenze del sito

Il processo di integrazione del nuovo cartridge di Klaviyo manterrà alcune delle preferenze del sito Klaviyo precedenti e ne aggiungerà anche di nuove. Dai un'occhiata alle preferenze del tuo sito nel gruppo di preferenze Klaviyo in Merchant tools > Site Preferences > Custom Preferences > klaviyo e verifica se sono state aggiunte preferenze personalizzate specifiche per il tuo sito web. Se hai personalizzato il cartridge per aggiungere impostazioni tue, ti consigliamo di mantenerle. Come riferimento, ecco le quattro preferenze del sito integrate nella precedente integrazione Klaviyo:

• Klaviyo abilitato (ID: klaviyo_enabled)
  Flag per indicare se Klaviyo è attivo o disattivo.
• Account Klaviyo (ID: klaviyo_account)
  La tua chiave API pubblica di Klaviyo, o l'ID del sito.
• Chiave API privata di Klaviyo (ID: klaviyo_api_key)
  Una chiave API privata di Klaviyo.
• Tipo di immagine per Klaviyo (ID: klaviyo_image_size)
  Grande, piccolo, miniatura, ecc.

Prima di configurare la nuova cartuccia, ti consigliamo di eseguire il backup delle preferenze attuali del sito esportandole in Administration > Site Development > Site Import & Export. Espandi Sites, poi Nome sito e seleziona la casella Site Preferences prima di inserire un nome file in cui esportarle. Le preferenze attuali di Klaviyo non dovrebbero risentirne quando installerai in seguito la nuova cartuccia, ma è una buona idea eseguire un backup per consultarle in futuro.

Rimuovi le cartucce Klaviyo dal percorso della cartuccia

Rimuovi int_klaviyo_core e int_klaviyo (Site Genesis) oppure int_klaviyo_sfra (SFRA) dal percorso della cartuccia in Amministrazione > Siti > Gestisci siti > [Nome sito] > Impostazioni. Se non esegui questo passaggio, riceverai errori dovuti al fatto che SFCC cercherà cartridge da caricare che non esistono più.

Controlla la console sviluppatore e il log lato server per eventuali errori

A questo punto, non dovresti più avere alcun codice Klaviyo nella tua base di codice. Ti consigliamo di controllare il frontend, visitare pagine come Risultati di ricerca, PLP e PDP ed eseguire azioni come aggiungere prodotti al carrello, avviare e completare il checkout. Mentre lo fai, tieni d'occhio la Console per sviluppatori per verificare se vengono generati nuovi errori. Fai lo stesso con il log delle richieste. Se stai visualizzando nuovi errori relativi a Klaviyo, è molto probabile che tu non abbia rimosso completamente tutto il codice Klaviyo precedente. È importante individuare l'origine di eventuali nuovi errori e annotarli prima di rimuoverli.

Installa il nuovo pacchetto Klaviyo

Segui i passaggi descritti in Primi passi con Salesforce Commerce Cloud per integrare la nuova cartuccia nella tua base di codice. Potrebbero esserci passaggi che non devi completare: ad esempio, la tua istanza SFCC potrebbe avere o non avere già le connessioni stabilite per la parte OCAPI, ma in generale dovresti seguire ogni passaggio di integrazione. Dovrai sicuramente sostituire entrambe le cartucce Klaviyo e aggiungere di nuovo gli snippet di codice.

Nota che dopo aver importato metadata.zip, avrai quattro nuove preferenze del sito, oltre alle quattro create dalla versione precedente della cartuccia. Le preferenze precedenti non dovrebbero essere state influenzate dall’importazione di quelle nuove, ma è consigliabile ricontrollare che tutte le preferenze del sito di Klaviyo siano corrette prima di procedere.

Poiché stai eseguendo l’aggiornamento da una cartuccia precedente alla versione 23.7.0, le nuove preferenze del sito Label Events as SFCC e Send Added To Cart Event as ‘Add To Cart’ devono essere impostate rispettivamente su No e Yes. In questo modo continuerai a inviare eventi senza l’etichetta della metrica Salesforce Commerce Cloud e userai il tipo di evento Add To Cart (anziché il nuovo Added to Cart). Se queste due preferenze del sito sono impostate in modo errato, la reportistica si interromperà e potrebbe interrompersi anche i flussi esistenti in Klaviyo.

Verifica che tutti gli eventi predefiniti funzionino

Prima di provare a ripristinare eventuali personalizzazioni dalla tua integrazione precedente, assicurati di verificare che la nuova installazione della cartuccia Klaviyo funzioni correttamente. Usa il frontend per generare eventi per Searched Site, Viewed Category, Viewed Product, Added To Cart, Started Checkout e Order Confirmation, quindi controlla il tuo account Klaviyo per assicurarti che questi eventi vengano tracciati correttamente.

Controlla la console per sviluppatori per eventuali nuovi errori che potrebbero essere correlati alle integrazioni su tutte le pagine che generano eventi Klaviyo. Abilita la registrazione dettagliata del servizio selezionando la casella di controllo Communication Log Enabled in Administration > Operations > Services > KlaviyoEventService - Details, quindi rivedi i file di log lato server per verificare che non ci siano errori e che i dati degli eventi vengano generati correttamente per ogni tipo di evento.

Confronta i dati degli eventi con la produzione

Ora dovresti confrontare i dati evento negli account Klaviyo di test e di produzione per assicurarti che non manchi nulla e che i valori attuali corrispondano al tipo previsto. È importante determinare se la nuova integrazione avrà effetti sulla reportistica o sui flussi. Noterai che ora vengono impostate e inviate a Klaviyo proprietà aggiuntive rispetto alla versione precedente del cartridge.

Aggiungi di nuovo le personalizzazioni specifiche del sito

Ora puoi iniziare ad aggiungere di nuovo le personalizzazioni nel tuo codice Klaviyo. Dato che ci sono importanti modifiche strutturali e architetturali con il pacchetto Klaviyo più recente, è improbabile che tu riesca semplicemente a copiare e incollare il codice personalizzato direttamente nel pacchetto Klaviyo.

Ogni tipo di evento nella cartuccia Klaviyo ha una funzione getData che si trova in un file di script separato, denominato in base a ciascun tipo di evento. Questi file si trovano nella cartella int_klaviyo_core/cartridge/scripts/klaviyo/eventData e sono il punto in cui è più probabile che tu intervenga per aggiungere o aggiornare gli oggetti dati passati per ciascun evento. Se stai creando nuovi eventi personalizzati, ti consigliamo di seguire il pattern consolidato di aggiungere codice ai controller lato server (ad esempio, direttamente in SiteGen o tramite server.append in SFRA) che richiama una funzione getData da un file di script dedicato al nuovo evento e poi utilizza la funzione trackEvent per inviare quei dati a Klaviyo tramite KlaviyoEventService.

Risultato

Ora hai aggiornato il pacchetto Klaviyo per Salesforce Commerce Cloud.

Risorse aggiuntive