Cómo configurar Klaviyo Customer Hub con Headless Shopify

Qué aprenderás

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 sin cabeza Shopify con acceso al escaparate API (token de acceso público / clave pública del escaparate API en Shopify's Headless Administrador).
2. Tu ID de empresa Klaviyo (utilizado por el cargador JavaScript in situ).
3. Decisión sobre el inicio de sesión del comprador: API de cuenta de cliente de Shopify o contraseña de un solo uso (OTP) de Klaviyo.
   1. Si utilizas cuentas existentes, 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). 

Información general

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 la cuenta y a útiles herramientas de compra. Para Shopify headless, conectas el script in situ de Klaviyo, eliges un método de inicio de sesión (API de cuentas de clientes u OTP de Klaviyo), y opcionalmente añades:

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

Utiliza 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.

Configuración

1 - Configurar los ajustes de Klaviyo Customer Hub

Primero, sigue Primeros pasos con Klaviyo Customer Hub y completa el asistente de incorporación, igual que 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 Storefront API del Headless Administrador de Shopify (Token de acceso público). 

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

Si seleccionas API de cuenta de cliente de Shopify, introduce también las rutas de inicio de sesión, cierre de sesión y opcional Gestionar cuenta/Gestionardirecciones (utilizadas 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 utilizas las funciones in situ de Klaviyo, es posible que tengas un cargador instalado. Confírmalo antes de añadir 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 empresa):

// 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 ha cargado 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>
)

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

3 - Mostrar el producto activo en Klaviyo Customer Hub

Añade 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 utilizar la métrica en otras partes de Klaviyo. Los siguientes fragmentos de seguimiento también se pueden añadir directamente a tu escaparate, las instrucciones se encuentran aquí, en nuestra documentación para desarrolladores Klaviyo: Integrar una plataforma de comercio electrónico 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 la autenticación de Cuentas de clientes API (recomendado)

Para utilizar las cuentas de cliente y la configuración de autenticación existentes en tu tienda, Klaviyo Customer Hub te pedirá que añadas una nueva ruta API a tu tienda que se encargará de pasar de forma segura el token de acceso de un comprador a nuestros servicios. Lo importante es que la nueva ruta API tenga nombre y pueda alcanzarse con '/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/API.authenticateCustomerHub.js
// TODO: Configuración
const COMPANY_ID = '';
export async function action({context}) {
 // Obtén el cliente de la cuenta de cliente 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 al Customer Hub de Klaviyo API
    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 tus cuentas de cliente existentes.

7 - Añade el widget Favoritos (recomendado)

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

Para añadir 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 Añadir a favoritos en las PDP; el artículo aparece en los Favoritos de Hub. 

8 - Añade bloques de preguntas frecuentes (recomendado)

De forma similar a añadir Favoritos, añadir bloques de FAQ es tan sencillo como añadir 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.

Añade 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

Prácticas recomendadas

1. Publica en producción sólo después de la verificación: mantén oculto el staging hasta que se haya completado 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 Activo en las PDP - mantiene el contexto del producto visible en el Hub y empuja a añadir al carrito. Impacto: tasa de conversión, tasa de repetición de compra.
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. Añadir Favoritos - crea una acción de guardar de baja fricción y una lista de favoritos persistente. Impacto: visitas repetidas, añadir al carrito.
5. Utiliza 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 API de Cuentas de clientes cuando esté disponible: mejora la continuidad para los compradores que han iniciado sesión. Impacto: calidad de la experiencia, desviación de la asistencia.  

Medir el éxito

Dónde ver los resultados: Utiliza Analytics > métrica para monitorizar la actividad de los productos vistos y el rendimiento de los flujos/campañas. Utiliza tu panel de ingresos de comercio electrónico para realizar un seguimiento de los cambios en la conversión y el valor medio del pedido tras activar Klaviyo Customer Hub. Métrica clave a vigilar: tasa de conversión desde PDP, tasa de add-to-cart, sesiones con aperturas de Hub (si están instrumentadas), ingresos por destinatario (tasa de repetición de compra), e ingresos impulsados por navegación vinculados a eventos de Producto Visto. 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? Asegúrate de que la hidratación del Producto Activo 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.  

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 empresa está configurado y que la visibilidad de Klaviyo Customer Hub es Live 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: La tarjeta de Producto activa no se muestra en el Hub en las PDP.

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

Corrección: Asegú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: Añade 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: Añade <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: Asegúrate de que el anclaje de la cuenta utiliza /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 /API/authenticateCustomerHub o falla la petición 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. 

PREGUNTA FRECUENTE

P: ¿Tengo que utilizar la API de cuentas de clientes de Shopify para iniciar sesión?

R: No. En su lugar, puedes utilizar la contraseña de un solo uso (OTP) de Klaviyo. Si ya utilizas cuentas de Shopify, conéctate a través de la API de cuentas de cliente para disfrutar de una experiencia perfecta. 

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

R: Si utilizas tus cuentas existentes, 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 encuentro la clave pública de la API de Storefront?

R: En Shopify's Headless Administrador en Storefront API > Token de acceso público (también llamado Storefront API clave pública). 

P: ¿Puede el Centro de Atención al Cliente de Klaviyo hacerse cargo del icono de mi cuenta?

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

P: ¿Es necesario Shopify Hydrogen?

R: No. El ejemplo de autenticación utiliza Hydrogen, pero cualquier framework puede implementar una ruta de servidor en /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í. Añade los respectivos divs contenedores en las PDP; también aparecerán en el cajón Hub.