Come configurare Customer Hub con Shopify headless

Collega Customer Hub di Klaviyo alla tua vetrina headless di Shopify. Abilita l'accesso, mostra i widget (Preferiti, FAQ) e potenzia le esperienze di prodotto attivo/visualizzato di recente per aumentare il coinvolgimento degli utenti e la conversione.

Cosa imparerai

Collegherai Customer Hub a una vetrina Shopify headless, sceglierai un metodo di accesso e pubblicherai l'Hub così che chi acquista possa accedervi in tutto il sito.

Prima di iniziare

Prerequisiti

1. Una vetrina Shopify headless con accesso alla Storefront API (token di accesso pubblico/chiave pubblica API Storefront nell'Amministratore headless di Shopify).
2. Il tuo ID aziendale Klaviyo (utilizzato dal loader JavaScript sul sito).
3. Decisione sull’accesso dell’acquirente: Shopify Customer Account API o Klaviyo One Time Password (OTP).
   1. Se utilizzi account esistenti, tieni pronti i percorsi Login, Logout e (facoltativi) Manage account e Manage addresses del tuo storefront.
4. Possibilità di modificare il codice del tuo storefront e distribuire le modifiche.
5. Chi può configurarlo: ti serve un ruolo dell’account che possa modificare le impostazioni di Customer Hub e pubblicare widget (Proprietario, Amministratore o un ruolo personalizzato con accesso in scrittura a Contenuti e chiavi API).

Panoramica

Customer Hub è una sovrapposizione a livello di sito che offre agli acquirenti un accesso più rapido alle azioni dell’account e a utili strumenti per lo shopping. Per Shopify headless, colleghi lo script on-site di Klaviyo, scegli un metodo di accesso (Customer Accounts API o Klaviyo OTP) e, facoltativamente, aggiungi:

1. Prodotto attivo: mostra il prodotto che un acquirente sta visualizzando nell'Hub.
2. Visualizzati di recente: elenca i prodotti visualizzati di recente utilizzando il tracciamento di Klaviyo.
3. Widget Preferiti e FAQ: vengono mostrati sulle PDP e all’interno dell’Hub. 

Usa Customer Hub quando ti serve un livello di assistenza sulla pagina che favorisce la scoperta dei prodotti e un checkout più rapido, migliorando la conversione e il valore del ciclo di vita.

Impostazione

1 - Configura le impostazioni di Customer Hub

Per prima cosa, segui Primi passi con Customer Hub e completa la procedura guidata di onboarding, proprio come faresti con qualsiasi altra configurazione. Una volta completata, vai a Customer Hub > Impostazioni. Vedrai la sezione di configurazione per Shopify headless.

Attiva Configurazione headless di Shopify e poi incolla la chiave pubblica della Storefront API dall’Amministratore headless di Shopify (token di accesso pubblico).

In Accesso acquirente, seleziona Shopify Customer Account API (consigliato, così tutte le tue app storefront possono condividere l’accesso di Shopify) oppure Klaviyo One Time Password (OTP, funziona solo con Klaviyo e non consente agli acquirenti di accedere ad altre app).

Se selezioni Shopify Customer Account API, inserisci anche i percorsi Accesso, Disconnessione e facoltativo Gestisci account/Gestisci indirizzi del tuo storefront (utilizzati per i reindirizzamenti tra l'Hub e il tuo sito).

Visibilità della pubblicazione: imposta Customer Hub su Live.

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

Suggerimento: Se utilizzi già le funzionalità onsite di Klaviyo, potresti avere già un loader. Conferma prima di aggiungere un secondo script.

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

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

Lo script onsite viene caricato su ogni pagina. Cerca il messaggio nella console: "Klaviyo JS script loaded successfully."  Nel layout root (ad esempio, root.tsx), includi il loader:

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

Dopo questo passaggio, window.customerHubApi diventa disponibile sulle pagine in cui è in esecuzione l'Hub.

3 - Mostra il prodotto attivo in Customer Hub

Aggiungi la chiamata hydrate alla pagina dei dettagli del prodotto (PDP) in modo che il prodotto corrente compaia 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>

Il Hub dovrebbe ora mostrare una scheda prodotto aggiuntiva per la PDP che l'acquirente sta visualizzando nella scheda "Chat" se l'hai abilitata.

4 - Abilita i prodotti visti di recente in Customer Hub

Implementa il tracciamento Viewed Product in modo che l'Hub possa compilare gli articoli Recently viewed e tu possa usare la metrica altrove in Klaviyo. I seguenti snippet di tracciamento possono anche essere aggiunti direttamente al tuo negozio online; le istruzioni sono disponibili qui nella nostra documentazione Klaviyo Developers: Integrare una piattaforma e-commerce senza un'integrazione Klaviyo predefinita.

5 - Abilita l’acquisizione del link dell’account

Affinché il Customer Hub di Klaviyo si apra facendo clic sull'icona dell'account nell'intestazione del tuo storefront, devi già avere un tag a esistente che rimanda a un link con /account (in tal caso lo sostituiremo automaticamente per te). In alternativa, puoi anche definire manualmente il link dell'icona in modo che punti a #k-hub per aprire il drawer.

6 - Configura Customer Hub con l'autenticazione API Customer Accounts (consigliato)

Per utilizzare gli account cliente e la configurazione di autenticazione del tuo negozio online esistente, Customer Hub richiederà l'aggiunta di una nuova route API al tuo negozio online che gestirà in modo sicuro il passaggio del token di accesso di un acquirente connesso ai nostri servizi. È importante che la nuova route API abbia un nome e sia raggiungibile con '/api/authenticateCustomerHub'.

Nota: l'esempio seguente di snippet di codice è per il framework Hydrogen di Shopify; negozi online più personalizzati potrebbero richiedere qualche ulteriore soluzione alternativa, tuttavia qui verrà delineato l'approccio generale.

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

Una volta configurato questo, oltre ai percorsi dello storefront definiti nelle impostazioni di Klaviyo, Customer Hub potrà collegarsi alla configurazione di autenticazione esistente e offrire un punto di accesso semplice agli account cliente esistenti.

7 - Aggiungi il widget Preferiti (consigliato)

Sia Preferiti che FAQ funzioneranno nel drawer di Customer Hub. Tuttavia, puoi aggiungere questi widget anche nelle PDP per aumentare il coinvolgimento degli utenti.

Per aggiungere un punto di accesso a Preferiti nelle PDP e all'interno dell'Hub:

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

Ora chi compra può fare clic su Aggiungi ai preferiti nelle pagine dei dettagli del prodotto; l’articolo viene visualizzato in Articoli preferiti nell’Hub.

8 - Aggiungi blocchi di FAQ (consigliato)

Analogamente all’aggiunta dei preferiti, aggiungere i blocchi delle FAQ è semplice come aggiungere un div nella pagina del prodotto con l’ID del prodotto passato per visualizzare le FAQ che puoi modificare e progettare in Klaviyo.

Aggiungi un blocco di FAQ specifiche per il prodotto che progetti in Klaviyo:

// products.tsx
// Example:
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 dovrebbero essere visualizzati nelle PDP se sono configurati e sono modificabili in Klaviyo

Procedure consigliate

1. Pubblica in produzione solo dopo la verifica — mantieni l’ambiente di staging nascosto finché il QA non è completo; poi imposta Live per esporre l’hub. Impatto: meno problemi di assistenza, time-to-value più rapido.
2. Idrata sempre il prodotto attivo sulle PDP — mantiene visibile il contesto del prodotto nell’hub e incentiva l’aggiunta al carrello. Impatto: tasso di conversione, tasso di acquisto ripetuto.
3. Implementa subito il tracciamento Viewed Product — compila Recently viewed e sblocca i flussi basati sulla navigazione. Impatto: coinvolgimento degli utenti e ricavi dal recupero della navigazione.
4. Aggiungi ai preferiti — crea un'azione di salvataggio a basso attrito e una shortlist persistente. Impatto: visite ripetute, aggiunta al carrello.
5. Usa le FAQ per gestire le obiezioni — rispondi direttamente alle domande su spedizione, materiali o resi per ridurre l’abbandono. Impatto: tasso di conversione.
6. Preferisci l'autenticazione lato server con Customer Accounts API quando disponibile: migliora la continuità per gli acquirenti che hanno effettuato l'accesso. Impatto: qualità dell'esperienza, riduzione delle richieste di assistenza. 

Misurazione dei risultati

Dove visualizzare i risultati: usa Analytics > metriche per monitorare l'attività Viewed Product e le prestazioni del flusso/campagna a valle. Usa i pannelli di controllo delle entrate e-commerce per monitorare le variazioni di conversione e valore medio dell'ordine dopo aver abilitato Customer Hub. Metriche chiave da monitorare: tasso di conversione da PDP, tasso di add-to-cart, sessioni con aperture dell'Hub (se strumentate), entrate per destinatario (entrate per destinatario) ed entrate generate dalla navigazione legate agli eventi Viewed Product. Checklist di correzioni rapide: attività Recently viewed bassa? Verifica che lo snippet di tracciamento Viewed Product venga attivato e che gli eventi siano attribuiti ai profili. Add-to-cart basso dall'Hub? Assicurati che l'idratazione Active Product venga eseguita su ogni PDP e che varianti/prezzi siano corretti. Pochi aggiunte ai Preferiti? Sposta lo slot Preferiti vicino alle CTA principali della PDP e conferma che data-product-id corrisponda al prodotto. 

Risoluzione dei problemi

Sintomo: Customer Hub non viene visualizzato sul sito.

Causa probabile: lo script non viene caricato oppure l’hub è Nascosto.

Correzione: verifica che customerHub.js venga caricato (controlla la console), che l’ ID azienda sia impostato e che la visibilità di Customer Hub sia Live in Customer Hub > Settings.

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

Causa probabile: URL dello script errato o ID azienda mancante.

Correzione: verifica https://static.klaviyo.com/onsite/js/<COMPANY_ID>/klaviyo.js e che COMPANY_ID sia compilato.

Sintomo: la scheda Prodotto attivo non viene mostrata nell'Hub nelle PDP.

Causa probabile: hydrateProduct non chiamato o handle del prodotto errato.

Correzione: assicurati che il ciclo di attesa venga eseguito e chiama window.customerHubApi.hydrateProduct("<handle>") con l’handle del prodotto corretto.

Sintomo: la sezione visualizzati di recente è vuota.

Causa probabile: il tracciamento Prodotto visualizzato non è implementato.

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

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

Causa probabile: container mancante o attributo errato.

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: facendo clic sull’icona dell’account, l’hub non si apre.

Causa probabile: il link nell'intestazione non rimanda a /account o #k-hub.

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

Sintomo: gli acquirenti non vengono riconosciuti come connessi nell'Hub.

Causa probabile: route /api/authenticateCustomerHub mancante o richiesta API non riuscita.

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

Domande frequenti

D: Devo usare l'API Shopify Customer Accounts per l'accesso?

A: No. In alternativa, puoi usare Klaviyo One Time Password (OTP). Se usi già gli account Shopify, connettiti tramite la Customer Accounts API per un'esperienza senza interruzioni.

D: Quali route del negozio online devo fornire?

R: Se utilizzi gli account esistenti, fornisci le route Accesso e Disconnessione; Gestisci account e Gestisci indirizzi sono facoltative per collegamenti più approfonditi.

D: Dove trovo la chiave pubblica API Storefront?

A: Nell’Amministratore Headless di Shopify, in Storefront API > Public access token (chiamato anche Storefront API public key).

D: Customer Hub può sostituire l'icona del mio account?

A: Sì. Se il link account nell'header utilizza /account, Customer Hub può aprirsi automaticamente; puoi anche puntarlo a #k-hub.

D: Shopify Hydrogen è obbligatorio?

A: No. L’esempio di autenticazione usa Hydrogen, ma qualsiasi framework può implementare una route del server in /api/authenticateCustomerHub che invia l’access token e company_id a Klaviyo.

D: i Preferiti e le FAQ possono essere presenti sulle PDP e all’interno dell’Hub?

A: Sì. Aggiungi i rispettivi div container sulle PDP; verranno visualizzati anche nel drawer dell’Hub.