Cómo actualizar tu cartucho de Salesforce Commerce Cloud

Objetivos del artículo

Aprende a actualizar tu cartucho Salesforce Commerce Cloud de Klaviyo. 

¿Está utilizando una versión de cartucho anterior a la 23.7.0? Recomendamos actualizar inmediatamente a la versión 23.7.0 o superior. Las versiones anteriores del cartucho utilizan las API v1 y v2 de Klaviyo, que han sido retiradas 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 una serie de mejoras significativas, algunas de las cuales son cambios arquitectónicos sobre cómo se activan los eventos. A continuación se detallan las consideraciones especiales para actualizar de cualquier versión inferior a la 23.70 a cualquier versión superior.

Comprende tus integraciones actuales

Es importante que estés familiarizado con tus integraciones SFCC actuales y con los cambios o personalizaciones que se hayan hecho específicamente para tu sitio web. Lo más importante es que tengas en cuenta si los datos específicos de los eventos que envías a Klaviyo han sido alterados o aumentados, y si has añadido algún evento personalizado.

Te recomendamos que compares tu código que ensambla datos de eventos con la versión anterior del cartucho Klaviyo, disponible en el Github de Klaviyo. Suponiendo que tus integraciones no hayan sido muy personalizadas, encontrarás tus funciones actuales de montaje de datos en int_klaviyo_core/cartridge/scripts/utils/Klaviyo/klaviyoUtils .js, y para la Confirmación de pedido en int_klaviyo_core/cartridge/scripts/utils/Klaviyo/emailUtils .js.

Anota cualquier personalización para que puedas volver a aplicarla una vez instalado el nuevo cartucho.

Conecta un sandbox SFCC a una cuenta de prueba Klaviyo

Si aún no has creado una cuenta secundaria de Klaviyo para pruebas, separada de la cuenta vinculada a tu entorno de producción SFCC, deberías hacerlo. A continuación, conecta tu entorno sandbox SFCC a la nueva cuenta. Te recomendamos que completes este paso utilizando tu versión anterior del cartucho Klaviyo para que puedas verificar que los eventos se envían y reciben correctamente en tu cuenta secundaria de Klaviyo antes de proceder a actualizar tu código base con el nuevo cartucho Klaviyo.

Elimina el código anterior del cartucho Klaviyo

Si tus integraciones no estaban muy personalizadas, podrás eliminar la mayoría de las integraciones anteriores de Klaviyo simplemente borrando de la base de código las dos carpetas de cartuchos de Klaviyo: int_klaviyo_core e int_klaviyo (para Site Genesis) o int_klaviyo_sfra (para SFRA). 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 los archivos JavaScript.

Para el Sitio Génesis

Standard integraciones para Site Genesis tendrá el siguiente código añadido a footer_UI.isml:

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

También se les añadirá el siguiente bloque a minicart.isml, carrito.isml, y cualquier otro archivo isml "carrito":

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

Para el SFRA

Standard integraciones para SFCC tendrá el siguiente código añadido a pageFooter.isml:

<isinclude template="klaviyo/klaviyoFooter"/>

También tendrán el siguiente código añadido 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, una vez eliminadas las carpetas de cartuchos y el fragmento de código antes mencionado, es aconsejable buscar en el código base la palabra "Klaviyo." Asegúrate de que estás familiarizado con lo que hace cualquier código relacionado con Klaviyoque permanezca en tu base de código antes de eliminarlo, ya que estos bloques pueden representar personalizaciones que tendrás que volver a poner en marcha después de instalar el nuevo cartucho.

Eliminar servicios

Las integraciones anteriores habrán creado un KlaviyoTrackService, un KlaviyoTrackProfile y unas KlaviyoTrackCredentials en Administración > Operaciones > Servicio. Los tres pueden eliminarse con seguridad, ya que el proceso de integración del nuevo cartucho de Klaviyo creará nuevos servicios con nombres diferentes.

No es fundamental que elimines los servicios antiguos, pero es recomendable que los limpies para evitar futuras confusiones.

Revisar las preferencias del sitio

El proceso de integración del nuevo cartucho Klaviyo conservará algunas de las preferencias del sitio Klaviyo anterior, y también añadirá algunas nuevas. Echa un vistazo a las preferencias de tu sitio en el Klaviyo grupo de preferencias en Herramientas del comerciante > Preferencias del sitio > Preferencias personalizadas > Klaviyo , y comprueba si se ha añadido alguna preferencia personalizada específicamente para tu sitio web. Si personalizaste el cartucho para añadir tus propios ajustes, querrás conservarlos. Como referencia, aquí tienes las cuatro preferencias de sitio que están incorporadas en las integraciones anteriores de Klaviyo:

• Klaviyo Activado (ID: klaviyo_enabled)
  Marca si Klaviyo está activado o desactivado.
• Klaviyo cuenta (ID: klaviyo_account)
  Tu Klaviyo clave pública de API, o ID del sitio.
• Klaviyo Clave privada de API (ID: klaviyo_api_key)
  A Klaviyo clave privada de API.
• Tipo de imagen para Klaviyo (ID: klaviyo_image_size)
  Grande, pequeña, miniatura, etc.

Antes de configurar el nuevo cartucho, te recomendamos que hagas una copia de seguridad de las preferencias de tu sitio actual exportándolas en Administración > Desarrollo del sitio > Importar sitio & Exportar. Expande Sitios, luego el Nombre de tu Sitio, y marca la casilla Preferencias del Sitio antes de introducir un nombre de archivo al que exportarlos. Tus preferencias actuales de Klaviyo no deberían verse afectadas cuando instales el nuevo cartucho, pero es buena idea volver a guardarlas para futuras consultas.

Retira los cartuchos Klaviyo del recorrido de los cartuchos

Elimina int_klaviyo_core e int_klaviyo (Site Genesis) o int_klaviyo_sfra (SFRA) de la ruta de tu cartucho en Administración > Sitios > Gestionar sitios > [Nombre del sitio] > Configuración. Si no realizas este paso, se producirán errores debidos a que SFCC está buscando cartuchos para cargar que ya no existen.

Comprueba si hay errores en la consola del desarrollador y en el registro del lado del servidor

Llegados a este punto, ya no deberías tener ningún código Klaviyo en tu base de código. Te recomendamos que revises tu frontend, visitando páginas como Resultados de búsqueda, PLPs y PDPs, y realizando acciones como añadir productos al carrito, entrar y completar la página de pago. Mientras lo haces, echa un vistazo a la Consola de Desarrollador para ver si se genera algún error nuevo. Haz lo mismo con el Registro de peticiones. Si estás viendo nuevos errores relacionados con Klaviyo, es muy probable que no hayas eliminado completamente todo el código anterior de Klaviyo. Es importante localizar el origen de los nuevos errores y anotarlos antes de eliminarlos.

Instala el nuevo cartucho Klaviyo

Sigue los pasos establecidos en primeros pasos con Salesforce Commerce Cloud para integrar el nuevo cartucho en tu código base. Puede que haya pasos que no necesites completar -por ejemplo, tu instancia SFCC puede tener o no las conexiones ya establecidas para la parte OCAPI-, pero en general, debes seguir cada paso de integraciones. Tendrás que sustituir definitivamente los dos cartuchos Klaviyo y volver a añadir fragmento de código. 

Ten en cuenta que después de importar metadatos.zip, tendrás cuatro nuevas preferencias de sitio, además de las cuatro que creaba la versión anterior del cartucho. Tus preferencias anteriores no deberían verse afectadas por la importación de las nuevas, pero se recomienda que vuelvas a comprobar que todas las preferencias del sitio Klaviyo son correctas antes de continuar.

Puesto que estás actualizando desde un cartucho anterior a la versión 23.7.0, las nuevas preferencias del sitio Etiquetar eventos como SFCC y Enviar evento añadido al carro como "Añadir al carro" deben establecerse en No y Sí, respectivamente. Esto seguirá enviando eventos sin la etiqueta métrica de Salesforce Commerce Cloud y utilizará el tipo de evento Añadir al carro(en lugar del nuevo Añadido al carro). Si estas dos preferencias de sitio están configuradas incorrectamente, se romperá la creación/elaboración de informes y, potencialmente, se romperá el flujo existente en Klaviyo.

Comprueba que todos los eventos "out-of-the-box" funcionan

Antes de intentar volver a añadir cualquier personalización de tus integraciones anteriores, asegúrate de verificar que la nueva instalación del cartucho Klaviyo funciona correctamente. Utiliza el frontend para generar eventos para Sitio buscado, Categoría vista, Producto visto, Añadido al carro, Página de pago iniciada y Confirmación de pedido, y luego comprueba tu Klaviyo cuenta para asegurarte de que estos eventos se están rastreando correctamente. 

Comprueba en la consola del desarrollador si hay nuevos errores relacionados con las integraciones en todas las páginas que generan eventos Klaviyo. Activa el registro detallado del servicio marcando la casilla Registro de comunicaciones activado en Administración > Operaciones > Servicios > KlaviyoEventService - Detalles y, a continuación, revisa los archivos de registro del lado del servidor para comprobar que no hay errores y que los datos de los eventos se están generando correctamente para cada tipo de evento.

Compara los datos del evento con la producción

Ahora debes comparar los datos de eventos en tu Klaviyo cuenta de pruebas y de producción para asegurarte de que no falta nada y de que los valores actuales coinciden con el tipo esperado. Es importante determinar si cualquier creación/elaboración de informes o flujo se verá afectado por las nuevas integraciones. Verás que ahora se establecen y envían a Klaviyo propiedades adicionales en comparación con la versión anterior del cartucho. 

Añade personalizaciones específicas para volver al sitio

Ahora puedes empezar a añadir personalizaciones de nuevo en tu código Klaviyo. Debido a que hay grandes cambios estructurales y arquitectónicos con el nuevo cartucho Klaviyo, es poco probable que puedas simplemente copiar y pegar código personalizado directamente en el cartucho Klaviyo.

Cada tipo de evento en el cartucho Klaviyo tiene una función getData que vive en un archivo de secuencia de comandos separado con el nombre de cada tipo de evento. Estos archivos se encuentran en la carpeta int_klaviyo_core/cartridge/scripts/Klaviyo /eventData, y son el lugar más probable que modifiques para añadir o actualizar los objetos de datos que se pasan para cada evento. Si vas a crear nuevos eventos personalizados, te recomendamos que sigas el patrón establecido de añadir código a los controladores del lado del servidor (es decir, 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 utilice la función trackEvent para enviar esos datos a Klaviyo a través del KlaviyoEventService.

Resultado

Ya has actualizado tu cartucho Klaviyo para Salesforce Commerce Cloud. 

Recursos adicionales 

• primeros pasos con Salesforce Commerce Cloud
• Referencia de datos de Salesforce Commerce Cloud
• Con qué frecuencia se sincronizan las integraciones de referencia
• Cómo ponerse en contacto con el equipo de asistencia