Customer Hub – JavaScript-API-Referenz

Übersicht

So steuerst du den Klaviyo Customer Hub – oder den eigenständigen Klaviyo Web-Chat – über deinen eigenen Storefront-Code mit der window.customerHubApi -JavaScript-API. Du öffnest und schließt das Erlebnis, navigierst zu einem bestimmten Bildschirm, sendest im Namen der Kund*innen eine Chat-Nachricht und hörst auf Events wie „Zum Warenkorb hinzufügen“.

Bevor du anfängst

Du benötigst:

• Klaviyo Customer Hub ist in deinem Storefront eingerichtet und geladen. Wenn du eine Headless- oder individuelle Storefront verwendest, folge zuerst So richtest du den Klaviyo Customer Hub mit Headless Shopify ein – dort wird das Hinzufügen des Onsite-Loaders beschrieben, der diese API verfügbar macht.
• Möglichkeit, deinen Shop-Code zu bearbeiten und bereitzustellen.

Was ist die Customer Hub API?

Immer wenn Klaviyo Customer Hub – oder der eigenständige Klaviyo Web-Chat – in deinem Storefront geladen wird, hängt Klaviyo eine kleine JavaScript-API als window.customerHubApi an das globale Objekt window an. Du kannst sie verwenden, um das Erlebnis aus deinem eigenen Code heraus zu öffnen, zu schließen und damit zu interagieren – zum Beispiel über eine*n benutzerdefinierte*n Button, Banner oder eine Produktseite.

if (window.customerHubApi) {
  window.customerHubApi.open();
}

Methoden

open(route?)

Öffnet das Customer-Hub-Seitenfenster.

• route (string, optional) – ein Pfad, zu dem beim Öffnen navigiert werden soll. Wenn dies ausgelassen wird, öffnet sich der Hub auf dem Bildschirm, der zuletzt angezeigt wurde.

// Open the Hub on its default screen
window.customerHubApi.open();

// Open the Hub directly to a specific screen
window.customerHubApi.open('/orders');

Verfügbare Routen

close()

Schließt das Klaviyo Customer Hub-Drop-down-Fenster. Der Hub bleibt auf dem aktuellen Bildschirm, sodass das erneute Öffnen mit open() (keine Route) Kund*innen an die Stelle zurückbringt, an der sie aufgehört haben.

window.customerHubApi.close();

sendChatMessage(message)

Öffnet den Customer Hub auf dem Chat- Bildschirm und sendet eine Nachricht im Namen der Kund*innen – nützlich für die Schaltflächen „Über dieses Produkt chatten“ oder „Hilfe erhalten“.

• message (string) – die zu sendende Nachricht.

window.customerHubApi.sendChatMessage('I have a question about my order.');

Wenn eine Anmeldung erforderlich ist: Wenn dein Shop verlangt, dass sich Kund*innen vor dem Chatten anmelden (und der AI Agent nicht aktiviert ist), werden die Kund*innen zum Chat-Bildschirm weitergeleitet, um sich zuerst anzumelden. Die Nachricht wird vorübergehend gespeichert und automatisch gesendet, sobald die Anmeldung abgeschlossen ist. Die gespeicherte Nachricht läuft nach etwa 10 Minuten ab, wenn die Anmeldung nicht abgeschlossen ist.

getActiveConversationId()

Gibt conversationId für die aktive Konversation zurück, die im Drawer stattfindet. Gibt null zurück, wenn keine Konversation stattfindet.

window.customerHubApi.getActiveConversationId();

Warte auf Ereignisse

window.customerHubApi.events ermöglicht es dir, Ereignisse zu abonnieren, die innerhalb des Klaviyo Customer Hub stattfinden.

addtocart

Wird ausgelöst, wenn Kund*innen im Hub ein Produkt in ihren Warenkorb legen. Nutze sie, um deinen Shop-Warenkorb zu synchronisieren.

window.customerHubApi.events.addEventListener('addtocart', (event) => {
  // event.detail.items is an array of { variantId, quantity }
  event.detail.items.forEach((item) => {
    console.log('Added to cart:', item.variantId, 'x', item.quantity);
  });
});

Vollständiges Beispiel

Eine Schaltfläche „Über dieses Produkt chatten“, die den Hub öffnet und eine Nachricht sendet, sowie ein Listener, der den Warenkorb synchronisiert, wenn Kund*innen einen Artikel aus dem Hub hinzufügen:

<button id="ask-about-product">Ask us about this product</button>

<script>
  document
    .getElementById('ask-about-product')
    .addEventListener('click', () => {
      if (window.customerHubApi) {
        window.customerHubApi.sendChatMessage(
          'I have a question about this product.'
        );
      }
    });

  // Sync the storefront cart when a customer adds an item from the Hub
  if (window.customerHubApi) {
    window.customerHubApi.events.addEventListener('addtocart', (event) => {
      refreshStorefrontCart(event.detail.items);
    });
  }
</script>

Weitere Ressourcen