Cómo actualizar el cartucho de Salesforce Commerce Cloud
Objetivos del artículo
Aprende a actualizar el cartucho de Klaviyo para Salesforce Commerce Cloud.
¿Estás usando una versión del cartucho anterior a la 23.7.0? Te recomendamos actualizar inmediatamente a la versión 23.7.0 o superior. Las versiones anteriores del cartucho usan la interfaz de programación de aplicaciones (API) v1 y v2 de Klaviyo, que fueron retiradas y ya no funcionan como se espera. Te recomendamos actualizar a la versión más reciente en la página de versiones de GitHub de Klaviyo.
Antes de empezar
La versión 23.7.0 incluye varias mejoras importantes, algunas de las cuales son cambios de arquitectura en torno a cómo se activan los eventos. Los pasos a continuación cubren la actualización de una versión anterior a la 23.7.0 a la versión 23.7.0 o posterior. Completa la actualización y las pruebas en un sandbox de SFCC antes de hacer cambios en el sitio de producción.
Comprende la integración actual
Es importante que estés familiarizado con tus integraciones actuales de SFCC y con los cambios o las personalizaciones que se hayan hecho específicamente para tu sitio web. Lo más importante es que consideres si los datos de eventos específicos que envías a Klaviyo se modificaron o ampliaron, y si agregaste algún evento personalizado.
Te recomendamos comparar el código que ensambla los datos del evento con la versión anterior del cartucho de Klaviyo, disponible en el GitHub de Klaviyo. Suponiendo que la integración no se haya personalizado demasiado, encontrarás las funciones actuales de ensamblaje de datos en int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js y, para Order Confirmation, en int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js.
Anota cualquier personalización para que puedas volver a aplicarla una vez que se haya instalado el nuevo cartucho.
Conectar un sandbox de SFCC a una cuenta de prueba de Klaviyo
Si todavía no has creado una cuenta secundaria de Klaviyo para hacer pruebas, separada de la cuenta vinculada a tu entorno de producción de SFCC, debes hacerlo. Luego, conecta tu entorno de sandbox de SFCC con la nueva cuenta, usando las claves de API pública y privada de esa cuenta en la configuración del cartridge de sandbox. Recomendamos completar este paso con la versión anterior del cartridge de Klaviyo para que puedas verificar que los eventos se envían y se reciben correctamente en tu cuenta secundaria de Klaviyo antes de continuar con la actualización de tu base de código con el nuevo cartridge de Klaviyo.
Eliminar el código del cartucho anterior de Klaviyo
Si tu integración no se personalizó mucho, podrás eliminar la mayor parte de la integración anterior de Klaviyo con solo borrar las dos carpetas del cartucho de Klaviyo: int_klaviyo_core y int_klaviyo (para Site Genesis) o int_klaviyo_sfra (para SFRA) del repositorio de código. Sin embargo, también tendrás que eliminar cualquier código específico de Klaviyo que se haya añadido a los archivos de plantilla y, posiblemente, a archivos JavaScript.
Para Site Genesis
Las integraciones Standard para Site Genesis tendrán el siguiente código agregado a footer_UI.isml:
<isinclude template="components/footer/klaviyoFooter"/>También se agregará el siguiente bloque a minicart.isml, cart.isml y cualquier otro archivo isml de "cart":
<isif condition="${pdict.CurrentHttpParameterMap.cartAction == 'add' || pdict.CurrentHttpParameterMap.cartAction
== 'update'}">
<isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyoAddToCart')}"/>
</isif>Para SFRA
A las integraciones Standard para SFRA se les agregará el siguiente código a pageFooter.isml:
<isinclude template="klaviyo/klaviyoFooter"/>También se agregará el siguiente código a la ruta AddProduct en el controlador Cart.js:
if(dw.system.Site.getCurrent().getCustomPreferenceValue('klaviyo_enabled')){
var KlaviyoUtils = require('*/cartridge/scripts/utils/klaviyo/klaviyoUtils');
KlaviyoUtils.trackAddToCart();
}Tanto para Site Genesis como para SFRA, después de que se hayan eliminado las carpetas de cartucho y los fragmentos de código mencionados anteriormente, se recomienda buscar en la base de código la palabra "Klaviyo". Asegúrate de entender qué hace cualquier código relacionado con Klaviyo que permanezca en la base de código antes de eliminarlo, ya que estos bloques pueden representar personalizaciones que tendrás que volver a implementar después de instalar el nuevo cartucho.
Eliminar servicios
Las integraciones anteriores habrán creado un KlaviyoTrackService, un KlaviyoTrackProfile y un KlaviyoTrackCredentials en Administration > Operations > Services. Los tres se pueden eliminar sin problema, ya que el proceso de integrar el nuevo cartucho de Klaviyo creará nuevos servicios con nombres diferentes.
No es crítico que se eliminen los servicios antiguos, pero se recomienda limpiarlos para evitar confusiones en el futuro.
Revisa las preferencias del sitio
El proceso de integrar el nuevo cartucho de Klaviyo conservará algunas de las preferencias anteriores del sitio de Klaviyo y también agregará algunas nuevas. Revisa las preferencias del sitio en el grupo de preferencias de Klaviyo en Merchant tools > Site Preferences > Custom Preferences > klaviyo y verifica si se agregaron preferencias personalizadas específicamente para tu sitio web. Si personalizaste el cartucho para agregar tus propios ajustes, te conviene conservarlos. Como referencia, estas son las cuatro preferencias del sitio que están integradas en la integración anterior de Klaviyo:
- Klaviyo habilitado (ID: klaviyo_enabled)
Marca si Klaviyo está activado o desactivado. - Cuenta de Klaviyo (ID: klaviyo_account)
Tu clave de API pública de Klaviyo o el ID del sitio. - Clave de API privada de Klaviyo (ID: klaviyo_api_key)
Una clave de API privada de Klaviyo. - Tipo de imagen para Klaviyo (ID: klaviyo_image_size)
Grande, pequeña, miniatura, etc.
Antes de configurar el nuevo cartucho, recomendamos respaldar tus preferencias actuales del sitio exportándolas en Administración > Desarrollo del sitio > Importación y exportación del sitio. Expande Sitios, luego Nombre del sitio, y marca la casilla Preferencias del sitio antes de ingresar un nombre de archivo para exportarlos. Tus preferencias actuales de Klaviyo no deberían verse afectadas negativamente cuando más adelante instales el nuevo cartucho, pero es una buena idea respaldarlas para consultarlas en el futuro.
Retira los cartuchos de Klaviyo de la ruta del cartucho
Elimina int_klaviyo_core y int_klaviyo (Site Genesis) o int_klaviyo_sfra (SFRA) de la ruta de cartuchos en Administración > Sitios > Administrar sitios > [Nombre del sitio] > Configuración. Si no realizas este paso, tendrás errores porque SFCC buscará cartuchos para cargar que ya no existen.
Revisa la consola del desarrollador y el registro del lado del servidor para ver si hay errores
En este punto, ya no deberías tener ningún código de Klaviyo en tu base de código. Recomendamos revisar el frontend, visitar páginas como Resultados de búsqueda, PLP y PDP, y realizar acciones como agregar productos al carrito, ingresar y completar el proceso de pago. Mientras lo haces, revisa la Consola del desarrollador para ver si se genera algún error nuevo. Haz lo mismo con el Registro de solicitudes. Si ves errores nuevos relacionados con Klaviyo, es muy probable que no hayas eliminado por completo todo el código anterior de Klaviyo. Es importante rastrear el origen de cualquier error nuevo y anotarlo antes de eliminarlo.
Instala el nuevo cartucho de Klaviyo
Sigue los pasos que se describen en Primeros pasos con Salesforce Commerce Cloud para integrar el nuevo cartucho en la base de código. Es posible que haya pasos que no necesites completar; por ejemplo, es posible que la instancia de SFCC ya tenga o no las conexiones establecidas para la parte de OCAPI, pero en general debes seguir cada paso de la integración. Definitivamente tendrás que reemplazar ambos cartuchos de Klaviyo y volver a agregar el fragmento de código.
No solo copies y pegues las nuevas carpetas del cartucho sobre las antiguas. Según las instrucciones anteriores, elimina por completo las carpetas antiguas antes de agregar las nuevas.
Importar metadata.zip agrega nuevas preferencias del sitio junto con las 4 enumeradas arriba. Revisa todas las preferencias del sitio de Klaviyo y confirma los valores existentes antes de continuar. Configura Selectores de Klaviyo Email y Selector de Klaviyo Email del checkout para los campos de correo electrónico del sitio, para que Klaviyo pueda identificar a los visitantes y hacer seguimiento de la actividad de checkout.
Como estás actualizando desde un cartucho anterior a la versión 23.7.0, las nuevas preferencias del sitio Label Events as SFCC y Send Added To Cart Event as "Add To Cart" deben configurarse como No y Sí, respectivamente. Esto seguirá enviando eventos sin la etiqueta de la métrica Salesforce Commerce Cloud y usará el tipo de evento Add To Cart (en lugar del nuevo Added to Cart). Tener estas dos preferencias del sitio configuradas incorrectamente ocasionará interrupciones en la elaboración de informes y, potencialmente, interrupciones en los flujos existentes en Klaviyo.
Verifica que todos los eventos listos para usar estén funcionando
Antes de intentar volver a agregar personalizaciones de la integración anterior, asegúrate de verificar que la nueva instalación del cartucho de Klaviyo funcione correctamente. Usa el frontend para generar eventos de búsqueda en el sitio, categoría vista, producto visto, agregado al carrito, inicio de checkout y confirmación del pedido, y luego revisa tu cuenta de Klaviyo para asegurarte de que estos eventos se estén rastreando correctamente.
Revisa la consola de desarrollador para ver si hay errores nuevos que puedan estar relacionados con las integraciones en todas las páginas que generan eventos de Klaviyo. Habilita el registro detallado del servicio marcando la casilla Communication Log Enabled en Administración > Operaciones > Servicios > KlaviyoEventService - Details y, luego, revisa los archivos de registro del lado del servidor para verificar que no haya errores y que los datos de eventos se estén generando correctamente para cada tipo de evento.
Comparar datos de eventos con producción
Ahora deberías comparar los datos de eventos en tus cuentas de Klaviyo de prueba y producción para asegurarte de que no falte nada y de que los valores actuales coincidan con el tipo esperado. Es importante determinar si la elaboración de informes o los flujo se verán afectados por la nueva integración. Verás que ahora se están configurando y enviando propiedades adicionales a Klaviyo en comparación con la versión anterior del cartucho.
Vuelve a agregar personalizaciones específicas del sitio
Ahora puedes empezar a volver a agregar personalizaciones en el código de Klaviyo. Debido a que hay cambios estructurales y de arquitectura importantes con el cartucho de Klaviyo más reciente, es poco probable que puedas simplemente copiar y pegar código personalizado directamente en el cartucho de Klaviyo.
Cada tipo de evento en el cartucho de Klaviyo tiene una función getData que se encuentra en un archivo de script separado, cuyo nombre corresponde a cada tipo de evento. Estos archivos se pueden encontrar en la carpeta int_klaviyo_core/cartridge/scripts/klaviyo/eventData y son el lugar más probable en el que harás cambios para agregar o actualizar los objetos de datos que se pasan para cada evento. Si estás creando nuevos eventos personalizados, recomendamos seguir el patrón establecido de agregar código a controladores del lado del servidor (esdecir, directamente en SiteGen o mediante server.append en SFRA) que llame a una función getData desde un archivo de script dedicado al nuevo evento y luego use la función trackEvent para enviar esos datos a Klaviyo mediante KlaviyoEventService.
Después de restaurar las personalizaciones, repite las comprobaciones de eventos y errores en el entorno de pruebas, incluidos los eventos personalizados y las propiedades personalizadas que usen los flujos. Una vez que finalicen las pruebas, implementa en producción la actualización probada con las claves de API y las preferencias del sitio de la cuenta de producción de Klaviyo, y luego verifica que los eventos lleguen a la cuenta de producción con los nombres y los datos esperados.
Resultado
Ahora actualizaste tu cartucho de Klaviyo para Salesforce Commerce Cloud.
Recursos adicionales
- Primeros pasos con Salesforce Commerce Cloud
Descubre cómo integrar Salesforce Commerce Cloud con Klaviyo. La integración del cartucho y la interfaz de programación de aplicaciones (API) de Klaviyo permite que los sitios web que usan Salesforce Commerce Cloud (anteriormente Demandware) se conecten rápidamente y envíen a Klaviyo datos tanto en tiempo real como históricos. Cuando integras Klaviyo con Salesforce Commerce Cloud (SFCC), Klaviyo comenzará a hacer seguimiento de las acciones que las personas realizan en tiempo real, como navegar por el sitio web, hacer seguimiento de búsquedas, ver productos, ver categorías, agregar artículos a un carrito, completar la compra y realizar pedidos.
- Referencia de datos de Salesforce Commerce Cloud
Descubre qué datos se sincronizan de Salesforce Commerce Cloud con Klaviyo después de habilitar las integraciones de Salesforce Commerce Cloud de Klaviyo y cómo puedes verlos.
- Referencia de la frecuencia de sincronización de integraciones
Descubre qué datos se sincronizan desde una integración específica de Klaviyo y con qué frecuencia se ejecuta la sincronización. Hemos organizado estas integraciones por plataformas de ecommerce, ESP y otras integraciones de datos.
- Cómo ponerse en contacto con el equipo de asistencia
Ofrecemos asistencia por correo electrónico y chat en vivo para los clientes de todos los planes de pago.