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

• Una vetrina Shopify headless con accesso alla Storefront API (token di accesso pubblico/chiave pubblica API Storefront nell'Amministratore headless di Shopify).
• Il tuo ID aziendale Klaviyo (utilizzato dal loader JavaScript sul sito).
• Decisione sull’accesso dell’acquirente: Shopify Customer Account API o Klaviyo One Time Password (OTP).
  • Se utilizzi account esistenti, tieni pronti i percorsi Login, Logout e (facoltativi) Manage account e Manage addresses del tuo storefront.
• Possibilità di modificare il codice del tuo storefront e distribuire le modifiche.
• Un ruolo dell'account con autorizzazione a modificare Customer Hub, come Proprietario o Amministratore. Per un ruolo personalizzato, includi le autorizzazioni di visualizzazione e modifica di Customer Hub.
• Una prova di Customer Hub o un piano che include Preferiti e Domande frequenti, se vuoi usare queste funzionalità.

Panoramica

Customer Hub è una sovrimpressione a livello di sito che offre a chi acquista un accesso più rapido alle azioni dell’account e a utili strumenti di acquisto. Per Shopify headless, devi collegare lo script onsite di Klaviyo, scegliere un metodo di accesso (Shopify Customer Account API o Klaviyo OTP) e, facoltativamente, aggiungere:

• Prodotto attivo: mostra il prodotto che un acquirente sta visualizzando nell'Hub.
• Visualizzati di recente: elenca i prodotti visualizzati di recente utilizzando il tracciamento di Klaviyo.
• Widget di Preferiti e FAQ: vengono visualizzati sulle pagine dei dettagli del prodotto (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. Mantieni Customer Hub nascosto finché la configurazione headless non è pronta. Poi vai su Customer Hub > Impostazioni e trova Configurazione headless di Shopify.

Attiva Headless Shopify configuration e incolla il tuo token di accesso pubblico di Shopify in Storefront API public key.

In Shopper login, seleziona Shopify Customer Account API per usare il tuo accesso Shopify esistente oppure Klaviyo One Time Password (OTP) per un accesso che funziona solo con Klaviyo.

Se selezioni Shopify Customer Account API, inserisci la rotta di accesso e la rotta di disconnessione della tua vetrina. Percorso Gestisci account e Percorso Gestisci indirizzi sono opzionali. Queste rotte reindirizzano chi acquista tra l’Hub e il tuo sito.

Se selezioni Klaviyo One Time Password (OTP), inserisci Nome visualizzato del negozio e E-mail di risposta. L'e-mail di risposta non può usare un indirizzo gmail.com o klaviyo.com.

Fai clic su Salva per salvare le impostazioni. Per controllare lo stato di pubblicazione dell’hub, fai clic su Apri editor. Mantieni lo stato Nascosto finché non completi la configurazione dello storefront e i test di seguito.

2. Carica il 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);

Nel layout radice (ad esempio, root.tsx), includi il loader in modo che lo script onsite venga caricato su ogni pagina. Cerca il messaggio della console "Klaviyo JS script loaded successfully."

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

Dopo che l'hub ha terminato il caricamento, window.customerHubApi diventa disponibile. Il messaggio di riuscita del loader conferma che lo script è stato caricato; attendi l’API Hub prima di chiamare hydrateProduct, come mostrato di seguito.

3. Mostra il prodotto attivo in Customer Hub

Aggiungi il seguente script all'HTML della pagina prodotto, sostituendo your-product-handle con l'handle prodotto Shopify attuale. Se il tuo storefront usa React o un altro framework con navigazione lato client, esegui la chiamata di hydration dal ciclo di vita della pagina di quel framework ogni volta che il prodotto cambia.

<!-- Product page HTML -->
<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>

Su desktop, Hub può mostrare la scheda prodotto corrente nella scheda Chat quando web chat è abilitata. Questa scheda non viene mostrata su mobile.

4. Abilita i prodotti visualizzati di recente in Customer Hub

Implementa il tracciamento Viewed Product nelle pagine prodotto, così puoi usare questa metrica in Klaviyo. Inoltre, chiama trackViewedItem per memorizzare nel browser di chi acquista i prodotti visualizzati di recente per l’Hub. Segui gli esempi di tracciamento in Integra una piattaforma e-commerce senza un'integrazione predefinita di Klaviyo.

5. Abilita l'acquisizione dell'account tramite link

Quando Customer Hub è Live, può sostituire i link dell’account che terminano con /account o /account/login in modo che aprano l’Hub. Per aprire l'hub da un'icona account personalizzata, imposta il link su #k-hub. Aggiungi data-k-hub-ignore a un link dell’account se deve continuare ad aprire la pagina dell’account del tuo negozio online.

6. Collega l'autenticazione dell'API Shopify Customer Account (consigliata)

Completa questo passaggio solo se hai selezionato Shopify Customer Account API in Accesso acquirente. Se hai selezionato Klaviyo One Time Password (OTP), passa direttamente al passaggio 7.

Aggiungi una route del server in /api/authenticateCustomerHub che accetti richieste POST e trasmetta a Klaviyo il token di accesso del cliente che ha effettuato l’accesso. Imposta COMPANY_ID nell’esempio sul tuo ID azienda Klaviyo.

L’esempio seguente utilizza il framework Hydrogen di Shopify. Adatta il percorso del server al tuo framework se utilizzi un storefront diverso.

// ./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 configurati questo percorso e i percorsi della vetrina nelle impostazioni di Klaviyo, Customer Hub può connettersi all’accesso esistente dell’account cliente.

7. Aggiungi il widget Preferiti (consigliato)

Preferiti e domande frequenti possono essere visualizzati nel drawer di Customer Hub. Puoi anche aggiungerli alle pagine dei dettagli del prodotto, così chi acquista può salvare i prodotti e trovare le risposte mentre naviga.

Per prima cosa, abilita i Preferiti nell'editor Hub. Poi vai su Customer Hub > Design, seleziona Preferiti e scegli quali acquirenti possono vedere il widget sul sito. Fai clic su Pubblica per salvare le impostazioni del widget, poi aggiungi il seguente contenitore alla pagina del prodotto. Sostituisci l’ID prodotto Shopify di esempio con l’ID del prodotto attuale.

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

Una volta che Customer Hub è Live e il widget è visibile all’acquirente, può fare clic su Aggiungi ai preferiti in una pagina prodotto. I prodotti salvati vengono visualizzati nell’esperienza Preferiti dell’Hub.

8. Aggiungi blocchi di FAQ (consigliato)

Crea i tuoi blocchi FAQ in Klaviyo. In Customer Hub > Design, seleziona FAQ, scegli le domande da mostrare nelle pagine prodotto e configura la visibilità e la grafica onsite. Fai clic su Pubblica per salvare le impostazioni prima di aggiungere il contenitore qui sotto.

Aggiungi questo contenitore alla pagina del prodotto con l'ID prodotto Shopify attuale. Le stesse domande frequenti selezionate vengono visualizzate in tutte le pagine prodotto; l'ID prodotto non seleziona domande diverse per ciascun prodotto.

// 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 pulsanti FAQ selezionati vengono visualizzati sulle pagine prodotto in base alle tue impostazioni di visibilità. Facendo clic su una domanda si apre la relativa risposta in Customer Hub.

9. Testa e attiva Customer Hub

Testa il codice del tuo storefront in staging prima di distribuirlo in produzione. L’acquisizione automatica dei link dell’account e il widget Preferiti onsite richiedono Live, quindi includili nelle verifiche finali in live.

1. Quando sei pronto per pubblicare, vai su Customer Hub > impostazioni e fai clic su Apri editor.
2. Salva eventuali modifiche di design dell’Hub in sospeso. Quindi seleziona Attivo nel menu a tendina dello stato oppure fai clic su Pubblica quando l’Hub è nascosto e non sono presenti modifiche non salvate.
3. Attendi la conferma che Customer Hub è attivo. Nel tuo storefront di produzione, verifica accesso e disconnessione, l'icona dell'account, la scheda prodotto della Chat su desktop se abilitata, i prodotti visti di recente e tutti i widget Preferiti o FAQ che hai aggiunto.

Procedure consigliate

• Pubblica in production solo dopo i test per evitare problemi di supporto. Mantieni l’Hub in production Nascosto finché la configurazione non è pronta, poi impostalo Live dall’editor dell’Hub.
• Idrata il prodotto attivo sulle PDP per mantenere il contesto del prodotto disponibile nell'Hub e aiutare chi acquista ad aggiungerlo al carrello. Monitora il tasso di conversione e le entrate per destinatario (RPR) per valutarne l'effetto.
• Implementa presto il tracciamento dei prodotti per compilare i prodotti visualizzati di recente e supportare i flussi basati sulla navigazione. Monitora il coinvolgimento degli utenti e le entrate del recupero della navigazione.
• Aggiungi Preferiti per offrire a chi acquista un modo semplice per salvare una lista ristretta. Monitora le visite ripetute e l’attività di aggiunta al carrello.
• Usa le domande frequenti per rispondere alle domande su spedizione, materiali o resi mentre chi acquista naviga. Controlla l’abbandono e il tasso di conversione.
• Quando disponibile, usa l’autenticazione lato server con la Shopify Customer Account API per mantenere la continuità per chi acquista dopo aver effettuato l’accesso e contribuire a ridurre le richieste di assistenza legate all’accesso.

Misurazione dei risultati

Usa Analytics > Metriche per monitorare l’attività Viewed Product. Esamina le prestazioni successive nei tuoi flussi e nelle tue campagne. Usa i pannelli di controllo delle entrate e-commerce per monitorare le variazioni della conversione e del valore medio dell'ordine (valore medio dell'ordine) dopo aver abilitato Customer Hub.

Monitora il tasso di conversione dalle pagine prodotto, il tasso di aggiunta al carrello, le sessioni con apertura di Hub (se strumentate), le entrate per destinatario (tasso di acquisto ripetuto) e le entrate generate dalla navigazione legate agli eventi Viewed Product.

Controlli rapidi

• Se l’attività dei “visualizzati di recente” è bassa, verifica il tracciamento dei prodotti e controlla che gli eventi Prodotto visualizzato siano attribuiti ai profili. Controlla anche il tracciamento dei “visualizzati di recente” basato sul browser.
• In caso di bassa attività di aggiunta al carrello dall’Hub, verifica che l’idratazione prodotto attiva venga eseguita su ogni PDP e che varianti e prezzi siano corretti.
• Per aggiunte ridotte ai Preferiti, posiziona lo slot Preferiti vicino alle call-to-action principali della pagina prodotto e verifica 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: conferma che customerHub.js venga caricato, che l’ID azienda sia impostato e che Customer Hub sia Live. Per cambiarne lo stato, vai su Customer Hub > Impostazioni > Apri editor e usa il menu a discesa dello stato.

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: manca la chiamata di idratazione, l’handle del prodotto non è corretto oppure stai controllando la scheda prodotto della chat da dispositivo mobile.

Correzione: sul desktop, apri Chat con web chat abilitata. Assicurati che il loop di attesa venga eseguito e chiama window.customerHubApi.hydrateProduct("<handle>") con l’handle prodotto corretto.

Sintomo: la sezione visualizzati di recente è vuota.

Causa probabile: tracciamento dei prodotti mancante o incompleto.

Correzione: aggiungi il tracciamento dell'evento Prodotto visualizzato e il tracciamento del browser trackViewedItem. Verifica gli eventi su un profilo riconosciuto e controlla i prodotti visualizzati di recente nello stesso browser.

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

Causa probabile: un contenitore mancante, un ID prodotto errato, un widget nascosto o un piano che non include la funzionalità.

Correzione: aggiungi <div class="kl-hub-favorites-slot" data-product-id="..."></div> o <div class="klaviyo-faqs-slot" data-product-id="..."></div> con l’ID prodotto corretto. Conferma l’accesso e la visibilità della funzionalità in Klaviyo e seleziona le FAQ per le pagine prodotto. Anche Customer Hub deve essere Live affinché venga visualizzato il widget Preferiti.

Sintomo: facendo clic sull’icona dell’account, l’hub non si apre.

Causa probabile: il link dell’account non corrisponde a un URL di account supportato, è escluso dall’acquisizione dell’account o Customer Hub è nascosto.

Correzione: imposta Customer Hub su Live, usa un link dell’account che termina con /account o /account/login, oppure imposta href="#k-hub". Rimuovi data-k-hub-ignore solo dai link che dovrebbero aprire l’Hub.

Sintomo: con l'API Shopify Customer Account selezionata, chi acquista non viene riconosciuto come connesso 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 Account per l’accesso?

R: No. In alternativa, puoi usare la Password univoca (OTP) di Klaviyo. Se usi già gli account Shopify, connettiti tramite la Shopify Customer Account API per un’esperienza senza interruzioni.

D: Quali route del negozio online devo fornire?

A: Per Shopify Customer Account API, fornisci percorso di accesso e percorso di disconnessione. Percorso di gestione dell’account e percorso di gestione degli indirizzi sono facoltativi per link più approfonditi.

D: Dove trovo la chiave pubblica API Storefront?

R: utilizza il token di accesso pubblico per la tua vetrina nel canale Headless di Shopify. Segui la guida di configurazione dell’API Storefront di Shopify, quindi inserisci il token pubblico nel campo Chiave pubblica dell’API Storefront di Klaviyo.

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

A: Sì. Quando Customer Hub è Attivo, i link che terminano con /account o /account/login possono aprire l’Hub automaticamente. Puoi anche far puntare il link del tuo account 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ì. Configura Preferiti e FAQ in Klaviyo, poi aggiungi i loro div contenitore alle pagine prodotto. La loro visibilità nell'hub e nelle pagine prodotto segue le impostazioni che scegli.