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

• 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).
• Tu ID de empresa de Klaviyo (usado por el cargador de JavaScript en el sitio).
• 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.
  • 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.
• Capacidad para editar el código de tu tienda y publicar cambios.
• Un rol de cuenta con permiso para editar Klaviyo Customer Hub, como Propietario o Administrador. Para un rol personalizado, incluye permisos de visualización y edición para Klaviyo Customer Hub.
• Una prueba de Klaviyo Customer Hub o un plan que incluya Favoritos y Preguntas frecuentes, si quieres usar estas funciones.

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 la cuenta y a herramientas de compra útiles. Para Shopify headless, conectas el script on-site de Klaviyo, eliges un método de inicio de sesión (interfaz de programación de aplicaciones (API) de cuenta de cliente de Shopify o OTP de Klaviyo) y, opcionalmente, agregas:

• Producto con actividad: muestra el producto que un comprador está viendo dentro del Hub.
• Visto recientemente: enumera los productos vistos recientemente mediante el seguimiento de Klaviyo.
• Widgets de favoritos y preguntas frecuentes: se muestran en las páginas de detalles del producto (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 la configuración de Klaviyo Customer Hub

Primero, sigue primeros pasos con Klaviyo Customer Hub y completa el asistente de incorporación. Mantén Klaviyo Customer Hub oculto hasta que la configuración headless esté lista. Luego ve a Klaviyo Customer Hub > Configuración y busca Configuración headless de Shopify.

Activa Configuración headless de Shopify y pega el token de acceso público de Shopify en Clave pública de la interfaz de programación de aplicaciones (API) de Storefront.

En inicio de sesión de compradores, selecciona interfaz de programación de aplicaciones (API) de cuenta de cliente de Shopify para usar tu inicio de sesión de Shopify existente, o Klaviyo One Time Password (OTP) para un inicio de sesión que funcione solo con Klaviyo.

Si seleccionas interfaz de programación de aplicaciones (API) de cuenta de cliente de Shopify, ingresa la ruta de inicio de sesión y la ruta de cierre de sesión de la tienda. Ruta de administrar cuenta y ruta de administrar direcciones son opcionales. Estas rutas redirigen a los compradores entre el Hub y tu sitio.

Si seleccionas Klaviyo One Time Password (OTP), ingresa Nombre para mostrar de la tienda y Correo electrónico de respuesta. El correo electrónico de respuesta no puede usar una dirección de gmail.com o klaviyo.com.

Haz clic en Guardar para guardar la configuración. Para comprobar el estado de publicación del Hub, haz clic en Abrir editor. Mantén el estado en Oculto hasta que termines la configuración de la tienda y las pruebas que se indican a continuación.

2. Carga 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);

En el diseño raíz (por ejemplo, root.tsx), incluye el cargador para que el script de onsite se cargue en todas las páginas. Busca el mensaje de la consola “Klaviyo JS script loaded successfully.”

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

Después de que el Hub termina de cargar, window.customerHubApi está disponible. El mensaje de éxito del cargador confirma que el script se cargó; espera la interfaz de programación de aplicaciones (API) del Hub antes de llamar a hydrateProduct, como se muestra a continuación.

3. Mostrar el producto con actividad en Klaviyo Customer Hub

Agrega el siguiente script al HTML de la página del producto, reemplazando your-product-handle con el identificador actual del producto de Shopify. Si tu storefront usa React u otro framework con navegación del lado del cliente, ejecuta la llamada de hidratación desde el ciclo de vida de página de ese framework cada vez que cambie el producto.

<!-- Product page HTML -->
<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>

En computadoras de escritorio, el Hub puede mostrar la tarjeta del producto actual en la pestaña Chat cuando el chat web está habilitado. Esta tarjeta no se muestra en dispositivos móviles.

4. Habilita los productos vistos recientemente en Klaviyo Customer Hub

Implementa el seguimiento de Viewed Product en las páginas de producto para que puedas usar esta métrica en Klaviyo. También llama a trackViewedItem para almacenar los productos vistos recientemente en el navegador del comprador para el Hub. Sigue los ejemplos de seguimiento en Integrar una plataforma de ecommerce sin una integración prediseñada de Klaviyo.

5. Habilitar la toma de control del enlace de la cuenta

Cuando Klaviyo Customer Hub está Activo, puede reemplazar enlaces de cuenta que terminen en /account o /account/login para que abran el Hub. Para abrir el Hub desde un icono de cuenta personalizado, configura el enlace en #k-hub. Agrega data-k-hub-ignore a un enlace de cuenta si debe seguir abriendo la página de cuenta de tu tienda online.

6. Conecta la autenticación de la interfaz de programación de aplicaciones (API) de la cuenta de cliente de Shopify (recomendado)

Completa este paso solo si seleccionaste interfaz de programación de aplicaciones (API) de cuenta de cliente de Shopify en inicio de sesión del comprador. Si seleccionaste contraseña de un solo uso (OTP) de Klaviyo, salta al paso 7.

Agrega una ruta del servidor en /api/authenticateCustomerHub que acepte solicitudes POST y pase el token de acceso del comprador que inició sesión a Klaviyo. Configura COMPANY_ID en el ejemplo con el ID de empresa de Klaviyo.

El siguiente ejemplo usa el framework Hydrogen de Shopify. Adapta la ruta del servidor a tu framework si usas una tienda diferente.

// ./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 se configuren esta ruta y las rutas de la tienda en línea en la configuración de Klaviyo, Klaviyo Customer Hub podrá conectarse al inicio de sesión de tu cuenta de cliente existente.

7. Agrega el widget de Favoritos (recomendado)

Los favoritos y las preguntas frecuentes pueden aparecer dentro del panel de Klaviyo Customer Hub. También puedes agregarlos a las páginas de detalles del producto para que los compradores guarden productos y encuentren respuestas mientras navegan.

Primero, habilita Favoritos en el editor del Hub. Luego, ve a Klaviyo Customer Hub > Diseño, selecciona Favoritos y elige qué compradores pueden ver el widget en el sitio. Haz clic en Publicar para guardar la configuración del widget y, luego, agrega el siguiente contenedor a la página del producto. Reemplaza el ID de producto de Shopify del ejemplo por el ID del producto actual.

// 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}
  />
)

Una vez que Klaviyo Customer Hub esté Activo y el widget sea visible para el comprador, puede hacer clic en Agregar a favoritos en una página de producto. Los productos guardados aparecen en la experiencia de Favoritos del Hub.

8. Agrega bloques de preguntas frecuentes (recomendado)

Crea tus bloques de preguntas frecuentes en Klaviyo. En Klaviyo Customer Hub > Diseño, selecciona FAQ, elige las preguntas que se mostrarán en las páginas de producto y configura la visibilidad en el sitio y el diseño. Haz clic en Publicar para guardar la configuración antes de agregar el contenedor a continuación.

Agrega este contenedor a la página del producto con el ID de producto actual de Shopify. Las mismas preguntas frecuentes seleccionadas aparecen en todas las páginas de producto; el ID de producto no selecciona preguntas diferentes para cada producto.

// 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 botones de preguntas frecuentes seleccionados aparecen en las páginas de producto según la configuración de visibilidad. Al hacer clic en una pregunta, se abre su respuesta en Klaviyo Customer Hub.

9. Probar y activar Klaviyo Customer Hub

Prueba el código de la tienda en staging antes de implementarlo en producción. La toma de control automática de vinculación de la cuenta y el widget de Favoritos en el sitio requieren Live, así que inclúyelos en las verificaciones finales en live.

1. Cuando estés listo para publicar, ve a Klaviyo Customer Hub > Configuración y haz clic en Abrir editor.
2. Guarda cualquier cambio pendiente en el diseño del Hub. Luego, selecciona Activo en el menú desplegable de estado o haz clic en Activar cuando el Hub esté oculto y no tenga cambios sin guardar.
3. Espera la confirmación de que Klaviyo Customer Hub está activo. En el escaparate de producción, revisa el inicio y cierre de sesión, el ícono de la cuenta, la tarjeta de producto de Chat de escritorio (si está habilitada), los productos vistos recientemente y cualquier widget de Favoritos o Preguntas frecuentes que hayas agregado.

Mejores prácticas

• Publica en producción solo después de hacer pruebas para ayudar a evitar problemas de soporte. Mantén el Hub de producción Oculto hasta que la configuración esté lista y, luego, cámbialo a En vivo desde el editor del Hub.
• Hidrata el producto con actividad en las PDP para mantener el contexto del producto disponible en el Hub y ayudar a los compradores a agregarlo al carrito. Monitorea la tasa de conversión y los ingresos por destinatario (ingresos por destinatario) para evaluar el efecto.
• Implementa el seguimiento de productos desde el inicio para completar la lista de productos vistos recientemente y respaldar los flujos basados en navegación. Monitorea la interacción y los ingresos de la recuperación de navegación.
• Agrega Favoritos para ofrecerles a los compradores una forma fácil de guardar una lista corta. Monitorea las visitas repetidas y la actividad de agregar al carrito.
• Usa las preguntas frecuentes para responder preguntas sobre envíos, materiales o devoluciones mientras los compradores navegan. Monitorea el abandono y la tasa de conversión.
• Usa autenticación del lado del servidor con la interfaz de programación de aplicaciones (API) de Shopify Customer cuenta cuando esté disponible para mantener la continuidad para los compradores que hayan iniciado sesión y ayudar a reducir las solicitudes de soporte relacionadas con el inicio de sesión.

Medición del éxito

Usa Analytics > Métricas para monitorear la actividad de Viewed Product. Revisa el desempeño posterior en tus flujos y campañas. Usa los paneles de ingresos de ecommerce para monitorear los cambios en la conversión y el valor medio del pedido (AOV) después de habilitar Klaviyo Customer Hub.

Monitorea la tasa de conversión desde las páginas de producto, la tasa de agregar al carrito, las sesiones con aperturas de Hub (si está instrumentado), los ingresos por destinatario (RPR, tasa de compras repetidas) y los ingresos impulsados por la navegación vinculados a eventos de Viewed Product.

Revisiones rápidas

• Si la actividad de vistos recientemente es baja, verifica el seguimiento de productos y comprueba que los eventos Viewed Product se atribuyan a los perfiles. También revisa el seguimiento de vistos recientemente basado en el navegador.
• Si hay poca actividad de agregar al carrito desde el Hub, verifica que la hidratación de productos con actividad se ejecute en cada PDP y que las variantes y los precios sean correctos.
• Si hay pocas adiciones a Favoritos, coloca el espacio de Favoritos cerca de los principales llamados a la acción de la página del producto y confirma que data-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 cargue, que el ID de la empresa esté configurado y que Klaviyo Customer Hub esté activo. Para cambiar el estado, ve a Klaviyo Customer Hub > Configuración > Abrir editor y usa el menú desplegable de estado.

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: falta la llamada de hidratación, el handle del producto es incorrecto o estás revisando la tarjeta de producto de Chat en un dispositivo móvil.

Corrección: En computadoras de escritorio, abre Chat con el chat web habilitado. Asegúrate de que el bucle de espera se ejecute y llama a window.customerHubApi.hydrateProduct("<handle>") con el identificador del producto correcto.

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

Causa probable: Falta o está incompleto el seguimiento del producto.

Corrección: Añadir el seguimiento del evento Viewed Product y el seguimiento del navegador trackViewedItem. Verifica eventos en un perfil reconocido y revisa los productos vistos recientemente en el mismo navegador.

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

Causa probable: falta un contenedor, el ID del producto es incorrecto, el widget está oculto o el plan no incluye la función.

Solución: Agrega <div class="kl-hub-favorites-slot" data-product-id="..."></div> o <div class="klaviyo-faqs-slot" data-product-id="..."></div> con el ID de producto correcto. Confirma el acceso y la visibilidad de las funciones en Klaviyo, y selecciona las preguntas frecuentes para las páginas de producto. Klaviyo Customer Hub también debe estar Live para que aparezca el widget de Favoritos.

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

Causa probable: El enlace de la cuenta no coincide con una URL de cuenta compatible, se excluye de la toma de control o Klaviyo Customer Hub está oculto.

Corrección: Configura Klaviyo Customer Hub como En vivo, usa un enlace de cuenta que termine en /account o /account/login, o configura href="#k-hub". Quita data-k-hub-ignore solo de los enlaces que deban abrir el Hub.

Síntoma: Con la interfaz de programación de aplicaciones (API) de cuenta de cliente de Shopify seleccionada, no se reconoce que los compradores hayan iniciado sesión 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 la contraseña de un solo uso (OTP) de Klaviyo. Si ya usas cuentas de Shopify, conéctate mediante la interfaz de programación de aplicaciones (API) de cuenta de cliente de Shopify para disfrutar de una experiencia sin interrupciones.

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

A: Para la interfaz de programación de aplicaciones (API) de cuentas de cliente de Shopify, proporciona la ruta de inicio de sesión y la ruta de cierre de sesión. La ruta de administración de la cuenta y la ruta de administración de direcciones son opcionales para un enlace más profundo.

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

A: Usa el token de acceso público de tu storefront en el canal Headless de Shopify. Sigue la guía de configuración de la interfaz de programación de aplicaciones (API) Storefront de Shopify y luego ingresa el token público en el campo Clave pública de la interfaz de programación de aplicaciones (API) Storefront de Klaviyo.

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

R: Sí. Cuando Klaviyo Customer Hub esté En vivo, los enlaces que terminan en /account o /account/login pueden abrir el Hub automáticamente. También puedes dirigir el enlace de la cuenta 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?

R: Sí. Configura Favoritos y preguntas frecuentes en Klaviyo y luego agrega sus divs de contenedor a las páginas de producto. La visibilidad en el Hub y en las páginas de producto sigue la configuración que elijas.