Informazioni di riferimento sull'API JavaScript nel Customer Hub

Cosa imparerai

Come controllare Customer Hub, o la web chat di Klaviyo autonoma, dal codice della vetrina sul sito usando l’API JavaScript window.customerHubApi. Aprirai e chiuderai l’esperienza, passerai a una schermata specifica, invierai un messaggio di chat per conto dell’acquirente e resterai in ascolto di eventi come l’aggiunta al carrello.

Prima di iniziare

Avrai bisogno di:

• Customer Hub configurato e caricato sulla vetrina sul sito. Se utilizzi una vetrina headless o personalizzata, segui prima Come configurare Customer Hub con Shopify headless: include l’aggiunta del loader onsite che rende disponibile questa API.
• Possibilità di modificare e distribuire il tuo codice del negozio online.

Cos'è il Customer Hub API

Ogni volta che Customer Hub, o la web chat standalone di Klaviyo, viene caricata sulla vetrina del tuo negozio, Klaviyo collega una piccola API JavaScript all'oggetto globale window come window.customerHubApi. Puoi usarla per aprire, chiudere e interagire con l'esperienza dal tuo codice, ad esempio da un pulsante personalizzato, un banner o una pagina prodotto.

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

Metodi

open(route?)

Apre il cassetto del Customer Hub.

• route (stringa, facoltativo) — un percorso di navigazione da seguire all’apertura. Se omesso, l’Hub si apre sulla schermata visualizzata l’ultima volta.

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

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

Percorsi disponibili

close()

Chiude il pannello a scomparsa del Customer Hub. L'Hub rimane nella schermata attuale, quindi riaprendolo con open() (nessun percorso) il cliente torna al punto in cui aveva interrotto.

window.customerHubApi.close();

sendChatMessage(message)

Apre il Customer Hub nella schermata della chat e invia un messaggio per conto del cliente, utile per i pulsanti "Chiacchiera di questo prodotto" o "Chiedi aiuto".

• message (string) — il messaggio da inviare.

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

Quando è richiesto l'accesso: se il tuo negozio richiede ai clienti di effettuare l'accesso prima di chattare (e l'AI Agent non è abilitato), il cliente viene indirizzato alla schermata Chat per accedere per primo. Il messaggio viene salvato temporaneamente e inviato automaticamente al termine dell'accesso. Se il login non viene completato, il messaggio salvato scade dopo circa 10 minuti.

getActiveConversationId()

Restituisce conversationId per la conversazione attiva in corso nel pannello a scomparsa. Restituisce null se non è in corso alcuna conversazione.

window.customerHubApi.getActiveConversationId();

Ascolta gli eventi

window.customerHubApi.events ti consente di iscriviti agli eventi che si verificano all'interno di Customer Hub.

addtocart

Si attiva quando un cliente aggiunge un prodotto al carrello dall'Hub. Utilizzalo per sincronizzare il tuo carrello della vetrina.

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

Esempio completo

Un pulsante "Chatta di questo prodotto" che apre l'Hub e invia un messaggio, oltre a un ascoltatore che sincronizza il carrello della vetrina quando un acquirente aggiunge un articolo dall'Hub:

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

Risorse aggiuntive