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

1. 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).
2. Votre ID d’entreprise Klaviyo (utilisé par le chargeur JavaScript onsite).
3. Décision concernant la connexion des acheteurs : API Shopify Customer Account ou mot de passe à usage unique Klaviyo (OTP).
   1. 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.
4. Possibilité de modifier le code de votre vitrine et de déployer des changements.
5. Qui peut configurer cela : vous devez disposer d’un rôle de compte qui peut modifier les paramètres de Klaviyo Customer Hub et publier des widgets (propriétaire, administrateur ou rôle personnalisé disposant d’un accès en écriture au contenu et aux clés d’API).

Vue d’ensemble

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

1. Produit actif: affiche le produit qu’un acheteur consulte dans le Hub.
2. Récemment consultés: répertorie les produits consultés récemment à l’aide du tracking de Klaviyo.
3. Widgets Favoris et FAQ : s’affichent sur les pages produit 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 - Configurer les paramètres de Klaviyo Customer Hub

Tout d’abord, suivez Démarrer avec Klaviyo Customer Hub et terminez l’assistant d’intégration, comme pour toute autre configuration. Une fois cette opération terminée, accédez à Klaviyo Customer Hub > Paramètres. Vous verrez la section Configuration Shopify headless.

Activez Headless Shopify configuration, puis collez votre clé d’API publique Storefront depuis Headless Admin de Shopify (jeton d’accès public).

Sous Connexion de l’acheteur, sélectionnez Shopify Customer Account API (recommandé afin que toutes vos applications de vitrine puissent partager la connexion Shopify) ou Klaviyo One Time Password (OTP, fonctionne uniquement avec Klaviyo et ne connectera pas les acheteurs à d’autres applications).

Si vous sélectionnez Shopify Customer Account API, saisissez également les itinéraires de votre vitrine Connexion, Déconnexion et, en option, Gérer le compte/Gérer les adresses (utilisés pour les redirections entre le Hub et votre site).

Visibilité de publication : définissez Klaviyo Customer Hub sur En ligne.

2 - Charger le JavaScript de Klaviyo Customer Hub (instructions pour les 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);

Le script onsite se charge sur chaque page. Recherchez le message de la console : « Klaviyo JS script loaded successfully. »  Dans votre mise en page racine (p. ex., root.tsx), inclure le loader :

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

Après cette étape, window.customerHubApi devient disponible sur les pages où le Hub s’exécute.

3 - Afficher le produit actif dans Klaviyo Customer Hub

Ajoutez l’appel hydrate sur votre page de détails du produit (PDP) afin que le produit actuel apparaisse dans le 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>

Le Hub doit désormais afficher une carte de produit supplémentaire pour le PDP que l’acheteur consulte dans l’onglet "Chat" si vous l’avez activé.

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

Implémentez le tracking des produits consultés afin que le Klaviyo Customer Hub puisse renseigner les éléments Récemment consultés et que vous puissiez utiliser l’indicateur ailleurs dans Klaviyo. Les extraits de code de tracking suivants peuvent également être ajoutés directement à votre vitrine. Vous trouverez les instructions ici, dans notre documentation Klaviyo Developers : Intégrer une plateforme e-commerce sans intégration Klaviyo préconfigurée.

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

Pour que le Klaviyo Customer Hub s’ouvre en cliquant sur l’icône de compte dans l’en-tête de votre vitrine, vous devez déjà disposer d’un tag a existant qui référence un lien avec /account (dans ce cas, nous le remplacerons automatiquement pour vous). Vous pouvez aussi définir manuellement le lien de l’icône pour qu’il pointe vers #k-hub afin d’ouvrir le tiroir.

6 - Configurer Klaviyo Customer Hub avec l’authentification de l’API Customer Accounts (recommandé)

Pour utiliser les comptes clients et la configuration d’authentification de votre vitrine existante, Klaviyo Customer Hub vous demandera d’ajouter une nouvelle route API à votre vitrine, qui gérera la transmission sécurisée du jeton d’accès d’un acheteur connecté à nos services. L’important est que la nouvelle route API soit nommée et accessible via « /api/authenticateCustomerHub ».

Remarque : l’exemple d’extrait de code suivant concerne le framework Hydrogen de Shopify ; des vitrines plus personnalisées peuvent nécessiter une solution de contournement supplémentaire, mais l’approche générale est présentée ici.

// ./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 cette configuration effectuée, ainsi que les routes de la vitrine définies dans les paramètres de Klaviyo, Klaviyo Customer Hub pourra se lier à votre configuration d’authentification existante et fournir un point d’entrée fluide vers vos comptes client existants.

7 - Ajoutez le widget Favoris (recommandé)

Les Favoris et les FAQ fonctionneront tous les deux dans le tiroir Klaviyo Customer Hub. Cependant, vous pouvez également ajouter ces widgets sur les PDP pour renforcer l’engagement.

Pour ajouter un point d’entrée Favoris sur les PDP et dans le 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}
  />
)

Les acheteurs peuvent désormais cliquer sur Ajouter aux favoris sur les PDP ; l’article apparaît dans Articles favoris du Hub.

8 - Ajouter des blocs de FAQ (recommandé)

Comme pour l’ajout de favoris, l’ajout de blocs de FAQ est aussi simple que d’ajouter une div sur votre page produit, avec l’ID du produit transmis pour afficher des FAQ que vous pouvez modifier et concevoir dans Klaviyo.

Ajoutez un bloc de FAQ spécifique à un produit que vous concevez dans 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} />
)

Les puces/boutons de FAQ devraient maintenant s’afficher sur les PDP s’ils sont configurés, et ils sont modifiables dans Klaviyo

Bonnes pratiques

1. Ne publiez en production qu’après vérification — gardez l’environnement de préproduction masqué jusqu’à la fin du QA, puis définissez Live pour exposer le Hub. Impact : moins de problèmes de support, une rentabilisation plus rapide.
2. Toujours hydrater le produit actif sur les PDP — conserve le contexte produit visible dans le Hub et incite à l’ajout au panier. Impact : taux de conversion, taux de réachat.
3. Mettre en œuvre tôt le tracking Viewed Product — alimente la section Récemment consultés et déverrouille les flux basés sur la navigation. Impact : engagement et revenus provenant de la récupération des abandons de navigation.
4. Ajouter des favoris — crée une action d’enregistrement simple et une liste restreinte persistante. Impact : visites répétées, ajout au panier.
5. Utilisez les FAQ pour traiter les objections — répondez directement aux questions sur l’expédition, les matériaux ou les retours afin de réduire l’abandon. Impact : taux de conversion.
6. Privilégiez l’authentification côté serveur avec l’API Customer Accounts lorsqu’elle est disponible — cela améliore la continuité pour les acheteurs connectés. Impact : qualité de l’expérience, diminution des demandes de support. 

Mesurer le succès

Où consulter les résultats : Utilisez Analyse > Indicateurs pour surveiller l’activité Viewed Product et les performances des flux/campagnes en aval. Utilisez vos tableaux de bord de chiffre d’affaires e-commerce pour suivre les changements de conversion et de valeur moyenne de la commande après l’activation de Klaviyo Customer Hub. Indicateurs clés à surveiller : taux de conversion à partir de la PDP, taux d’ajout au panier, sessions avec ouvertures de Hub (si instrumentées), chiffre d’affaires par destinataire (chiffre d’affaires par destinataire), et chiffre d’affaires généré par la navigation lié aux événements Viewed Product. Liste de contrôle des corrections rapides : faible activité « Récemment consulté » ? Vérifiez que l’extrait de code de tracking Viewed Product se déclenche et que les événements sont attribués aux profils. Faible ajout au panier depuis le Hub ? Assurez-vous que l’hydratation Produit actif s’exécute sur chaque PDP et que les variantes/prix sont corrects. Peu d’ajouts aux Favoris ? Déplacez l’emplacement Favoris près des CTA principaux de la PDP et confirmez que le 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 (vérifiez la console), que l’ ID de l’entreprise est défini et que la visibilité de Klaviyo Customer Hub est sur En ligne dans Klaviyo Customer Hub > Paramètres.

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 : hydrateProduct n’a pas été appelé ou le handle du produit est incorrect.

Correctif : 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 : le tracking Viewed Product n’est pas implémenté.

Solution : Ajoutez l’extrait de code de tracking Viewed Product depuis le guide du développeur et vérifiez les événements dans Klaviyo.

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

Cause probable : Conteneur manquant ou attribut incorrect.

Correctif : Ajoutez <div class="kl-hub-favorites-slot" data-product-id="..."> et/ou <div class="klaviyo-faqs-slot" data-product-id="..."> avec l’ID de produit correct.

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

Cause probable : Le lien d’en-tête ne pointe pas vers /account ou #k-hub.

Correctif: Assurez-vous que l’ancre du compte utilise /account (auto‐takeover) ou définissez href="#k-hub".

Symptôme : 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 l’API Shopify Customer Accounts pour la connexion ?

R : Non. Vous pouvez utiliser Mot de passe unique de Klaviyo (OTP) à la place. Si vous utilisez déjà les comptes Shopify, connectez-vous via l’API Customer Accounts pour une expérience fluide.

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

R : Si vous utilisez vos comptes existants, fournissez des routes Connexion et Déconnexion ; Gérer le compte et Gérer les adresses sont facultatifs pour un lien plus profond.

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

R : Dans l’administrateur Headless de Shopify, sous Storefront API > Jeton d’accès public (également appelé clé publique de l’API Storefront).

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

R : Oui. Si le lien de compte de votre en-tête utilise /account, Klaviyo Customer Hub peut s’ouvrir automatiquement ; vous pouvez également le diriger 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. Ajoutez les div de conteneur correspondantes sur les PDP ; elles s’afficheront également dans le tiroir du Hub.