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

• 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).
• Tu id. de empresa de Klaviyo (utilizado por el cargador de JavaScript del sitio).
• Decisión sobre el inicio de sesión de compradores: Shopify Customer Account API o contraseña de un solo uso (OTP) de Klaviyo.
  • 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.
• Capacidad para editar el código de tu escaparate e implementar cambios.
• Un rol de cuenta con permiso para editar Klaviyo Customer Hub, como Propietario o Administrador. En el caso de un rol personalizado, incluye permisos de visualización y edición de Customer Hub.
• Una prueba de Klaviyo Customer Hub o un plan que incluya Favoritos y Preguntas frecuentes, si quieres usar estas funciones.

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 in situ de Klaviyo, eliges un método de inicio de sesión (Shopify Customer Account API o Klaviyo OTP) y, de forma opcional, añades:

• Producto activo: muestra el producto que un comprador está viendo dentro del Hub.
• Vistos 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 (PDPs) 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. Configura los ajustes 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. Después, ve a Klaviyo Customer Hub > Ajustes y busca Configuración de Shopify headless.

Activa Headless Shopify configuration y pega el token de acceso público de Shopify en Storefront API public key.

En Shopper login, selecciona Shopify Customer Account API para usar tu inicio de sesión actual de Shopify o Klaviyo One Time Password (OTP) para un inicio de sesión que funcione solo con Klaviyo.

Si seleccionas API de cuenta de cliente de Shopify, introduce la ruta de inicio de sesión y la ruta de cierre de sesión de la tienda. La ruta de gestión de cuenta y la ruta de gestión de direcciones son opcionales. Estas rutas redirigen a los compradores entre el Hub y tu sitio.

Si seleccionas Klaviyo One Time Password (OTP), introduce Nombre para mostrar de la tienda y Responder al email. El email 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 del escaparate y las pruebas que se indican abajo.

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);

En el diseño raíz (por ejemplo, root.tsx), incluye el cargador para que el script del sitio se cargue en todas las páginas. Busca el mensaje de 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 termine de cargarse, window.customerHubApi estará disponible. El mensaje de éxito del cargador confirma que el script se cargó; espera a la API del Hub antes de llamar a hydrateProduct, como se muestra a continuación.

3. Muestra el producto activo en Klaviyo Customer Hub

Añade el siguiente script al HTML de la página del producto y sustituye your-product-handle por el identificador del producto actual de Shopify. Si el storefront utiliza React u otro framework con navegación del lado del cliente, ejecuta la llamada de hydration desde el ciclo de vida de la 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 ordenadores, 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 comercio electrónico sin una integración de Klaviyo prediseñada.

5. Habilitar el secuestro del enlace de la cuenta

Cuando Klaviyo Customer Hub esté activo, puede reemplazar los enlaces de cuenta que terminan en /account o /account/login para que abran el Hub. Para abrir el Hub desde un icono de cuenta personalizado, configura el enlace como #k-hub. Añade data-k-hub-ignore a un enlace de cuenta si debe seguir abriendo la página de cuenta de la tienda.

6. Conecta la autenticación de la API de cuentas de cliente de Shopify (recomendado)

Completa este paso solo si seleccionaste API de cuentas de cliente de Shopify en inicio de sesión del comprador. Si seleccionaste Klaviyo One Time Password (OTP), pasa al paso 7.

Añade una ruta de servidor en /api/authenticateCustomerHub que acepte solicitudes POST y pase el token de acceso del comprador que ha iniciado sesión a Klaviyo. Configura COMPANY_ID en el ejemplo con el ID de la empresa de Klaviyo.

El siguiente ejemplo utiliza el framework Hydrogen de Shopify. Adapta la ruta del servidor a tu framework si usas un escaparate 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 hayan configurado esta ruta y las rutas de la tienda en la configuración de Klaviyo, Klaviyo Customer Hub podrá conectarse al inicio de sesión de tu cuenta de cliente existente.

7. Añade el widget de Favoritos (recomendado)

Los favoritos y las preguntas frecuentes pueden aparecer dentro del panel lateral de Klaviyo Customer Hub. También puedes añadirlos a las páginas de detalles del producto para que los compradores puedan guardar productos y encontrar 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 del sitio. Haz clic en Publicar para guardar la configuración del widget y, a continuación, añade el siguiente contenedor a la página de producto. Sustituye el ID del producto de Shopify de 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 esté visible para el comprador, puede hacer clic en Añadir a favoritos en una página de producto. Sus productos guardados aparecen en la experiencia de Favoritos del Hub.

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

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

Añade este contenedor a la página del producto con el ID de producto de Shopify actual. 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 la respuesta en Klaviyo Customer Hub.

9. Probar y activar Klaviyo Customer Hub

Prueba el código de la tienda en un entorno de ensayo antes de implementarlo en producción. La apropiación automática del enlace de cuenta y el widget de Favoritos en el sitio requieren Live, así que inclúyelos en las comprobaciones finales en vivo.

1. Cuando estés listo para publicar, ve a Klaviyo Customer Hub > Ajustes y haz clic en Abrir editor.
2. Guarda cualquier cambio de diseño del Hub pendiente. Después, selecciona En directo en el menú desplegable de estado o haz clic en Publicar cuando el Hub esté oculto y no haya cambios sin guardar.
3. Espera la confirmación de que Klaviyo Customer Hub esté activo. En el escaparate de producción, comprueba el inicio y cierre de sesión, el icono de cuenta, la tarjeta de producto de Chat en el ordenador (si está habilitada), los productos vistos recientemente y cualquier widget de Favoritos o preguntas frecuentes que hayas añadido.

Prácticas recomendadas

• Publica en producción solo después de hacer pruebas para ayudar a evitar incidencias con el soporte. Mantén el Hub de producción Oculto hasta que la configuración esté lista y, luego, ponlo En directo desde el editor del Hub.
• Hidrata el producto activo en las PDP para mantener el contexto del producto disponible en el Hub y ayudar a los compradores a añadirlo al carrito. Supervisa la tasa de conversión y los ingresos por destinatario (tasa de repetición de compra) para evaluar el efecto.
• Implementa el seguimiento de productos con antelación para completar los productos vistos recientemente y respaldar los flujos basados en la navegación. Supervisa el compromiso y los ingresos de la recuperación de navegación.
• Añade Favoritos para que los compradores puedan guardar fácilmente una lista corta. Supervisa las visitas recurrentes y la actividad de añadir al carrito.
• Usa las preguntas frecuentes para responder a preguntas sobre envíos, materiales o devoluciones mientras los compradores navegan. Controla el abandono y la tasa de conversión.
• Usa la autenticación del lado del servidor con Shopify Customer Account API cuando esté disponible para mantener la continuidad de los compradores que hayan iniciado sesión y ayudar a reducir las solicitudes de asistencia relacionadas con el inicio de sesión.

Medir el éxito

Usa Analytics > métricas para supervisar la actividad de Viewed Product. Revisa el rendimiento posterior en los flujos y las campañas. Usa los paneles de ingresos de comercio electrónico para hacer un seguimiento de los cambios en la conversión y el valor medio del pedido (valor medio del pedido) después de activar Klaviyo Customer Hub.

Supervisa la tasa de conversión de las páginas de producto, la tasa de añadir al carrito, las sesiones con aperturas del Hub (si está instrumentado), los ingresos por destinatario (tasa de repetición de compra) y los ingresos impulsados por la navegación asociados a eventos Viewed Product.

Comprobaciones rápidas

• Si la actividad de vistos recientemente es baja, verifica el seguimiento de productos y comprueba que los eventos Viewed Product se atribuyen a los perfiles. Comprueba también el seguimiento de vistos recientemente basado en el navegador.
• Si hay poca actividad de añadir al carrito desde el Hub, comprueba que la hidratación de productos activa se ejecuta en cada PDP y que las variantes y los precios son correctos.
• Si hay pocas adiciones a Favoritos, coloca la ranura de Favoritos cerca de las principales llamadas a la acción (CTA) de la página del producto y confirma que data-product-id 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, que el ID de la empresa está configurado y que Klaviyo Customer Hub está en vivo. Para cambiar el estado, ve a Klaviyo Customer Hub > Settings > Open editor y usa el desplegable de estado.

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

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

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

Causa probable: Falta o está incompleto el seguimiento de productos.

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

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

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

Corrección: añade <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 a las funciones y la visibilidad en Klaviyo, y selecciona las preguntas frecuentes para las páginas de producto. Klaviyo Customer Hub también debe estar Activo para que aparezca el widget de Favoritos.

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

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

Solució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". Elimina data-k-hub-ignore solo de los enlaces que deban abrir el Hub.

Síntoma: con la API de cuentas de cliente de Shopify seleccionada, no se reconoce que los compradores hayan iniciado sesión en el 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 cuenta de cliente de Shopify para iniciar sesión?

R: 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 cuenta de cliente de Shopify para disfrutar de una experiencia fluida.

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

A: Para la API de cuenta de cliente de Shopify, proporciona la ruta de inicio de sesión y la ruta de cierre de sesión. La ruta de gestión de la cuenta y la ruta de gestión de direcciones son opcionales para un enlace más profundo.

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

A: Usa el token de acceso público de la tienda en el canal Headless de Shopify. Sigue la guía de configuración de Storefront API de Shopify y, a continuación, introduce el token público en el campo Clave pública de Storefront API de Klaviyo.

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

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

A: Sí. Configura Favoritos y preguntas frecuentes en Klaviyo y, luego, añade los divs de su contenedor a las páginas de producto. Su visibilidad en el hub y en las páginas de producto depende de la configuración que elijas.