Come configurare il Customer Hub di Klaviyo con Headless Shopify

Cosa imparerai

Dovrai collegare Klaviyo Customer Hub a un negozio headless Shopify, scegliere un metodo di login e pubblicare l'Hub in modo che gli acquirenti possano accedervi in tutto il sito.

Prima di iniziare

Prerequisiti 

⚠️ Nota: prima di procedere, devi contattare il tuo rappresentante, il CSM o Klaviyo l'assistenza per abilitare l'assistenza Headless Shopify per il tuo account Klaviyo in modo da poter accedere alle configurazioni necessarie. Come contattare l'assistenza

1. Uno storefront headless Shopify con accesso allo storefront API (token di accesso pubblico / chiave pubblica dello storefront API nell'amministratore headless Shopify).
2. Il tuo ID aziendale di Klaviyo (utilizzato dal caricatore JavaScript in loco).
3. Decisione sul login dell'acquirente: API dell'account cliente di Shopify o Klaviyo One Time Password (OTP).
   1. Se utilizzi account esistenti, tieni pronti i percorsi Login, Logout e (opzionale) Gestisci account e Gestisci indirizzi del tuo negozio.
4. Possibilità di modificare il codice della vetrina e distribuire le modifiche.
5. Chi può configurarlo: È necessario un ruolo dell'account che possa modificare le impostazioni di Klaviyo Customer Hub e pubblicare widget (Proprietario, Amministratore, o un ruolo personalizzato che abbia accesso in scrittura a Contenuti e chiave API). 

Panoramica

Klaviyo Customer Hub è un overlay per tutto il sito che consente agli acquirenti di accedere più rapidamente alle azioni dell'account e agli strumenti utili per lo shopping. Per Shopify senza testa, si collega lo script onsite di Klaviyo, si sceglie un metodo di accesso (Customer Accounts API o Klaviyo OTP) e si aggiunge un'opzione:

1. Prodotto attivo: mostra il prodotto che l'acquirente sta visualizzando all'interno dell'Hub.
2. Visti di recente: elenco dei prodotti visti di recente utilizzando il tracciamento di Klaviyo.
3. Widget Preferiti e FAQ: renderli sui PDP e all'interno dell'Hub.  

Utilizza Klaviyo Customer Hub quando vuoi un livello di assistenza on-page che ti permetta di scoprire i prodotti e accelerare il checkout, migliorando la conversione e il valore del ciclo di vita.

Impostazione

1 - Configurare le impostazioni dell'hub clienti di Klaviyo

Per prima cosa, segui Primi passi con Klaviyo Customer Hub e completa la procedura guidata di onboarding, come per qualsiasi altra configurazione. Una volta completata questa operazione, vai su Klaviyo Customer Hub > Impostazioni. Vedrai la sezione di configurazione di Headless Shopify. 

Incolla la chiave pubblica del tuo Storefront API da Shopify'amministratore senza testa (token di accesso pubblico). 

Alla voce Accesso acquirente, seleziona Shopify Customer Account API (consigliato in modo che tutte le tue app possano condividere il login di Shopify) o Klaviyo One Time Password (OTP, funziona solo con Klaviyo e non fa accedere gli acquirenti ad altre app). 

Se selezioni Shopify Customer Account API, inserisci anche i percorsi Login, Logout e Manage account/Manageaddresses (utilizzati per i reindirizzamenti tra l'Hub e il tuo sito). 

Pubblica visibilità: imposta Klaviyo Customer Hub su Live. 

2 - Carica il JavaScript di Klaviyo Customer Hub (istruzioni per gli sviluppatori)

Suggerimento: se già gestisci Klaviyo onsite funzionalità, potresti avere già un caricatore. Conferma prima di aggiungere un secondo script. 

Crea /public/customerHub.js (o un file equivalente) con il seguente loader (sostituisci COMPANY_ID con la chiave API pubblica di Klaviyo, nota anche come ID dell'azienda):

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

Lo script in loco viene caricato su ogni pagina. Cerca il messaggio della console: "Lo script Klaviyo JS è stato caricato con successo".  Nel tuo layout principale (ad esempio, root.tsx), includere il caricatore:

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

Dopo questo passaggio, window.customerHubApi diventa disponibile nelle pagine in cui viene eseguito l'Hub. 

3 - Mostra il prodotto attivo nell'Hub clienti di Klaviyo

Aggiungi il richiamo all'idrato nella pagina di dettaglio del prodotto (PDP) in modo che il prodotto attuale appaia nell'Hub:

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

L'Hub dovrebbe ora visualizzare una scheda prodotto aggiuntiva per il PDP che l'acquirente sta visualizzando nella scheda "Chat" se l'hai abilitata. 

4 - Abilita i prodotti visti di recente nel Customer Hub di Klaviyo

Implementa il tracciamento dei prodotti visualizzati in modo che l'Hub possa inserire gli articoli visualizzati di recente e tu possa utilizzare la metrica in altre parti di Klaviyo. I seguenti snippet di tracciamento possono anche essere aggiunti direttamente alla tua vetrina; le istruzioni sono disponibili qui nella nostra documentazione per sviluppatori Klaviyo: Integrare una piattaforma di e-commerce senza un predefinito Klaviyo integrazioni.

5 - Abilita l'acquisizione del link dell'account

Affinché l'Hub clienti di Klaviyo di Klaviyosi apra cliccando sull'icona dell'account nell'intestazione della tua vetrina, è necessario che tu abbia già un a-tag esistente che faccia riferimento a un link con /account (in tal caso lo sostituiremo automaticamente). Oppure puoi anche definire manualmente il link dell'icona che punta a #k-hub per aprire il cassetto.

6 - Configura Klaviyo Customer Hub con l'autenticazione degli account cliente API (consigliato)

Per poter utilizzare l'account cliente e l'autenticazione della tua vetrina esistente, Klaviyo Customer Hub ti chiederà di aggiungere una nuova rotta API alla tua vetrina che si occuperà di passare in modo sicuro il token di accesso di un acquirente Accedi ai nostri servizi. L'importante è che la nuova rotta API abbia un nome e possa essere portata con '/API/authenticateCustomerHub'.

Nota: il seguente esempio di snippet di codice si riferisce al framework Hydrogen di Shopify; storefront più personalizzati potrebbero richiedere qualche soluzione aggiuntiva, tuttavia l'approccio generale sarà illustrato qui.

// ./app/routes/API.authenticateCustomerHub.js
// TODO: Configurazione
const COMPANY_ID = '';
export async function action({context}) {
 // Preleva il Client Account Cliente API dal contesto del tuo storefront
 const {customerAccount} = context;
 try {
 // Ottieni il token di accesso per il cliente corrente
 const accessToken = await customerAccount.getAccessToken();
    if (!accessToken) {
 return new Response(JSON.stringify({message: 'User not logged in'}), {
        status: 200,
      });
 }
   // Inviare il token di accesso al 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();
    // Restituiamo la risposta effettiva da Klaviyo Customer Hub con lo stesso codice di stato
 return new Response(responseData, {
 status: response.status,
      header: {
        'Content-Type':
          response.headers.get('content-type') || 'application/json',
      },
 });
 } catch (error) {
 return new Response(null, {status: 500});
 }
}

Una volta configurato questo, così come i percorsi della vetrina definiti nelle impostazioni di Klaviyo, Klaviyo Customer Hub sarà in grado di collegarsi alla tua configurazione di autenticazione esistente e di fornire un punto di accesso continuo agli account dei tuoi clienti.

7 - Aggiungi il widget Preferiti (consigliato)

Sia i Preferiti che le FAQ funzionano all'interno del cassetto di Klaviyo Customer Hub. Tuttavia, puoi aggiungere questi widget anche sui PDP per ottenere un ulteriore coinvolgimento degli utenti.

Per aggiungere un punto di accesso ai Preferiti sui PDP e all'interno dell'Hub:

// products.tsx
// Identificatori di esempio:
// 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}
  />
 )

Gli acquirenti possono ora fare clic su Aggiungi ai preferiti sui PDP; l'articolo viene visualizzato negli articoli preferiti dell'Hub. 

8 - Aggiungi blocchi di FAQ (consigliato)

Come per l'aggiunta dei Preferiti, l'aggiunta di blocchi FAQ è semplice come l'aggiunta di un div nella pagina del prodotto con l'ID del prodotto passato per rendere le FAQ che puoi modificare e progettare in Klaviyo.

Aggiungi un blocco FAQ specifico per il prodotto che hai progettato in Klaviyo:

// products.tsx
// Esempio:
const gid = "gid://Shopify/Product/12345";
const productId = gid.split('/').pop();

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

I chip/pulsanti delle FAQ ora vengono visualizzati sui PDP se sono impostati e sono modificabili in Klaviyo.

Procedure consigliate

1. Pubblica in produzione solo dopo la verifica: tieni nascosta la fase di staging fino al completamento della QA; poi imposta la funzione Live per esporre l'Hub. Impatto: meno problemi di assistenza, time-to-value più rapido.
2. Idrata sempre il prodotto attivo sui PDP: mantiene il contesto del prodotto visibile nell'Hub e favorisce l'aggiunta al carrello. Impatto: tasso di conversione, tasso di acquisto ripetuto.
3. Implementa il tracciamento dei prodotti visti in anticipo - popola i prodotti visti di recente e sblocca il flusso basato sulla navigazione. Impatto: coinvolgimento degli utenti (engagement) e ricavi dal recupero delle pagine.
4. Aggiungi preferiti - crea un'azione di salvataggio a basso attrito e una lista di preferiti persistente. Impatto: visite ripetute, add-to-cart.
5. Usa le FAQ per le obiezioni: rispondi alle domande sulla spedizione, sui materiali o sui resi in linea per ridurre gli abbandoni. Impatto: tasso di conversione.
6. Preferisci l'autenticazione lato server con l'API Account cliente quando disponibile: migliora la continuità per gli acquirenti che hanno effettuato il login. Impatto: qualità dell'esperienza, deviazione dell'assistenza.  

Misurazione dei risultati

Dove visualizzare i risultati: Utilizza le metriche di Analytics > per controllare l'attività del prodotto visualizzato e le prestazioni del flusso/campagna a valle. Utilizza il pannello di controllo del tuo e-commerce per monitorare le conversioni e le modifiche al valore medio dell'ordine dopo aver abilitato Klaviyo Customer Hub. Metriche chiave da tenere d'occhio: tasso di conversione da PDP, tasso di add-to-cart, sessioni con aperture dell'Hub (se strumentate), entrate per destinatario (tasso di acquisto ripetuto) e entrate browse-driven legate agli eventi Viewed Product. Lista di controllo per le soluzioni rapide: Bassa Attività visualizzate di recente? Verifica che il tracciamento del prodotto visualizzato sia attivo e che gli eventi siano attribuiti al profilo. Basso numero di aggiunte al carrello da parte dell'Hub? Assicurati che l'idratazione attiva dei prodotti funzioni su ogni PDP e che le varianti e i prezzi siano corretti. Qualche aggiunta ai preferiti? Sposta lo slot dei preferiti vicino alle CTA del PDP principale e conferma che il data-product-id corrisponda al prodotto.  

Risoluzione dei problemi

Sintomo: Klaviyo Customer Hub non appare sul sito.

Causa probabile: Lo script non si carica o l'hub è nascosto.

Correzione: verifica che customerHub.js sia caricato (controlla la console), che l'ID dell'azienda sia impostato e che la visibilità di Klaviyo Customer Hub sia attiva nelle Impostazioni di Klaviyo Customer Hub > . 

Sintomo: la console mostra "Failed to load Klaviyo JS script".

Causa probabile: URL dello script non corretto o ID azienda mancante.

Correggi: Verifica che https://static.Klaviyo.com/onsite/js/<COMPANY_ID>/Klaviyo.js e che COMPANY_ID sia popolato. 

Sintomo: la scheda prodotto attiva non viene visualizzata nell'Hub sui PDP.

Causa probabile: hydrateProduct non chiamato o maniglia del prodotto errata.

Correzione: Assicurarsi che il ciclo di attesa venga eseguito e chiamare window.customerHubApi.hydrateProduct("<handle>" ) con l'impugnatura corretta del prodotto. 

Sintomo: la sezione "Visti di recente" è vuota.

Causa probabile: Tracciamento del prodotto visualizzato non implementato.

Correzione: aggiungi lo snippet di tracciamento Viewed Product dalla guida per gli sviluppatori e verifica gli eventi in Klaviyo. 

Sintomo: i widget Preferiti o FAQ non vengono visualizzati sul PDP.

Causa probabile: Contenitore mancante o attributo sbagliato.

Correzione: Aggiungi <div class="kl-hub-favorites-slot" data-product-id="..."> e/o <div class="klaviyo-faqs-slot" data-product-id="..."> con l'ID prodotto corretto. 

Sintomo: cliccando sull'icona dell'account non si apre l'Hub.

Causa probabile: Il link dell'intestazione non punta a /account o a #k-hub.

Correzione: assicurarsi che l'ancora dell'account utilizzi /account (acquisizione automatica) o impostare href="#k-hub". 

Sintomo: gli acquirenti non vengono riconosciuti come Accedi all'interno dell'Hub.

Causa probabile: Manca la rotta /API/authenticateCustomerHub o la richiesta API è fallita.

Correzione: implementa l'esempio di Hydrogen (o l'equivalente del tuo framework), invia access_token e company_id all'endpoint di login di Klaviyo e restituisci la risposta. 

Domande frequenti

D: Devo utilizzare l'API di Shopify Customer Accounts per il login?

R: No. Puoi invece utilizzare la One Time Password (OTP) di Klaviyo. Se utilizzi già un account Shopify, connettiti tramite l'API Customer Accounts per un'esperienza senza soluzione di continuità. 

D: Quali percorsi devo fornire per le vetrine?

R: Se utilizzi gli account esistenti, fornisci i percorsi di Login e Logout; Gestisci account e Gestisci indirizzi sono opzionali per un collegamento più profondo. 

D: Dove posso trovare la chiave pubblica dell'API Storefront?

R: In Shopify's Headless Amministratore sotto Storefront API > Public access token (chiamato anche Storefront API public key). 

D: Il Customer Hub di Klaviyo può prendere in carico l'icona del mio account?

R: Sì. Se il link all'account della tua testata utilizza /account, Klaviyo Customer Hub può aprirsi automaticamente; puoi anche puntare a #k-hub. 

D: È necessario Shopify Hydrogen?

R: No. L'esempio di autenticazione utilizza Hydrogen, ma qualsiasi framework può implementare una rotta server a /API/authenticateCustomerHub che invia il token di accesso e il company_id a Klaviyo. 

D: I Preferiti e le FAQ possono essere presenti sui PDP e all'interno dell'Hub?

R: Sì. Aggiungi i rispettivi div contenitore sui PDP; verranno visualizzati anche nel cassetto Hub.