Come aggiornare la sua cartuccia di Salesforce Commerce Cloud

Imparerai

Scopra come aggiornare la sua cartuccia Klaviyo Salesforce Commerce Cloud. 

Sta utilizzando una versione della cartuccia precedente a 23.7.0? Consigliamo di aggiornare immediatamente alla versione 23.7.0 o superiore. Le versioni precedenti della cartuccia utilizzano le API v1 e v2 di Klaviyo, che sono state ritirate e non funzionano più come previsto. Raccomandiamo sempre di aggiornare alla nostra versione più recente (attualmente, 24.1.0).

Prima di iniziare

La versione 23.7.0 (rilasciata il 13 luglio 2023) include una serie di miglioramenti significativi, alcuni dei quali sono modifiche architettoniche sul modo in cui gli eventi vengono attivati. Le considerazioni speciali per l'aggiornamento da qualsiasi versione inferiore a 23.70 a qualsiasi versione superiore sono descritte di seguito.

Capire la sua attuale integrazione

È importante conoscere la sua attuale integrazione con l'SFCC e quali modifiche o personalizzazioni sono state apportate specificamente per il suo sito web. Soprattutto, deve considerare se i dati specifici degli eventi che invia a Klaviyo sono stati modificati o aumentati e se ha aggiunto eventi personalizzati.

Consigliamo di confrontare il suo codice che assembla i dati degli eventi con la versione precedente della cartuccia Klaviyo, disponibile su Github di Klaviyo. Supponendo che la sua integrazione non sia stata fortemente personalizzata, troverà le sue attuali funzioni di assemblaggio dei dati in int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js, e per la Conferma dell'ordine in int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js.

Prenda nota di eventuali personalizzazioni, in modo da poterle riapplicare una volta installata la nuova cartuccia.

Colleghi una sandbox SFCC ad un account di prova Klaviyo

Se non ha ancora creato un account Klaviyo secondario per i test, separato dall'account legato al suo ambiente di produzione SFCC, dovrebbe farlo. Quindi, colleghi il suo ambiente sandbox SFCC al nuovo account. Le consigliamo di completare questo passaggio utilizzando la versione precedente della cartuccia Klaviyo, in modo da poter verificare che gli eventi vengano inviati e ricevuti con successo dal suo account Klaviyo secondario, prima di procedere all'aggiornamento della sua base di codice con la nuova cartuccia Klaviyo.

Rimuova il codice della cartuccia Klaviyo precedente

Se la sua integrazione non è stata fortemente personalizzata, potrà rimuovere la maggior parte della precedente integrazione Klaviyo semplicemente eliminando le due cartelle Klaviyo: int_klaviyo_core e int_klaviyo (per Site Genesis) o int_klaviyo_sfra (per SFRA) dal codice base. Tuttavia, dovrà anche rimuovere qualsiasi codice specifico di Klaviyo che possa essere stato aggiunto ai file di template e, eventualmente, 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"/>

Avranno anche il seguente blocco aggiunto a minicart.isml, cart.isml, e qualsiasi altro 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"/>

Avranno anche il seguente codice aggiunto al percorso 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 aver rimosso le cartelle delle cartucce e i frammenti di codice sopra menzionati, è consigliabile cercare nella base di codice la parola "Klaviyo". Prima di rimuoverlo, si assicuri di conoscere le funzioni del codice legato a Klaviyo che rimane nella sua base di codice, in quanto questi blocchi potrebbero rappresentare personalizzazioni che dovrà rimettere a posto dopo l'installazione della nuova cartuccia.

Rimuovere i servizi

L'integrazione precedente avrà creato un KlaviyoTrackService, KlaviyoTrackProfile e KlaviyoTrackCredentials in Amministrazione > Operations > Service. Tutti e tre possono essere tranquillamente rimossi, poiché il processo di integrazione della nuova cartuccia Klaviyo creerà nuovi servizi con nomi diversi.

Non è fondamentale che i vecchi servizi vengano rimossi, ma si raccomanda di pulirli per evitare confusione in futuro.

Rivedere le preferenze del sito

Il processo di integrazione della nuova cartuccia Klaviyo manterrà alcune delle preferenze del sito Klaviyo precedente e ne aggiungerà altre. Dia un'occhiata alle sue preferenze del sito nel gruppo di preferenze di Klaviyo all'indirizzo Strumenti del commerciante > Preferenze del sito > Preferenze personalizzate > klaviyo, e verifichi se sono state aggiunte preferenze personalizzate specifiche per il suo sito web. Se ha personalizzato la cartuccia per aggiungere le sue impostazioni, vorrà conservarle. Come riferimento, ecco le quattro preferenze del sito integrate nella precedente integrazione di Klaviyo:

• Klaviyo abilitato (ID: klaviyo_enabled)
  Segnala se Klaviyo è attivo o meno.
• Account Klaviyo (ID: klaviyo_account)
  La sua chiave API pubblica di Klaviyo, o 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, piccola, miniatura, ecc.

Prima di configurare la nuova cartuccia, le consigliamo di eseguire il backup delle preferenze attuali del sito esportandole in Amministrazione > Sviluppo del sito > Importazione del sito & Esportazione. Espanda Siti, quindi il nome del suo sito e selezioni la casella Preferenze del sito prima di inserire un nome di file in cui esportarli. Le sue preferenze attuali di Klaviyo non dovrebbero essere influenzate negativamente quando installa la nuova cartuccia, ma è una buona idea fare un backup per riferimento futuro.

Rimuova le cartucce Klaviyo dal percorso della cartuccia

Rimuova int_klaviyo_core e int_klaviyo (Site Genesis) o int_klaviyo_sfra (SFRA) dal percorso della sua cartuccia in Amministrazione > Siti > Gestione siti > [Nome sito] > Impostazioni. Se non esegue questo passaggio, si verificheranno errori dovuti al fatto che SFCC cerca cartucce da caricare che non esistono più.

Controlli la console dello sviluppatore e il log del lato server per verificare la presenza di errori.

A questo punto, non dovrebbe più avere alcun codice Klaviyo nella sua base di codice. Raccomandiamo di esaminare il suo frontend, visitando pagine come Risultati di ricerca, PLP e PDP, ed eseguendo azioni come l'aggiunta di prodotti al carrello, l'ingresso e il completamento del checkout. Mentre lo fa, tenga d'occhio la Developer Console per vedere se vengono generati nuovi errori. Faccia lo stesso con il Registro delle richieste. Se sta vedendo nuovi errori relativi a Klaviyo, è molto probabile che non abbia rimosso completamente tutto il codice Klaviyo precedente. È importante rintracciare la fonte di qualsiasi nuovo errore e annotarlo prima di rimuoverlo.

Installi la nuova cartuccia Klaviyo

Segua la procedura descritta in Come iniziare con Salesforce Commerce Cloud per integrare la nuova cartuccia nella sua base di codice. Ci possono essere dei passaggi che non è necessario completare - ad esempio, la sua istanza SFCC può o meno avere le connessioni già stabilite per la parte OCAPI - ma in generale, deve seguire ogni fase dell'integrazione. Dovrà sicuramente sostituire entrambe le cartucce di Klaviyo e aggiungere nuovamente i frammenti di codice. 

Si noti che dopo aver importato i metadati.zip, avrà quattro nuove preferenze del sito, oltre alle quattro create dalla versione precedente della cartuccia. Le sue preferenze precedenti non dovrebbero essere influenzate dall'importazione di quelle nuove, ma si raccomanda di controllare due volte che tutte le preferenze del sito Klaviyo siano corrette prima di procedere.

Poiché sta effettuando l'aggiornamento da una cartuccia precedente alla versione 23.7.0, le nuove preferenze del sito Etichetta gli eventi come SFCC e Invia evento aggiunto al carrello come 'Aggiungi al carrello' devono essere impostate rispettivamente su No e Sì. In questo modo continuerà a inviare eventi senza l'etichetta metrica di Salesforce Commerce Cloud e utilizzerà il tipo di evento Aggiungi al carrello (rispetto al nuovo Aggiunto al carrello). Se queste due preferenze del sito sono impostate in modo errato, si verificherà un'interruzione della segnalazione e potenzialmente un'interruzione dei flussi esistenti in Klaviyo.

Verifichi che tutti gli eventi out-of-the-box funzionino.

Prima di tentare di aggiungere nuovamente qualsiasi personalizzazione dalla sua precedente integrazione, si assicuri di verificare che la nuova installazione della cartuccia Klaviyo funzioni correttamente. Utilizzi il frontend per generare eventi per Ricerca del sito, Categoria visualizzata, Prodotto visualizzato, Aggiunta al carrello, Avvio del checkout e Conferma dell'ordine, e poi controlli il suo account Klaviyo per assicurarsi che questi eventi siano tracciati correttamente. 

Controlli la console per sviluppatori per eventuali nuovi errori legati all'integrazione su tutte le pagine che generano eventi Klaviyo. Abiliti la registrazione verbosa del servizio selezionando la casella di controllo Registro comunicazioni abilitato in Amministrazione > Operazioni > Servizi > KlaviyoEventService - Dettagli, e poi esamini i file di registro lato server per verificare che non ci siano errori e che i dati degli eventi siano generati correttamente per ogni tipo di evento.

Confronta i dati degli eventi con la produzione

Dovrebbe ora confrontare i dati degli eventi nei suoi account Klaviyo di test e di produzione per assicurarsi che non manchi nulla e che i valori attuali corrispondano al tipo previsto. È importante determinare se i rapporti o i flussi saranno influenzati dalla nuova integrazione. Si accorgerà che ora vengono impostate e inviate a Klaviyo ulteriori proprietà rispetto alla versione precedente della cartuccia. 

Riaggiornamento delle personalizzazioni specifiche per il sito

Ora può iniziare ad aggiungere le personalizzazioni nel suo codice Klaviyo. A causa delle pesanti modifiche strutturali e architettoniche apportate alla nuova cartuccia Klaviyo, è improbabile che possa semplicemente copiare e incollare il codice personalizzato direttamente nella cartuccia Klaviyo.

Ogni tipo di evento nella cartuccia Klaviyo ha una funzione getData che vive in un file di script separato, denominato per ogni tipo di evento. Questi file si trovano nella cartella int_klaviyo_core/cartridge/scripts/klaviyo/eventData e sono il luogo che probabilmente modificherà per aggiungere o aggiornare gli oggetti dati che vengono passati per ogni evento. Se sta creando nuovi eventi personalizzati, le consigliamo di seguire lo schema consolidato di aggiungere codice ai controllori 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 questi dati a Klaviyo tramite il KlaviyoEventService.

Risultato

Ora ha aggiornato la sua cartuccia Klaviyo per Salesforce Commerce Cloud. 

Risorse aggiuntive 

• Iniziare con Salesforce Commerce Cloud
• Riferimento dati Salesforce Commerce Cloud
• Con quale frequenza le integrazioni sincronizzano il riferimento
• Come contattare l'assistenza