So aktualisierst du deine Salesforce Commerce Cloud Cartridge

Übersicht

Hier erfährst du, wie du dein Klaviyo Salesforce Commerce Cloud Cartridge upgraden kannst.

Verwendest du eine Cartridge-Version, die älter als 23.7.0 ist? Wir empfehlen eine sofortige Aktualisierung auf Version 23.7.0 oder höher. Ältere Versionen der Cartridge verwenden Klaviyos v1- und v2-API, die eingestellt wurden und nicht mehr wie erwartet funktionieren. Wir empfehlen ein Upgrade auf die neueste Version auf der GitHub-Releases-Seite von Klaviyo.

Bevor du anfängst

Version 23.7.0 enthält eine Reihe wichtiger Verbesserungen, von denen einige architektonische Änderungen daran betreffen, wie Events ausgelöst werden. Die folgenden Schritte behandeln das Upgrade von einer Version vor 23.7.0 auf Version 23.7.0 oder höher. Schließe das Upgrade und die Tests in einer SFCC-Sandbox ab, bevor du Änderungen an deiner Produktionswebsite vornimmst.

Deine aktuellen Integrationen verstehen

Es ist wichtig, mit deiner aktuellen SFCC-Integration vertraut zu sein und zu wissen, welche Änderungen oder Anpassungen möglicherweise speziell für deine Website vorgenommen wurden. Am wichtigsten ist, dass du berücksichtigen solltest, ob die spezifischen Ereignisdaten, die du an Klaviyo sendest, geändert oder erweitert wurden und ob du benutzerdefinierte Ereignisse hinzugefügt hast.

Wir empfehlen, deinen Code, der Ereignisdaten zusammenstellt, mit der vorherigen Version der Klaviyo-Cartridge zu vergleichen, die auf Klaviyos GitHub verfügbar ist. Unter der Annahme, dass deine Integration nicht stark angepasst wurde, findest du deine aktuellen Datenzusammenstellungsfunktionen in int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js und für Order Confirmation in int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js.

Notiere alle Anpassungen, damit du sie erneut anwenden kannst, sobald die neue Cartridge installiert wurde.

Eine SFCC-Sandbox mit einem Klaviyo-Testkonto verbinden

Wenn du noch kein separates sekundäres Klaviyo-Konto zum Testen erstellt hast, getrennt von dem Konto, das an deine SFCC-Produktionsumgebung gebunden ist, solltest du das tun. Verbinde dann deine SFCC-Sandbox-Umgebung mit dem neuen Konto, indem du die öffentlichen und privaten API-Schlüssel dieses Kontos in den Sandbox-Cartridge-Einstellungen verwendest. Wir empfehlen, diesen Schritt mit deiner bisherigen Klaviyo-Cartridge-Version abzuschließen, damit du verifizieren kannst, dass Ereignisse erfolgreich an dein sekundäres Klaviyo-Konto gesendet und von ihm empfangen werden, bevor du mit dem Upgrade deiner Codebasis mit der neuen Klaviyo-Cartridge fortfährst.

Entferne den vorherigen Klaviyo-Cartridge-Code

Wenn deine Integrationen nicht stark angepasst wurden, kannst du den Großteil der vorherigen Klaviyo-Integration entfernen, indem du einfach die beiden Klaviyo-Cartridge-Ordner int_klaviyo_core und entweder int_klaviyo (für Site Genesis) oder int_klaviyo_sfra (für SFRA) aus der Codebasis löschst. Du musst aber auch allen Klaviyo-spezifischen Code entfernen, der möglicherweise zu Vorlagendateien und ggf. JavaScript-Dateien hinzugefügt wurde.

Für Site Genesis

Standard-Integrationen für Site Genesis fügen footer_UI.isml folgenden Code hinzu:

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

Sie fügen auch den folgenden Block zu minicart.isml hinzu, cart.isml und alle anderen „cart“-isml-Dateien:

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

Für SFRA

Standard Integrationen für SFRA fügen pageFooter.isml folgenden Code hinzu:

<isinclude template="klaviyo/klaviyoFooter"/>

Außerdem wird ihnen der folgende Code zur AddProduct-Route im Cart.js-Controller hinzugefügt:

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

Sowohl für Site Genesis als auch für SFRA ist es ratsam, nachdem die Cartridge-Ordner und die oben genannten Code-Fragmente entfernt wurden, die Codebase nach dem Wort „Klaviyo“ zu durchsuchen. Stell sicher, dass du weißt, was jeglicher Klaviyo-bezogener Code, der in deiner Codebase verbleibt, macht, bevor du ihn entfernst, da diese Blöcke Anpassungen darstellen können, die du nach der Installation der neuen Cartridge wieder einbauen musst.

Services entfernen

Die vorherige Integration hat unter Administration > Vorgänge > Services einen KlaviyoTrackService, KlaviyoTrackProfile und KlaviyoTrackCredentials erstellt. Alle drei können bedenkenlos entfernt werden, da beim Prozess der Integration der neuen Klaviyo-Cartridge neue Services mit anderen Namen erstellt werden.

Es ist nicht entscheidend, dass die alten Dienste entfernt werden, aber es wird empfohlen, sie zu bereinigen, um zukünftige Verwirrung zu vermeiden.

Website-Einstellungen überprüfen

Der Prozess der Integration der neuen Klaviyo-Cartridge übernimmt einige der bisherigen Klaviyo-Website-Einstellungen und fügt außerdem einige neue hinzu. Sieh dir deine Website-Einstellungen in der Einstellungsgruppe Klaviyo unter Merchant Tools > Site Preferences > Custom Preferences > klaviyo an und prüfe, ob speziell für deine Website benutzerdefinierte Einstellungen hinzugefügt wurden. Wenn du die Cartridge angepasst hast, um deine eigenen Einstellungen hinzuzufügen, solltest du sie beibehalten. Zur Referenz: Hier sind die vier Website-Einstellungen, die in die vorherige Klaviyo-Integration integriert sind:

• Klaviyo aktiviert (ID: klaviyo_enabled)
  Markierung, ob Klaviyo ein- oder ausgeschaltet ist.
• Klaviyo-Konto (ID: klaviyo_account)
  Dein öffentlicher API-Schlüssel von Klaviyo oder deine Site-ID.
• Klaviyo privater API-Schlüssel (ID: klaviyo_api_key)
  Ein privater API-Schlüssel von Klaviyo.
• Bildtyp für Klaviyo (ID: klaviyo_image_size)
  Groß, klein, Thumbnail usw.

Bevor du die neue Cartridge einrichtest, empfehlen wir, deine aktuellen Website-Einstellungen zu sichern, indem du sie unter Administration > Site Development > Site Import & Export exportierst. Erweitere Sites, dann deinen Site Name, und aktiviere das Kontrollkästchen „Site Preferences“, bevor du einen Dateinamen eingibst, um sie zu exportieren. Deine aktuellen Klaviyo-Einstellungen sollten nicht beeinträchtigt werden, wenn du später die neue Cartridge installierst, aber es ist eine gute Idee, sie zur späteren Referenz zu sichern.

Entferne die Klaviyo Cartridges aus dem Cartridge-Pfad

Entferne int_klaviyo_core und entweder int_klaviyo (Site Genesis) oder int_klaviyo_sfra (SFRA) aus deinem Cartridge-Pfad unter Administration > Sites > Manage Sites > [Site Name] > Settings. Wenn du diesen Schritt nicht ausführst, treten Fehler auf, weil SFCC nach Cartridges sucht, die geladen werden sollen und nicht mehr existieren.

Überprüfe die Entwicklerkonsole und das serverseitige Protokoll auf Fehler.

Zu diesem Zeitpunkt solltest du keinen Klaviyo-Code mehr in deiner Codebasis haben. Wir empfehlen, dein Frontend zu überprüfen, Seiten wie Suchergebnisse, PLPs und PDPs zu besuchen und Aktionen wie Produkte in den Warenkorb zu legen, den Checkout zu starten und abzuschließen. Behalte dabei die Developer Console im Blick, um zu sehen, ob neue Fehler generiert werden. Mach dasselbe mit dem Request Log. Wenn du neue Fehler im Zusammenhang mit Klaviyo siehst, ist es sehr wahrscheinlich, dass du nicht den gesamten bisherigen Klaviyo-Code vollständig entfernt hast. Es ist wichtig, die Quelle neuer Fehler aufzuspüren und sie zu notieren, bevor du sie entfernst.

Die neue Klaviyo Cartridge installieren

Folge den Schritten in Erste Schritte mit Salesforce Commerce Cloud, um die neue Cartridge in deine Codebasis zu integrieren. Es kann Schritte geben, die du nicht abschließen musst – zum Beispiel kann deine SFCC-Instanz für den OCAPI-Teil Verbindungen bereits eingerichtet haben oder auch nicht –, aber im Allgemeinen solltest du jeden Integrationsschritt befolgen. Du musst auf jeden Fall beide Klaviyo-Cartridges ersetzen und Code-Fragmente wieder hinzufügen.

Durch das Importieren von metadata.zip werden neue Website-Einstellungen zusätzlich zu den 4 oben aufgeführten hinzugefügt. Überprüfe alle Website-Einstellungen von Klaviyo und bestätige deine vorhandenen Werte, bevor du fortfährst. Konfiguriere Klaviyo Email Selectors und Checkout Email Selector für die E-Mail-Felder deiner Website, damit Klaviyo Besucher*innen identifizieren und Checkout-Aktivitäten nachverfolgen kann.

Da du von einer Cartridge vor Version 23.7.0 upgradest, sollten die neuen Site Preferences Label Events as SFCC und Send Added To Cart Event as „Add To Cart“ auf No bzw. Yes gesetzt werden. Dadurch werden weiterhin Events ohne das Salesforce Commerce Cloud -Metrik-Label gesendet und der Event-Typ Add To Cart verwendet (anstatt des neuen Added to Cart). Wenn diese beiden Site Preferences falsch gesetzt sind, führt das zu einem Ausfall des Reporting und potenziell zu einem Ausfall bestehender Flows in Klaviyo.

Überprüfe, dass alle Standardereignisse funktionieren

Bevor du versuchst, Anpassungen aus deiner vorherigen Integrationen wieder hinzuzufügen, vergewissere dich, dass die neue Installation der Klaviyo-Kassette korrekt funktioniert. Verwende das Frontend, um Events für Website gesucht, Kategorie angesehen, Produkt angesehen, Zum Warenkorb hinzugefügt, Checkout gestartet und Bestellbestätigung zu generieren, und überprüfe dann dein Klaviyo-Konto, um sicherzustellen, dass diese Events korrekt getrackt werden.

Prüfe die Entwicklerkonsole auf allen Seiten, die Klaviyo-Ereignisse erzeugen, auf neue Fehler, die möglicherweise mit der Integration zusammenhängen. Aktiviere die ausführliche Service-Protokollierung, indem du das Kontrollkästchen Communication Log Enabled unter Administration > Operations > Services > KlaviyoEventService - Details aktivierst, und prüfe dann die serverseitigen Protokolldateien, um zu verifizieren, dass es keine Fehler gibt und dass Ereignisdaten für jeden Ereignistyp korrekt generiert werden.

Ereignisdaten mit Produktion vergleichen

Vergleiche jetzt die Ereignisdaten in deinen Klaviyo-Konten für Tests und Produktion, um sicherzustellen, dass nichts fehlt und dass die aktuellen Werte dem erwarteten Typ entsprechen. Es ist wichtig festzustellen, ob Reporting oder Flows von der neuen Integrationen betroffen sind. Du wirst feststellen, dass im Vergleich zur vorherigen Cartridge-Version jetzt zusätzliche Eigenschaften festgelegt und an Klaviyo gesendet werden.

Füge standortspezifische Anpassungen wieder hinzu

Du kannst jetzt wieder damit beginnen, Anpassungen in deinen Klaviyo-Code einzufügen. Aufgrund der erheblichen strukturellen und architektonischen Änderungen mit der neuesten Klaviyo Cartridge ist es unwahrscheinlich, dass du benutzerdefinierten Code einfach per Copy-and-paste direkt in die Klaviyo Cartridge einfügen kannst.

Jeder Ereignistyp in der Klaviyo-Cartridge hat eine getData-Funktion, die in einer separaten Skriptdatei enthalten ist, die nach dem jeweiligen Ereignistyp benannt ist. Diese Dateien findest du im Ordner int_klaviyo_core/cartridge/scripts/klaviyo/eventData und hier wirst du am ehesten Änderungen vornehmen, um die Datenobjekte hinzuzufügen oder zu aktualisieren, die für jedes Ereignis übergeben werden. Wenn du neue benutzerdefinierte Ereignisse erstellst, empfehlen wir, dem etablierten Muster zu folgen: Code zu serverseitigen Controllern (d. h. direkt in SiteGen oder über server.append in SFRA) hinzufügen, der eine getData-Funktion aus einer dem neuen Ereignis gewidmeten Skriptdatei aufruft und anschließend die trackEvent-Funktion verwendet, um diese Daten über den KlaviyoEventService an Klaviyo zu senden.

Nachdem du deine Anpassungen wiederhergestellt hast, wiederhole die Ereignis- und Fehlerprüfungen in der Sandbox, einschließlich aller benutzerdefinierten Ereignisse und Eigenschaften, die von deinen Flows verwendet werden. Sobald die Tests abgeschlossen sind, stelle das getestete Upgrade mithilfe der API-Schlüssel und Website-Einstellungen deines Klaviyo-Produktionskontos in der Produktion bereit und überprüfe dann, dass Ereignisse das Produktionskonto mit den erwarteten Namen und Daten erreichen.

Ergebnis

Du hast dein Klaviyo-Cartridge für Salesforce Commerce Cloud jetzt aktualisiert.

Weitere Ressourcen