Hoe je je Salesforce Commerce Cloud-cartridge kunt upgraden

Wat je leert

Leer hoe je je Klaviyo Salesforce Commerce Cloud cartridge kunt upgraden. 

Gebruikt u een cartridgeversie ouder dan 23.7.0? Wij raden u aan onmiddellijk te upgraden naar versie 23.7.0 of hoger. Oudere versies van de cartridge maken gebruik van Klaviyo's v1- en v2-API's, die zijn verouderd en niet langer naar behoren functioneren. Wij raden altijd aan om te upgraden naar onze nieuwste versie (momenteel 25.7.0).

Voordat je van start gaat

Versie 23.7.0 bevat een aantal zinvolle verbeteringen, waarvan sommige architecturale veranderingen zijn in de manier waarop gebeurtenissen worden geactiveerd. Speciale overwegingen voor het upgraden van een versie lager dan 23.70 naar een versie hoger worden hieronder beschreven.

Je huidige integraties begrijpen

Het is belangrijk dat je op de hoogte bent van je huidige SFCC-integraties en welke wijzigingen of aanpassingen specifiek voor jouw website zijn gemaakt. Het belangrijkste is dat je nagaat of de specifieke gebeurtenisgegevens die je naar Klaviyo stuurt al dan niet zijn gewijzigd of uitgebreid, en of je aangepaste gebeurtenissen hebt toegevoegd.

We raden aan om je code die gebeurtenisgegevens samenstelt te vergelijken met de vorige versie van de Klaviyo cartridge, die beschikbaar is op Klaviyo's Github. Ervan uitgaande dat uw integraties niet zwaar zijn aangepast, vindt u uw huidige gegevensverzamelfuncties in int_klaviyo_core/cartridge/scripts/utils/Klaviyo/klaviyoUtils .js, en voor Orderbevestiging 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.

Verbind een SFCC zandbak met een Klaviyo test account

Als je nog geen secundair Klaviyo account hebt aangemaakt om te testen, los van het account dat gekoppeld is aan je SFCC productieomgeving, dan moet je dat doen. Verbind vervolgens je SFCC sandbox omgeving met het nieuwe account. We raden aan om deze stap uit te voeren met uw vorige Klaviyo cartridge versie, zodat u kunt controleren of gebeurtenissen met succes worden verzonden naar en ontvangen door uw secundaire Klaviyo account voordat u verder gaat met het upgraden van uw codebase met de nieuwe Klaviyo cartridge.

Verwijder de vorige Klaviyo-cartridgecode

Als je integraties niet zwaar zijn aangepast, kun je het merendeel van de vorige Klaviyo integraties verwijderen door simpelweg de twee Klaviyo cartridge mappen: int_klaviyo_core en ofwel int_klaviyo (voor Site Genesis) of int_klaviyo_sfra (voor SFRA) uit de codebase te verwijderen. Je zult echter ook alle Klaviyo-specifieke code moeten verwijderen die mogelijk is toegevoegd aan template bestanden, en mogelijk JavaScript-bestanden.

Voor Site Genesis

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

<isinclude template="componenten/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 hebben de volgende code toegevoegd aan pageFooter.isml:

<isinclude template="klaviyo/klaviyoFooter"/>

Ze hebben 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 raadzaam om na het verwijderen van de cartridge-mappen en het hierboven genoemde codefragment te zoeken in de codebase naar het woord "Klaviyo.". Zorg ervoor dat je weet wat alle Klaviyo-gerelateerde code in je codebase doet voordat je deze verwijdert, omdat dit blok aanpassingen kan vertegenwoordigen die je terug moet plaatsen nadat de nieuwe cartridge is geïnstalleerd.

Diensten verwijderen

De vorige integraties hebben een KlaviyoTrackService, KlaviyoTrackProfile en KlaviyoTrackCredentials aangemaakt bij Administratie > Operations > Service. Alle drie kunnen veilig worden verwijderd omdat het integratieproces van de nieuwe Klaviyo cartridge nieuwe diensten met verschillende namen zal creëren.

Het is niet essentieel dat de oude diensten worden verwijderd, maar het is wel aan te raden om ze op te ruimen om verwarring in de toekomst te voorkomen.

Sitevoorkeuren bekijken

Tijdens het integratieproces van de nieuwe Klaviyo cartridge zullen sommige voorkeuren van de vorige Klaviyo site behouden blijven en zullen er ook enkele nieuwe worden toegevoegd. Kijk eens naar je sitevoorkeuren in de Klaviyo voorkeurengroep op Merchant tools > Sitevoorkeuren > Aangepaste voorkeuren > Klaviyo , en kijk of er aangepaste voorkeuren specifiek voor jouw website zijn toegevoegd. Als je de cartridge hebt aangepast om je eigen instellingen toe te voegen, dan wil je die bewaren. Ter referentie zijn hier de vier sitevoorkeuren die zijn ingebouwd in de vorige Klaviyo integraties:

• Klaviyo inschakelen (ID: klaviyo_enabled)
  Vlag of Klaviyo aan of uit staat.
• Klaviyo account (ID: klaviyo_account)
  Uw openbare Klaviyo API-sleutel of site-ID.
• Klaviyo Privé API-sleutel (ID: klaviyo_api_key)
  Een Klaviyo privé API-sleutel.
• Type afbeelding voor Klaviyo (ID: klaviyo_image_size)
  Groot, klein, miniatuur, enz.

Voordat je de nieuwe cartridge instelt, raden we je aan een back-up te maken van je huidige sitevoorkeuren door deze te exporteren via Beheer > Siteontwikkeling > Site importeren & Exporteren. Vouw Sites uit, vervolgens je sitenaam en vink het vak Sitevoorkeuren aan voordat je een bestandsnaam invoert om ze naar te exporteren. Je huidige voorkeuren op Klaviyo zouden niet negatief beïnvloed moeten worden als je later de nieuwe cartridge installeert, maar het is een goed idee om ze terug te zetten voor toekomstig gebruik.

Verwijder de Klaviyo cartridges uit het cartridgepad

Verwijder int_klaviyo_core en ofwel int_klaviyo (Site Genesis) of int_klaviyo_sfra (SFRA) uit je cartridgepad op Administration > Sites > Manage Sites > [Site Name] > Settings. Als je deze stap niet uitvoert, krijg je fouten doordat SFCC zoekt naar cartridges om te laden die niet meer bestaan.

Controleer de ontwikkelaarsconsole en het logboek van de server op fouten

Op dit punt zou u geen Klaviyo code meer in uw codebase moeten hebben. We raden je aan je voorkant te bekijken, pagina's te bezoeken zoals Zoekresultaten, PLP's en PDP's, en acties uit te voeren zoals producten toevoegen aan je winkelwagen, binnenkomen en afrekenen. Houd daarbij de Developer Console in de gaten om te zien of er nieuwe fouten worden gegenereerd. Doe hetzelfde met het aanvraaglogboek. Als je nieuwe fouten met betrekking tot Klaviyo ziet, is de kans groot dat je niet alle vorige Klaviyo code volledig hebt verwijderd. Het is belangrijk om de bron van nieuwe fouten op te sporen 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 te integreren in je codebase. Er kunnen stappen zijn die je niet hoeft te voltooien - je SFCC instance kan bijvoorbeeld al wel of niet de verbindingen hebben opgezet voor het OCAPI gedeelte - maar in het algemeen moet je elke stap van de integraties volgen. Je moet zeker beide Klaviyo cartridges vervangen en terug codefragment toevoegen. 

Merk op dat na het importeren van metadata.zip, heb je vier nieuwe sitevoorkeuren, naast de vier die werden aangemaakt in de vorige versie van de cartridge. Uw vorige voorkeuren zouden niet beïnvloed moeten zijn door het importeren van de nieuwe, maar het is aan te raden om te controleren of alle voorkeuren van de Klaviyo site correct zijn voordat u verder gaat.

Omdat je een upgrade uitvoert vanaf een cartridge voorafgaand aan versie 23.7.0, moeten de nieuwe sitevoorkeuren Gebeurtenissen labelen als SFCC en Gebeurtenis toegevoegd aan winkelwagentje verzenden als 'Toevoegen aan winkelwagentje' worden ingesteld op respectievelijk Nee en Ja. Dit zal doorgaan met het verzenden van gebeurtenissen zonder het Salesforce Commerce Cloud meetwaarde label en wordt het evenementtype Aan winkelwagen toevoegen gebruikt (in tegenstelling tot het nieuwe Aan winkelwagen toegevoegd). Als deze twee sitevoorkeuren verkeerd zijn ingesteld, wordt de rapportage verbroken en mogelijk ook de bestaande flow in Klaviyo.

Controleer of alle out-of-the-box gebeurtenissen werken

Controleer of de nieuwe installatie van de Klaviyo cartridge correct werkt voordat je probeert om aanpassingen van je vorige integraties toe te voegen. Gebruik de voorkant om gebeurtenissen te genereren voor Gezochte site, Bekeken categorie, Bekeken product, Toegevoegd aan winkelwagen, Gestart met afrekenen en Orderbevestiging en controleer vervolgens je Klaviyo account om er zeker van te zijn dat deze gebeurtenissen correct worden bijgehouden. 

Controleer de ontwikkelaarsconsole op nieuwe fouten die gerelateerd kunnen zijn aan de integraties op alle pagina's die Klaviyo events genereren. Schakel verbose service logging in door het Communicatie Log inschakelen selectievakje in te schakelen op Administratie > Operations > Services > KlaviyoEventService - Details, en bekijk dan de server-side logbestanden om te controleren of er geen fouten zijn en of gebeurtenisgegevens correct worden gegenereerd voor elk gebeurtenistype.

Vergelijk evenementgegevens met productie

Je moet nu de gebeurtenisgegevens in je test- en productieaccount op Klaviyo vergelijken om er zeker van te zijn dat er niets ontbreekt en dat de huidige waarden overeenkomen met het verwachte type. Het is belangrijk om te bepalen of de rapportage of doorstroming beïnvloed wordt door de nieuwe integraties. Je zult zien dat er nu extra eigenschappen worden ingesteld en naar Klaviyo worden verzonden in vergelijking met de vorige cartridge-versie. 

Terug site-specifieke aanpassingen toevoegen

Je kunt nu beginnen met het toevoegen van aanpassingen terug in je Klaviyo code. Omdat er grote structurele en architecturale veranderingen zijn in de nieuwste Klaviyo cartridge, is het onwaarschijnlijk dat je gewoon aangepaste code kunt kopiëren en plakken in de Klaviyo cartridge.

Elk gebeurtenistype in de Klaviyo cartridge heeft een getData functie die leeft in een apart scriptbestand met de naam van elk gebeurtenistype. Deze bestanden kunnen worden gevonden in de map int_klaviyo_core/cartridge/scripts/Klaviyo /eventData, en zijn de meest waarschijnlijke plaats die je zult wijzigen om de gegevensobjecten die voor elke gebeurtenis worden doorgegeven toe te voegen of update. Als je nieuwe aangepaste gebeurtenissen aanmaakt, raden we je aan om het vaste patroon te volgen van het toevoegen van code 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 gewijd is aan de nieuwe gebeurtenis en vervolgens de trackEvent functie gebruikt om die gegevens naar Klaviyo te sturen via de KlaviyoEventService.

Resultaat

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

Extra hulpbronnen 

• Aan de slag met Salesforce Commerce Cloud
• Salesforce Commerce Cloud gegevens referentie
• Hoe vaak integraties referentie synchroniseren
• Meer informatie over hoe je contact opneemt met support