Wie man Klaviyo Customer Hub mit Headless einrichtet Shopify

Übersicht

Du verbindest den Klaviyo Customer Hub mit einer Headless-Storefront Shopify, wählst eine Login-Methode und veröffentlichst den Hub, damit die Kunden auf der gesamten Website darauf zugreifen können.

Bevor du anfängst

Voraussetzungen 

⚠️ Hinweis: Du musst deinen Vertreter, CSM oder Klaviyo Support kontaktieren, um den Headless Shopify Support für dein Klaviyo Konto zu aktivieren, bevor du fortfährst, damit du auf die notwendigen Konfigurationen zugreifen kannst. Wie du den Support kontaktierst

1. Eine headless Shopify Storefront mit Zugriff auf die Storefront API (Public access token / Storefront API public key in Shopify's Headless Administrator).
2. Deine Klaviyo-Unternehmens-ID (wird vom Onsite-JavaScript-Loader verwendet).
3. Entscheidung über den Shopper-Login: Shopify-Kundenkonto-API oder Klaviyo One Time Password (OTP).
   1. Wenn du bereits bestehende Konten verwendest, halte die Routen Login, Logout und (optional) Konto verwalten und Adressen verwalten für dein Schaufenster bereit.
4. Du kannst deinen Schaufenstercode bearbeiten und Änderungen vornehmen.
5. Wer kann dies einrichten: Du brauchst eine Kontorolle, die die Einstellungen des Klaviyo Customer Hub bearbeiten und das Widget veröffentlichen kann (Kontoinhaber, Administrator oder eine benutzerdefinierte Rolle, die Schreibzugriff auf Inhalte und API-Schlüssel hat). 

Übersicht

Der Klaviyo Customer Hub ist ein standortübergreifendes Overlay, das Kunden einen schnelleren Zugriff auf Kontoaktionen und hilfreiche Shopping-Tools ermöglicht. Für Headless Shopify verbindest du das Onsite-Skript von Klaviyo, wählst eine Anmeldemethode (Kundenkonten-API oder Klaviyo OTP) und fügst sie optional hinzu:

1. aktiv Produkt: Zeigt das Produkt an, das ein Shopper im Hub betrachtet.
2. Kürzlich angeschaut: Liste der zuletzt angesehenen Produkte mit Klaviyo's Tracking.
3. Favoriten- und FAQ-Widget: wird auf PDPs und im Hub angezeigt.  

Nutze Klaviyo Customer Hub, wenn du einen On-Page-Hilfslayer brauchst, der die Produktentdeckung und den Checkout beschleunigt und so die Conversion und den Lifetime Value verbessert.

Einrichten

1 - Konfiguriere die Einstellungen des Klaviyo Customer Hub

Befolge zunächst Erste Schritte mit Klaviyo Customer Hub und schließe den Onboarding-Assistenten ab, wie bei jeder anderen Einrichtung auch. Sobald dies abgeschlossen ist, gehe zu Klaviyo Customer Hub > Einstellungen. Du siehst nun den Abschnitt zur Konfiguration von Headless Shopify. 

Füge deinen öffentlichen Schlüssel für Storefront API aus Shopify's Headless Administrator (Public access token) ein. 

Wähle unter Shopper Login die Shopify Customer Account API (empfohlen, damit alle deine Storefront-Apps den Shopify-Login gemeinsam nutzen können) oder Klaviyo One Time Password (OTP, funktioniert nur mit Klaviyo und loggt die Kunden nicht in andere Apps ein). 

Wenn du die Shopify-Kundenkonto-API auswählst, gibst du auch die Login- und Logout-Routen für dein Schaufenster sowie die optionalen Routen „Konto verwalten“ und „Adressen verwalten“ ein (die für Weiterleitungen zwischen dem Hub und deiner Website verwendet werden). 

Sichtbarkeit veröffentlichen: Setze den Klaviyo Customer Hub auf Live. 

2 - Lade das Klaviyo Customer Hub JavaScript (Anleitung für Entwickler)

Tipp: Wenn du bereits Klaviyo Onsite-Funktionen verwendest, hast du vielleicht schon einen Loader installiert. Bestätige, bevor du ein zweites Skript hinzufügst. 

Erstelle /public/customerHub.js (oder eine gleichwertige Datei) mit dem folgenden Loader (ersetze COMPANY_ID durch deinen öffentlichen API-Schlüssel von Klaviyo, auch bekannt als deine Unternehmens-ID):

// customerHub.js
// TODO: Konfiguration
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);

Das Onsite-Skript wird auf jeder Seite geladen. Achte auf die Konsolenmeldung: „Klaviyo JS-Skript erfolgreich geladen“.  In deinem Stammlayout (z. B. root.tsx), den Lader einschließen:

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

Nach diesem Schritt wird window.customerHubApi wird auf Seiten verfügbar, auf denen der Hub läuft. 

3 - Das aktive Produkt im Klaviyo Customer Hub anzeigen

Füge den Hydrat-Aufruf auf deiner Produkt-Detailseite (PDP ) hinzu, damit das aktuelle Produkt im Hub erscheint:

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

DerHub sollte jetzt eine zusätzliche Produktkarte für den PDP anzeigen, den der Shopper auf der Registerkarte „Chat“ ansieht, wenn du diese Funktion aktiviert hast. 

4 - Aktiviere kürzlich angesehene Produkte im Klaviyo Customer Hub

Implementiere das Tracking der angesehenen Produkte, damit der Hub die zuletzt angesehenen Artikel auflisten kann und du die Metrik an anderer Stelle in Klaviyo verwenden kannst. Die folgenden Tracking-Snippets können auch direkt zu deiner Storefront hinzugefügt werden. Eine Anleitung dazu findest du hier in unserer Klaviyo Entwicklerdokumentation: Integriere eine E-Commerce-Plattform ohne vorkonfiguriert Klaviyo Integrationen.

5 - Aktiviere die Übernahme von Kontoverbindungen

Damit Klaviyoden Klaviyo Customer Hub öffnen kann, indem du auf das Konto-Symbol in der Kopfzeile deiner Storefront klickst, musst du bereits einen a-Tag haben, der auf einen Link mit /account verweist (in diesem Fall werden wir ihn automatisch für dich ersetzen). Du kannst den Icon-Link auch manuell definieren, damit er auf #k-hub zeigt, um die Schublade zu öffnen.

6 - Klaviyo Customer Hub mit Kundenkonten einrichten API Authentifizierung (empfohlen)

Um die Kundenkonten und die Authentifizierungseinstellungen deiner bestehenden Storefront zu nutzen, musst du eine neue API Route zu deiner Storefront hinzufügen, die das Access Token eines angemeldeten Käufers sicher an unsere Services weiterleitet. Wichtig ist, dass die neue API Route benannt ist und mit '/API/authenticateCustomerHub' erreicht werden kann.

Hinweis: Das folgende Code-Fragment-Beispiel bezieht sich auf das Hydrogen-Framework von Shopify. Für individuellere Storefronts sind möglicherweise zusätzliche Maßnahmen erforderlich, aber die allgemeine Vorgehensweise wird hier beschrieben.

// ./app/routes/API.authenticateCustomerHub.js
// TODO: Konfiguration
const COMPANY_ID = '';
export async function action({context}) {
 // Ziehe den Kunden-Account API Client aus dem Kontext deiner Storefront
 const {customerAccount} = context;
 try {
 // Hole das Access-Token für den aktuellen Kunden
 const accessToken = await customerAccount.getAccessToken();
    if (!accessToken) {
 return new Response(JSON.stringify({message: 'User not logged in'}), {
        status: 200,
      });
 }
   // Sende das Zugriffstoken an den Klaviyo 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();
    // Rückgabe der eigentlichen Antwort von Klaviyo Customer Hub mit demselben 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});
 }
}

Sobald dies konfiguriert ist und die Schaufensterrouten in den Einstellungen von Klaviyodefiniert sind, kann Klaviyo Customer Hub mit deiner bestehenden Authentifizierung verknüpft werden und einen nahtlosen Zugang zu deinen bestehenden Kundenkonten bieten.

7 - Füge das Favoriten-Widget hinzu (empfohlen)

Sowohl Favoriten als auch FAQs funktionieren in der Schublade des Klaviyo Customer Hub. Du kannst diese Widgets aber auch auf PDPs für zusätzliches Kundenengagement hinzufügen.

So fügst du einen Favoriten-Einstiegspunkt auf den PDPs und im Hub hinzu:

// products.tsx
// Beispielbezeichner:
// id: gid://Shopify/Product/12345
// data-product-id: 12345
const gid = „gid://Shopify/Produkt/12345“;
const productId = gid.Split('/').pop();

return (
 < div
 className=„kl-hub-favorites-slot“
 data-product-id={productId}
  />
 )

Shopper können jetzt bei PDPs auf Zu Favoriten hinzufügen klicken; der Artikel erscheint dann in den Favoriten des Hubs. 

8 - FAQ-Blöcke hinzufügen (empfohlen)

Ähnlich wie beim Hinzufügen von Favoriten ist das Hinzufügen von FAQ-Blöcken so einfach wie das Hinzufügen eines Divs auf deiner Produktseite mit der übergebenen Produkt-ID, um FAQ's zu erstellen, die du in Klaviyo bearbeiten und gestalten kannst.

Füge einen produktspezifischen FAQ-Block hinzu, den du in Klaviyo gestaltest:

// products.tsx
// Beispiel:
const gid = „gid://Shopify/Product/12345“;
const productId = gid.Split('/').pop();

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

FAQ-Chips/Buttons sollten jetzt auf PDPs dargestellt werden, wenn sie eingerichtet sind und in Klaviyo bearbeitet werden können.

Best Practices

1. Veröffentliche erst nach der Überprüfung in der Produktion - halte Staging versteckt, bis die QA abgeschlossen ist; setze dann Live, um den Hub freizugeben. Auswirkung: weniger Support-Probleme, kürzere Time-to-Value.
2. Hydratisiere immer das aktive Produkt auf PDPs - so bleibt der Produktkontext im Hub sichtbar und fördert das Hinzufügen zum Warenkorb. Auswirkungen: Conversion-Rate, Wiederkaufrate.
3. Implementiere die Nachverfolgung von angesehenen Produkten frühzeitig - füllt „Kürzlich angesehen“ aus und schaltet den Browse-basierten Flow frei. Auswirkungen: Kundenengagement und Einnahmen aus der Rückgewinnung von Stöbern.
4. Favoriten hinzufügen - erstellt eine reibungsarme Speicheraktion und eine dauerhafte Auswahlliste. Auswirkung: Wiederholte Besuche, Add-to-cart.
5. Verwende FAQs für Einwände - beantworte Fragen zu Versand, Material oder Rücksendungen inline, um Abbrüche zu vermeiden. Auswirkungen: Conversion-Rate.
6. Bevorzuge die serverseitige Anmeldung mit der Kundenkonten-API, wenn sie verfügbar ist - das verbessert die Kontinuität für eingeloggte Kunden. Auswirkung: Erlebnisqualität, Ablenkung durch Unterstützung.  

Messen deiner Erfolge

Wo du die Ergebnisse sehen kannst: Verwende Analytics > Metrik, um die gesehene Produktaktivität und die nachgelagerte Flow-/Kampagnenleistung zu überwachen. Nutze dein E-Commerce Umsatz Dashboard, um Conversion- und durchschnittliche Bestellwertänderungen nach der Aktivierung von Klaviyo Customer Hub zu verfolgen. Wichtige Metrik, die du beobachten solltest: Conversion-Rate aus der PDP, Add-to-Cart-Rate, Sitzungen mit Hub-Öffnungen (falls instrumentiert), Umsatz pro Empfänger (Wiederkaufrate) und browse-getriebener Umsatz in Verbindung mit Viewed Product Events. Quick Fixes Checkliste: Niedrig Kürzlich gesehene Aktivität? Überprüfe, ob das Snippet „ Viewed Product Tracking“ ausgelöst wird und die Ereignisse dem Profil zugeordnet werden. Niedrige Add-to-Cart-Werte vom Hub? Stelle sicher, dass aktiv Product hydration auf jeder PDP läuft und dass Variante/Preise korrekt sind. Ein paar Favoriten hinzugefügt? Verschiebe den Favoriten-Slot in die Nähe der zentralen PDP-CTAs und bestätige, dass die data-product-id dem Produkt entspricht.  

Fehlerbehebung

Symptom: Der Klaviyo Customer Hub erscheint nicht auf der Website.

Wahrscheinliche Ursache: Das Skript wird nicht geladen oder der Hub ist versteckt.

Fix: Bestätige, dass customerHub.js geladen wird (überprüfe die Konsole), die Unternehmens-ID gesetzt ist und die Sichtbarkeit von Klaviyo Customer Hub in den Einstellungen von Klaviyo Customer Hub > live ist. 

Symptom: Die Konsole zeigt „Das Klaviyo JS-Skript konnte nicht geladen werden“.

Wahrscheinliche Ursache: Falsche Skript-URL oder fehlende Unternehmens-ID.

Beheben: Überprüfe https://static.Klaviyo.com/onsite/js/<COMPANY_ID>/Klaviyo.js und dass COMPANY_ID ausgefüllt ist. 

Symptom: Die aktiv Produktkarte wird nicht im Hub der PDP angezeigt.

Wahrscheinliche Ursache: hydrateProdukt nicht aufgerufen oder falscher Produktgriff.

Fix: Sicherstellen, dass die Warteschleife läuft und window.customerHubApi.hydrateProduct(„<handle>“ ) aufrufen mit dem richtigen Produktgriff. 

Symptom: Der Abschnitt „Kürzlich angesehen“ ist leer.

Wahrscheinliche Ursache: Gesehenes Produkt-Tracking nicht implementiert.

Fix: Füge das Viewed Product Tracking Snippet aus dem Entwicklerhandbuch hinzu und verifiziere Ereignisse in Klaviyo. 

Symptom: Die Favoriten oder das FAQ-Widget werden auf dem PDP nicht angezeigt.

Wahrscheinliche Ursache: Fehlender Container oder falsches Attribut.

Fix: Füge <div class=„kl-hub-favorites-slot“ data-product-id=„...“> und/oder <div class=„klaviyo-faqs-slot“ data-product-id=„...“> mit der richtigen Produkt-ID hinzu. 

Symptom: Wenn du auf das Kontosymbol klickst, wird der Hub nicht geöffnet.

Wahrscheinliche Ursache: Der Header-Link zeigt nicht auf /account oder #k-hub.

Fix: Stelle sicher, dass der Account-Anker /account verwendet (Auto-Übernahme) oder setze href=„#k-hub“. 

Symptom: Shopper werden im Hub nicht als angemeldet erkannt.

Wahrscheinliche Ursache: Fehlende Route /API/authenticateCustomerHub oder fehlgeschlagene API Anfrage.

Lösung: Implementiere das Hydrogen-Beispiel (oder ein entsprechendes Framework), sende access_token und company_id an den Login-Endpunkt von Klaviyo und gib die Antwort zurück. 

FAQ

F: Muss ich die Shopify-Kundenkonten-API für die Anmeldung verwenden?

A: Nein. Du kannst stattdessen das Klaviyo One Time Password (OTP ) verwenden. Wenn du bereits Shopify-Konten verwendest, kannst du dich über die Kundenkonten-API verbinden, um ein nahtloses Erlebnis zu schaffen. 

F: Welche Schaufensterrouten muss ich angeben?

A: Wenn du deine bestehenden Konten verwendest, gibst du die Routen Login und Logout an; Konto verwalten und Adressen verwalten sind optional für eine tiefere Verknüpfung. 

F: Wo finde ich den öffentlichen Schlüssel der Storefront API?

A: In Shopify's Headless Administrator unter Storefront API > Public access token (auch Storefront API public key genannt). 

F: Kann Klaviyo Customer Hub mein Kontosymbol übernehmen?

A: Ja. Wenn der Account-Link deines Headers /account verwendet, kann sich Klaviyo Customer Hub automatisch öffnen; du kannst ihn auch auf #k-hub verweisen. 

F: Ist Shopify Hydrogen erforderlich?

A: Nein. Das Authentifizierungsbeispiel verwendet Hydrogen, aber jedes Framework kann eine Server-Route unter /API/authenticateCustomerHub implementieren, die das Access-Token und die company_id an Klaviyo sendet. 

F: Können Favoriten und FAQs auf PDPs und im Hub leben?

A: Ja. Füge die entsprechenden Container-Divs auf den PDPs hinzu; sie werden auch in der Hub-Schublade erscheinen.