Informacje dodatkowe o interfejsie API JavaScript Klaviyo Customer Hub

Czego się dowiesz?

Jak kontrolować Klaviyo Customer Hub — lub samodzielny czat online Klaviyo — z poziomu własnego kodu sklepu internetowego za pomocą interfejsu JavaScript API window.customerHubApi. Otworzysz i zamkniesz to środowisko, przejdziesz do konkretnego ekranu, wyślesz wiadomość na czacie w imieniu kupującego i będziesz nasłuchiwać zdarzeń, takich jak dodanie do koszyka.

Kilka słów na początek

Potrzebne będą:

• Klaviyo Customer Hub skonfigurowany i załadowany w Twoim sklepie. Jeśli korzystasz ze sklepu typu headless lub niestandardowego, najpierw postępuj zgodnie z instrukcjami w artykule Jak skonfigurować Klaviyo Customer Hub z Headless Shopify — zawiera informacje o dodaniu modułu ładującego na stronie, który udostępnia to API.
• Możliwość edytowania i wdrażania kodu sklepu.

Czym jest interfejs API Klaviyo Customer Hub

Za każdym razem, gdy na Twoim sklepie wczytuje się Klaviyo Customer Hub — lub samodzielny czat online Klaviyo — Klaviyo dołącza małe API JavaScript do globalnego obiektu window jako window.customerHubApi. Możesz go użyć do otwierania, zamykania i interakcji z tym doświadczeniem z własnego kodu — na przykład z niestandardowego przycisku, banera lub strony produktu.

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

Metody

open(route?)

Otwiera szufladę Klaviyo Customer Hub.

• route (ciąg znaków, opcjonalnie) — ścieżka, do której ma przejść podczas otwierania. Jeśli zostanie pominięta, Hub otworzy się na ekranie, który był wyświetlany jako ostatni.

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

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

Dostępne trasy

close()

Zamyka panel wysuwany Klaviyo Customer Hub. Hub pozostaje na bieżącym ekranie, więc ponowne otwarcie za pomocą open() (bez trasy) przenosi klienta z powrotem do miejsca, w którym skończył.

window.customerHubApi.close();

sendChatMessage(message)

Otwiera Klaviyo Customer Hub na ekranie czatu i przesyła wiadomość w imieniu klienta. Jest to przydatne w przypadku przycisków „Czat na temat tego produktu” lub „Uzyskaj pomoc”.

• message (string) — wiadomość do wysłania.

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

Gdy logowanie jest wymagane: jeśli Twój sklep wymaga, aby klienci się zalogowali przed rozpoczęciem czatu (a Agent AI jest wyłączony), klient zostanie przeniesiony do ekranu Czatu, aby się zalogować. Wiadomość zostanie tymczasowo zapisana i wysłana automatycznie po zakończeniu logowania. Zapisana wiadomość wygasa po około 10 minutach, jeśli logowanie nie zostało ukończone.

sendConversationContext(context)

Kolejkuje kontekst zebrany poza rozmową na czacie — np. odpowiedzi z ankiety przed czatem — aby wysłać go wraz z następną wiadomością czatu od klienta. Klaviyo następnie zapisuje ten kontekst i odwołuje się do niego przez resztę tej rozmowy.

• context (object) — obiekt odpowiedzi na ankietę zawierający tablicę entries. Każdy wpis musi zawierać question i answer.

window.customerHubApi.sendConversationContext({
  type: 'survey-response',
  entries: [
    { question: 'What color are you interested in?', answer: 'Red' },
  ],
});

getActiveConversationId()

Zwraca conversationId dla aktywnej konwersacji prowadzonej w wysuwanym panelu. Zwraca null, jeśli nie trwa żadna konwersacja.

window.customerHubApi.getActiveConversationId();

Nasłuchuj zdarzeń

window.customerHubApi.events umożliwia subskrybowanie zdarzeń, które dzieją się w Klaviyo Customer Hub.

addtocart

Uruchamiany, gdy klient dodaje do koszyka produkt z poziomu Hubu. Użyj go, aby zsynchronizować koszyk w sklepie.

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

Pełny przykład

Przycisk „Czat na temat tego produktu”, który otwiera Hub i przesyła wiadomość, oraz detektor, który synchronizuje koszyk w sklepie, gdy kupujący doda produkt z Centrum:

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

Dodatkowe źródła