So aktualisierst du deine Salesforce Commerce Cloud Cartridge

Du wirst lernen

Erfahre, wie du deine Klaviyo Salesforce Commerce Cloud Cartridge aktualisieren kannst. 

Benutzt du eine Kassettenversion, die älter als 23.7.0 ist? Wir empfehlen, sofort auf Version 23.7.0 oder höher zu aktualisieren. Ältere Versionen der Kassette verwenden Klaviyo's v1 und v2 API, die im Ruhestand sind und nicht mehr wie erwartet funktionieren. Wir empfehlen immer ein Upgrade auf unsere neueste Version (derzeit 24.1.0).

Bevor du beginnst

Version 23.7.0 (veröffentlicht am 13. Juli 2023) enthält eine Reihe sinnvoller Verbesserungen, von denen einige architektonische Änderungen an der Art und Weise sind, wie Ereignisse ausgelöst werden. Besondere Überlegungen für ein Upgrade von einer Version unter 23.70 auf eine höhere Version sind im Folgenden aufgeführt.

Verstehe deine aktuelle Integration

Es ist wichtig, dass du mit deiner aktuellen SFCC-Integration vertraut bist und weißt, welche Änderungen oder Anpassungen speziell für deine Website vorgenommen wurden. Am wichtigsten ist, dass du dir überlegst, ob die spezifischen Ereignisdaten, die du an Klaviyo sendest, verändert oder erweitert wurden und ob du benutzerdefinierte Ereignisse hinzugefügt hast.

Wir empfehlen, deinen Code, der die Ereignisdaten zusammenstellt, mit der vorherigen Version der Klaviyo Cartridge zu vergleichen, die auf Klaviyo's Github verfügbar ist. Unter der Annahme, dass deine Integration nicht stark angepasst wurde, findest du deine aktuellen Funktionen zur Datenzusammenstellung in int_klaviyo_core/cartridge/scripts/utils/Klaviyo/klaviyoUtils.js und für die Bestellbestätigung in int_klaviyo_core/cartridge/scripts/utils/Klaviyo/emailUtils.js.

Notiere dir alle Anpassungen, damit du sie nach der Installation der neuen Kassette wieder anwenden kannst.

Verbinde eine SFCC-Sandbox mit einem Klaviyo-Testkonto

Wenn du noch kein zweites Klaviyo-Konto für Testzwecke eingerichtet hast, das von dem Konto getrennt ist, das mit deiner SFCC-Produktionsumgebung verbunden ist, solltest du dies tun. Verbinde dann deine SFCC-Sandbox-Umgebung mit dem neuen Konto. Wir empfehlen, diesen Schritt mit deiner vorherigen Klaviyo-Cartridge-Version durchzuführen, damit du überprüfen kannst, ob Ereignisse erfolgreich an dein zweites Klaviyo-Konto gesendet und von diesem empfangen werden, bevor du mit dem Upgrade deiner Codebasis auf die neue Klaviyo-Cartridge fortfährst.

Entferne den vorherigen Klaviyo Cartridge Code

Wenn deine Integration nicht stark angepasst wurde, 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. Allerdings musst du auch jeglichen Klaviyo-spezifischen Code entfernen, der zu den Vorlagedateien hinzugefügt wurde, sowie möglicherweise JavaScript-Dateien.

Für Site Genesis

Bei Standard-Integrationen für Site Genesis wird der folgende Code zu footer_UI.isml hinzugefügt:

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

Außerdem wird der folgende Block zur minicart.isml hinzugefügt, 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 SFCC wird der folgende Code zur pageFooter.isml hinzugefügt:

<isinclude template="klaviyo/klaviyoFooter"/>

Außerdem wird 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 das oben erwähnte Code-Fragment entfernt wurden, die Codebase nach dem Wort "Klaviyo" zu durchsuchen. Vergewissere dich, dass du weißt, was der Klaviyo-bezogene Code in deiner Codebasis macht, bevor du ihn entfernst, denn diese Blöcke können Anpassungen sein, die du nach der Installation der neuen Cartridge wieder einbauen musst.

Dienste entfernen

Die vorherige Integration hat einen KlaviyoTrackService, ein KlaviyoTrackProfile und KlaviyoTrackCredentials unter Administration > Operations > Service erstellt. Alle drei können sicher entfernt werden, da durch die Integration der neuen Klaviyo-Cartridge neue Dienste mit anderen Namen entstehen werden.

Es ist nicht zwingend notwendig, dass die alten Dienste entfernt werden, aber es wird empfohlen, sie zu säubern, um zukünftige Verwechslungen zu vermeiden.

Website-Einstellungen überprüfen

Bei der Integration der neuen Klaviyo-Cartridge werden einige der bisherigen Klaviyo-Site-Einstellungen beibehalten, aber auch einige neue hinzugefügt. Wirf einen Blick auf deine Website-Einstellungen in der Klaviyo unter Händlertools > Site-Einstellungen > Benutzerdefinierte Einstellungen > Klaviyo und überprüfe, ob benutzerdefinierte Einstellungen speziell für deine Website hinzugefügt wurden. Wenn du die Patrone angepasst hast, um deine eigenen Einstellungen hinzuzufügen, solltest du diese beibehalten. Als Referenz findest du hier die vier Website-Einstellungen, die in der vorherigen Klaviyo-Integration enthalten sind:

• Klaviyo Aktiviert (ID: klaviyo_enabled)
  Flagge, ob Klaviyo aktiviert oder deaktiviert 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 Klaviyo privater API-Schlüssel.
• Bildtyp für Klaviyo (ID: klaviyo_image_size)
  Groß, klein, Thumbnail, etc.

Bevor du die neue Kassette einrichtest, empfehlen wir dir, deine aktuellen Website-Einstellungen zu sichern, indem du sie unter Administration > Website-Entwicklung > Website importieren & Exportieren exportierst. Erweitere Sites, dann deinen Site-Namen und markiere das Feld Site Preferences, bevor du einen Dateinamen für den Export eingibst. Deine aktuellen Klaviyo-Einstellungen sollten nicht beeinträchtigt werden, wenn du später die neue Kassette installierst, aber es ist eine gute Idee, sie für die Zukunft zu sichern.

Entferne die Klaviyo-Patronen aus dem Patronenpfad

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] > Einstellungen. Wenn du diesen Schritt nicht durchführst, bekommst du Fehler, weil SFCC nach Kassetten sucht, die 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 das Hinzufügen von Produkten zum Warenkorb, die Eingabe und das Abschließen von Bezahlvorgängen durchzuführen. Behalte dabei die Entwicklerkonsole im Auge, um zu sehen, ob neue Fehler erzeugt werden. Mach dasselbe mit dem Anforderungsprotokoll. Wenn du neue Fehler im Zusammenhang mit Klaviyo siehst, ist die Wahrscheinlichkeit groß, dass du den vorherigen Klaviyo-Code nicht vollständig entfernt hast. Es ist wichtig, dass du die Quelle neuer Fehler aufspürst und sie notierst, bevor du sie entfernst.

Installiere die neue Klaviyo-Patrone

Befolge die Schritte, die in Erste Schritte mit Salesforce Commerce Cloud beschrieben sind, um die neue Cartridge in deine Codebasis zu integrieren. Es kann sein, dass du einige Schritte nicht ausführen musst - zum Beispiel kann es sein, dass deine SFCC-Instanz die Verbindungen für den OCAPI-Teil bereits hergestellt hat oder nicht - aber im Allgemeinen solltest du jeden Schritt der Integration befolgen. Du musst auf jeden Fall beide Klaviyo Patronen ersetzen und Code-Fragment wieder hinzufügen. 

Beachte, dass nach dem Import von metadata.zip, hast du vier neue Website-Einstellungen, zusätzlich zu den vier, die von der vorherigen Version der Cartridge erstellt wurden. Deine bisherigen Einstellungen sollten durch den Import der neuen Einstellungen nicht beeinträchtigt worden sein, aber es wird empfohlen, dass du noch einmal überprüfst, ob alle Einstellungen der Klaviyo-Website korrekt sind, bevor du fortfährst.

Da du ein Upgrade von einer Cartridge vor Version 23.7.0 durchführst, sollten die neuen Website-Einstellungen Ereignisse als SFCC kennzeichnen und In-Warenkorb-Ereignis als "In den Warenkorb legen" senden auf Nein bzw. Ja eingestellt sein. Dadurch werden weiterhin Ereignisse ohne das Salesforce Commerce Cloud Metrik-Label gesendet und der Ereignistyp "In den Warenkorb" (im Gegensatz zum neuen Typ "In den Warenkorb") verwendet. Wenn diese beiden Website-Einstellungen falsch gesetzt sind, führt dies zu einer Unterbrechung des Berichtswesens und möglicherweise auch zu einer Unterbrechung des bestehenden Flusses in Klaviyo.

Überprüfe, ob alle Out-of-the-Box-Ereignisse funktionieren

Bevor du versuchst, Anpassungen aus deiner vorherigen Integration wieder hinzuzufügen, solltest du sicherstellen, dass die neue Installation der Klaviyo-Cartridge korrekt funktioniert. Verwende das Frontend, um Ereignisse für Gesuchte Seite, Gesehene Kategorie, Gesehenes Produkt, In den Warenkorb gelegt, Bezahlvorgang gestartet und Bestellbestätigung zu generieren, und überprüfe dann dein Klaviyo Konto, um sicherzustellen, dass diese Ereignisse korrekt verfolgt werden. 

Überprüfe die Entwicklerkonsole auf allen Seiten, die Klaviyo-Ereignisse erzeugen, auf neue Fehler, die mit der Integration zusammenhängen könnten. Aktiviere die ausführliche Serviceprotokollierung, indem du das Kontrollkästchen Kommunikationsprotokoll aktiviert unter Administration > Vorgänge > Services > KlaviyoEventService - Details aktivierst und dann die serverseitigen Protokolldateien überprüfst, um sicherzustellen, dass keine Fehler vorliegen und dass die Ereignisdaten für jeden Ereignistyp ordnungsgemäß generiert werden.

Ereignisdaten mit der Produktion vergleichen

Du solltest jetzt die Ereignisdaten in deinen Test- und Produktionskonten Klaviyo vergleichen, um sicherzustellen, dass nichts fehlt und dass die aktuellen Werte dem erwarteten Typ entsprechen. Es ist wichtig, dass du feststellst, ob das Reporting oder der Flow von der neuen Integration betroffen sein werden. Du wirst feststellen, dass im Vergleich zur vorherigen Cartridge-Version nun zusätzliche Eigenschaften festgelegt und an Klaviyo gesendet werden. 

Standortbezogene Anpassungen wieder hinzufügen

Jetzt kannst du damit beginnen, Anpassungen in deinem Klaviyo-Code vorzunehmen. Da es bei der neuesten Klaviyo-Cartridge erhebliche strukturelle und architektonische Änderungen gibt, ist es unwahrscheinlich, dass du deinen eigenen Code einfach kopieren und direkt in die Klaviyo-Cartridge einfügen kannst.

Jeder Ereignistyp in der Klaviyo-Cartridge hat eine getData-Funktion, die in einer separaten Skriptdatei für den jeweiligen Ereignistyp steht. Diese Dateien befinden sich im Ordner int_klaviyo_core/cartridge/scripts/Klaviyo/eventData und sind der wahrscheinlichste Ort, an dem du Änderungen vornehmen wirst, um die Datenobjekte, die für jedes Ereignis übergeben werden, hinzuzufügen oder zu aktualisieren. Wenn du neue benutzerdefinierte Ereignisse erstellst, empfehlen wir dir, dem bewährten Muster zu folgen und Code zu serverseitigen Controllern hinzuzufügen (d.h. direkt in SiteGen oder über server.append in SFRA), der eine getData-Funktion aus einer Skriptdatei aufruft, die dem neuen Ereignis gewidmet ist, und dann die trackEvent-Funktion verwendet, um diese Daten über den KlaviyoEventService an Klaviyo zu senden.

Ergebnis

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

Zusätzliche Ressourcen 

• Erste Schritte mit Salesforce Commerce Cloud
• Salesforce Commerce Cloud Datenreferenz
• Wie oft die Integrationen die Referenz synchronisieren
• Wie man Kontakt unterstützt