Comment configurer Klaviyo Customer Hub avec Shopify headless

Connectez Klaviyo Customer Hub à votre vitrine Shopify headless. Activez la connexion, mettez en avant des widgets (Favoris, FAQ) et alimentez les expériences produit Actifs/Récemment consultés pour augmenter l’engagement et la conversion.

Objectif de cet article

Vous connecterez Klaviyo Customer Hub à une vitrine headless Shopify, choisirez une méthode de connexion et publierez le Hub afin que les acheteurs puissent y accéder sur l’ensemble du site.

Avant de commencer

Prérequis

• Une vitrine Shopify headless avec accès à l’API Storefront (jeton d’accès public/clé publique d’API Storefront dans l’administrateur headless de Shopify).
• Votre ID d’entreprise Klaviyo (utilisé par le chargeur JavaScript onsite).
• Décision concernant la connexion des acheteurs : API Shopify Customer Account ou mot de passe à usage unique Klaviyo (OTP).
  • Si vous utilisez des comptes existants, préparez les itinéraires Connexion, Déconnexion et (facultatif) Gérer le compte et Gérer les adresses de votre vitrine.
• Possibilité de modifier le code de votre vitrine et de déployer des changements.
• Un rôle de compte autorisé à modifier Klaviyo Customer Hub, comme propriétaire ou administrateur. Pour un rôle personnalisé, incluez les autorisations d’affichage et de modification de Klaviyo Customer Hub.
• Un essai de Klaviyo Customer Hub ou un forfait incluant les Favoris et les FAQ, si vous souhaitez utiliser ces fonctionnalités.

Vue d’ensemble

Klaviyo Customer Hub est une superposition à l’échelle du site qui permet aux acheteurs d’accéder plus rapidement aux actions liées au compte et à des outils d’achat utiles. Pour Shopify headless, vous connectez le script onsite de Klaviyo, choisissez une méthode de connexion (API Shopify Customer Account ou OTP Klaviyo) et, si vous le souhaitez, ajoutez :

• Produit actif: affiche le produit qu’un acheteur consulte dans le Hub.
• Récemment consultés: répertorie les produits consultés récemment à l’aide du tracking de Klaviyo.
• Widgets Favoris et FAQs : s’affichent sur les pages de détail produit (PDP) et dans le Hub.

Utilisez Klaviyo Customer Hub lorsque vous souhaitez une couche d’assistance sur la page qui favorise la découverte de produits et un passage en caisse plus rapide, améliorant la conversion et la valeur vie.

Configuration

1. Configurez les paramètres de Klaviyo Customer Hub

Tout d’abord, suivez Démarrer avec Klaviyo Customer Hub et terminez l’assistant d’intégration. Gardez Klaviyo Customer Hub masqué jusqu’à ce que votre configuration headless soit prête. Ensuite, accédez à Klaviyo Customer Hub > Paramètres, puis recherchez Configuration headless Shopify.

Activez Headless Shopify configuration et collez votre jeton d’accès public Shopify dans Storefront API public key.

Sous Connexion des acheteurs, sélectionnez Shopify Customer Account API pour utiliser votre connexion Shopify existante, ou Klaviyo One Time Password (OTP) pour une connexion qui fonctionne uniquement avec Klaviyo.

Si vous sélectionnez Shopify Customer Account API, saisissez la route de connexion et la route de déconnexion de votre vitrine. Les itinéraires de gestion du compte et de gestion des adresses sont facultatifs. Ces itinéraires redirigent les acheteurs entre le Hub et votre site.

Si vous sélectionnez Klaviyo One Time Password (OTP), saisissez Nom d’affichage de la boutique et Répondre à l’e-mail. L’e-mail de réponse ne peut pas utiliser une adresse gmail.com ou klaviyo.com.

Cliquez sur Enregistrer pour enregistrer vos paramètres. Pour vérifier le statut de publication du Hub, cliquez sur Ouvrir l’éditeur. Conservez le statut Masqué jusqu’à ce que vous terminiez la configuration de la vitrine et les tests ci-dessous.

2. Chargez le JavaScript du Klaviyo Customer Hub (instructions destinées aux développeurs)

Conseil : Si vous utilisez déjà les fonctionnalités sur site de Klaviyo, vous avez peut-être déjà un chargeur en place. Confirmez avant d’ajouter un deuxième script.

Créez /public/customerHub.js (ou équivalent) avec le chargeur suivant (remplacez COMPANY_ID par votre clé d’API publique Klaviyo, également appelée votre ID d’entreprise) :

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

Dans votre mise en page racine (par exemple : root.tsx), incluez le chargeur afin que le script onsite se charge sur chaque page. Recherchez le message de console « Klaviyo JS script loaded successfully. »

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

Une fois le Hub terminé de charger, window.customerHubApi devient disponible. Le message de réussite du chargeur confirme que le script s’est chargé ; attendez l’API du Hub avant d’appeler hydrateProduct, comme indiqué ci-dessous.

3. Afficher le produit actif dans Klaviyo Customer Hub

Ajoutez le script suivant au code HTML de votre page produit, en remplaçant your-product-handle par le handle produit Shopify actuel. Si votre vitrine utilise React ou un autre framework avec une navigation côté client, exécutez l’appel d’hydratation depuis le cycle de vie de page de ce framework à chaque fois que le produit change.

<!-- 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>

Sur ordinateur, le Hub peut afficher la fiche produit actuelle dans l’onglet Chat lorsque le chat web est activé. Cette fiche n’est pas affichée sur mobile.

4. Activer les produits récemment consultés dans Klaviyo Customer Hub

Mettez en place le tracking Viewed Product sur vos pages produit afin de pouvoir utiliser cet indicateur dans Klaviyo. Appelez également trackViewedItem pour stocker les produits récemment consultés dans le navigateur de l’acheteur pour le Hub. Suivez les exemples de tracking dans Intégrer une plateforme e-commerce sans intégration Klaviyo préconçue.

5. Activer la prise de contrôle du lien de compte

Lorsque Klaviyo Customer Hub est Live, il peut remplacer les liens de compte se terminant par /account ou /account/login afin qu’ils ouvrent le Hub. Pour ouvrir le Hub à partir d’une icône de compte personnalisée, définissez le lien sur #k-hub. Ajoutez data-k-hub-ignore à un lien de compte s’il doit continuer à ouvrir la page de compte de votre vitrine.

6. Connecter l’authentification de l’API Shopify Customer Account (recommandé)

Effectuez cette étape uniquement si vous avez sélectionné Shopify Customer Account API sous Connexion de l’acheteur. Si vous avez sélectionné Klaviyo One Time Password (OTP), passez à l’étape 7.

Ajoutez une route côté serveur à /api/authenticateCustomerHub qui accepte les requêtes POST et transmet à Klaviyo le jeton d’accès de l’acheteur connecté. Définissez COMPANY_ID dans l’exemple sur l’ID de votre entreprise Klaviyo.

L’exemple suivant utilise le framework Hydrogen de Shopify. Adaptez la route côté serveur à votre framework si vous utilisez une vitrine différente.

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

Une fois que cet itinéraire et les itinéraires de la vitrine dans les paramètres de Klaviyo sont configurés, Klaviyo Customer Hub peut se connecter à la connexion existante du compte client.

7. Ajouter le widget Favorites (recommandé)

Les favoris et les FAQ peuvent apparaître dans le tiroir Klaviyo Customer Hub. Vous pouvez également les ajouter aux pages de détails des produits afin que les acheteurs puissent enregistrer des produits et trouver des réponses pendant qu’ils naviguent.

Activez d’abord Favoris dans l’éditeur du Hub. Ensuite, accédez à Klaviyo Customer Hub > Design, sélectionnez Favorites, puis choisissez quels acheteurs peuvent voir le widget sur site. Cliquez sur Publier pour enregistrer les paramètres de votre widget, puis ajoutez le conteneur suivant à votre page produit. Remplacez l’ID de produit Shopify de l’exemple par l’ID du produit actuel.

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

Une fois que Klaviyo Customer Hub est Live et que le widget est visible pour l’acheteur, celui-ci peut cliquer sur Ajouter aux favoris sur une page produit. Les produits qu’il a enregistrés apparaissent dans l’expérience Favoris du Hub.

8. Ajoutez des blocs de FAQ (recommandé)

Créez vos blocs de FAQ dans Klaviyo. Dans Klaviyo Customer Hub > Design, sélectionnez FAQ, choisissez les questions à afficher sur les pages produit, et configurez la visibilité et le design sur le site. Cliquez sur Publier pour enregistrer vos paramètres avant d’ajouter le conteneur ci-dessous.

Ajoutez ce conteneur à votre page produit avec l’ID produit Shopify actuel. Les mêmes FAQ sélectionnées apparaissent sur toutes les pages produit ; l’ID produit ne sélectionne pas des questions différentes pour chaque produit.

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

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

Les boutons FAQ sélectionnés apparaissent sur les pages produit en fonction de vos paramètres de visibilité. Le fait de cliquer sur une question ouvre sa réponse dans Klaviyo Customer Hub.

9. Testez et mettez Klaviyo Customer Hub en ligne

Testez le code de votre vitrine en préproduction avant de le déployer en production. La prise de contrôle automatique de la liaison de compte et le widget Favoris sur site nécessitent Live; incluez-les donc dans vos vérifications finales en production.

1. Lorsque vous êtes prêt à publier, accédez à Klaviyo Customer Hub > Paramètres, puis cliquez sur Ouvrir l’éditeur.
2. Enregistrez toutes les modifications de conception du Hub en attente. Ensuite, sélectionnez En ligne dans la liste déroulante d’état, ou cliquez sur Mettre en ligne lorsque le Hub est masqué et n’a aucune modification non enregistrée.
3. Attendez la confirmation que Klaviyo Customer Hub est en ligne. Sur votre vitrine de production, vérifiez la connexion et la déconnexion, l’icône de compte, la fiche produit Chat sur ordinateur (si elle est activée), les produits consultés récemment, ainsi que tous les widgets Favoris ou FAQ que vous avez ajoutés.

Bonnes pratiques

• Ne publiez en production qu’après avoir effectué des tests, afin d’éviter des problèmes d’assistance. Gardez le Hub de production masqué jusqu’à ce que la configuration soit prête, puis définissez-le comme actif depuis l’éditeur de Hub.
• Hydratez le produit actif sur les PDP afin de conserver le contexte produit disponible dans le Hub et d’aider les acheteurs à l’ajouter à leur panier. Surveillez le taux de conversion et le chiffre d’affaires par destinataire (RPR) pour évaluer l’effet.
• Mettez en place le tracking produit dès le début afin d’alimenter les produits récemment consultés et de prendre en charge les flux basés sur la navigation. Surveillez l’engagement et les revenus issus de la récupération après navigation.
• Ajoutez les Favoris pour offrir aux acheteurs un moyen simple d’enregistrer une liste restreinte. Surveillez les visites répétées et l’activité d’ajout au panier.
• Utilisez une FAQ pour répondre aux questions sur la livraison, les matériaux, ou les retours pendant que les acheteurs parcourent le site. Surveillez les abandons et le taux de conversion.
• Utilisez l’authentification côté serveur avec l’ API Shopify Customer Account lorsque celle-ci est disponible afin d’assurer la continuité pour les clients connectés et de contribuer à réduire les demandes d’assistance liées à la connexion.

Mesurer le succès

Utilisez Analyses > Indicateurs pour surveiller l’activité Produit consulté. Examinez les performances en aval dans vos flux et campagnes. Utilisez vos tableaux de bord des revenus e-commerce pour suivre les changements de conversion et de valeur moyenne de la commande (valeur moyenne de la commande) après avoir activé Klaviyo Customer Hub.

Surveillez le taux de conversion des pages produit, le taux d’ajout au panier, les sessions avec ouvertures Hub (si instrumenté), le chiffre d’affaires par destinataire (taux de réachat), et le chiffre d’affaires issu de la navigation lié aux événements Viewed Product.

Vérifications rapides

• En cas de faible activité de consultation récente, vérifiez le tracking des produits et assurez-vous que les événements Viewed Product sont attribués aux profils. Vérifiez également le tracking des produits consultés récemment basé sur le navigateur.
• En cas de faible activité d’ajout au panier depuis le Hub, vérifiez que l’hydratation des produits active s’exécute sur chaque PDP et que les variantes ainsi que les prix sont corrects.
• Pour peu d’ajouts aux Favoris, placez l’emplacement Favoris près des appels à l’action (CTA) de la page produit principale, et confirmez que data-product-id correspond au produit.

Résolution de problèmes

Symptôme : Le Klaviyo Customer Hub n’apparaît pas sur le site.

Cause probable : le script ne se charge pas ou le Hub est Masqué.

Correctif : confirmez que customerHub.js se charge, que l’ID de l’entreprise est défini, et que Klaviyo Customer Hub est EN DIRECT. Pour changer son statut, accédez à Klaviyo Customer Hub > Paramètres > Ouvrir l’éditeur, et utilisez le menu déroulant du statut.

Symptôme: la console affiche « Failed to load Klaviyo JS script. »

Cause probable : URL de script incorrecte ou ID d’entreprise manquant.

Correctif: Vérifiez https://static.klaviyo.com/onsite/js/<COMPANY_ID>/klaviyo.js et que COMPANY_ID est renseigné.

Symptôme : La carte Produit actif ne s’affiche pas dans le hub sur les PDP.

Cause probable : l’appel d’hydratation est manquant, le handle du produit est incorrect ou vous consultez la fiche produit Chat sur mobile.

Correctif : sur ordinateur, ouvrez Chat lorsque le chat web est activé. Assurez-vous que la boucle d’attente s’exécute, et appelez window.customerHubApi.hydrateProduct("<handle>") avec le handle de produit correct.

Symptôme : la section Récemment consultés est vide.

Cause probable : tracking des produits manquant ou incomplet.

Correctif : ajouter le tracking de l'événement Viewed Product et le tracking du navigateur trackViewedItem. Vérifiez les événements sur un profil reconnu et consultez les produits récemment consultés dans le même navigateur.

Symptôme : les widget Favoris ou FAQ ne s’affichent pas sur la PDP.

Cause probable : un conteneur manquant, un ID de produit incorrect, un widget masqué ou un forfait qui n’inclut pas la fonctionnalité.

Correctif : ajoutez <div class="kl-hub-favorites-slot" data-product-id="..."></div> ou <div class="klaviyo-faqs-slot" data-product-id="..."></div> avec l’ID de produit correct. Confirmez l’accès et la visibilité des fonctionnalités dans Klaviyo, et sélectionnez des FAQ pour les pages produit. Klaviyo Customer Hub doit également être En ligne pour que le widget Favoris s’affiche.

Symptôme : Le fait de cliquer sur l’icône du compte n’ouvre pas le Hub.

Cause probable : le lien du compte ne correspond pas à une URL de compte prise en charge, est exclu de la reprise de compte, ou Klaviyo Customer Hub est masqué.

Correctif : définissez Klaviyo Customer Hub sur En ligne, utilisez un lien de compte se terminant par /account ou /account/login, ou définissez href="#k-hub". Supprimez data-k-hub-ignore uniquement des liens qui doivent ouvrir le Hub.

Symptôme : lorsque l’API des comptes clients Shopify est sélectionnée, les acheteurs ne sont pas reconnus comme étant connectés dans le hub.

Cause probable: route /api/authenticateCustomerHub manquante ou requête API en échec.

Correctif : Implémentez l’exemple Hydrogen (ou l’équivalent de votre framework), envoyez access_token et company_id au points de terminaison de connexion Klaviyo, puis renvoyez la réponse.

FAQ

Q: Dois-je utiliser la Shopify Customer Account API pour me connecter ?

R : Non. Vous pouvez plutôt utiliser le mot de passe unique (OTP) de Klaviyo. Si vous utilisez déjà des comptes Shopify, connectez-vous via l’API de compte client Shopify pour une expérience fluide.

Q: Quelles routes de boutique en ligne dois-je fournir ?

R : Pour l’ API de compte client Shopify, fournissez l’ itinéraire de connexion et l’ itinéraire de déconnexion. Les itinéraire de gestion du compte et itinéraire de gestion des adresses sont facultatifs pour une liaison plus approfondie.

Q : Où puis-je trouver la clé d’API publique de la vitrine ?

R : utilisez le jeton d’accès public pour votre vitrine dans le canal Headless de Shopify. Suivez le guide de configuration de l’API Storefront de Shopify, puis saisissez le jeton public dans le champ Clé publique de l’API Storefront de Klaviyo.

Q : Klaviyo Customer Hub peut-il remplacer mon icône de compte ?

R : Oui. Lorsque Klaviyo Customer Hub est Live, les liens se terminant par /account ou /account/login peuvent ouvrir le Hub automatiquement. Vous pouvez également faire pointer le lien de votre compte vers #k-hub.

Q : Shopify Hydrogen est-il requis ?

R : Non. L’exemple d’authentification utilise Hydrogen, mais n’importe quel framework peut mettre en œuvre une route serveur à /api/authenticateCustomerHub qui publie le jeton d’accès et le company_id sur Klaviyo.

Q : Les favoris et les FAQ peuvent-ils s’afficher sur les pages produit (PDP) et dans le Hub ?

R : Oui. Configurez les Favoris et les FAQ dans Klaviyo, puis ajoutez leurs div conteneurs à vos pages produit. Leur visibilité dans le Hub et sur les pages produit suit les paramètres que vous choisissez.