Comment mettre à niveau votre cartouche Salesforce Commerce Cloud ?

Vous apprendrez

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

Utilisez-vous une version de cartouche antérieure à la 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 à la version la plus récente (actuellement, 24.1.0).

Avant de commencer

La version 23.7.0 (publiée le 13 juillet 2023) comprend un certain nombre d'améliorations significatives, dont certaines sont des changements architecturaux concernant la façon dont les événements sont déclenchés. Les considérations particulières relatives à la mise à niveau d'une version inférieure à 23.70 vers une version supérieure sont détaillées ci-dessous.

Comprendre votre intégration actuelle

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

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

Notez les personnalisations éventuelles afin de pouvoir les réappliquer après l'installation de la nouvelle cartouche.

Connectez un bac à sable SFCC à un compte de test Klaviyo

Si vous n'avez pas encore créé un 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 en utilisant la version précédente de la cartouche Klaviyo afin que vous puissiez vérifier que les événements sont bien envoyés et reçus par votre compte Klaviyo secondaire avant de procéder à la mise à niveau de votre base de code avec la nouvelle cartouche Klaviyo.

Retirez le code de la cartouche Klaviyo précédente

Si votre intégration n'a pas été fortement personnalisée, vous pourrez supprimer la majeure partie de l'intégration Klaviyo précédente en supprimant simplement les deux dossiers de cartouches Klaviyo : int_klaviyo_core et int_klaviyo (pour Site Genesis) ou int_klaviyo_sfra (pour SFRA) de la base de code. Cependant, vous devrez également supprimer tout code spécifique à Klaviyo qui aurait pu être ajouté aux fichiers de modèles, 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"/>

Le bloc suivant sera également ajouté au fichier minicart.isml, cart.isml, et tout autre fichier isml "cart" :

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

Pour le SFRA

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

<isinclude template="klaviyo/klaviyoFooter"/>

Le code suivant sera également 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 et SFRA, une fois que les dossiers de cartouches et les extraits de code mentionnés ci-dessus ont été supprimés, il est conseillé de rechercher le mot "Klaviyo" dans la base de code. Assurez-vous de bien connaître le fonctionnement de tout code lié à Klaviyo qui reste dans votre base de code avant de le supprimer, car ces blocs peuvent représenter des personnalisations que vous devrez remettre en place après l'installation de la nouvelle cartouche.

Supprimer les services

L'intégration précédente aura créé un KlaviyoTrackService, un KlaviyoTrackProfile et des KlaviyoTrackCredentials sur Administration > Operations > Service. Les trois peuvent être supprimés 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 indispensable de supprimer les anciens services, mais il est recommandé de les nettoyer pour éviter toute confusion future.

Réviser les préférences du site

Le processus d'intégration de la nouvelle cartouche Klaviyo conservera certaines des préférences de l'ancien site Klaviyo et en ajoutera d'autres. Jetez un coup d'œil à vos préférences de site dans le groupe de préférences de Klaviyo sur Merchant tools > Site Preferences > Custom Preferences > 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 y ajouter vos propres paramètres, vous voudrez les conserver. À titre de référence, voici les quatre préférences de site qui sont intégrées dans l'ancienne intégration de Klaviyo :

• Klaviyo activé (ID : klaviyo_enabled)
  Indique si Klaviyo est activé ou non.
• 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 de Klaviyo.
• Type d'image pour Klaviyo (ID : klaviyo_image_size)
  Grande, petite, miniature, etc.

Avant de configurer la nouvelle cartouche, nous vous recommandons de sauvegarder les préférences de votre site actuel en les exportant sur Administration > Développement du site > Importation du site & Exportation. Développez Sites, puis le nom de votre site, et cochez la case Préférences du site avant de saisir un nom de fichier pour l'exportation. Vos préférences Klaviyo actuelles ne devraient pas être affectées par l'installation ultérieure de la nouvelle cartouche, mais il est conseillé de les sauvegarder pour s'y référer ultérieurement.

Retirez les cartouches Klaviyo du chemin des cartouches.

Supprimez int_klaviyo_core et int_klaviyo (Site Genesis) ou int_klaviyo_sfra (SFRA) de votre chemin de cartouche à 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 le SFCC recherche des cartouches à charger qui n'existent plus.

Vérifiez les erreurs dans la console du développeur et dans le journal de bord du serveur.

À ce stade, vous ne devriez plus avoir de code Klaviyo dans votre base de code. Nous vous recommandons d'examiner votre interface utilisateur, de visiter des pages telles que les résultats de recherche, les PLP et les PDP, et d'effectuer des actions telles que l'ajout de produits au panier, l'entrée et la finalisation de la commande. Pendant ce temps, gardez un œil sur la Developer Console pour voir si de nouvelles erreurs sont générées. Faites de même avec le journal des demandes. Si vous voyez de nouvelles erreurs liées à Klaviyo, il y a de fortes chances que vous n'ayez pas complètement supprimé tout le code Klaviyo précédent. Il est important de rechercher la source de toute nouvelle erreur et de la noter avant de la supprimer.

Installez la nouvelle cartouche Klaviyo

Suivez les étapes décrites dans la section 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 des métadonnées.zip, vous aurez quatre nouvelles préférences de site, en plus des quatre qui étaient créées par la version précédente de la cartouche. Vos préférences précédentes ne devraient pas être affectées par l'importation des nouvelles, mais il est recommandé de vérifier que toutes les préférences du site Klaviyo sont correctes avant de continuer.

Puisque vous mettez à jour une cartouche antérieure à la version 23.7.0, les nouvelles préférences du site Étiqueter les événements comme SFCC et Envoyer l'événement ajouté au panier comme "Ajouter au panier" doivent être réglées sur Non et Oui, respectivement. Cela permettra de continuer à envoyer des événements sans l'étiquette métrique de Salesforce Commerce Cloud et d'utiliser le type d'événement " Ajouter au panier " (par opposition au nouveau type " Ajouté au panier"). Si ces deux préférences de site sont mal réglées, les rapports seront interrompus et les flux existants dans Klaviyo risquent d'être interrompus.

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

Avant d'essayer d'ajouter les personnalisations de votre intégration précédente, assurez-vous que la nouvelle installation de la cartouche Klaviyo fonctionne correctement. Utilisez le frontend pour générer des événements pour la recherche du site, la consultation de la catégorie, la consultation du produit, l' ajout au panier, le début du paiement et la confirmation de la commande, puis vérifiez votre compte Klaviyo pour vous assurer que ces événements sont suivis correctement. 

Vérifiez la console du développeur pour 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 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 pas d'erreurs et que les données d'événement sont correctement générées pour chaque type d'événement.

Comparer les données de l'événement avec la production

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

Ajouter des personnalisations spécifiques au site

Vous pouvez maintenant commencer à ajouter des personnalisations dans votre code Klaviyo. En raison des changements structurels et architecturaux importants apportés à la nouvelle cartouche Klaviyo, il est peu probable que vous puissiez simplement copier et coller un code personnalisé directement dans la cartouche Klaviyo.

Chaque type d'événement dans la cartouche Klaviyo a une fonction getData qui se trouve dans un fichier script séparé nommé pour chaque type d'événement. Ces fichiers se trouvent dans le dossier int_klaviyo_core/cartridge/scripts/klaviyo/eventData et sont les endroits les plus susceptibles d'être modifiés afin d'ajouter ou de mettre à jour les objets de données qui sont transmis pour chaque événement. Si vous créez de nouveaux événements personnalisés, nous vous recommandons de suivre le modèle établi qui consiste à ajouter du code aux 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 script dédié au nouvel événement, puis utilise la fonction trackEvent pour envoyer ces données à Klaviyo via le KlaviyoEventService.

Résultats

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

Ressources complémentaires 

• Démarrer avec Salesforce Commerce Cloud
• Référence des données de Salesforce Commerce Cloud
• Fréquence de synchronisation de la référence des intégrations
• Comment contacter l'assistance