Hoe Klaviyo Customer Hub instellen met Headless Shopify
Verbind Klaviyo Customer Hub met je headless Shopify winkel. Maak inloggen, oppervlaktewidgets (favorieten, veelgestelde vragen) en Power Actief/Recent Bekeken productervaringen mogelijk om betrokkenheid en conversie te verhogen.
Wat je leert
Je verbindt Klaviyo Customer Hub met een headless Shopify storefront, kiest een inlogmethode en publiceert de Hub zodat shoppers er overal toegang toe hebben.
Klaviyo Customer Hub ondersteunt momenteel Shopify storefronts, waaronder Shopify Headless. Extra e-commerce platform support is abonnement.
Stuur voor feedback over de functionaliteit van Klaviyo Customer Hub een e-mail naar customerhub@klaviyo.com.
Voordat je van start gaat
VereistenVereisten
⚠️ Opmerking: Je moet contact opnemen met je vertegenwoordiger, CSM of Klaviyo support om Headless Shopify support in te schakelen voor je Klaviyo account voordat je verder gaat, zodat je toegang krijgt tot de benodigde configuraties. Contact opnemen support
- Een storefront zonder hoofd Shopify met toegang tot het Storefront API (openbaar toegangstoken / openbare sleutel van Storefront API in Shopify's Headless Beheerder).
- Uw Klaviyo bedrijfs-ID (gebruikt door de JavaScript-lader op locatie).
- Beslissing over inloggen shopper: Shopify Klantaccount API of Klaviyo One Time Password (OTP).
- Als je een bestaande account gebruikt, zorg er dan voor dat de Login, Logout en (optioneel) Beheer account en Beheer adressen routes van je winkel klaar zijn.
- Mogelijkheid om je winkelcode te bewerken en wijzigingen te implementeren.
- Wie kan dit instellen: Je hebt een account rol nodig die Klaviyo Customer Hub instellingen kan bewerken en widget kan publiceren (eigenaar, Beheerder, of een aangepaste rol die schrijftoegang heeft tot Content en API-sleutel).
Overzicht
Overzicht
Klaviyo Customer Hub is een sitebrede overlay die shoppers sneller toegang geeft tot account acties en handige shoppingtools. Voor headless Shopify maak je verbinding met Klaviyo's onsite script, kies je een inlogmethode (klantenaccount API of Klaviyo OTP) en voeg je optioneel toe:
- Actief Product: toont het product dat een shopper in de Hub bekijkt.
- Onlangs bekeken: lijst onlangs bekeken producten met Klaviyo's tracking.
- widget Favorieten en Veelgestelde vragen: weergeven op PDP's en in de Hub.
Gebruik Klaviyo Customer Hub als je een on-page assistentielaag wilt die productontdekking en sneller afrekenen stimuleert, waardoor conversie en levenslange waarde verbeteren.
Instelling
Instelling
1 - Configureer de instellingen van Klaviyo Customer Hub1 - Configureer de instellingen van Klaviyo Customer Hub
Volg eerst Aan de slag met Klaviyo Customer Hub en voltooi de onboarding wizard, net als bij elke andere setup. Zodra dit is voltooid, ga je naar Klaviyo Customer Hub > Instellingen. Je ziet de Headless Shopify configuratiesectie.
Plak je Storefront API publieke sleutel van Shopify's Headless Beheerder (openbaar toegangstoken).
Selecteer onder Shopper login Shopify Klantaccount API (aanbevolen zodat al je winkel apps Shopify's login kunnen delen) of Klaviyo One Time Password (OTP, werkt alleen met Klaviyo en zal shoppers niet inloggen in andere apps).
Als je Shopify Klantaccount API selecteert, voer dan ook de Login, Logout en optionele Manage account/Manageaddresses routes in (gebruikt voor omleidingen tussen de Hub en je site).
Zichtbaarheid publiceren: zet Klaviyo Customer Hub op Live.
2 - Laad de Klaviyo Customer Hub JavaScript (Instructies voor ontwikkelaars)
2 - Laad de Klaviyo Customer Hub JavaScript (Instructies voor ontwikkelaars)
Tip: Als je al Klaviyo onsite functies draait, heb je misschien al een loader. Bevestig dit voordat je een tweede script toevoegt.
Maak /public/customerHub.js (of gelijkwaardig) met de volgende loader (vervang COMPANY_ID door uw Klaviyo openbare API-sleutel, ook bekend als uw bedrijfs-ID):
// customerHub.js
// TODO: Configuratie
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 de consolemelding: "Klaviyo JS script succesvol geladen". In je root indeling (bijvoorbeeld root.tsx), ook de lader:
// root.tsx
return (
<html>
<body>
< script src="/customerHub.js" defer></script>
</body>
</html>
)Na deze stap zal window.customerHubApi wordt beschikbaar op pagina's waar de Hub wordt uitgevoerd.
3 - Toon het actieve product in Klaviyo Customer Hub
3 - Toon het actieve product in Klaviyo Customer Hub
Voeg de hydratatie-oproep toe aan je productdetailpagina (PDP) zodat het huidige product in de Hub verschijnt:
<!-- -->
< script type="text/javascript">
(function() {
function waitForCustomerHubApi() {
return new Promise((resolve) => {
const check = () => {
if (window.customerHubApi && window.customerHubApi.hydrateProduct) {
resolve();
} anders {
requestAnimationFrame(check);
}
};
check();
});
}
waitForCustomerHubApi().then() => {
window.customerHubApi.hydrateProduct("your-product-handle");
});
}();
</script>DeHub zou nu een extra productkaart moeten tonen voor de PDP die de shopper bekijkt op het tabblad "Chat" als je dat hebt ingeschakeld.
4 - Recent bekeken producten inschakelen in Klaviyo Customer Hub
4 - Recent bekeken producten inschakelen in Klaviyo Customer Hub
Implementeer Bekeken product tracking zodat de Hub Onlangs bekeken items kan vullen en je de meetwaarde elders in Klaviyo kunt gebruiken. De volgende tracking snippets kunnen ook direct aan je winkelpui worden toegevoegd, instructies vind je hier in onze Klaviyo Ontwikkelaarsdocumentatie: Integreer een e-commerce platform zonder kant-en-klare Klaviyo integraties.
5 - Schakel account link takeover in
5 - Schakel account link takeover in
Om Klaviyo's Klaviyo Customer Hub te kunnen openen door op het account icoon in de header van je winkel te klikken, moet je al een bestaande a-tag hebben die verwijst naar een link met /account (in dat geval vervangen wij deze automatisch voor je). Je kunt ook handmatig de pictogramlink definiëren om naar #k-hub te wijzen om de lade te openen.
6 - Stel Klaviyo Customer Hub in met klantaccount API authenticatie (aanbevolen)
Om de klantaccount- en verificatie-instellingen van je bestaande storefront te kunnen gebruiken, moet je bij Klaviyo Customer Hub een nieuwe API route aan je storefront toevoegen die zorgt voor het veilig doorgeven van het toegangstoken van een inloggen shopper aan onze diensten. Wat belangrijk is, is dat de nieuwe route API een naam krijgt en kan worden bereikt met '/API/authenticateCustomerHub'.
Opmerking: het volgende voorbeeld van een codefragment is voor Shopify's Hydrogen framework. Voor meer aangepaste storefronts kan een extra workaround nodig zijn, maar de algemene aanpak wordt hier beschreven.
// ./app/routes/API.authenticateCustomerHub.js
// TODO: Configuratie
const COMPANY_ID = '';
export async function action({context}) {
// Haal de klantaccount API Client uit de context van je storefront
const {customerAccount} = context;
try {
// Haal het toegangstoken voor de huidige klant op
const accessToken = await customerAccount.getAccessToken();
if (!accessToken) {
return new Response(JSON.stringify({message: 'User not logged in'}), {
status: 200,
});
} //
// Stuur het toegangstoken naar de Klaviyo Customer Hub API
const response = await fetch(
'https://atlas-app.services.klaviyo.com/api/onsite/headless-shopify-login',
{
methode: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
access_token: accessToken,
company_id: COMPANY_ID,
}),
},
);
const responseData = await response.text();
// Stuur het eigenlijke antwoord terug van Klaviyo Customer Hub met dezelfde statuscode
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, evenals de storefront routes die zijn gedefinieerd in Klaviyo's instellingen, zal Klaviyo Customer Hub in staat zijn om te koppelen aan je bestaande authenticatie setup en een naadloos toegangspunt bieden tot je bestaande klantenaccount.
7 - De widget Favorieten toevoegen (aanbevolen)7 - De widget Favorieten toevoegen (aanbevolen)
Zowel favorieten als veelgestelde vragen werken binnen de Klaviyo Customer Hub-lade. Je kunt deze widget echter ook op PDP's toevoegen voor extra betrokkenheid.
Om een toegangspunt voor favorieten toe te voegen op PDP's en in de Hub:
// products.tsx
// Voorbeeld identifiers:
// id: gid://Shopify/Product/12345
// data-product-id: 12345
const gid = "gid://Shopify/Product/12345";
const productId = gid.splitsing('/').pop();
return (
< div
className="kl-hub-favorites-slot"
data-product-id={productId}
/>
)Shoppers kunnen nu op Toevoegen aan favorieten op PDP's klikken; het item verschijnt dan in de Favoriete items van de Hub.
8 - FAQ-blokken toevoegen (aanbevolen)
8 - FAQ-blokken toevoegen (aanbevolen)
Net als het toevoegen van favorieten, is het toevoegen van FAQ-blokken zo eenvoudig als het toevoegen van een div op uw productpagina met de product-ID die wordt doorgegeven om FAQ's te renderen die u kunt bewerken en ontwerpen in Klaviyo.
Voeg een productspecifiek FAQs-blok toe dat je in Klaviyo ontwerpt:
// products.tsx
// Voorbeeld:
const gid = "gid://Shopify/Product/12345";
const productId = gid.splitsing('/').pop();
return (
< div className="klaviyo-faqs-slot" data-product-id={productId} />
)FAQ chips/knoppen moeten nu worden weergegeven op PDP's als ze zijn ingesteld en kunnen worden bewerkt in Klaviyo.
Best practices
Best practices
- Publiceer pas na verificatie naar productie - houd staging verborgen totdat QA is voltooid; stel dan Live in om de Hub bloot te stellen. Impact: minder ondersteuningsproblemen, snellere time-to-value.
- Hydrateer altijd het actieve product op PDP's - houdt de productcontext zichtbaar in de Hub en stimuleert add-to-cart. Effect: conversiepercentage, percentage herhaalaankopen.
- Implementeer Vroeg Bekeken product tracking - vult Onlangs bekeken en ontgrendelt op bladeren gebaseerde flow. Impact: betrokkenheid en inkomsten uit browseherstel.
- Favorieten toevoegen - creëert een wrijvingsarme opslagactie en een blijvende shortlist. Impact: herhalingsbezoeken, toevoegen aan winkelwagentje.
- Gebruik FAQ's voor bezwaren - beantwoord vragen over verzending, materialen of retourzendingen inline om drop-off te verminderen. Impact: conversiepercentage.
- Geef de voorkeur aan server-side auth met klantaccount API als dat beschikbaar is - verbetert de continuïteit voor ingelogde shoppers. Impact: ervaringskwaliteit, support doorbuiging.
Succes meten
Succes meten
Waar kun je resultaten bekijken: Gebruik Analytics > meetwaarde om in de gaten te houden Bekeken productactiviteit en downstream flow/campagne prestaties. Gebruik je e-commerce inkomsten dashboard om conversie en gemiddelde bestelwaarde wijzigingen bij te houden nadat je Klaviyo Customer Hub hebt ingeschakeld. Belangrijke meetwaarden om in de gaten te houden: conversiepercentage uit PDP, add-to-cart rate, sessies met Hub opens (indien geïnstrumenteerd), inkomsten per ontvanger (percentage herhaalaankopen) en browse-gedreven inkomsten gekoppeld aan Viewed Product events. Checklist voor snelle oplossingen: Laag Recent bekeken activiteit? Controleer of de Viewed Product tracking snippet afgaat en of gebeurtenissen worden toegewezen aan profiel. Lage add-to-cart van Hub? Zorg ervoor dat actieve producthydratatie op elke PDP wordt uitgevoerd en dat variatie/prijzen correct zijn. Weinig favorieten toegevoegd? Verplaats de Favorieten-sleuf naar de kern van de PDP CTA's en controleer of het data-product-id overeenkomt met het product.
Probleemoplossing
Probleemoplossing
Symptoom: Klaviyo Customer Hub verschijnt niet op de site.
Waarschijnlijke oorzaak: Script wordt niet geladen of Hub is verborgen.
Fix: Bevestig dat customerHub.js laadt (controleer console), dat de bedrijfs-ID is ingesteld en dat de zichtbaarheid van Klaviyo Customer Hub Live is in Klaviyo Customer Hub > Instellingen.
Symptoom: Console toont "Mislukt om Klaviyo JS script te laden".
Waarschijnlijke oorzaak: Onjuiste script-URL of ontbrekende bedrijfs-ID.
Herstellen: Controleer https://static.Klaviyo.com/onsite/js/<COMPANY_ID>/Klaviyo.js en dat COMPANY_ID is ingevuld.
Symptoom: actieve productkaart wordt niet weergegeven in de Hub op PDP's.
Waarschijnlijke oorzaak: hydrateProduct niet genoemd of verkeerde productgreep.
Fix: Zorg ervoor dat de wachtlus wordt uitgevoerd en roep window.customerHubApi.hydrateProduct("<handle>" ) aan. met het juiste producthandvat.
Symptoom: Onlangs bekeken sectie is leeg.
Waarschijnlijke oorzaak: Bekeken Product tracking niet geïmplementeerd.
Fix: Voeg de Viewed Product tracking snippet uit de developer guide toe en controleer events in Klaviyo.
Symptoom: widget Favorieten of FAQ worden niet weergegeven op PDP.
Waarschijnlijke oorzaak: Ontbrekende container of verkeerd attribuut.
Fix: 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 pictogram account klikt, wordt de Hub niet geopend.
Waarschijnlijke oorzaak: Header link wijst niet naar /account of #k-hub.
Fix: Zorg ervoor dat het account anker /account gebruikt (auto-takeover) of stel href="#k-hub" in.
Symptoom: Shoppers worden niet herkend als inloggen in de Hub.
Waarschijnlijke oorzaak: Ontbrekende /API/authenticateCustomerHub route of mislukt API verzoek.
Fix: Implementeer het Hydrogen voorbeeld (of je framework equivalent), stuur access_token en company_id naar Klaviyo's login eindpunt, en retourneer het antwoord.
Veelgestelde vragen
Veelgestelde vragen
V: Moet ik Shopify Klantaccount API gebruiken om in te loggen?
A: Nee. In plaats daarvan kun je Klaviyo One Time Password (OTP) gebruiken. Als je al gebruik maakt van Shopify account, maak dan verbinding via het Klantenaccount API voor een naadloze ervaring.
V: Welke winkelroutes moet ik opgeven?
A: Als je je bestaande account gebruikt, moet je Login en Logout routes opgeven; Beheer account en Beheer adressen zijn optioneel voor een diepere koppeling.
V: Waar vind ik de openbare sleutel van de Storefront API?
A: In Shopify's Headless Beheerder onder Storefront API > Public access token (ook wel Storefront API public key genoemd).
V: Kan Klaviyo Customer Hub mijn account icoon overnemen?
A: Ja. Als je header's account link /account gebruikt, kan Klaviyo Customer Hub automatisch openen; je kunt het ook verwijzen naar #k-hub.
V: Is Shopify Hydrogen vereist?
A: Nee. Het authenticatievoorbeeld maakt gebruik van Hydrogen, maar elk framework kan een serverroute implementeren op /API/authenticateCustomerHub die het toegangstoken en bedrijfs_id naar Klaviyo stuurt.
V: Kunnen favorieten en veelgestelde vragen op PDP's en in de Hub staan?
A: Ja. Voeg de respectieve containerdivs toe aan de PDP's; ze komen ook tevoorschijn in de Hub-lade.