Cómo actualizar su cartucho de Salesforce Commerce Cloud

Qué aprenderás

Aprenda a actualizar su cartucho de Salesforce Commerce Cloud de Klaviyo. 

¿Está utilizando una versión del 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 se han retirado y ya no funcionan como se esperaba. Siempre recomendamos actualizar a nuestra versión más reciente (actualmente, 24.1.0).

Antes de empezar

La versión 23.7.0 (publicada el 13 de julio de 2023) incluye una serie de mejoras significativas, algunas de las cuales son cambios arquitectónicos en torno a la forma en que 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.

Comprenda su integración actual

Es importante que esté familiarizado con su integración SFCC actual y con los cambios o personalizaciones que se hayan podido realizar específicamente para su sitio web. Lo más importante es que tenga en cuenta si los datos específicos de los eventos que envía a Klaviyo han sido alterados o aumentados, y si ha añadido algún evento personalizado.

Le recomendamos que compare su código que ensambla datos de eventos con la versión anterior del cartucho de Klaviyo, disponible en el Github de Klaviyo. Suponiendo que su integración no haya sido muy personalizada, encontrará sus funciones actuales de ensamblaje de datos en int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js, y para la Confirmación de pedidos en int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js.

Anote cualquier personalización para poder volver a aplicarla una vez instalado el nuevo cartucho.

Conectar un sandbox SFCC a una cuenta de prueba Klaviyo

Si aún no ha creado una cuenta secundaria de Klaviyo para pruebas, separada de la cuenta vinculada a su entorno de producción SFCC, debería hacerlo. A continuación, conecte su entorno sandbox SFCC a la nueva cuenta. Le recomendamos completar este paso utilizando su versión anterior del cartucho Klaviyo para que pueda verificar que los eventos están siendo enviados y recibidos con éxito por su cuenta secundaria Klaviyo antes de proceder a actualizar su base de código con el nuevo cartucho Klaviyo.

Eliminar el código anterior del cartucho Klaviyo

Si su integración no estaba muy personalizada, podrá eliminar la mayor parte de la integración anterior de Klaviyo simplemente borrando las dos carpetas de cartuchos de Klaviyo: int_klaviyo_core e int_klaviyo (para Site Genesis) o int_klaviyo_sfra (para SFRA) de la base de código. Sin embargo, también tendrá que eliminar cualquier código específico de Klaviyo que pueda haber sido añadido a los archivos de plantilla, y posiblemente a los archivos JavaScript.

Para Site Genesis

Las integraciones estándar para Site Genesis tendrán 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, cart.isml, y cualquier otro archivo "cart" isml:

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

Para el SFRA

Las integraciones estándar 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, una vez eliminadas las carpetas de cartuchos y los fragmentos de código mencionados, es aconsejable buscar en el código base la palabra "Klaviyo". Asegúrese de que está familiarizado con lo que hace cualquier código relacionado con Klaviyo que permanezca en su base de código antes de eliminarlo, ya que estos bloques pueden representar personalizaciones que necesitará volver a poner en su lugar una vez instalado el nuevo cartucho.

Eliminar servicios

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

No es fundamental que elimine los servicios antiguos, pero es recomendable que los limpie 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. Eche un vistazo a las preferencias de su sitio en el grupo de preferencias de Klaviyo en Herramientas del comerciante > Preferencias del sitio > Preferencias personalizadas > klaviyo, y compruebe si se ha añadido alguna preferencia personalizada específicamente para su sitio web. Si personalizó el cartucho para añadir sus propios ajustes, querrá conservarlos. Como referencia, aquí están las cuatro preferencias del sitio que se construyen en la integración anterior Klaviyo:

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

Antes de configurar el nuevo cartucho, le recomendamos que haga una copia de seguridad de las preferencias de su sitio actual exportándolas en Administración > Desarrollo del sitio > Importación del sitio & Exportación. Expanda Sitios, luego el nombre de su sitio y marque la casilla Preferencias del sitio antes de introducir un nombre de archivo al que exportarlos. Sus preferencias actuales de Klaviyo no deberían verse afectadas negativamente cuando instale posteriormente el nuevo cartucho, pero es una buena idea hacer una copia de seguridad de las mismas para futuras referencias.

Retire los cartuchos Klaviyo del recorrido de los cartuchos

Elimine int_klaviyo_core e int_klaviyo (Site Genesis) o int_klaviyo_sfra (SFRA) de la ruta de su cartucho en Administración > Sitios > Gestionar sitios > [Nombre del sitio] > Configuración. Si no realiza este paso, obtendrá errores derivados de que SFCC busca cartuchos para cargar que ya no existen.

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

En este punto, ya no debería tener ningún código Klaviyo en su base de código. Recomendamos revisar su frontend, visitando páginas como Resultados de búsqueda, PLPs y PDPs, y realizando acciones como añadir productos al carrito, entrar y completar el pago. Mientras lo hace, no pierda de vista la consola de desarrollador para ver si se genera algún error nuevo. Haga lo mismo con el registro de solicitudes. Si está viendo nuevos errores relacionados con Klaviyo, es muy probable que no haya eliminado completamente todo el código anterior de Klaviyo. Es importante rastrear el origen de cualquier nuevo error y anotarlo antes de eliminarlo.

Instale el nuevo cartucho Klaviyo

Siga los pasos establecidos en Introducción a Salesforce Commerce Cloud para integrar el nuevo cartucho en su base de código. Puede que haya pasos que no necesite completar -por ejemplo, su instancia SFCC puede o no tener las conexiones ya establecidas para la parte OCAPI- pero, en general, debe seguir cada paso de la integración. Definitivamente tendrá que sustituir ambos cartuchos Klaviyo y volver a añadir fragmentos de código. 

Tenga en cuenta que después de importar metadatos.zip, dispondrá de cuatro nuevas preferencias de sitio, además de las cuatro creadas por la versión anterior del cartucho. Sus preferencias anteriores no deberían haberse visto afectadas por la importación de las nuevas, pero se recomienda que vuelva a comprobar que todas las preferencias del sitio Klaviyo son correctas antes de continuar.

Dado que está 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 a la cesta como 'Añadir a la cesta' deben establecerse en No y Sí, respectivamente. Esto continuará enviando eventos sin la etiqueta métrica de Salesforce Commerce Cloud y utilizará el tipo de evento Añadir al carro (en oposición al nuevo Añadido al carro). Tener estas dos preferencias de sitio configuradas incorrectamente resultará en una ruptura de los informes y potencialmente, una ruptura de los flujos existentes en Klaviyo.

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

Antes de intentar añadir de nuevo cualquier personalización de su integración anterior, asegúrese de verificar que la nueva instalación del cartucho Klaviyo funciona correctamente. Utilice el frontend para generar eventos para Sitio buscado, Categoría vista, Producto visto, Añadido al carro, Pedido iniciado y Confirmación de pedido y, a continuación, compruebe su cuenta de Klaviyo para asegurarse de que estos eventos se están rastreando correctamente. 

Compruebe en la consola del desarrollador cualquier nuevo error que pueda estar relacionado con la integración en todas las páginas que generan eventos Klaviyo. Active el registro detallado del servicio marcando la casilla Registro de comunicaciones activado en Administración > Operaciones > Servicios > KlaviyoEventService - Detalles y, a continuación, revise los archivos de registro 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.

Comparar los datos de los eventos con la producción

Ahora debería comparar los datos de los eventos en sus cuentas de Klaviyo de prueba y de producción para asegurarse de que no falta nada y de que los valores actuales coinciden con el tipo esperado. Es importante determinar si algún informe o flujo se verá afectado por la nueva integración. Comprobará que ahora se establecen y envían propiedades adicionales a Klaviyo en comparación con la versión anterior del cartucho. 

Volver a añadir personalizaciones específicas del sitio

Ahora puede empezar a añadir personalizaciones en su código Klaviyo. Debido al hecho de que hay fuertes cambios estructurales y arquitectónicos con el cartucho Klaviyo más reciente, es poco probable que usted será capaz de 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 script separado llamado para 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 altere para añadir o actualizar los objetos de datos que se pasan para cada evento. Si está creando nuevos eventos personalizados, le recomendamos que siga el patrón establecido de añadir código a los controladores del lado del servidor (es decir, directamente en SiteGen o a través de server.append en SFRA) que llame a una función getData desde un archivo de script dedicado al nuevo evento y, a continuación, utilice la función trackEvent para enviar esos datos a Klaviyo a través del KlaviyoEventService.

Resultado

Ya ha actualizado su cartucho Klaviyo para Salesforce Commerce Cloud. 

Recursos adicionales 

• Introducción a 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 servicio de asistencia