Hoe je je Salesforce Commerce Cloud-cartridge upgradet

Wat je leert

Ontdek hoe je je Klaviyo Salesforce Commerce Cloud-cartridge kunt upgraden.

Gebruik je een cartridgeversie ouder dan 23.7.0? We raden aan om onmiddellijk te upgraden naar versie 23.7.0 of hoger. Oudere versies van de cartridge gebruiken Klaviyo’s v1- en v2-API’s, die buiten gebruik zijn gesteld en niet meer werken zoals verwacht. We raden altijd aan om te upgraden naar onze nieuwste versie (op dit moment 25.7.0).

Voordat je van start gaat

Versie 23.7.0 bevat een aantal betekenisvolle verbeteringen, waaronder een aantal architectuurwijzigingen rondom hoe gebeurtenissen worden geactiveerd. Speciale aandachtspunten voor upgraden van elke versie onder 23.70 naar elke versie daarboven worden hieronder beschreven.

Begrijp je huidige integraties

Het is belangrijk dat je bekend bent met je huidige SFCC-integratie en welke wijzigingen of aanpassingen specifiek voor je website zijn gedaan. Het belangrijkste is dat je nagaat of de specifieke eventdata die je naar Klaviyo stuurt, zijn gewijzigd of aangevuld en of je aangepaste events hebt toegevoegd.

We raden aan om je code waarmee eventgegevens worden samengesteld te vergelijken met de vorige versie van de Klaviyo-cartridge, beschikbaar op Klaviyo’s Github. Als je integraties niet sterk is aangepast, vind je je huidige functies voor het samenstellen van data in int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js en voor Order Confirmation in int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js.

Noteer eventuele aanpassingen, zodat je ze opnieuw kunt toepassen zodra de nieuwe cartridge is geïnstalleerd.

Koppel een SFCC-sandbox aan een Klaviyo-testaccount

Als je nog geen secundair Klaviyo-account hebt aangemaakt voor testen, los van het account dat gekoppeld is aan je SFCC-productieomgeving, doe dat dan. Koppel vervolgens je SFCC-sandboxomgeving aan het nieuwe account. We raden aan deze stap te voltooien met je vorige Klaviyo-cartridgeversie, zodat je kunt verifiëren dat events succesvol worden verzonden naar en ontvangen door je secundaire Klaviyo-account voordat je doorgaat met het upgraden van je codebase met de nieuwe Klaviyo-cartridge.

Verwijder de vorige Klaviyo-cartridgecode

Als je integratie niet sterk was aangepast, kun je het grootste deel van de vorige Klaviyo-integratie verwijderen door simpelweg de twee Klaviyo-cartridgemappen te verwijderen: int_klaviyo_core en int_klaviyo (voor Site Genesis) of int_klaviyo_sfra (voor SFRA) uit de codebase. Je moet echter ook alle Klaviyo-specifieke code verwijderen die mogelijk is toegevoegd aan templatebestanden en mogelijk ook JavaScript-bestanden.

Voor Site Genesis

Standard-integraties voor Site Genesis hebben de volgende code toegevoegd aan footer_UI.isml:

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

Ze krijgen ook het volgende blok toegevoegd aan minicart.isml, cart.isml en alle andere 'cart'-isml-bestanden:

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

Voor SFRA

Standard integraties voor SFCC krijgen de volgende code toegevoegd aan pageFooter.isml:

<isinclude template="klaviyo/klaviyoFooter"/>

Ze krijgen ook de volgende code toegevoegd aan de AddProduct-route in de Cart.js-controller:

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

Voor zowel Site Genesis als SFRA is het, nadat de cartridgemappen en de hierboven genoemde codefragmenten zijn verwijderd, aan te raden om in de codebase te zoeken naar het woord "Klaviyo." Zorg dat je weet wat eventuele Klaviyo-gerelateerde code die nog in je codebase staat doet voordat je deze verwijdert, want deze blokken kunnen aanpassingen zijn die je weer moet terugzetten nadat de nieuwe cartridge is geïnstalleerd.

Services verwijderen

De vorige integratie heeft een KlaviyoTrackService, KlaviyoTrackProfile en KlaviyoTrackCredentials aangemaakt bij Beheer > Bewerkingen > Service. Alle drie kunnen veilig worden verwijderd, omdat het integreren van de nieuwe Klaviyo-cartridge nieuwe services met andere namen aanmaakt.

Het is niet kritisch dat de oude services worden verwijderd, maar het wordt aanbevolen dat je ze opruimt om toekomstige verwarring te voorkomen.

Voorkeuren voor reviewsites

Bij het integreren van de nieuwe Klaviyo-cartridge blijven sommige van de eerdere Klaviyo-sitevoorkeuren behouden en worden er ook enkele nieuwe toegevoegd. Bekijk je sitevoorkeuren in de voorkeursgroep Klaviyo onder Merchant tools > Site Preferences > Custom Preferences > klaviyo, en controleer of er aangepaste voorkeuren zijn toegevoegd die specifiek voor je website zijn. Als je de cartridge hebt aangepast om je eigen instellingen toe te voegen, wil je die behouden. Ter referentie: dit zijn de vier sitevoorkeuren die zijn ingebouwd in de vorige Klaviyo-integratie:

• Klaviyo ingeschakeld (ID: klaviyo_enabled)
  Vlag om aan te geven of Klaviyo aan of uit staat.
• Klaviyo-account (ID: klaviyo_account)
  Je openbare API-sleutel van Klaviyo, of site-ID.
• Klaviyo Private API-sleutel (ID: klaviyo_api_key)
  Een Klaviyo private API-sleutel.
• Afbeeldingstype voor Klaviyo (ID: klaviyo_image_size)
  Groot, klein, miniatuur, enz.

Voordat je de nieuwe cartridge instelt, raden we aan je huidige sitevoorkeuren te back-uppen door ze te exporteren via Administratie > Siteontwikkeling > Site-import en export. Vouw Sites uit, daarna je Sitenaam, en vink het vakje Sitevoorkeuren aan voordat je een bestandsnaam invoert om ze naar te exporteren. Je huidige Klaviyo-voorkeuren zouden niet nadelig beïnvloed moeten worden wanneer je later de nieuwe cartridge installeert, maar het is een goed idee om ze te back-uppen voor toekomstig gebruik.

Verwijder de Klaviyo-cartridges uit het cartridgepad

Verwijder int_klaviyo_core en int_klaviyo (Site Genesis) of int_klaviyo_sfra (SFRA) uit je cartridgepad bij Beheer > Sites > Sites beheren > [Sitenaam] > Instellingen. Als je deze stap niet uitvoert, krijg je fouten doordat SFCC zoekt naar cartridges om te laden die niet meer bestaan.

Controleer de developer console en de server side-log op fouten.

Op dit punt zou je geen Klaviyo-code meer in je codebase moeten hebben. We raden aan je frontend te controleren, pagina's te bezoeken zoals Zoekresultaten, PLP's en PDP's, en acties uit te voeren zoals producten aan winkelwagen toevoegen, checkout openen en checkout voltooien. Terwijl je dat doet, houd je de Developer Console in de gaten om te zien of er nieuwe fouten worden gegenereerd. Doe hetzelfde met het aanvraaglogboek. Als je nieuwe fouten ziet die verband houden met Klaviyo, is de kans groot dat je niet alle eerdere Klaviyo-code volledig hebt verwijderd. Het is belangrijk om de bron van eventuele nieuwe fouten te achterhalen en ze te noteren voordat je ze verwijdert.

Installeer de nieuwe Klaviyo-cartridge

Volg de stappen in Aan de slag met Salesforce Commerce Cloud om de nieuwe cartridge in je codebase te integreren. Er kunnen stappen zijn die je niet hoeft uit te voeren – je SFCC-instance kan de verbindingen voor het OCAPI-gedeelte bijvoorbeeld al wel of nog niet hebben ingesteld – maar over het algemeen kun je elke stap van de integraties volgen. Je moet beide Klaviyo-cartridges zeker vervangen en codefragmenten weer toevoegen.

Let op: nadat je metadata.zip hebt geïmporteerd, heb je vier nieuwe sitevoorkeuren, naast de vier die door de vorige versie van de cartridge zijn gemaakt. Je eerdere voorkeuren zouden niet beïnvloed mogen zijn door het importeren van de nieuwe, maar we raden je aan om dubbel te controleren of alle Klaviyo-sitevoorkeuren correct zijn voordat je doorgaat.

Omdat je upgradet vanaf een cartridge van vóór versie 23.7.0, moeten de nieuwe sitevoorkeuren Label Events as SFCC en Send Added To Cart Event as ‘Add To Cart’ worden ingesteld op respectievelijk Nee en Ja. Hierdoor worden events zonder het meetwaarde-label Salesforce Commerce Cloud verstuurd en wordt het eventtype Add To Cart gebruikt (in plaats van het nieuwe Added to Cart). Als deze twee sitevoorkeuren onjuist zijn ingesteld, leidt dat tot een onderbreking van de rapportage en mogelijk tot een onderbreking van bestaande flows in Klaviyo.

Controleer of alle standaardevents werken

Voordat je probeert om aanpassingen uit je vorige integratie weer toe te voegen, moet je controleren of de nieuwe installatie van de Klaviyo-cartridge correct werkt. Gebruik de frontend om events te genereren voor Site doorzocht, Categorie bekeken, Product bekeken, Toegevoegd aan winkelwagen, Checkout gestart en Bestellingsbevestiging, en controleer vervolgens je Klaviyo-account om ervoor te zorgen dat deze events correct worden bijgehouden.

Controleer de developer console op nieuwe fouten die mogelijk verband houden met de integraties op alle pagina's die Klaviyo-events genereren. Schakel uitgebreide servicelogging in door het selectievakje Communication Log Enabled aan te vinken bij Administration > Operations > Services > KlaviyoEventService - Details en bekijk daarna de server-side logbestanden om te controleren of er geen fouten zijn en of gebeurtenisgegevens correct worden gegenereerd voor elk gebeurtenistype.

Vergelijk eventgegevens met productie

Je moet nu de eventgegevens in je test- en productie-Klaviyo-accounts vergelijken om te controleren of er niets ontbreekt en of de huidige waarden overeenkomen met het verwachte type. Het is belangrijk om te bepalen of rapportage of flows worden beïnvloed door de nieuwe integratie. Je zult zien dat er nu extra properties worden ingesteld en naar Klaviyo worden verzonden in vergelijking met de vorige cartridgeversie.

Sitespecifieke aanpassingen weer toevoegen

Je kunt nu weer beginnen met het toevoegen van aanpassingen in je Klaviyo-code. Door de grote structurele en architectonische wijzigingen in de nieuwste Klaviyo-cartridge is het onwaarschijnlijk dat je aangepaste code eenvoudigweg kunt kopiëren en plakken in de Klaviyo-cartridge.

Elk gebeurtenistype in de Klaviyo-cartridge heeft een getData-functie die in een apart scriptbestand staat dat is vernoemd naar elk gebeurtenistype. Deze bestanden vind je in de map int_klaviyo_core/cartridge/scripts/klaviyo/eventData, en dit is de plek die je het meest waarschijnlijk aanpast om de gegevensobjecten die voor elke gebeurtenis worden doorgegeven toe te voegen of bij te werken. Als je nieuwe aangepaste gebeurtenissen maakt, raden we aan het bestaande patroon te volgen: code toevoegen aan server-side controllers (d.w.z. rechtstreeks in SiteGen of via server.append in SFRA) die een getData-functie aanroept vanuit een scriptbestand dat speciaal is bedoeld voor de nieuwe gebeurtenis, en vervolgens de trackEvent-functie gebruikt om die gegevens via de KlaviyoEventService naar Klaviyo te sturen.

Resultaat

Je hebt nu je Klaviyo-cartridge voor Salesforce Commerce Cloud geüpgraded.

Extra hulpbronnen