So richtest du Klaviyo Customer Hub mit Headless Shopify ein

Verbinde Klaviyo Customer Hub mit deinem Headless-Shopify-Storefront. Login aktivieren, Widget anzeigen (Favoriten, FAQs) und aktive/kürzlich angesehene Produkterlebnisse ermöglichen, um Kundenengagement und Conversion zu steigern.

Übersicht

Du verbindest den Klaviyo Customer Hub mit einem Headless-Shopify-Storefront, wählst eine Anmeldemethode aus und veröffentlichst den Hub, damit Shopper*innen site‐wide darauf zugreifen können.

Bevor du anfängst

Voraussetzungen

1. Ein Headless-Shopify-Storefront mit Zugriff auf die Storefront API (Public access token/Storefront API public key in Shopifys Headless Administrator).
2. Deine Klaviyo company ID (wird vom Onsite-JavaScript-Loader verwendet).
3. Entscheidung zum Shopper-Login: Shopify Customer Konto API oder Klaviyo One Time Password (OTP).
   1. Wenn du vorhandene Konten verwendest, halte die Routen für Login, Logout und (optional) Konto verwalten und Adressen verwalten deines Shops bereit.
4. Möglichkeit, deinen Storefront-Code zu bearbeiten und Änderungen bereitzustellen.
5. Wer das einrichten kann: Du brauchst eine Kontorolle, mit der du die Einstellungen für Klaviyo Customer Hub bearbeiten und Widget veröffentlichen kannst (Kontoinhaber, Administrator oder eine benutzerdefinierte Rolle mit Schreibzugriff auf Inhalte und API-Schlüssel).

Übersicht

Klaviyo Customer Hub ist ein websiteweites Overlay, das Käufer*innen schnelleren Zugriff auf Kontoaktionen und hilfreiche Shopping-Tools bietet. Für Headless Shopify verbindest du das Onsite-Script von Klaviyo, wählst eine Login-Methode (Customer Accounts API oder Klaviyo OTP) und fügst optional Folgendes hinzu:

1. Aktives Produkt: zeigt das Produkt, das sich Kund*innen im Hub ansehen.
2. Kürzlich angesehen: listet kürzlich angesehene Produkte mithilfe des Trackings von Klaviyo auf.
3. Widgets Favoriten und FAQs: werden auf PDPs und im Hub gerendert. 

Nutze den Klaviyo Customer Hub, wenn du eine On-Page-Unterstützungsebene möchtest, die die Produktentdeckung fördert und einen schnelleren Checkout ermöglicht und so Conversion und Lifetime Value verbessert.

Einrichten

1 – Einstellungen für den Klaviyo Customer Hub konfigurieren

Folge zuerst Erste Schritte mit dem Klaviyo Customer Hub und schließe den Onboarding-Assistenten ab, genau wie bei jeder anderen Einrichtung. Wenn das abgeschlossen ist, gehe zu Klaviyo Customer Hub > Einstellungen. Du siehst den Abschnitt zur Headless-Shopify-Konfiguration.

Schalte die Headless-Shopify-Konfiguration ein und füge dann deinen Storefront-API öffentlichen Schlüssel aus Shopifys Headless-Administrator (Public access token) ein.

Wähle unter Shopper-Login die Shopify Customer Konto 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 meldet Shopper*innen nicht bei anderen Apps an).

Wenn Shopify Customer Account API ausgewählt wird, gib außerdem die Routen für Anmelden, Abmelden und optional Konto verwalten/Adressen verwalten im Storefront ein (werden für Weiterleitungen zwischen dem Hub und der Website verwendet).

Sichtbarkeit veröffentlichen: Klaviyo Customer Hub auf Live setzen.

2 – Das Klaviyo Customer Hub JavaScript laden (Anweisungen für Entwickler*innen)

Tipp: Wenn du Klaviyo-Funktionen vor Ort bereits nutzt, ist möglicherweise schon ein Loader eingerichtet. 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 Klaviyo öffentlichen API-Schlüssel, auch als deine Company ID bekannt):

// 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);

Das Onsite-Skript wird auf jeder Seite geladen. Suche nach der Konsolenmeldung: „Klaviyo JS script loaded successfully.“  Füge in deinem Root-Layout (z. B. root.tsx) den Loader ein:

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

Nach diesem Schritt window.customerHubApi wird auf Seiten verfügbar, auf denen der Hub ausgeführt wird.

3 – Das aktive Produkt im Klaviyo Customer Hub anzeigen

Füge den Hydrate-Aufruf auf deiner Produktdetailseite (PDP) hinzu, damit das aktuelle Produkt im Hub angezeigt wird:

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

Der Hub sollte jetzt auf der Registerkarte „Chat“ eine zusätzliche Produktkarte für die PDP anzeigen, die sich die Shopper*innen gerade ansehen, wenn du dies aktiviert hast.

4 - Zuletzt angesehene Produkte im Klaviyo Customer Hub aktivieren

Implementiere das Produkt angesehen -Tracking, damit der Hub Zuletzt angesehen -Artikel befüllen kann und du die Metrik an anderer Stelle in Klaviyo verwenden kannst. Die folgenden Tracking-Snippets können auch direkt zu deinem Shop hinzugefügt werden; Anweisungen findest du hier in unserer Klaviyo Developers-Dokumentation: Eine E-Commerce-Plattform ohne vorgefertigte Klaviyo-Integrationen integrieren.

5 – Konto-Link-Übernahme aktivieren

Damit sich der Klaviyo Customer Hub durch Klicken auf das Kontosymbol in der Kopfzeile deines Storefronts öffnet, musst du bereits ein vorhandenes a-Tag haben, das auf einen Link mit /Konto verweist (in diesem Fall ersetzen wir ihn automatisch für dich). Oder du kannst den Icon-Link auch manuell so definieren, dass er auf #k-hub verweist, um die Schublade zu öffnen.

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

Um das bestehende Kundenkonto und die Authentifizierungseinrichtung deines Storefronts zu verwenden, musst du für den Klaviyo Customer Hub eine neue API-Route zu deinem Storefront hinzufügen, die die sichere Weitergabe des Zugriffstokens eines angemeldeten Shopper*innen an unsere Services übernimmt. Wichtig ist, dass die neue API-Route benannt ist und unter „/api/authenticateCustomerHub“ erreichbar ist.

Hinweis: Das folgende Beispiel für ein Code-Fragment ist für Shopifys Hydrogen-Framework. Stärker angepasste Storefronts erfordern möglicherweise zusätzliche Workarounds, der allgemeine Ansatz wird hier jedoch erläutert.

// ./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});
  }
}

Sobald dies konfiguriert ist, sowie die Storefront-Routen in Klaviyos Einstellungen definiert sind, kann Klaviyo Customer Hub auf dein bestehendes Authentifizierungs-Setup verlinken und einen nahtlosen Einstieg in deine bestehenden Kund*innenkonten bereitstellen.

7 – Das Favoriten-Widget hinzufügen (empfohlen)

Sowohl Favoriten als auch FAQs funktionieren in der Klaviyo Customer Hub-Schublade. Du kannst diese Widget jedoch auch auf PDPs hinzufügen, um zusätzliches Kundenengagement zu erzielen.

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

// 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}
  />
)

Shopper*innen können jetzt auf PDPs auf Zu Favoriten hinzufügen klicken; das Element erscheint in den Favorisierten Artikeln im Hub.

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

Ähnlich wie beim Hinzufügen von Favoriten ist das Hinzufügen von FAQ-Blöcken genauso einfach wie das Hinzufügen eines Divs auf deiner Produktseite, wobei die Produkt-ID übergeben wird, um FAQs zu rendern, die du in Klaviyo bearbeiten und gestalten kannst.

Einen produktspezifischen FAQ-Block hinzufügen, den du in Klaviyo entwirfst:

// 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/-Schaltflächen sollten jetzt auf PDPs gerendert werden, wenn sie eingerichtet sind, und können in Klaviyo bearbeitet werden.

Best Practices

1. Erst nach der Verifizierung in der Produktionsumgebung veröffentlichen – Staging verborgen lassen, bis QA abgeschlossen ist; dann Live festlegen, um den Hub verfügbar zu machen. Auswirkung: weniger Support-Anfragen, schnellere Time-to-Value.
2. Das aktive Produkt auf PDPs immer hydratisieren – sorgt dafür, dass der Produktkontext im Hub sichtbar bleibt, und regt zum In-den-Warenkorb-legen an. Auswirkung: Conversion-Rate, Wiederkaufrate.
3. Tracking von angesehenen Produkten früh implementieren – füllt „Zuletzt angesehen“ und schaltet browse-basierte Flows frei. Auswirkung: Kundenengagement und Umsatz durch Browse-Recovery.
4. Favoriten hinzufügen: Erstellt eine reibungslose Speicheraktion und eine dauerhafte Auswahlliste. Auswirkung: wiederholte Besuche, Zum-Warenkorb-hinzugefügt.
5. FAQs für Einwände verwenden – Versand-, Material- oder Rücksendefragen direkt beantworten, um Abbrüche zu reduzieren. Auswirkung: Conversion-Rate.
6. Serverseitige Auth mit der Customer Accounts API bevorzugen, wenn verfügbar – verbessert die Kontinuität für eingeloggte Shopper*innen. Auswirkung: Erlebnisqualität, weniger Supportanfragen. 

Messen deiner Erfolge

Wo du Ergebnisse ansehen kannst: Verwende Analytics > Metrik, um die Aktivität von Viewed Product und die nachgelagerte Flow-/Kampagnen-Performance zu überwachen. Verwende deine E-Commerce-Umsatz-Dashboards, um Conversion- und Änderungen beim durchschnittlichen Bestellwert zu verfolgen, nachdem du das Klaviyo Customer Hub aktiviert hast. Wichtige Metriken, die du im Blick behalten solltest: Conversion-Rate von der PDP, Add-to-Cart-Rate, Sitzungen mit Hub-Öffnungen (falls instrumentiert), Umsatz pro Empfänger (RPR) und Browse-gestützter Umsatz, der mit Viewed-Product-Events verknüpft ist. Checkliste für schnelle Korrekturen: Niedrige Recently viewed-Aktivität? Prüfe, ob das Viewed Product -Tracking-Snippet ausgelöst wird und ob Events Profilen zugeordnet werden. Niedriges Add-to-Cart aus dem Hub? Stelle sicher, dass die aktive Active-Product-Hydration auf jeder PDP ausgeführt wird und dass Varianten/Preise korrekt sind. Wenig Favorites-Hinzufügungen? Verschiebe den Favorites-Slot in die Nähe der wichtigsten PDP-CTAs und bestätige, dass die data-product-id mit dem Produkt übereinstimmt. 

Fehlerbehebung

Symptom: Der Klaviyo Customer Hub wird auf der Website nicht angezeigt.

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

Fix: Bestätige, dass customerHub.js geladen wird (Konsole prüfen), die Unternehmens-ID festgelegt ist und die Sichtbarkeit von Klaviyo Customer Hub in Klaviyo Customer Hub > Einstellungen auf Live gesetzt ist.

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

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

Fix: Prüfe https://static.klaviyo.com/onsite/js/<COMPANY_ID>/klaviyo.js und ob COMPANY_ID ausgefüllt ist.

Symptom: Die Karte „Aktives Produkt“ wird im Hub auf PDPs nicht angezeigt.

Wahrscheinliche Ursache: hydrateProduct wurde nicht aufgerufen oder falscher Product Handle.

Korrektur: Stelle sicher, dass die Warteschleife ausgeführt wird, und rufe window.customerHubApi.hydrateProduct(„<handle>“) mit dem korrekten Produkthandle auf.

Symptom: Der Abschnitt „Zuletzt angesehen“ ist leer.

Wahrscheinliche Ursache: Viewed Product-Tracking nicht implementiert.

Fix: Füge das Viewed Product -Tracking-Snippet aus dem Leitfaden für Entwickler*innen hinzu und überprüfe Ereignisse in Klaviyo.

Symptom: Favoriten- oder FAQ-Widgets werden nicht auf PDP gerendert.

Wahrscheinliche Ursache: Fehlender Container oder falsches Attribut.

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

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

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

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

Symptom: Shopper*innen werden im Hub nicht als angemeldet erkannt.

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

Fix: Implementiere das Hydrogen-Beispiel (oder das entsprechende Äquivalent deines Frameworks), sende access_token und company_id an Klaviyos Login-Endpunkt und gib die Antwort zurück.

FAQ

F: Muss ich die Shopify-Konto-API für das Login verwenden?

A: Nein. Du kannst stattdessen Klaviyo One Time Password (OTP) verwenden. Wenn du bereits Shopify-Konten verwendest, stelle über die Customer Accounts API eine Verbindung her, um eine nahtlose Erfahrung zu ermöglichen.

F: Welche Storefront-Routen muss ich angeben?

A: Wenn du deine bestehenden Konten verwendest, stelle Anmelden - und Abmelden -Routen bereit; Konto verwalten und Adressen verwalten sind optional für tieferes Linking.

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

A: In Shopifys 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 Kontolink in deiner Kopfzeile /account verwendet, kann sich der 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 Zugriffstoken und die company_id an Klaviyo postet.

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

A: Ja. Füge die jeweiligen Container-divs auf PDPs hinzu; sie werden auch in der Hub-Schublade angezeigt.