Cómo configurar Klaviyo Customer Hub con Headless Shopify

Conecta Klaviyo Customer Hub con tu tienda headless de Shopify. Habilita el inicio de sesión, muestra widgets (Favoritos, preguntas frecuentes) y potencia experiencias de producto con actividad/recientemente visto para aumentar la interacción y la conversión.

Objetivos del artículo

Conectarás Klaviyo Customer Hub a una tienda headless de 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

Prerrequisitos

1. Un escaparate de Shopify sin interfaz (headless) con acceso a la interfaz de programación de aplicaciones (API) de Storefront (token de acceso público/clave pública de la interfaz de programación de aplicaciones (API) de Storefront en el Administrador de Headless de Shopify).
2. Tu ID de empresa de Klaviyo (usado por el cargador de JavaScript en el sitio).
3. Decisión sobre el inicio de sesión del comprador: interfaz de programación de aplicaciones (API) de cuentas de cliente de Shopify o contraseña de un solo uso (OTP) de Klaviyo.
   1. Si usas cuentas existentes, ten listas las rutas de Iniciar sesión, Cerrar sesión y (opcional) Administrar cuenta y Administrar direcciones de tu tienda.
4. Capacidad para editar el código de tu tienda y publicar cambios.
5. Quién puede configurar esto: Necesitas una función de cuenta que pueda editar la configuración de Klaviyo Customer Hub y publicar widget (Propietario, Administrador o una función personalizada que tenga acceso de escritura a Contenido y claves de API).

Resumen

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

1. Producto con actividad: muestra el producto que un comprador está viendo dentro del Hub.
2. Visto recientemente: enumera los productos vistos recientemente mediante el seguimiento de Klaviyo.
3. Widgets de Favoritos y preguntas frecuentes: se renderizan en las PDP y dentro del Hub. 

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

Configurar

1 - Configura 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 que esto se complete, ve a Klaviyo Customer Hub > Configuración. Verás la sección de configuración headless de Shopify.

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

En Inicio de sesión de compradores, selecciona Shopify Customer Account interfaz de programación de aplicaciones (API) (recomendado para que todas las apps de tu tienda puedan compartir el inicio de sesión de Shopify) o Contraseña de un solo uso de Klaviyo (OTP, solo funciona con Klaviyo y no permitirá que los compradores inicien sesión en ninguna otra app).

Si seleccionas interfaz de programación de aplicaciones (API) de cuenta de cliente de Shopify, también ingresa las rutas de Iniciar sesión, Cerrar sesión y Administrar cuenta/Administrar direcciones opcionales de la tienda (se usan para redirecciones entre el Hub y tu sitio).

Visibilidad de publicación: configura Klaviyo Customer Hub como Activo.

2: Cargar el JavaScript de Klaviyo Customer Hub (Instrucciones para desarrolladores)

Consejo: Si ya usas las funciones onsite de Klaviyo, es posible que ya tengas un loader configurado. Confirma antes de agregar un segundo script.

Crea /public/customerHub.js (o equivalente) con el siguiente cargador (reemplaza COMPANY_ID con tu clave de API pública de Klaviyo, también conocida como tu ID de empresa):

// customerHub.js
// TODO: Configuration
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 onsite se carga en todas las páginas. Busca el mensaje de consola: “Klaviyo JS script loaded successfully.”  En el layout raíz (p. ej., root.tsx), incluye el loader:

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

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

3: Mostrar el producto con actividad en Klaviyo Customer Hub

Agrega la llamada de hidratación en la 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.customerHubApi.hydrateProduct) {
            resolve();
          } else {
            requestAnimationFrame(check);
          }
        };
        check();
      });
    }
    waitForCustomerHubApi().then(() => {
      window.customerHubApi.hydrateProduct("your-product-handle");
    });
  })();
</script>

El Hub ahora debería mostrar una tarjeta de producto adicional para la PDP que el comprador está viendo en la pestaña "Chat" si la tienes habilitada.

4: habilitar los productos vistos recientemente en Klaviyo Customer Hub

Implementa el seguimiento de Producto visto para que el Hub pueda completar los artículos Vistos recientemente y puedas usar la métrica en otras partes de Klaviyo. Los siguientes fragmentos de seguimiento también se pueden agregar directamente a tu tienda; puedes encontrar las instrucciones aquí en nuestra documentación de Klaviyo para desarrolladores: Integra una plataforma de ecommerce sin una integración preconfigurada de Klaviyo.

5 - Habilitar la apropiación del vínculo de la cuenta

Para que Klaviyo Customer Hub se abra al hacer clic en el ícono de cuenta en el encabezado de tu tienda, ya debes tener una etiqueta a existente que haga referencia a un enlace con /account (en ese caso, la reemplazaremos automáticamente). O también puedes definir manualmente el enlace del ícono para que apunte a #k-hub y así abrir el panel.

6: configura Klaviyo Customer Hub con autenticación de la interfaz de programación de aplicaciones (API) de cuentas de cliente (recomendado)

Para poder usar las cuentas de cliente y la configuración de autenticación existentes de tu tienda, Klaviyo Customer Hub necesitará que agregues una nueva ruta de interfaz de programación de aplicaciones (API) a tu tienda para gestionar de forma segura el envío del token de acceso de un comprador que haya iniciado sesión a nuestros servicios. Lo importante es que la nueva ruta de la interfaz de programación de aplicaciones (API) tenga nombre y se pueda acceder a ella con "/api/authenticateCustomerHub".

Nota: el siguiente ejemplo de fragmento de código es para el framework Hydrogen de Shopify; las tiendas más personalizadas pueden requerir algunas soluciones alternativas adicionales. Sin embargo, aquí se describirá el enfoque general.

// ./app/routes/api.authenticateCustomerHub.js
// TODO: Configuration
const COMPANY_ID = '';
export async function action({context}) {
  // Pull the Customer Account API Client from your storefront's context
  const {customerAccount} = context;
  try {
    // Get the access token for the current customer
    const accessToken = await customerAccount.getAccessToken();
    if (!accessToken) {
      return new Response(JSON.stringify({message: 'User not logged in'}), {
        status: 200,
      });
    }
    // Send the access token to the Customer Hub API
    const response = await fetch(
      'https://atlas-app.services.klaviyo.com/api/onsite/headless-shopify-login',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          access_token: accessToken,
          company_id: COMPANY_ID,
        }),
      },
    );
    const responseData = await response.text();
    // Return the actual response from Customer Hub with the same status code
    return new Response(responseData, {
      status: response.status,
      headers: {
        'Content-Type':
          response.headers.get('content-type') || 'application/json',
      },
    });
  } catch (error) {
    return new Response(null, {status: 500});
  }
}

Una vez que esto esté configurado, así como las rutas de la tienda definidas en la configuración de Klaviyo, Klaviyo Customer Hub podrá vincularse a tu configuración de autenticación existente y proporcionar un punto de entrada sin interrupciones a las cuentas de cliente existentes.

7: Agrega el widget de favoritos (recomendado)

Tanto Favoritos como Preguntas frecuentes funcionarán dentro del panel deslizable de Klaviyo Customer Hub. Sin embargo, también puedes agregar estos widget en las PDP para generar más interacción.

Para agregar un punto de entrada de Favoritos en las páginas de detalles de producto y dentro del Hub:

// products.tsx
// Example identifiers:
//   id: gid://shopify/Product/12345
//   data-product-id: 12345
const gid = "gid://shopify/Product/12345";
const productId = gid.split('/').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 Artículos favoritos del Hub.

8: agrega bloques de preguntas frecuentes (recomendado)

De forma similar a agregar Favoritos, agregar bloques de preguntas frecuentes es tan sencillo como agregar un div en la página del producto con el ID del producto incluido para mostrar preguntas frecuentes que puedes editar y diseñar en Klaviyo.

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

// products.tsx
// Example:
const gid = "gid://shopify/Product/12345";
const productId = gid.split('/').pop();

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

Los chips/botones de preguntas frecuentes ahora deberían mostrarse en las PDP si están configurados, y se pueden editar en Klaviyo.

Mejores prácticas

1. Publica en producción solo después de la verificación: mantén el entorno de staging oculto hasta que se complete el QA; luego configura En vivo para exponer el Hub. Impacto: menos problemas de soporte, tiempo de obtención de valor más rápido.
2. Hidrata siempre el Producto con actividad en las PDP — mantiene el contexto del producto visible en el Hub e impulsa agregar al carrito. Impacto: tasa de conversión, tasa de compras repetidas.
3. Implementa el seguimiento de producto visto desde el inicio: completa la sección Vistos recientemente y habilita flujos basados en la navegación. Impacto: interacción e ingresos de la recuperación de navegación.
4. Añadir favoritos — crea una acción de guardado de baja fricción y una lista de opciones persistente. Impacto: visitas repetidas, añadir al carrito.
5. Usa las preguntas frecuentes para responder a objeciones: responde en línea preguntas sobre envíos, materiales o devoluciones para reducir el abandono. Impacto: tasa de conversión.
6. Prefiere la autenticación del lado del servidor con la interfaz de programación de aplicaciones (API) de cuentas de cliente cuando esté disponible: mejora la continuidad para compradores con sesión iniciada. Impacto: calidad de la experiencia, desvío de solicitudes de soporte. 

Medición del éxito

Dónde ver los resultados: Utiliza Análisis > Métricas para monitorear la actividad de Producto Visto y el rendimiento del flujo o la campaña posteriores. Utiliza tus paneles de ingresos de ecommerce para realizar un seguimiento de las conversiones y los cambios en el valor medio del pedido (AOV) después de habilitar el Klaviyo Customer Hub. Métricas clave a observar: tasa de conversión de la PDP, tasa de adición al carrito, sesiones con aperturas en el Hub (si están instrumentadas), ingresos por destinatario (RPR) e ingresos impulsados por la navegación vinculados a eventos de Producto Visto. Lista de comprobación de soluciones rápidas: ¿Actividad baja vista recientemente? Verifica que el fragmento de seguimiento Producto Visto se esté activando y que los eventos se atribuyan a perfiles. ¿El add-to-cart del Hub es bajo? Asegúrate de que la hidratación de Producto Activo funcione en todas las PDP y de que las variantes/precios sean correctos. ¿Se añaden pocos favoritos? Mueve la ranura Favoritos cerca de las CTA principales de la PDP y confirma que el dato-product-id coincida 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 está cargando o el hub está Oculto.

Solución: Confirma que customerHub.js se carga (revisa la consola), que el ID de empresa esté configurado y que la visibilidad de Klaviyo Customer Hub esté en En vivo en Klaviyo Customer Hub > Configuración.

Síntoma: La consola muestra “No se pudo cargar el script de Klaviyo JS”.

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

Solución: Verifica https://static.klaviyo.com/onsite/js/<COMPANY_ID>/klaviyo.js y que COMPANY_ID esté completado.

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

Causa probable: no se llamó a hydrateProduct o el identificador del producto es incorrecto.

Solución: asegúrate de que el bucle de espera se ejecute y llama a window.customerHubApi.hydrateProduct("<handle>") con el identificador de producto correcto.

Síntoma: La sección de vistos recientemente está vacía.

Causa probable: No se implementó el seguimiento de Producto visto.

Solución: Agrega el fragmento de seguimiento de Producto visto desde la guía para desarrolladores y verifica los eventos en Klaviyo.

Síntoma: los widgets de Favoritos o preguntas frecuentes no se renderizan en la PDP.

Causa probable: Falta el contenedor o el atributo es 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 ícono de la cuenta, no se abre el Hub.

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

Corrección: Asegúrate de que el ancla de la cuenta use /account (toma de control automática) o establece href="#k-hub".

Síntoma: Los compradores no se reconocen como con sesión iniciada dentro del Hub.

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

Corrección: Implementa el ejemplo de Hydrogen (o el equivalente de tu framework), envía access_token y company_id al punto de conexión de inicio de sesión de Klaviyo, y devuelve la respuesta.

Preguntas frecuentes

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

A: No. En su lugar, puedes usar Contraseña de un solo uso (OTP) de Klaviyo. Si ya usas cuentas de Shopify, conéctate a través de la interfaz de programación de aplicaciones (API) de cuentas de cliente para disfrutar de una experiencia sin fricciones.

P: ¿Qué rutas de la tienda necesito proporcionar?

A: Si usas tus cuentas existentes, proporciona rutas de Inicio de sesión y Cerrar sesión; Administrar cuenta y Administrar direcciones son opcionales para una vinculación más profunda.

P: ¿Dónde encuentro la clave pública de la API de Storefront?

A: En el Administrador sin interfaz de Shopify, en API de Storefront > Token de acceso público (también llamado clave pública de la API de Storefront).

P: ¿Klaviyo Customer Hub puede reemplazar el ícono de mi cuenta?

R: Sí. Si el enlace de cuenta del encabezado usa /account, Klaviyo Customer Hub puede abrirse automáticamente; también puedes dirigirlo a #k-hub.

P: ¿Se requiere Shopify Hydrogen?

A: No. El ejemplo de autenticación usa Hydrogen, pero cualquier framework puede implementar una ruta de servidor en /api/authenticateCustomerHub que publique el token de acceso y company_id en Klaviyo.

P: ¿Favoritos y preguntas frecuentes pueden aparecer en las PDP y dentro del hub?

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