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 die APIs v1 und v2 von Klaviyo, die eingestellt wurden und nicht mehr wie erwartet funktionieren. Wir empfehlen immer ein Upgrade auf unsere neueste Version (aktuell 25.7.0).

Bevor du anfängst

Version 23.7.0 enthält eine Reihe bedeutender Verbesserungen, von denen einige architektonische Änderungen daran sind, wie Events ausgelöst werden. Besondere Hinweise für das Upgrade von jeder Version unter 23.70 auf jede Version darüber werden unten beschrieben.

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. Wenn deine Integrationen nicht stark angepasst wurden, findest du deine aktuellen Datenzusammenstellungsfunktionen in int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js und für Bestellbestätigung 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 sekundäres Klaviyo-Konto zum Testen erstellt hast, getrennt von dem Konto, das mit deiner SFCC-Produktionsumgebung verknüpft ist, solltest du das tun. Verbinde dann deine SFCC-Sandbox-Umgebung mit dem neuen Konto. Wir empfehlen, diesen Schritt mit deiner bisherigen Klaviyo-Cartridge-Version abzuschließen, damit du überprüfen kannst, dass Events erfolgreich an dein sekundäres Klaviyo-Konto gesendet und von diesem empfangen werden, bevor du mit dem Upgrade deiner Codebase 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

Bei Standard-Integrationen für SFCC wird der folgende Code zu 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 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 > Operations > Service einen KlaviyoTrackService, ein KlaviyoTrackProfile und KlaviyoTrackCredentials erstellt. Alle drei können sicher entfernt werden, da durch die Integration der neuen Klaviyo-Kartusche 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.

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

Da du ein Upgrade von einem Cartridge vor Version 23.7.0 durchführst, sollten die neuen Site-Einstellungen Label Events as SFCC und Send Added To Cart Event as ‘Add To Cart’ auf Nein bzw. Ja gesetzt werden. Dadurch werden weiterhin Events ohne die Salesforce Commerce Cloud Metrik-Bezeichnung gesendet und der Event-Typ Add To Cart verwendet (im Gegensatz zum neuen Added to Cart). Wenn diese beiden Site-Einstellungen falsch gesetzt sind, führt das zu einer Unterbrechung des Reportings und möglicherweise zu einer Unterbrechung bestehender Flow 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.

Ergebnis

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