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 las interfaz de programación de aplicaciones (API) v1 y v2 de Klaviyo, que se retiraron y ya no funcionan como se esperaba. Siempre recomendamos actualizar a nuestra versión más reciente (actualmente, 25.7.0).

Antes de empezar

La versión 23.7.0 incluye varias mejoras significativas, algunas de las cuales son cambios de arquitectura en torno a cómo se activan los eventos. A continuación se detallan consideraciones especiales para actualizar de cualquier versión anterior a la 23.70 a cualquier versión posterior.

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.

Recomendamos comparar el código que ensambla los datos de eventos con la versión anterior del cartucho de Klaviyo, disponible en Github de Klaviyo. Suponiendo que la integración no se haya personalizado en gran medida, encontrarás las funciones actuales de ensamblaje de datos en int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js, y las de 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 creaste una cuenta secundaria de Klaviyo para pruebas, independiente de la cuenta que está vinculada a tu entorno de producción de SFCC, deberías hacerlo. Luego, conecta tu entorno de sandbox de SFCC a la nueva cuenta. Recomendamos completar este paso con la versión anterior del cartucho de Klaviyo para que puedas verificar que los eventos se envíen y se reciban correctamente en la cuenta secundaria de Klaviyo antes de continuar con la actualización de la base de código con el nuevo cartucho 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

Las integraciones Standard para SFCC tendrán el siguiente código agregado 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

La integración anterior habrá creado un KlaviyoTrackService, KlaviyoTrackProfile y KlaviyoTrackCredentials en Administración > Operaciones > Servicio. Los 3 se pueden eliminar de forma segura, ya que el proceso de integración del 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.

Ten en cuenta que, después de importar metadata.zip, tendrás cuatro preferencias nuevas del sitio, además de las cuatro que se crearon con la versión anterior del cartridge. Las preferencias anteriores no deberían haberse visto afectadas al importar las nuevas, pero se recomienda verificar que todas las preferencias del sitio de Klaviyo sean correctas antes de continuar.

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 en No y Yes, respectivamente. Esto seguirá enviando eventos sin la etiqueta de métrica Salesforce Commerce Cloud y usará el tipo de evento Add To Cart (en lugar del nuevo Added to Cart). Si estas dos preferencias del sitio se configuran incorrectamente, se interrumpirá la elaboración de informes y, posiblemente, también se interrumpirán 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.

Resultado

Ahora actualizaste tu cartucho de Klaviyo para Salesforce Commerce Cloud.

Recursos adicionales