Zo stel je Klaviyo Customer Hub in met headless Shopify
Verbind Klaviyo Customer Hub met je headless Shopify-storefront. Schakel inloggen in, toon widgets (Favorieten, veelgestelde vragen) en gebruik actieve/recent bekeken productervaringen om betrokkenheid en conversie te verhogen.
Wat je leert
Je koppelt Klaviyo Customer Hub aan een headless Shopify-storefront, kiest een inlogmethode en publiceert de Hub zodat shoppers er sitebreed toegang toe hebben.
Klaviyo Customer Hub voor Shopify ondersteunt momenteel standaard storefronts en Shopify Headless. Voor WooCommerce ga je naar https://help.klaviyo.com/hc/es-es/articles/47792369863451
Voor feedback over de functionaliteit van Klaviyo Customer Hub kun je een e-mail sturen naar customerhub@klaviyo.com.
Voordat je van start gaat
Vereisten
- Een headless Shopify-storefront met toegang tot de Storefront API (openbare toegangstoken/Storefront API openbare sleutel in Shopify’s Headless-beheerder).
- Je Klaviyo-bedrijfs-ID (gebruikt door de onsite JavaScript-loader).
- Beslissing over shopper-login: Shopify Customer Account API of Klaviyo One Time Password (OTP).
- Als je bestaande account gebruikt, zorg dan dat je routes voor Inloggen, Uitloggen en (optioneel) Account beheren en Adressen beheren voor je webshop klaarstaan.
- Mogelijkheid om je webshopcode te bewerken en wijzigingen te implementeren.
- Wie dit kan instellen: Je hebt een accountrol nodig waarmee je instellingen voor Klaviyo Customer Hub kunt bewerken en widgets kunt publiceren (eigenaar, Beheerder of een aangepaste rol met schrijftoegang tot Content en API-sleutels).
Overzicht
Klaviyo Customer Hub is een overlay voor de hele site waarmee shoppers sneller toegang krijgen tot accountacties en handige shoppingtools. Voor headless Shopify koppel je Klaviyo's on-site script, kies je een inlogmethode (Customer Accounts API of Klaviyo OTP) en voeg je optioneel het volgende toe:
- Actief product: toont het product dat een shopper bekijkt in de Hub.
- Onlangs bekeken: toont onlangs bekeken producten met Klaviyo’s tracking.
- Favorieten - en Veelgestelde vragen -widgets: worden weergegeven op PDP's en in de hub.
Gebruik Klaviyo Customer Hub wanneer je een assistentielaag op de pagina wilt die productontdekking en sneller afrekenen stimuleert, waardoor conversie en levenslange waarde verbeteren.
Instelling
1 - Instellingen van Klaviyo Customer Hub configureren
Volg eerst Aan de slag met Klaviyo Customer Hub en voltooi de onboardingwizard, net als bij elke andere setup. Zodra dit is voltooid, ga je naar Klaviyo Customer Hub > Instellingen. Je ziet de sectie Headless Shopify-configuratie.
Schakel Headless Shopify-configuratie in en plak vervolgens je openbare Storefront API-sleutel uit de Headless Admin van Shopify (openbaar toegangstoken).
Selecteer onder Inloggen voor shoppers Shopify Customer Account API (aanbevolen, zodat al je storefront-apps Shopify's inlog kunnen delen) of Klaviyo One Time Password (OTP, werkt alleen met Klaviyo en logt shoppers niet in bij andere apps).
Als je Shopify Customer Account API selecteert, voer dan ook je storefront-routes voor Inloggen, Uitloggen en optioneel Account beheren/Adressen beheren in (gebruikt voor redirects tussen de Hub en je site).
Zichtbaarheid bij publiceren: stel Klaviyo Customer Hub in op Live.
2 - Laad de Klaviyo Customer Hub-JavaScript (instructies voor ontwikkelaars)
Tip: Als je al Klaviyo-functies op je site gebruikt, heb je mogelijk al een loader ingesteld. Bevestig dit voordat je een tweede script toevoegt.
Maak /public/customerHub.js (of een equivalent) met de volgende loader (vervang COMPANY_ID door je Klaviyo openbare API-sleutel, ook wel je bedrijfs-ID genoemd):
// 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);Het onsite-script wordt op elke pagina geladen. Zoek naar het consolebericht: "Klaviyo JS script loaded successfully." In je rootlayout (bijv. root.tsx), neem je de loader op:
// root.tsx
return (
<html>
<body>
<script src="/customerHub.js" defer></script>
</body>
</html>
)Na deze stap wordt window.customerHubApi beschikbaar op pagina's waar de Hub draait.
3 - Het actieve product weergeven in Klaviyo Customer Hub
Voeg de hydrate-aanroep toe op je productdetailpagina (PDP), zodat het huidige product in de hub wordt weergegeven:
<!-- 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>De Hub moet nu een extra productkaart weergeven voor de PDP die de shopper bekijkt op het tabblad "Chat", als je dit hebt ingeschakeld.
4 - Recent bekeken producten inschakelen in Klaviyo Customer Hub
Implementeer tracking van Product bekeken zodat de Hub Onlangs bekeken -items kan invullen en je de meetwaarde elders in Klaviyo kunt gebruiken. De volgende tracking-snippets kunnen ook rechtstreeks aan je storefront worden toegevoegd; instructies vind je hier in onze Klaviyo Developers-documentatie: Een e-commerceplatform integreren zonder een vooraf gebouwde Klaviyo-integratie.
5 - Accountlinkovername inschakelen
Zodat de Klaviyo Customer Hub wordt geopend wanneer je in de header van je webshop op het accountpictogram klikt, moet je al een bestaande a-tag hebben die verwijst naar een link met /account (in dat geval vervangen we deze automatisch voor je). Of je kunt ook handmatig instellen dat de icon-link verwijst naar #k-hub om de drawer te openen.
6 - Stel Klaviyo Customer Hub in met authenticatie via de Customer Accounts API (aanbevolen)
Om de bestaande customer accounts en authenticatie-instelling van je webshop te gebruiken, moet je voor Klaviyo Customer Hub een nieuwe API-route aan je webshop toevoegen die het access token van een ingelogde shopper veilig aan onze services doorgeeft. Wat belangrijk is, is dat de nieuwe API-route een naam heeft en bereikbaar is via ‘/api/authenticateCustomerHub’.
Opmerking: het volgende codefragment is een voorbeeld voor Shopify's Hydrogen-framework. Meer aangepaste webshops vereisen mogelijk extra workarounds, maar de algemene aanpak wordt hier uitgelegd.
// ./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});
}
}Zodra dit is geconfigureerd, en ook de storefront-routes zijn gedefinieerd in de instellingen van Klaviyo, kan Klaviyo Customer Hub koppelen met je bestaande authenticatieconfiguratie en een naadloos startpunt bieden voor je bestaande klantaccounts.
7 - Voeg de widget Favorieten toe (aanbevolen)
Zowel Favorieten als veelgestelde vragen werken in de Klaviyo Customer Hub-lade. Je kunt deze widget echter ook toevoegen op PDP's voor extra betrokkenheid.
Om een favorieten-ingangspunt toe te voegen op PDP's en in de 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}
/>
)Shoppers kunnen nu op Toevoegen aan favorieten klikken op PDP's; het item verschijnt in de Favoriete items van de Hub.
8 - FAQ-blokken toevoegen (aanbevolen)
Net als bij het toevoegen van Favorieten is het toevoegen van FAQ-blokken net zo eenvoudig als het toevoegen van een div op je productpagina, met de product-ID die wordt doorgegeven om FAQ’s te renderen die je in Klaviyo kunt bewerken en ontwerpen.
Voeg een productspecifiek blok met veelgestelde vragen toe dat je ontwerpt in 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} />
)FAQ-chips/knoppen zouden nu op PDP's moeten worden weergegeven als ze zijn ingesteld, en zijn bewerkbaar in Klaviyo
Best practices
- Publiceer pas naar productie na verificatie – houd staging verborgen totdat QA is voltooid; stel daarna Live in om de hub zichtbaar te maken. Impact: minder supportproblemen, snellere time-to-value.
- Hydrateer het actieve product op PDP's altijd – houdt de productcontext zichtbaar in de Hub en stimuleert toevoegen aan winkelwagen. Impact: conversiepercentage, percentage herhaalaankopen.
- Implementeer Viewed Product-tracking vroeg – vult Onlangs bekeken aan en ontgrendelt browse-based flow. Impact: betrokkenheid en omzet uit browse recovery.
- Favorieten toevoegen — maakt een soepele opslagactie en een blijvende shortlist. Impact: herhaalbezoeken, toevoegen aan winkelwagen.
- Gebruik veelgestelde vragen voor bezwaren – beantwoord vragen over verzending, materialen of retourneren inline om afhaken te verminderen. Impact: conversiepercentage.
- Geef de voorkeur aan server-side auth met Customer Accounts API wanneer beschikbaar — verbetert de continuïteit voor ingelogde shoppers. Impact: kwaliteit van de ervaring, minder supportvragen.
Succes meten
Waar je resultaten kunt bekijken: gebruik Analytics > Meetwaarden om de activiteit van Viewed Product en de downstream prestaties van flows/campagnes te monitoren. Gebruik je e-commerce omzetdashboard(s) om conversie en veranderingen in de gemiddelde bestelwaarde te volgen nadat je Klaviyo Customer Hub hebt ingeschakeld. Belangrijke meetwaarden om in de gaten te houden: conversiepercentage vanaf PDP, add-to-cart-percentage, sessies met Hub-openingen (indien geïnstrumenteerd), inkomsten per ontvanger (RPR) en browse-gedreven omzet die is gekoppeld aan Viewed Product-events. Checklist met snelle fixes: Lage Recently viewed-activiteit? Controleer of de Viewed Product -tracking snippet wordt geactiveerd en of events aan profielen worden toegeschreven. Laag add-to-cart vanuit Hub? Zorg ervoor dat Actief Product -hydration op elke PDP wordt uitgevoerd en dat variaties/prijzen correct zijn. Weinig toevoegingen aan Favorieten? Verplaats de Favorieten-slot naar de buurt van de belangrijkste PDP-CTA's en bevestig dat de data-product-id overeenkomt met het product.
Probleemoplossing
Symptoom: Klaviyo Customer Hub wordt niet op de site weergegeven.
Waarschijnlijke oorzaak: Script wordt niet geladen of Hub is Verborgen.
Oplossing: Bevestig dat customerHub.js wordt geladen (controleer de console), dat de company ID is ingesteld en dat de zichtbaarheid van Klaviyo Customer Hub Live is in Klaviyo Customer Hub > Instellingen.
Symptoom: De console toont "Failed to load Klaviyo JS script."
Waarschijnlijke oorzaak: onjuiste script-URL of ontbrekende bedrijfs-ID.
Oplossing: Controleer https://static.klaviyo.com/onsite/js/<COMPANY_ID>/klaviyo.js en of COMPANY_ID is ingevuld.
Symptoom: de kaart voor actief product wordt niet weergegeven in de hub op PDP's.
Waarschijnlijke oorzaak: hydrateProduct niet aangeroepen of onjuiste product-handle.
Oplossing: Zorg dat de wachlus wordt uitgevoerd en roep window.customerHubApi.hydrateProduct("<handle>") aan met de juiste product-handle.
Symptoom: sectie Recent bekeken is leeg.
Waarschijnlijke oorzaak: tracking van bekeken producten niet geïmplementeerd.
Oplossing: Voeg het tracking-snippet Viewed Product toe vanuit de ontwikkelaarshandleiding en verifieer gebeurtenissen in Klaviyo.
Symptoom: Favorieten- of FAQ-widgets worden niet weergegeven op de PDP.
Waarschijnlijke oorzaak: Ontbrekende container of onjuist kenmerk.
Oplossing: Voeg <div class="kl-hub-favorites-slot" data-product-id="..."> en/of <div class="klaviyo-faqs-slot" data-product-id="..."> toe met de juiste product-ID.
Symptoom: Als je op het accountpictogram klikt, wordt de Hub niet geopend.
Waarschijnlijke oorzaak: De headerlink verwijst niet naar /account of #k-hub.
Oplossing: Zorg dat het accountanker /account gebruikt (auto‐takeover) of stel href="#k-hub" in.
Symptoom: Shoppers worden niet herkend als ingelogd in de Hub.
Waarschijnlijke oorzaak: Ontbrekende /api/authenticateCustomerHub-route of mislukte API-aanvraag.
Oplossing: Implementeer het Hydrogen-voorbeeld (of het equivalent voor je framework), stuur access_token en company_id naar het login-eindpunt van Klaviyo en retourneer de response.
Veelgestelde vragen
V: Moet ik de Shopify Customer Accounts API gebruiken voor inloggen?
A: Nee. Je kunt in plaats daarvan Eenmalig wachtwoord van Klaviyo (OTP, One Time Password) gebruiken. Als je al Shopify-accounts gebruikt, maak dan verbinding via de API voor klantaccounts voor een naadloze ervaring.
V: Welke storefront-routes moet ik aanleveren?
A: Als je je bestaande accounts gebruikt, geef dan routes voor Inloggen en Uitloggen op; Account beheren en Adressen beheren zijn optioneel voor diepere links.
V: Waar vind ik de openbare storefront-API-sleutel?
A: In Shopify's Headless Beheerder onder Storefront API > Openbaar toegangstoken (ook wel Storefront API openbare sleutel genoemd).
V: Kan Klaviyo Customer Hub mijn accountpictogram overnemen?
A: Ja. Als de accountlink van je header /account gebruikt, kan Klaviyo Customer Hub automatisch openen; je kunt deze ook verwijzen naar #k-hub.
V: Is Shopify Hydrogen vereist?
A: Nee. In het authenticatievoorbeeld wordt Hydrogen gebruikt, maar elk framework kan een serverroute implementeren op /api/authenticateCustomerHub die het access token en company_id naar Klaviyo post.
V: Kunnen favorieten en veelgestelde vragen op productdetailpagina’s (PDP’s) en in de Hub staan?
A: Ja. Voeg de respectieve container-divs toe op PDP's; ze verschijnen ook in de Hub-lade.