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 cartouche 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 d’effectuer une mise à niveau vers la dernière version sur la page des versions GitHub de Klaviyo.
Avant de commencer
La version 23.7.0 inclut un certain nombre d’améliorations significatives, dont certaines sont des changements d’architecture concernant la manière dont les événements sont déclenchés. Les étapes ci-dessous couvrent la mise à niveau depuis une version antérieure à la 23.7.0 vers la version 23.7.0 ou une version ultérieure. Effectuez la mise à niveau et les tests dans un sandbox SFCC avant d’apporter des modifications à votre site de production.
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 à 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 celles de Order Confirmation 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 associé à votre environnement de production SFCC, vous devez le faire. Ensuite, connectez votre environnement sandbox SFCC au nouveau compte, en utilisant la clé d’API publique et la clé d’API privée de ce compte dans les paramètres de la cartouche sandbox. Nous vous recommandons d’effectuer cette étape à l’aide de la version précédente de votre cartouche 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 la nouvelle cartouche 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 SFRA auront le code suivant ajouté à pageFooter.isml :
<isinclude template="klaviyo/klaviyoFooter"/>Ils verront é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 > Services. Vous pouvez supprimer ces trois éléments en toute sécurité, car le processus d’intégration de la nouvelle cartouche Klaviyo créera de nouveaux services portant 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.
Ne copiez/collez pas simplement les nouveaux dossiers de cartouches par-dessus les anciens. Conformément aux instructions ci-dessus, supprimez complètement les anciens dossiers avant d’ajouter les nouveaux.
L’importation de metadata.zip ajoute de nouvelles préférences de site en plus des 4 listées ci-dessus. Passez en revue toutes les préférences de site Klaviyo et confirmez vos valeurs existantes avant de poursuivre. Configurez les sélecteurs d’e-mail Klaviyo et le sélecteur d’e-mail de paiement pour les champs d’e-mail de votre site afin que Klaviyo puisse identifier les visiteurs et suivre l’activité de paiement.
Étant donné que vous effectuez une mise à niveau depuis une cartouche antérieure à 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 No et Yes, 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 (plutôt que le nouveau Added to Cart). Le fait de définir incorrectement ces deux préférences de site entraînera une rupture du reporting et, potentiellement, une rupture 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.
Après avoir restauré vos personnalisations, répétez les vérifications des événements et des erreurs dans le bac à sable, y compris tous les événements personnalisés et les propriétés personnalisées utilisés par vos flux. Une fois les tests terminés, déployez la mise à niveau testée en production en utilisant les clés d’API et les préférences du site de votre compte Klaviyo de production, puis vérifiez que les événements atteignent le compte de production avec les noms et les données attendus.
Résultat
Vous avez maintenant mis à niveau votre cartouche Klaviyo pour Salesforce Commerce Cloud.
Ressources supplémentaires
- Démarrer avec Salesforce Commerce Cloud
Découvrez comment intégrer Salesforce Commerce Cloud à Klaviyo. L’intégration de la cartouche et de l’API Klaviyo permet aux sites web utilisant Salesforce Commerce Cloud (anciennement Demandware) de se connecter rapidement et d’envoyer à Klaviyo des données en temps réel et historiques. Lorsque vous intégrez Klaviyo à Salesforce Commerce Cloud (SFCC), Klaviyo commence à suivre en temps réel les actions effectuées par les utilisateurs, comme la navigation sur le site web, le suivi des recherches, la consultation des produits, la consultation des catégories, l’ajout d’articles au panier, le passage en caisse et la commande.
- Référence des données Salesforce Commerce Cloud
Découvrez quelles données se synchronisent de Salesforce Commerce Cloud vers Klaviyo après l’activation des intégrations Salesforce Commerce Cloud de Klaviyo, et comment vous pouvez les consulter.
- Documentation sur la fréquence de synchronisation des intégrations
Découvrez quelles données sont synchronisées à partir d’une intégration Klaviyo spécifique et à quelle fréquence la synchronisation s’exécute. Nous avons organisé ces intégrations par plateformes d’e-commerce, ESP et autres intégrations de données.
- Comment contacter l’assistance
Nous proposons une assistance par e-mail et par chat en direct aux clients sur tous les forfaits payants.