Comment configurer le Customer Hub avec Headless Shopify

Objectif de cet article

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

Avant de commencer

Prérequis 

⚠️ Remarque : avant de continuer, vous devez contacter votre représentant, votre CSM ou l’assistance Klaviyo pour activer la prise en charge de Headless Shopify pour votre compte Klaviyo afin de pouvoir accéder aux configurations nécessaires. Comment contacter l’assistance

1. Une vitrine Shopify headless avec accès à Storefront API (jeton d’accès public / clé publique API Storefront dans l’Administrateur Headless de Shopify).
2. Votre identifiant d’ entreprise Klaviyo (utilisé par le chargeur JavaScript sur site).
3. Décision concernant la connexion de l’acheteur : compte client Shopify API ou mot de passe unique Klaviyo.
   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 boutique.
4. Possibilité de modifier le code de votre vitrine et de déployer les modifications.
5. Qui peut le configurer : Vous avez besoin d’un rôle de compte qui peut modifier les paramètres du Customer Hub et publier des widgets (Propriétaire, Administrateur ou un rôle personnalisé qui dispose d’un accès en écriture au contenu et aux Clés d'API). 

Vue d’ensemble

Le Customer Hub est une fonctionnalité qui se superpose à l’ensemble du site et qui permet aux acheteurs d’accéder plus rapidement aux actions du compte et à des outils d’achat utiles. Pour Shopify headless, vous connectez le script sur site de Klaviyo, choisissez une méthode de connexion (API des comptes clients ou mot de passe unique Klaviyo) et ajoutez éventuellement :

1. Produit actif: affiche le produit qu’un acheteur consulte dans le Hub.
2. Récemment consultés: répertorie les produits récemment consultés en utilisant le tracking de Klaviyo.
3. widgets Favoris et FAQ : s’affichent sur les PDP et dans le Hub.  

Utilisez le Customer Hub lorsque vous souhaitez bénéficier d’une assistance sur la page pour accélérer la page de commande et la découverte de produits, et ainsi améliorer la conversion et la valeur vie.

Configuration

1 - Configurer les paramètres du Customer Hub

Tout d’abord, suivez Démarrer avec le Customer Hub et terminez l’assistant d’onboarding, comme pour toute autre configuration. Une fois cette étape terminée, accédez à Customer Hub > Settings. Vous verrez la section Configuration de Headless Shopify. 

Collez votre clé publique API Storefront depuis l’Administrateur Headless de Shopify (jeton d’accès public). 

Sous Connexion à l’acheteur, sélectionnez Shopify Customer Account API (recommandé pour que toutes vos applications vitrine puissent partager le même identifiant Shopify) ou Klaviyo One Time Password (OTP, mot de passe unique, fonctionne uniquement avec Klaviyo et ne connecte pas les acheteurs à d’autres applications). 

Si vous sélectionnez Shopify Customer Account API, saisissez également vos itinéraires de connexion, de déconnexion et, si vous le souhaitez,de gestion ducompte /de la gestion desadresses (utilisés pour les redirections entre le Hub et votre site). 

Visibilité de la publication : passez le Customer Hub en Actif. 

2 - Charger le JavaScript du Customer Hub (instructions pour le développeur)

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

Créez /public/customerHub.js (ou l’équivalent) avec le chargeur suivant (remplacez COMPANY_ID par votre Clé d'API publique Klaviyo, également connue sous le nom d’identifiant de votre 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 sur site se charge sur chaque page. Recherchez le message de la console : « Le script JS Klaviyo a bien été chargé. »  Dans votre mise en page racine (par exemple, root.tsx), inclure le chargeur :

// 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 le Customer Hub

Ajoutez l’appel hydrate sur votre page de détails sur le produit (PDP) afin que le produit actuel apparaisse dans le Hub :

< !—<!-- products.tsx —> <script type=« text/javascript »> (function() { function WaitForCustomerHubApi() { return new Promise((reject) => { const check = () => { if (window.customerHubApi) --> & et window.customerHubApi.hydrateProduct) {
            resolve();
          } autre {
            requestAnimationFrame(check);
          }
        }; check(); }); } WaitForCustomerHubApi().then() => {
      window.customerHubApi.hydrateProduct("your-product-handle");
    }); })();
</script>

Le Hub doit maintenant afficher une carte 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 le Customer Hub

Mettez en œuvre le tracking Viewed Product afin que le Hub puisse remplir les articles récemment consultés et que vous puissiez utiliser l'indicateur ailleurs dans Klaviyo. Les extraits de tracking suivants peuvent également être ajoutés directement à votre boutique. Vous trouverez des instructions dans notre documentation sur les développeurs Klaviyo : Intégrer une plateforme e-commerce sans intégration Klaviyo préconçue.

5 - Activer la prise de contrôle des liens du compte

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

6 - Configurer le Customer Hub avec l’authentification de l’API des comptes clients (recommandé)

Afin d’utiliser les comptes clients de votre boutique et la configuration de l’authentification, le Customer Hub vous demandera d’ajouter à votre boutique un nouvel itinéraire API qui se chargera de transmettre en toute sécurité à nos services le jeton d’accès d’un acheteur connecté. Ce qui est important, c’est que la nouvelle route API porte un nom et qu’elle soit accessible avec « /api/authenticateCustomerHub ».

Remarque : l’exemple d’extrait de code ci-dessous concerne le cadre Hydrogen de Shopify. Des boutiques plus personnalisées peuvent nécessiter une solution de contournement supplémentaire, mais l’approche générale sera décrite ici.

// ./app/routes/api.authenticateCustomerHub.js // TODO: Configuration const COMPANY_ID = ''; export async function action({context}) { // Extraire le Customer Account API Client du contexte de votre boutique {customerAccount} = context ; essayez { // Obtenir le jeton d’accès pour le compte client actuel accessToken = await customerAccount.getAccessToken();
    if (!accessToken) { return new Response(JSON.stringify({message: 'User not logged in'}), {
        status: 200,
      }); } // Envoyez le jeton d’accès au 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();
    // Retourner la réponse réelle du Customer Hub avec le même code de statut retourner new Response(responseData, { status: response.status,
      en-têtes : {
        'Content-Type':
          response.headers.get('content-type') || 'application/json',
      }, }); } catch (erreur) { return new Response(null, {status: 500}); } }

Une fois cette configuration terminée, ainsi que les itinéraires de la boutique définis dans les paramètres de Klaviyo, le Customer Hub pourra se connecter à la configuration de votre authentification et fournir un point d’accès fluide à vos comptes clients existants.

7 - Ajouter le widget des favoris (recommandé)

Les favoris et les FAQ fonctionneront dans le tiroir du Customer Hub. Cependant, vous pouvez également ajouter ces widgets sur les PDP pour un engagement supplémentaire.

Pour ajouter un point d’entrée Favoris sur les PDP et dans le Hub :

// products.tsx // Exemples d’identifiants : // 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 les articles préférés du Hub. 

8 - Ajouter des blocs de FAQ (recommandé)

Comme pour les Favoris, l’ajout de blocs de FAQ est aussi simple que l’ajout d’un code de réduction sur votre page produit avec son identifiant de produit transmis pour afficher les FAQ que vous pouvez modifier et concevoir dans Klaviyo.

Ajoutez un bloc de FAQ spécifique à votre produit que vous concevez dans Klaviyo :

// products.tsx // Exemple : const gid = « gid://shopify/Product/12345 »; const productId = gid.split('/').pop();

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

Les puces/boutons FAQ doivent désormais s’afficher sur les PDP s’ils sont configurés, et sont modifiables dans Klaviyo

Bonnes pratiques

1. Publiez le contenu en production uniquement après vérification : gardez la mise en scène cachée jusqu’à ce que l’assurance qualité soit terminée, puis activez le Hub pour l’exposer. Impact : moins de problèmes d’assistance, délai de rentabilité plus court.
2. Hydratez toujours le produit actif sur les PDP : le contexte produit reste visible dans le Hub et incite à ajouter le produit au panier. Impact : taux de conversion, RPR.
3. Mettez en œuvre le tracking Viewed Product de manière anticipée : alimente les flux Récemment consultés et débloque les flux basés sur la navigation. Impact : engagement et chiffre d’affaires générés par la récupération de la navigation.
4. Ajouter des favoris : crée une action d’enregistrement facile et une liste restreinte persistante. Impact : visites répétées, ajout au panier.
5. Utilisez les FAQ pour les objections : répondez aux questions sur l’expédition, le matériel ou les retours en ligne afin de réduire le décrochage. Impact : taux de conversion.
6. Privilégiez l’authentification côté serveur avec l’API des comptes clients lorsque celle-ci est disponible. Elle améliore la continuité pour les acheteurs connectés. Impact : qualité de l’expérience, repli sur soi.  

Mesurer le succès

Où consulter les résultats : Utilisez Analyses > Indicateurs pour suivre l’activité des produits consultés 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 commande après l’activation du Customer Hub. Indicateurs clés à surveiller : taux de conversion de la PDP, taux d’ajout au panier, sessions avec ouvertures du Hub (si elles sont instrumentées), chiffre d’affaires par destinataire (RPR) et chiffre d’affaires généré par la navigation lié aux événements Viewed Product. Checklist des correctifs rapides : Faible activité récemment consultée ? Vérifiez que l’extrait de tracking Viewed Product se déclenche et que les événements sont attribués aux profils. Le Hub vous permet d’ajouter peu de produits à votre panier ? Assurez-vous que l’hydratation du produit actif fonctionne sur chaque PDP et que les variantes/prix sont corrects. Vous ajoutez peu de favoris ? Placez l’emplacement Favoris près des CTA principaux de votre PDP et vérifiez que l’identifiant du produit correspond au produit.  

Résolution de problèmes

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

Cause probable : Script non chargé ou Hub masqué.

Correction : vérifiez que customerHub.js se charge (vérifiez la console), que l’ identifiant de l’entreprise est défini et que la visibilité du Customer Hub est en ligne dans Customer Hub > Settings. 

Symptôme : la console affiche « Échec du chargement du script JS Klaviyo ».

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

Correction : vérifiez que https://static.klaviyo.com/onsite/js/<COMPANY_ID>/klaviyo.js est renseigné. 

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

Cause probable : hydrateProduit non appelé ou mauvais descripteur de produit.

Correction : assurez-vous que la boucle d’attente fonctionne et appelez window.customerHubApi.hydrateProduct(« <handle>») avec le bon descripteur de produit. 

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

Cause probable : tracking Viewed Product non mis en œuvre.

Correction : ajoutez l’extrait de tracking Viewed Product du guide de développement et vérifiez les événements dans Klaviyo. 

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

Cause probable : conteneur manquant ou attribut incorrect.

Corrigez : ajoutez <div class=« kl-hub-favorites-slot » data-product-id= »...« > et/ou <div class= »Klaviyo-faqs-slot » data-product-id= »...« > avec le bon identifiant de produit. 

Symptôme : lorsque vous cliquez sur l’icône du compte, le Hub ne s’ouvre pas.

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

Correction : assurez-vous que l’ancrage du compte utilise /account (auto-take-over) ou set href= »#k-hub ». 

Symptôme : les acheteurs ne sont pas reconnus comme connectés dans le Hub.

Cause probable : itinéraire /api/authenticateCustomerHub manquant ou échec de la demande API.

Correction : mettez en œuvre l’exemple Hydrogen (ou l’équivalent de votre framework), envoyez access_token et company_id au points de terminaison de connexion de Klaviyo, puis renvoyez la réponse. 

FAQ

Q : Dois-je utiliser l’API des comptes clients Shopify pour me connecter ?

A : Non. Vous pouvez utiliser Klaviyo One Time Password (OTP) à la place. Si vous utilisez déjà des comptes Shopify, connectez-vous via l’API des comptes clients pour une expérience fluide. 

Q : Quels itinéraires dois-je proposer ?

R : Si vous utilisez vos comptes existants, fournissez les itinéraires de connexion et de déconnexion ; les options Gérer le compte et Gérer les adresses sont facultatives pour une liaison plus approfondie. 

Q : Où puis-je trouver la clé publique API Storefront ?

A : Dans l’Administrateur headless de Shopify sous Storefront API > Jeton d’accès public (également appelé clé publique API Storefront). 

Q : Le Customer Hub peut-il prendre le contrôle de l’icône de mon compte ?

R : Oui. Si le lien du compte de votre en-tête utilise /account, le Customer Hub peut s’ouvrir automatiquement. Vous pouvez également le diriger vers #k-hub. 

Q : Shopify Hydrogen est-il nécessaire ?

A : Non. L’exemple d’authentification utilise Hydrogen, mais n’importe quel framework peut mettre en œuvre un itinéraire de serveur dans /api/authenticateCustomerHub qui poste le jeton d’accès et company_id sur Klaviyo. 

Q : Les favoris et les FAQ peuvent-ils être intégrés aux PDP et au Hub ?

R : Oui. Ajoutez les conteneurs div respectifs sur les PDP ; ils apparaîtront également dans le tiroir Hub.