Cómo configurar Klaviyo Customer Hub con Headless Shopify

Objetivos del artículo

Conectarás Klaviyo Customer Hub a un escaparate headless Shopify, elegirás un método de inicio de sesión y publicarás el Hub para que los compradores puedan acceder a él en todo el sitio.

Antes de empezar

Requisitos previos 

1. Un escaparate headless Shopify con acceso al Storefront interfaz de programación de aplicaciones (API) (Token de acceso público / Clave pública del Storefront interfaz de programación de aplicaciones (API) en Shopify's Headless Administrador).
2. Tu ID de empresa Klaviyo (empleado por el cargador JavaScript in situ).
3. Decisión sobre el inicio de sesión del comprador: Shopify Cliente cuenta interfaz de programación de aplicaciones (API) o Klaviyo One Time Password (OTP).
   1. Si empleas una cuenta existente, ten preparadas las rutas de inicio de sesión, cierre de sesión y (opcional) Gestionar cuenta y Gestionar direcciones de tu tienda.
4. Posibilidad de editar el código de tu tienda y desplegar los cambios.
5. Quién puede configurarlo: Necesitas un rol de cuenta que pueda editar la configuración de Klaviyo Customer Hub y publicar widget (Propietario, Administrador, o un rol personalizado que tenga acceso de escritura a Contenido y clave de API). 

Resumen

Klaviyo Customer Hub es una superposición en todo el sitio que ofrece a los compradores un acceso más rápido a las acciones de cuenta y a útiles herramientas de compra. Para headless Shopify, conectas Klaviyo's onsite script, eliges un método de inicio de sesión (Cliente cuenta interfaz de programación de aplicaciones (API) o Klaviyo OTP), y opcionalmente agregas:

1. con actividad Producto: muestra el producto que un comprador está viendo dentro del Hub.
2. Vistos recientemente: lista de productos vistos recientemente empleando el seguimiento de Klaviyo.
3. Widget de Favoritos y Preguntas Frecuentes: renderizado en las PDP y dentro del Hub.  

Emplea Klaviyo Customer Hub cuando quieras una capa de asistencia en la página que impulse el descubrimiento de productos y una compra más rápida, mejorando la conversión y el valor de vida.

Configurar

1 - Configurar los ajustes de Klaviyo Customer Hub

Primero, sigue los primeros pasos con Klaviyo Customer Hub y completa el asistente de incorporación, como con cualquier otra configuración. Una vez completado esto, ve a Klaviyo Customer Hub > Configuración. Verás la sección de configuración de Headless Shopify. 

Activa la configuración de Headless Shopify y luego pega tu clave pública de interfaz de programación de aplicaciones (API) de Storefront desde el Headless Administrador de Shopify (Token de acceso público). 

En Inicio de sesión del comprador, selecciona Cliente de Shopify cuenta interfaz de programación de aplicaciones (API) (recomendado para que todas tus aplicaciones de tienda puedan compartir el inicio de sesión de Shopify) o Klaviyo Contraseña de un solo uso (OTP, sólo funciona con Klaviyo y no iniciará sesión de los compradores en ninguna otra aplicación). 

Si seleccionas Shopify Cuenta de cliente interfaz de programación de aplicaciones (API), introduce también el inicio de sesión de tu tienda, el cierre de sesión y las rutas opcionales Gestionar cuenta/Gestionardirecciones (empleadas para las redirecciones entre Hub y tu sitio). 

Publicar visibilidad: pon el Centro de Clientes Klaviyo en Directo. 

2 - Carga el JavaScript de Klaviyo Customer Hub (Instrucciones para desarrolladores)

Consejo: Si ya empleas las funciones in situ de Klaviyo, es posible que tengas un cargador instalado. Confírmalo antes de agregar un segundo guión. 

Crea /public/customerHub.js (o equivalente) con el siguiente cargador (sustituye COMPANY_ID por tu clave de API pública de Klaviyo, también conocida como ID de tu compañía):

// customerHub.js
// TODO: Configuración
const COMPANY_ID = '';
const script = document.createElement('script');
script.src = `https://static.Klaviyo.com/onsite/js/${COMPANY_ID}/Klaviyo.js`;
script.async = true;
script.onload = () => { console.log('Klaviyo JS script loaded successfully'); };
script.onerror = () => { console.error('Failed to load Klaviyo JS script'); };
document.body.appendChild(script);

El script in situ se carga en cada página. Busca el mensaje de consola "El script JS de Klaviyo se cargó correctamente".  En tu diseño raíz (por ejemplo, raíz.tsx), incluye el cargador:

// root.tsx
return (
  <html>
    <body>
      < script src="/customerHub.js" defer></script>
    </body>
  </html>
)

Luego de este paso, window.customerHubApi está disponible en las páginas en las que se ejecuta el Hub. 

3 - Mostrar el producto con actividad en Klaviyo Customer Hub

Agrega la llamada a hidrato en tu página de detalles del producto (PDP ) para que el producto actual aparezca en el Hub:

<!-- products.tsx -->
< script type="text/javascript"> 
 (function() {
 function waitForCustomerHubApi() {
 return new Promise((resolve) => {
 const check = () => {
 if (window.customerHubApi && window.clienteHubApi.hidratarProducto) {
            resolve();
          } else {
            requestAnimationFrame(check);
          }
        };
 check();
 });
 }
 waitForCustomerHubApi().then(() => {
      window.customerHubApi.hydrateProduct("your-product-handle");
    });
 })();
</script>

Hubdebería mostrar ahora una ficha de producto adicional para el PDP que el comprador está viendo en la pestaña "Chat" si la tienes activada. 

4 - Habilitar los productos vistos recientemente en Klaviyo Customer Hub

Implementa el seguimiento de Productos vistos para que el Hub pueda rellenar Artículos vistos recientemente y puedas emplear la métrica en otras partes de Klaviyo. Los siguientes fragmentos de seguimiento también se pueden agregar directamente a tu escaparate, las instrucciones se encuentran aquí, en nuestra documentación para desarrolladores Klaviyo: Integrar una plataforma ecommerce sin un prediseñado Klaviyo integraciones.

5 - Habilitar la toma de enlaces de cuenta

Para que Klaviyo's Klaviyo Customer Hub se abra al hacer clic en el icono de cuenta de la cabecera de tu tienda, necesitas tener ya una a-etiqueta que haga referencia a un enlace con /cuenta (en cuyo caso la sustituiremos automáticamente por ti). O también puedes definir manualmente el enlace del icono para que apunte a #k-hub con el fin de abrir el cajón.

6 - Configura Klaviyo Customer Hub con autenticación de cuenta de cliente interfaz de programación de aplicaciones (API) (recomendado)

Para emplear la cuenta de cliente y la configuración de autenticación existentes en tu tienda, Klaviyo Customer Hub te pedirá que añadas una nueva ruta de interfaz de programación de aplicaciones (API) a tu tienda que se encargará de pasar de forma segura el token de acceso del comprador a nuestros servicios. Lo importante es que la nueva ruta interfaz de programación de aplicaciones (API) se denomine y pueda alcanzar con '/interfaz de programación de aplicaciones (API)/authenticateCustomerHub'.

Nota: el siguiente ejemplo de fragmento de código es para el marco Hydrogen de Shopify, los escaparates más personalizados pueden requerir alguna solución adicional, sin embargo, aquí se describirá el enfoque general.

// ./app/rutas/interfaz de programación de aplicaciones (API).authenticateCustomerHub.js
// TODO: Configuración
const COMPANY_ID = '';
export async function action({context}) {
 // Extrae el Cliente de cuenta de cliente interfaz de programación de aplicaciones (API) del contexto de tu tienda
 const {customerAccount} = context;
 try {
 // Obtén el token de acceso del cliente actual
 const accessToken = await customerAccount.getAccessToken();
    if (!accessToken) {
 return new Response(JSON.stringify({message: 'User not logged in'}), {
        status: 200,
      });
 }
   // Envía el token de acceso a la interfaz de programación de aplicaciones (API) de Klaviyo Customer Hub
 const response = await fetch(
 'https://atlas-app.services.klaviyo.com/api/onsite/headless-shopify-login',
      {
 método: 'POST',
 cabeceras: {
          'Content-Type': 'application/json',
        },
 body: JSON.stringify({
          access_token: accessToken,
          company_id: COMPANY_ID,
        }),
 },
 );
 const responseData = await response.text();
    // Devuelve la respuesta real de Klaviyo Customer Hub con el mismo código de estado
 return new Response(responseData, {
 status: response.status,
      cabeceras: {
        'Content-Type':
          response.headers.get('content-type') || 'application/json',
      },
 });
 } catch (error) {
 return new Response(null, {status: 500});
 }
}

Una vez configurado esto, así como las rutas del escaparate definidas en la configuración de Klaviyo, Klaviyo Customer Hub podrá enlazar con tu configuración de autenticación existente y proporcionar un punto de entrada sin fisuras a tu cuenta de cliente existente.

7 - Agrega el widget Favoritos (recomendado)

Tanto los Favoritos como las Preguntas Frecuentes funcionarán dentro del cajón de Klaviyo Customer Hub. Sin embargo, puedes agregar estos widget también en las PDP para una interacción adicional.

Para agregar un punto de entrada de Favoritos en las PDP y dentro del Hub:

// products.tsx
// Identificadores de ejemplo:
// id: gid://Shopify/Product/12345
// data-product-id: 12345
const gid = "gid://Shopify/Producto/12345";
const productId = gid.división('/').pop();

return (
 < div
 className="kl-hub-favorites-slot"
 data-product-id={productId}
  />
 )

Ahora los compradores pueden hacer clic en Agregar a favoritos en las PDP; el artículo aparece en los Favoritos de Hub. 

8 - Agrega bloques de preguntas frecuentes (recomendado)

De forma similar a agregar Favoritos, agregar bloques de FAQ es tan sencillo como agregar un div en tu página de producto con su ID de producto pasado para generar FAQ que puedes editar y diseñar en Klaviyo.

Agrega un bloque de preguntas frecuentes específicas de producto que diseñes en Klaviyo:

// products.tsx
// Ejemplo:
const gid = "gid://Shopify/Product/12345";
const productId = gid.división('/').pop();

return (
 < div className="klaviyo-faqs-slot" data-product-id={productId} />
 )

Las fichas/botones de FAQ ahora deberían aparecer en los PDP si están configurados y son editables en Klaviyo

Mejores prácticas

1. Publica en producción sólo luego de la verificación: mantén oculto el staging hasta que se completó el QA; entonces ponlo en Directo para exponer el Hub. Impacto: menos problemas de asistencia, tiempo de obtención de valor más rápido.
2. Hidrata siempre el Producto con actividad en las PDP - mantiene visible el contexto del producto en el Hub y anima a agregar al carrito. Impacto: tasa de conversión, tasa de compras repetidas.
3. Implementa el seguimiento temprano de Productos v istos - rellena Vistos recientemente y desbloquea el flujo basado en la navegación. Impacto: interacción e ingresos por recuperación de navegación.
4. Agregar Favoritos - crea una acción de almacenar de baja fricción y una lista de favoritos persistente. Impacto: visitas repetidas, agregar al carrito.
5. Emplea preguntas frecuentes para las objeciones: responde a las preguntas sobre envíos, materiales o devoluciones en línea para reducir el abandono. Impacto: tasa de conversión.
6. Prefiere la autenticación en el servidor con la cuenta de cliente interfaz de programación de aplicaciones (API) cuando esté disponible - mejora la continuidad para los compradores registrados. Impacto: calidad de la experiencia, desviación del equipo de asistencia.  

Medir el éxito

Dónde ver los resultados: Emplea Analytics > métrica para monitorizar la actividad de los productos vistos y el rendimiento de los flujos/campañas. Emplea tu panel ecommerce ingresos para realizar un seguimiento de los cambios en la conversión y el valor medio del pedido (AOV) tras activar Klaviyo Customer Hub. Métrica clave a vigilar: tasa de conversión desde PDP, tasa de agregar al carrito, sesiones con aperturas de Hub (si están instrumentadas), ingresos por destinatario (tasa de compras repetidas), e ingresos impulsados por la navegación vinculados a eventos de Productos vistos. Lista de soluciones rápidas: Baja ¿Actividad vista recientemente? Comprueba que el fragmento de seguimiento de Producto Visto se dispara y que los eventos se atribuyen al perfil. ¿Poca adición al carrito desde Hub? Cerciórate con actividad La hidratación del producto se ejecuta en cada PDP y que la variante/los precios son correctos. ¿Pocos añadidos favoritos? Mueve la ranura de Favoritos cerca de los CTA de la PDP central y confirma que el id-producto-datos coincide con el producto.  

Guía de solución de problemas

Síntoma: Klaviyo Customer Hub no aparece en el sitio.

Causa probable: El script no se carga o el Hub está oculto.

Corrección: Confirma que customerHub.js se carga (comprueba la consola), que el ID de la compañía está configurado y que la visibilidad de Klaviyo Customer Hub está activa en Klaviyo Customer Hub > Configuración. 

Síntoma: La consola muestra "Error al cargar el script Klaviyo JS".

Causa probable: URL de script incorrecta o falta el ID de empresa.

Corrige: Comprueba https://static.Klaviyo.com/onsite/js/<COMPANY_ID>/Klaviyo.js y que COMPANY_ID esté rellenado. 

Síntoma: con actividad La tarjeta de producto no aparece en el Hub en las PDP.

Causa probable: hidratoProducto no llamado o asa de producto incorrecta.

Corrección: Cerciórate de que se ejecuta el bucle de espera y llama a window.customerHubApi.hydrateProduct("<handle>" ) con el asa correcta del producto. 

Síntoma: La sección "Vistos recientemente" está vacía.

Causa probable: Seguimiento del producto visto no implementado.

Corrección: Agrega el fragmento de seguimiento de Producto Visto de la guía del desarrollador y verifica los eventos en Klaviyo. 

Síntoma: Los favoritos o el widget de preguntas frecuentes no se muestran en la PDP.

Causa probable: Contenedor ausente o atributo incorrecto.

Corrección: Agrega <div class="kl-hub-favorites-slot" data-product-id="..."> y/o <div class="klaviyo-faqs-slot" data-product-id="..."> con el ID de producto correcto. 

Síntoma: Al hacer clic en el icono de la cuenta no se abre Hub.

Causa probable: El enlace de cabecera no apunta a /cuenta o #k-hub.

Corrección: Cerciórate de que el anclaje de la cuenta emplea /cuenta (toma automática) o establece href="#k-hub". 

Síntoma: No se reconoce a los compradores como iniciadores de sesión dentro del Hub.

Causa probable: Falta la ruta /interfaz de programación de aplicaciones (API)/authenticateCustomerHub o falla la petición interfaz de programación de aplicaciones (API).

Solución: Implementa el ejemplo de Hydrogen (o tu framework equivalente), envía access_token y company_id a Klaviyo's login punto de conexión, y devuelve la respuesta. 

Preguntas frecuentes

P: ¿Tengo que emplear Shopify Cuenta cliente interfaz de programación de aplicaciones (API) para iniciar sesión?

R: No. En su lugar, puedes emplear la contraseña de un solo uso (OTP) de Klaviyo. Si ya empleas Shopify cuenta, conéctate a través de la interfaz de programación de aplicaciones (API) de Cuenta cliente para disfrutar de una experiencia fluida. 

P: ¿Qué rutas de tiendas tengo que proporcionar?

R: Si empleas tu cuenta existente, proporciona las rutas de inicio de sesión y cierre de sesión; Gestionar cuenta y Gestionar direcciones son opcionales para una vinculación más profunda. 

P: ¿Dónde puedo encontrar la clave pública de la interfaz de programación de aplicaciones (API) de Storefront?

R: En Shopify's Headless Administrador en Storefront interfaz de programación de aplicaciones (API ) > Public access token (también llamada Storefront interfaz de programación de aplicaciones (API) public key). 

P: ¿Puede Klaviyo Customer Hub hacer cargo del icono de mi cuenta?

R: Sí. Si el enlace de cuenta de tu cabecera emplea /cuenta, Klaviyo Customer Hub puede abrir automáticamente; también puedes apuntar a #k-hub. 

P: ¿Es necesario Shopify Hydrogen?

R: No. El ejemplo de autenticación emplea Hydrogen, pero cualquier framework puede implementar una ruta de servidor en /interfaz de programación de aplicaciones (API)/authenticateCustomerHub que publique el token de acceso y el company_id en Klaviyo. 

P: ¿Los Favoritos y las Preguntas Frecuentes pueden vivir en las PDP y dentro del Hub?

R: Sí. Agrega los respectivos divs contenedores en las PDP; también aparecerán en el cajón Hub.