Cómo actualizar tu cartucho de Salesforce Commerce Cloud

Qué aprenderás

Descubre cómo actualizar tu cartucho de Klaviyo para Salesforce Commerce Cloud.

¿Estás usando una versión del cartucho anterior a la 23.7.0? Te recomendamos que lo actualices inmediatamente a la versión 23.7.0 o una posterior. Las versiones anteriores del cartucho usan las API v1 y v2 de Klaviyo, que ya no están disponibles ni funcionan como se espera. 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 relacionados con cómo se activan los eventos. A continuación se detallan consideraciones especiales para la actualización desde cualquier versión anterior a la 23.70 a cualquier versión posterior a ella.

Comprende tus integraciones actuales

Es importante que estés familiarizado con tus integraciones actuales de SFCC y con los cambios o las personalizaciones que se hayan realizado específicamente para tu sitio web. Lo más importante es que deberías considerar si los datos de eventos específicos que envías a Klaviyo se han modificado o ampliado, y si has añadido algún evento personalizado.

Te recomendamos comparar tu código que ensambla los datos del evento con la versión anterior del cartucho de Klaviyo, disponible en Github de Klaviyo. Si suponemos que tus integraciones no se han personalizado demasiado, encontrarás tus funciones actuales de ensamblaje de datos en int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js, y para Confirmación de pedido en int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js.

Anota las personalizaciones para que puedas volver a aplicarlas 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, deberías hacerlo. Luego, conecta tu entorno de sandbox de SFCC a la nueva cuenta. Te recomendamos completar este paso con tu versión anterior del cartucho de Klaviyo para que puedas comprobar que los eventos se envían correctamente y se reciben en tu cuenta secundaria de Klaviyo antes de proceder a actualizar tu 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ó en gran medida, podrás eliminar la mayoría de la integración anterior de Klaviyo simplemente borrando las dos carpetas de cartuchos de Klaviyo: int_klaviyo_core y int_klaviyo (para Site Genesis) o int_klaviyo_sfra (para SFRA) de la base de código. Sin embargo, también tendrás que eliminar cualquier código específico de Klaviyo que pueda haberse añadido a archivos de plantilla y, posiblemente, a archivos JavaScript.

Para Site Genesis

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

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

También se añadirá el siguiente bloque a minicart.isml, cart.isml y cualquier otro archivo isml de «carrito»:

<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 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, después de que se hayan eliminado las carpetas de los cartuchos y los fragmentos de código mencionados anteriormente, es aconsejable buscar en el código base la palabra «Klaviyo». Asegúrate de saber qué hace cualquier código relacionado con Klaviyo que permanezca en tu código base antes de eliminarlo, ya que estos bloques pueden representar personalizaciones que tendrás que volver a aplicar 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 tres se pueden eliminar de forma segura, ya que el proceso de integrar el nuevo cartucho de Klaviyo creará nuevos servicios con nombres diferentes.

No es fundamental que se eliminen los servicios antiguos, pero se recomienda limpiarlos para evitar confusiones en el futuro.

Revisar las preferencias del sitio

El proceso de integración del nuevo cartucho de Klaviyo conservará algunas de las preferencias anteriores del sitio de Klaviyo y también añadirá algunas nuevas. Echa un vistazo a tus preferencias del sitio en el grupo de preferencias Klaviyo, en Herramientas para comerciantes > Preferencias del sitio > Preferencias personalizadas > Klaviyo, y comprueba si se han añadido preferencias personalizadas específicas para tu sitio web. Si personalizaste el cartucho para añadir tus propios ajustes, te interesará conservarlos. Como referencia, estas son las cuatro preferencias del sitio que están integradas en las integraciones anteriores 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 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 hacer una copia de seguridad de tus preferencias actuales del sitio exportándolas en Administración > Desarrollo del sitio > Importar y exportar sitio. Expande Sitios, luego Nombre del sitio, y marca la casilla Preferencias del sitio antes de introducir un nombre de archivo para exportarlas a él. Tus preferencias actuales de Klaviyo no deberían verse afectadas negativamente cuando instales el nuevo cartucho más adelante, pero es buena idea hacer una copia de seguridad para consultarla en el futuro.

Elimina los cartuchos de Klaviyo de la ruta de cartuchos.

Elimina int_klaviyo_core y también int_klaviyo (Site Genesis) o int_klaviyo_sfra (SFRA) de la ruta de cartuchos en Administración > Sitios > Administrar sitios > [Nombre del sitio] > Ajustes. Si no realizas este paso, obtendrás errores debido a que SFCC busca cartuchos para cargar que ya no existen.

Comprueba 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 tu frontend, visitar páginas como Resultados de búsqueda, PLP y PDP, y realizar acciones como añadir productos al carrito, iniciar y completar el proceso de compra. Mientras lo haces, revisa la Consola para desarrolladores para ver si se generan errores nuevos. 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 localizar el origen de cualquier error nuevo y anotarlo antes de eliminarlo.

Instala el nuevo paquete de Klaviyo

Sigue los pasos que se describen en Primeros pasos con Salesforce Commerce Cloud para integrar el nuevo cartucho en tu base de código. Puede haber pasos que no necesites completar (por ejemplo, tu instancia de SFCC puede tener o no las conexiones ya establecidas para la parte de OCAPI), pero, en general, debes seguir cada paso de las integraciones. Sin duda, tendrás que sustituir ambos cartuchos de Klaviyo y volver a añadir fragmentos de código.

Ten en cuenta que, después de importar metadata.zip, tendrás cuatro nuevas preferencias del sitio, además de las cuatro que creó la versión anterior del cartucho. Es probable que tus preferencias anteriores no se hayan visto afectadas por la importación de las nuevas, pero se recomienda que verifiques que todas las preferencias del sitio de Klaviyo son 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 de 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 están configuradas incorrectamente, se interrumpirá la elaboración de informes y, potencialmente, se interrumpirán los flujos existentes en Klaviyo.

Verifica que todos los eventos predeterminados estén funcionando

Antes de intentar volver a añadir cualquiera de las personalizaciones de tus integraciones anteriores, asegúrate de verificar que la nueva instalación del cartucho de Klaviyo funciona correctamente. Usa el frontend para generar eventos de Búsqueda en el sitio, Categoría vista, Producto visto, Añadido al carrito, Pago iniciado y Confirmación del pedido, y luego revisa tu cuenta de Klaviyo para asegurarte de que estos eventos se estén rastreando correctamente.

Comprueba la consola de desarrollador para ver si hay nuevos errores que puedan estar relacionados con las integraciones en todas las páginas que generen eventos de Klaviyo. Habilita el registro detallado del servicio marcando la casilla Communication Log Enabled en Administration > Operations > Services > KlaviyoEventService - Details y, a continuación, revisa los archivos de registro 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 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 la elaboración de informes o los flujos se verán afectados por la nueva integración. Verás que ahora se están configurando y enviando a Klaviyo propiedades adicionales en comparación con la versión anterior del cartucho.

Añadir personalizaciones específicas del sitio

Ahora puedes empezar a volver a añadir personalizaciones a tu código de Klaviyo. Debido a que hay importantes cambios estructurales y arquitectónicos en 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 del cartucho de Klaviyo tiene una función getData que se encuentra en un archivo de script independiente, que lleva el nombre de 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 añadir o actualizar los objetos de datos que se pasan para cada evento. Si vas a crear nuevos eventos personalizados, te recomendamos seguir el patrón establecido de añadir código a 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, a continuación, use la función trackEvent para enviar esos datos a Klaviyo mediante KlaviyoEventService.

Resultado

Ya has actualizado tu cartucho de Klaviyo para Salesforce Commerce Cloud.

Recursos adicionales