Cómo configurar Klaviyo Customer Hub con Shopify sin interfaz

Conecta Klaviyo Customer Hub a tu escaparate headless de Shopify. Habilita el inicio de sesión, muestra widgets (Favoritos, preguntas frecuentes) e impulsa las experiencias de producto Activo/Visto recientemente para aumentar el compromiso y la conversión.

Qué aprenderás

Conectarás Klaviyo Customer Hub a una tienda Shopify sin interfaz, 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. Una tienda de Shopify headless con acceso a la API de Storefront (token de acceso público/clave pública de la API de Storefront en el Administrador de Shopify Headless).
2. Tu id. de empresa de Klaviyo (utilizado por el cargador de JavaScript del sitio).
3. Decisión sobre el inicio de sesión de compradores: Shopify Customer Account API o contraseña de un solo uso (OTP) de Klaviyo.
   1. Si usas 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. Capacidad para editar el código de tu escaparate e implementar 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 widgets (Propietario, Administrador o una función personalizada que tenga acceso de escritura a Contenido y clave de API).

Introducción

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

1. Producto activo: muestra el producto que un comprador está viendo dentro del Hub.
2. Vistos recientemente: enumera los productos vistos recientemente mediante el seguimiento de Klaviyo.
3. Widgets de favoritos y preguntas frecuentes: renderizado en 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 pago más rápido, 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, como en cualquier otra configuración. Cuando esto se complete, ve a Klaviyo Customer Hub > Ajustes. Verás la sección de configuración de Shopify en arquitectura headless.

Activa configuración de Headless Shopify y, después, pega tu clave pública de la API Storefront desde el Administrador de Headless de Shopify (token de acceso público).

En Inicio de sesión de compradores, selecciona Shopify Customer Account API (se recomienda para que todas las apps de tu tienda online 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 otras apps).

Si seleccionas Shopify Customer Account API, introduce también las rutas de tu escaparate de Inicio de sesión, Cerrar sesión y la opcional Gestionar cuenta/Gestionar direcciones (se usan para redirecciones entre el Hub y tu sitio).

Visibilidad de publicación: establece Klaviyo Customer Hub como En directo.

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

Consejo: Si ya utilizas las funciones in situ de Klaviyo, puede que ya tengas un cargador en funcionamiento. Confirma antes de añadir un segundo script.

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 tu identificador 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 del sitio se carga en todas las páginas. Busca el mensaje de la consola: «Klaviyo JS script loaded successfully».  En tu diseño raíz (p. ej., root.tsx), incluye el cargador:

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

Después de este paso, window.customerHubApi pasa a estar 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 hydrate 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.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 has habilitado.

4 - Habilita los productos vistos recientemente en Klaviyo Customer Hub

Implementa el seguimiento de Viewed Product para que el Hub pueda rellenar los artículos Recently viewed y puedas usar la métrica en otras partes de Klaviyo. Los siguientes fragmentos de seguimiento también se pueden añadir directamente a tu tienda. Puedes encontrar las instrucciones aquí, en nuestra documentación de Klaviyo Developers: Integrate an ecommerce platform without a pre-built Klaviyo integration.

5: habilitar la toma de control del enlace de la cuenta

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

6: configurar Klaviyo Customer Hub con la autenticación de la API de cuentas de clientes (recomendado)

Para usar las cuentas de cliente de tu escaparate actual y la configuración de autenticación, Klaviyo Customer Hub requerirá que añadas una nueva ruta de API a tu escaparate que se encargará de pasar de forma segura el token de acceso de un comprador que haya iniciado sesión a nuestros servicios. Lo importante es que la nueva ruta de API tenga un 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; los escaparates más personalizados 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 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 actual y proporcionar un punto de entrada sin fricciones en tus cuentas de cliente existentes.

7: añadir el widget Favoritos (recomendado)

Tanto Favoritos como Preguntas frecuentes funcionarán dentro del panel desplegable de Klaviyo Customer Hub. Sin embargo, también puedes añadir estos widget en PDP para aumentar el compromiso.

Para añadir un punto de entrada de Favoritos en las PDP 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 Añadir a favoritos en las PDP; el artículo aparece en Artículos favoritos del Hub.

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

Al igual que al añadir Favoritos, añadir bloques de preguntas frecuentes es tan sencillo como añadir un div en tu página de producto con su ID de producto incluido para mostrar las preguntas frecuentes, que puedes editar y diseñar en Klaviyo.

Añade un bloque de preguntas frecuentes específicas 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 deberían mostrarse ahora en las páginas de detalles del producto (PDP) si están configurados, y se pueden editar en Klaviyo

Prácticas recomendadas

1. Publica en producción solo después de la verificación (mantén el entorno de preproducción oculto hasta que se complete el aseguramiento de calidad; luego, configura En vivo para mostrar el Hub). Impacto: menos incidencias de soporte, menor tiempo de obtención de valor.
2. Hidratar siempre el Producto activo en las PDP (mantiene el contexto del producto visible en el Hub y fomenta que se añada al carrito). Impacto: tasa de conversión, tasa de repetición de compra.
3. Implementa el seguimiento de producto visto lo antes posible (rellena Vistos recientemente y desbloquea flujos basados en navegación). Impacto: compromiso e ingresos de la recuperación de navegación.
4. Añadir a favoritos: crea una acción de guardado sencilla y una lista corta persistente. Impacto: visitas repetidas, adición al carrito.
5. Usa las preguntas frecuentes para abordar objeciones (responde en línea a preguntas sobre envío, materiales o devoluciones para reducir el abandono). Impacto: tasa de conversión.
6. Prefiere la autenticación del lado del servidor con la API de cuentas de clientes cuando esté disponible. Esto mejora la continuidad para los compradores que inician sesión. Impacto: calidad de la experiencia y desviación de la asistencia. 

Medir el éxito

Dónde ver los resultados: usa Análisis > Métricas para supervisar la actividad de Producto visto y el rendimiento posterior de los flujos y las campañas. Usa tus paneles de ingresos de comercio electrónico para hacer un seguimiento de los cambios en la conversión y el valor medio del pedido tras habilitar Klaviyo Customer Hub. Métricas clave que debes supervisar: tasa de conversión desde PDP, tasa de añadir al carrito, sesiones con aperturas del Hub (si está instrumentado), ingresos por destinatario (ingresos por destinatario) e ingresos impulsados por navegación vinculados a eventos Viewed Product. Lista de comprobación de soluciones rápidas: ¿Poca actividad de Vistos recientemente? Verifica que el fragmento de seguimiento de Viewed Product se esté activando y que los eventos se atribuyan a perfiles. ¿Pocos añadidos al carrito desde el Hub? Asegúrate de que la hidratación de Active Product se ejecute en cada PDP y de que las variantes y los precios sean correctos. ¿Pocas incorporaciones a Favoritos? Mueve el espacio de Favoritos cerca de las CTA principales de la PDP y confirma que data-product-id coincida 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 (revisa la consola), que el identificador 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 «Failed to load Klaviyo JS script.»

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

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

Síntoma: la tarjeta de Producto activo no se muestra en el Hub en las PDP.

Causa probable: hidrataNo se ha llamado al producto o su manejo es incorrecto.

Correcció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 Vistos recientemente está vacía.

Causa probable: no se ha implementado el seguimiento de Producto Visto.

Solución: Añade el fragmento de seguimiento Viewed Product de la guía para desarrolladores y verifica los eventos en Klaviyo.

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

Causa probable: falta el contenedor o el atributo es 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 el Hub.

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

Solución: Asegúrate de que el anclaje de la cuenta use /account (auto‐takeover) o configura href="#k-hub".

Síntoma: no se reconoce que los compradores hayan iniciado sesión dentro del Hub.

Causa probable: falta la ruta /api/authenticateCustomerHub o error de solicitud de la API.

Solució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 API de Shopify Customer Accounts para el inicio de 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 API de cuentas de clientes para disfrutar de una experiencia fluida.

P: ¿Qué rutas de tienda online tengo que proporcionar?

A: Si usas tus cuentas existentes, proporciona las rutas de Inicio de sesión y Cerrar sesión; Gestionar cuenta y Gestionar direcciones son opcionales para un enlace más profundo.

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

R: En el Administrador headless de Shopify, en Storefront API > Public access token (también llamado Storefront API public key).

P: ¿Puede Klaviyo Customer Hub tomar el control del icono de mi cuenta?

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

P: ¿Es obligatorio 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 el company_id en Klaviyo.

P: ¿Pueden Favoritos y Preguntas frecuentes estar en las PDP y dentro del Hub?

R: Sí. Añade los respectivos contenedores div en las PDP; también aparecerán en el cajón del Hub.