Comment mettre à niveau votre cartouche Salesforce Commerce Cloud

Objectif de cet article

Découvrez comment mettre à niveau votre cartouche Klaviyo Salesforce Commerce Cloud.

Utilisez-vous une version de cartridge antérieure à 23.7.0 ? Nous vous recommandons de passer immédiatement à la version 23.7.0 ou à une version plus récente. Les anciennes versions de la cartouche utilisent les API v1 et v2 de Klaviyo, qui ont été retirées et ne fonctionnent plus comme prévu. Nous vous recommandons toujours de passer à notre version la plus récente (actuellement, 25.7.0).

Avant de commencer

La version 23.7.0 inclut un certain nombre d’améliorations significatives, dont certaines sont des changements d’architecture liés à la façon dont les événements sont déclenchés. Les considérations particulières pour la mise à niveau depuis toute version antérieure à 23.70 vers toute version ultérieure sont détaillées ci-dessous.

Comprendre vos intégrations actuelles

Il est important de bien connaître votre intégration SFCC actuelle et les changements ou personnalisations qui ont pu être apportés spécifiquement à votre site web. Surtout, vous devez déterminer si les données d’événement spécifiques que vous envoyez à Klaviyo ont été modifiées ou enrichies, et si vous avez ajouté des événements personnalisés.

Nous vous recommandons de comparer votre code qui assemble les données d’événement avec la version précédente de la cartouche Klaviyo, disponible sur le Github de Klaviyo. En supposant que vos intégrations n’ont pas été fortement personnalisées, vous trouverez vos fonctions d’assemblage de données actuelles dans int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js, et pour Confirmation de commande dans int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js.

Notez toutes les personnalisations afin de pouvoir les réappliquer une fois la nouvelle cartouche installée.

Connectez un sandbox SFCC à un compte de test Klaviyo

Si vous n’avez pas encore créé de compte Klaviyo secondaire pour les tests, distinct du compte lié à votre environnement de production SFCC, vous devriez le faire. Ensuite, connectez votre environnement sandbox SFCC au nouveau compte. Nous vous recommandons d’effectuer cette étape avec votre version antérieure du cartridge Klaviyo afin de vérifier que les événements sont bien envoyés à votre compte Klaviyo secondaire et reçus par celui-ci avant de procéder à la mise à niveau de votre base de code avec le nouveau cartridge Klaviyo.

Supprimer le code de cartouche Klaviyo précédent

Si vos intégrations n’ont pas fait l’objet de nombreuses personnalisations, vous pourrez supprimer la majorité de l’intégration Klaviyo précédente en supprimant simplement les deux dossiers de cartouche Klaviyo : int_klaviyo_core et soit int_klaviyo (pour Site Genesis), soit int_klaviyo_sfra (pour SFRA) de la base de code. Cependant, vous devrez également supprimer tout code spécifique à Klaviyo qui pourrait avoir été ajouté aux fichiers de modèle, et éventuellement aux fichiers JavaScript.

Pour Site Genesis

Les intégrations Standard pour Site Genesis auront le code suivant ajouté à footer_UI.isml :

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

Ils auront également le bloc suivant ajouté à minicart.isml, cart.isml, ainsi que tout autre fichier isml « cart » :

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

Pour SFRA

Les intégrations Standard pour SFCC auront le code suivant ajouté à pageFooter.isml :

<isinclude template="klaviyo/klaviyoFooter"/>

Ils auront également le code suivant ajouté à la route AddProduct dans le contrôleur Cart.js :

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

Pour Site Genesis comme pour SFRA, après avoir supprimé les dossiers de cartridge et les extraits de code mentionnés ci-dessus, il est conseillé de rechercher le mot « Klaviyo » dans la base de code. Assurez-vous de bien comprendre ce que fait tout code lié à Klaviyo encore présent dans votre base de code avant de le supprimer, car ces blocs peuvent correspondre à des personnalisations que vous devrez remettre en place après l’installation de la nouvelle cartridge.

Supprimer des services

L’intégration précédente aura créé un KlaviyoTrackService, un KlaviyoTrackProfile et un KlaviyoTrackCredentials dans Administration > Opérations > Service. Vous pouvez supprimer les trois en toute sécurité, car le processus d’intégration de la nouvelle cartouche Klaviyo créera de nouveaux services avec des noms différents.

Il n’est pas essentiel que les anciens services soient supprimés, mais il est recommandé de les nettoyer afin d’éviter toute confusion ultérieure.

Consultez les préférences du site

Le processus d’intégration de la nouvelle cartouche Klaviyo conservera certaines des préférences de site Klaviyo précédentes et en ajoutera également de nouvelles. Consultez les préférences de votre site dans le groupe de préférences Klaviyo sous Outils marchand > Préférences du site > Préférences personnalisées > klaviyo, et vérifiez si des préférences personnalisées ont été ajoutées spécifiquement pour votre site web. Si vous avez personnalisé la cartouche pour ajouter vos propres paramètres, vous voudrez les conserver. Pour référence, voici les quatre préférences de site intégrées à l’intégration Klaviyo précédente :

• Klaviyo activé (ID: klaviyo_enabled)
  Indique si Klaviyo est activé ou désactivé.
• Compte Klaviyo (ID : klaviyo_account)
  Votre clé d’API publique Klaviyo, ou ID de site.
• Clé d’API privée Klaviyo (ID: klaviyo_api_key)
  Une clé d’API privée Klaviyo.
• Type d’image pour Klaviyo (ID : klaviyo_image_size)
  Grand, petit, miniature, etc.

Avant de configurer la nouvelle cartouche, nous vous recommandons de sauvegarder les préférences actuelles de votre site en les exportant depuis Administration > Développement du site > Importation et exportation du site. Développez Sites, puis Nom du site, et cochez la case Préférences du site avant de saisir un nom de fichier vers lequel les exporter. Vos préférences Klaviyo actuelles ne devraient pas être affectées négativement lorsque vous installerez la nouvelle cartouche ultérieurement, mais il est conseillé de les sauvegarder pour référence ultérieure.

Retirez les cartouches Klaviyo du chemin de cartouche

Supprimez int_klaviyo_core et soit int_klaviyo (Site Genesis), soit int_klaviyo_sfra (SFRA) de votre chemin de cartouche dans Administration > Sites > Gérer les sites > [Nom du site] > Paramètres. Si vous n’effectuez pas cette étape, vous obtiendrez des erreurs résultant du fait que SFCC recherche des cartridges à charger qui n’existent plus.

Vérifiez la console du développeur et le journal côté serveur pour détecter des erreurs

À ce stade, vous ne devriez plus avoir de code Klaviyo dans votre base de code. Nous vous recommandons de passer en revue votre interface frontend, de visiter des pages telles que les résultats de recherche, les PLP et les PDP, et d’effectuer des actions telles qu’ajouter des produits au panier, saisir et finaliser le paiement. Ce faisant, gardez un œil sur la console de développement pour voir si de nouvelles erreurs sont générées. Faites de même avec le journal des requêtes. Si vous constatez de nouvelles erreurs liées à Klaviyo, il est fort probable que vous n’ayez pas complètement supprimé tout le code Klaviyo précédent. Il est important d’identifier la source de toute nouvelle erreur et de la noter avant de la supprimer.

Installer la nouvelle cartouche Klaviyo

Suivez les étapes décrites dans Démarrer avec Salesforce Commerce Cloud pour intégrer la nouvelle cartouche dans votre base de code. Il se peut que certaines étapes ne soient pas nécessaires — par exemple, votre instance SFCC peut ou non avoir les connexions déjà établies pour la partie OCAPI — mais en général, vous devez suivre chaque étape de l’intégration. Vous devrez certainement remplacer les deux cartouches Klaviyo et ajouter des extraits de code.

Notez qu’après l’importation de metadata.zip, Vous aurez quatre nouvelles préférences de site, en plus des quatre qui ont été créées par la version précédente de la cartouche. Vos préférences précédentes ne devraient pas avoir été affectées par l’importation des nouvelles, mais il est recommandé de vérifier à nouveau que toutes les préférences de site Klaviyo sont correctes avant de continuer.

Comme vous effectuez une mise à niveau depuis un cartridge antérieur à la version 23.7.0, les nouvelles préférences de site Label Events as SFCC et Send Added To Cart Event as ‘Add To Cart’ doivent être définies sur Non et Oui, respectivement. Cela continuera d’envoyer des événements sans le libellé d’indicateur Salesforce Commerce Cloud et utilisera le type d’événement Add To Cart (au lieu du nouveau Added to Cart). Si ces deux préférences de site ne sont pas configurées correctement, cela entraînera une interruption du reporting et, potentiellement, une interruption des flux existants dans Klaviyo.

Vérifiez que tous les événements prêts à l’emploi fonctionnent

Avant d’essayer de réintégrer des personnalisations de votre intégration précédente, veillez à vérifier que la nouvelle installation du cartridge Klaviyo fonctionne correctement. Utilisez le frontend pour générer des événements pour Searched Site, Viewed Category, Viewed Product, Added To Cart, Started Checkout et Order Confirmation, puis vérifiez dans votre compte Klaviyo que ces événements sont correctement suivis.

Vérifiez la console du développeur pour détecter toute nouvelle erreur qui pourrait être liée à l’intégration sur toutes les pages qui génèrent des événements Klaviyo. Activez la journalisation détaillée du service en cochant la case Communication Log Enabled dans Administration > Operations > Services > KlaviyoEventService - Details, puis examinez les fichiers journaux côté serveur pour vérifier qu’il n’y a aucune erreur et que les données d’événement sont correctement générées pour chaque type d’événement.

Comparer les données d’événement avec la production

Vous devez maintenant comparer les données d’événement dans vos comptes Klaviyo de test et de production afin de vous assurer qu’il ne manque rien et que les valeurs actuelles correspondent au type attendu. Il est important de déterminer si un reporting ou des flux seront affectés par la nouvelle intégration. Vous constaterez que des propriétés supplémentaires sont désormais définies et envoyées à Klaviyo par rapport à la version précédente de la cartouche.

Ajouter de nouveau les personnalisations propres au site

Vous pouvez maintenant recommencer à ajouter des personnalisations dans votre code Klaviyo. En raison de changements structurels et architecturaux importants dans le tout dernier cartridge Klaviyo, il est peu probable que vous puissiez simplement copier-coller du code personnalisé directement dans le cartridge Klaviyo.

Chaque type d’événement dans la cartouche Klaviyo dispose d’une fonction getData située dans un fichier de script distinct nommé en fonction de chaque type d’événement. Ces fichiers se trouvent dans le dossier int_klaviyo_core/cartridge/scripts/klaviyo/eventData et constituent l’endroit le plus probable que vous modifierez afin d’ajouter ou de mettre à jour les objets de données transmis pour chaque événement. Si vous créez de nouveaux événements personnalisés, nous vous recommandons de suivre le modèle établi consistant à ajouter du code à des contrôleurs côté serveur (c’est-à-dire directement dans SiteGen ou via server.append dans SFRA) qui appelle une fonction getData à partir d’un fichier de script dédié au nouvel événement, puis utilise la fonction trackEvent pour envoyer ces données à Klaviyo via le KlaviyoEventService.

Résultat

Vous avez maintenant mis à niveau votre cartouche Klaviyo pour Salesforce Commerce Cloud.

Ressources supplémentaires