Jak skonfigurować Klaviyo Customer Hub z Headless Shopify
Połącz Klaviyo Customer Hub ze swoim headless storefrontem Shopify. Włącz logowanie, wyświetl widżety (Ulubione, FAQ) oraz zapewnij obsługę funkcji produktowych Aktywni/Ostatnio oglądane, aby zwiększyć zaangażowanie i konwersję.
Czego się dowiesz?
Połączysz Klaviyo Customer Hub z bezgłowym storefrontem Shopify, wybierzesz metodę logowania i opublikujesz Hub, aby klienci mogli uzyskać do niego dostęp w całej witrynie.
Klaviyo Customer Hub dla Shopify obsługuje obecnie standardowe witryny sklepowe oraz Shopify Headless. W przypadku WooCommerce przejdź do https://help.klaviyo.com/hc/es-es/articles/47792369863451
Kilka słów na początek
Wymagania wstępne
- Bezobsługowy sklep Shopify z dostępem do Storefront API (publiczny token dostępu / klucz publiczny Storefront API w Headless Admin Shopify).
- Twój identyfikator firmy Klaviyo (używany przez moduł ładujący JavaScript na stronie).
- Decyzja dotycząca logowania kupujących: Shopify Customer Account API lub jednorazowe hasło (OTP) w Klaviyo.
- Jeśli używasz istniejących kont, przygotuj ścieżki dla przycisków Zaloguj się, Wyloguj się oraz (opcjonalnie) Zarządzaj kontem i Zarządzaj adresami w swoim sklepie.
- Możliwość edytowania kodu storefrontu i wdrażania zmian.
- Rola konta z uprawnieniami do edytowania Klaviyo Customer Hub, np. właściciel lub administrator. W przypadku roli niestandardowej uwzględnij uprawnienia do wyświetlania i edytowania Klaviyo Customer Hub.
- Okres próbny Klaviyo Customer Hub lub plan, który obejmuje Ulubione i FAQ, jeśli chcesz korzystać z tych funkcji.
Przegląd
Klaviyo Customer Hub to nakładka na całą witrynę, która zapewnia kupującym szybszy dostęp do działań na koncie i przydatnych narzędzi zakupowych. W przypadku headless Shopify podłączasz skrypt onsite Klaviyo, wybierasz metodę logowania (Shopify Customer konto API lub Klaviyo OTP), a opcjonalnie dodajesz:
- Aktywny produkt: pokazuje produkt, który kupujący przegląda w Hubie.
- Ostatnio przeglądane: wyświetla listę ostatnio przeglądanych produktów, korzystając ze śledzenia Klaviyo.
- Widżety ulubionych i FAQ: wyświetlają się na stronach szczegółów produktu (PDP) oraz w Hubie.
Klaviyo Customer Hub używaj, gdy potrzebujesz warstwy pomocy na stronie, która wspiera odkrywanie produktów i szybsze finalizowanie zakupu, poprawiając konwersję i wartość życiową.
Konfiguracja
1. Skonfiguruj ustawienia Klaviyo Customer Hub
Najpierw wykonaj kroki z Pierwsze kroki z Klaviyo Customer Hub i ukończ kreator wdrożenia. Pozostaw Klaviyo Customer Hub ukryty, dopóki Twoja konfiguracja headless nie będzie gotowa. Następnie przejdź do Klaviyo Customer Hub > Ustawienia i znajdź Konfiguracja headless Shopify.

Włącz konfigurację Headless Shopify i wklej swój publiczny token dostępu Shopify w polu klucz publiczny Storefront API.
W sekcji Logowanie klienta wybierz Shopify Customer Konto API, aby używać istniejących danych logowania Shopify, lub Klaviyo One Time Password (OTP), aby logowanie działało tylko z Klaviyo.

Jeśli wybierzesz Shopify Customer konto API, wpisz trasę logowania i trasę wylogowania dla swojego sklepu. Trasa zarządzania kontem i trasa zarządzania adresami są opcjonalne. Te trasy przekierowują kupujących między Hubem a Twoją stroną.

Jeśli wybierzesz Klaviyo One Time Password (OTP), wpisz Nazwa wyświetlana sklepu i E-mail do odpowiedzi. Adres e-mail do odpowiedzi nie może być adresem w domenie gmail.com ani klaviyo.com.
Kliknij Zapisz, aby zapisać ustawienia. Aby sprawdzić status publikacji Hubu, kliknij Otwórz edytor. Pozostaw status Ukryty, dopóki nie ukończysz konfiguracji witryny sklepu oraz poniższych testów.

2. Załaduj JavaScript Klaviyo Customer Hub (instrukcje dla deweloperów)
Wskazówka: Jeśli masz już uruchomione funkcje Klaviyo onsite, możesz mieć już skonfigurowany moduł ładujący. Potwierdź przed dodaniem drugiego skryptu.
Utwórz /public/customerHub.js (lub odpowiednik) z następującym programem ładującym (zastąp COMPANY_ID swoim publicznym kluczem API Klaviyo, znanym również jako identyfikator firmy):
// 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);W swoim głównym układzie (np. root.tsx) dodaj loader, aby skrypt onsite ładował się na każdej stronie. Sprawdź w konsoli komunikat „Klaviyo JS script loaded successfully.”
// root.tsx
return (
<html>
<body>
<script src="/customerHub.js" defer></script>
</body>
</html>
)Po zakończeniu ładowania Huba dostępne staje się window.customerHubApi. Komunikat o powodzeniu ładowania potwierdza, że skrypt został załadowany; poczekaj na Hub API, zanim wywołasz hydrateProduct, jak pokazano poniżej.
3. Pokaż aktywny produkt w Klaviyo Customer Hub
Dodaj ten skrypt do kodu HTML strony produktu, zastępując your-product-handle bieżącym identyfikatorem produktu w Shopify. Jeśli Twój sklep korzysta z Reacta lub innego frameworka z nawigacją po stronie klienta, uruchom wywołanie hydratacji w ramach cyklu życia strony tego frameworka za każdym razem, gdy produkt się zmieni.

<!-- 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>Na komputerze Hub może wyświetlać bieżącą kartę produktu na karcie Czat, gdy włączony jest czat online. Ta karta nie jest wyświetlana na urządzeniach mobilnych.
4. Włącz ostatnio przeglądane produkty w Klaviyo Customer Hub
Wdróż śledzenie Viewed Product na stronach produktów, aby móc używać tej metryki w Klaviyo. Wywołaj też trackViewedItem, aby zapisywać ostatnio przeglądane produkty w przeglądarce kupującego na potrzeby Hub. Postępuj zgodnie z przykładami śledzenia w Zintegruj platformę e-commerce bez wstępnie zbudowanej integracji Klaviyo.

5. Włącz przejęcie linku do konta
Gdy Klaviyo Customer Hub jest aktywny, może zastąpić linki do konta kończące się na /account lub /account/login, aby otwierały Hub. Aby otworzyć Hub z niestandardowej ikony konta, ustaw link na #k-hub. Dodaj data-k-hub-ignore do linku do konta, jeśli ma on nadal otwierać stronę konta w Twoim sklepie.

6. Połącz uwierzytelnianie Shopify Customer konto API (zalecane)
Wykonaj ten krok tylko wtedy, jeśli w sekcji Shopper login wybrałeś(-aś) Shopify Customer konto API. Jeśli wybrałeś(-aś) Klaviyo One Time Password (OTP), przejdź do kroku 7.
Dodaj ścieżkę na serwerze pod adresem /api/authenticateCustomerHub, która akceptuje żądania POST i przekazuje do Klaviyo token dostępu zalogowanego klienta. W przykładzie ustaw COMPANY_ID na identyfikator firmy Klaviyo.
Poniższy przykład wykorzystuje framework Hydrogen firmy Shopify. Dostosuj trasę serwera do swojego frameworka, jeśli używasz innego storefrontu.
// ./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});
}
}Gdy ta trasa oraz trasy witryny sklepowej w ustawieniach Klaviyo zostaną skonfigurowane, Klaviyo Customer Hub będzie mógł połączyć się z Twoim istniejącym loginem do konta klienta.
7. Dodaj widżet Ulubione (zalecane)
Ulubione i często zadawane pytania mogą wyświetlać się w wysuwanym panelu Klaviyo Customer Hub. Możesz też dodać je do stron szczegółów produktu, aby klienci mogli zapisywać produkty i znajdować odpowiedzi podczas przeglądania.
Najpierw włącz Ulubione w edytorze Hub. Następnie przejdź do Klaviyo Customer Hub > Design, wybierz Ulubione i wskaż, którzy kupujący mogą widzieć widżet na stronie. Kliknij Opublikuj, aby zapisać ustawienia widżetu, a następnie dodaj poniższy kontener do strony produktu. Zastąp przykładowy identyfikator produktu Shopify identyfikatorem bieżącego produktu.
// 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}
/>
)Gdy Klaviyo Customer Hub jest aktywny, a widżet jest widoczny dla kupującego, może on kliknąć Dodaj do ulubionych na stronie produktu. Zapisane produkty pojawią się w sekcji Ulubione w Hubie.

8. Dodaj bloki FAQ (zalecane)
Utwórz swoje bloki FAQ w Klaviyo. W Klaviyo Customer Hub > Projekt wybierz FAQ, wybierz pytania do wyświetlania na stronach produktów oraz skonfiguruj widoczność i projekt na stronie. Kliknij Opublikuj, aby zapisać ustawienia przed dodaniem poniższego kontenera.
Dodaj ten kontener do strony produktu z bieżącym identyfikatorem produktu Shopify. Te same wybrane FAQ wyświetlają się na stronach produktów; identyfikator produktu nie wybiera innych pytań dla każdego produktu.
// products.tsx
// Example:
const gid = "gid://shopify/Product/12345";
const productId = gid.split('/').pop();
return (
<div className="klaviyo-faqs-slot" data-product-id={productId} />
)Wybrane przyciski FAQ pojawiają się na stronach produktów zgodnie z Twoimi ustawieniami widoczności. Kliknięcie pytania otwiera jego odpowiedź w Klaviyo Customer Hub.
9. Przetestuj i aktywuj Klaviyo Customer Hub
Przetestuj kod witryny sklepu w środowisku stagingowym, zanim wdrożysz go na produkcję. Automatyczne przejęcie łączenia konta oraz widżet Ulubione na stronie wymagają Live, więc uwzględnij je w końcowych kontrolach na środowisku live.
- Gdy będziesz gotowy(-a) do publikacji, przejdź do Klaviyo Customer Hub > Ustawienia i kliknij Otwórz edytor.
- Zapisz wszystkie oczekujące zmiany projektu Hub. Następnie wybierz Na żywo z listy rozwijanej statusu lub kliknij Opublikuj, gdy Hub jest ukryty i nie ma niezapisanych zmian.
- Poczekaj na potwierdzenie, że Klaviyo Customer Hub działa. W swoim produkcyjnym sklepie sprawdź logowanie i wylogowanie, ikonę konta, kartę produktu Czat na komputerze (jeśli jest włączona), ostatnio oglądane produkty oraz wszelkie widżety Ulubione lub FAQ, które dodano.
Najlepsze praktyki
- Opublikuj w środowisku produkcyjnym dopiero po testach, aby uniknąć problemów z pomocą techniczną. Pozostaw Hub produkcyjny jako Ukryty, dopóki konfiguracja nie będzie gotowa, a potem ustaw go jako Aktywny w edytorze Huba.
- Zasilaj aktywny produkt danymi na stronach PDP, aby zachować kontekst produktu dostępny w Hubie i pomóc kupującym dodać go do koszyka. Monitoruj wskaźnik konwersji i przychody na odbiorcę (przychody na odbiorcę), aby ocenić efekt.
- Wdróż śledzenie produktów wcześnie, aby uzupełnić sekcję ostatnio oglądanych produktów i wspierać sekwencje oparte na przeglądaniu. Monitoruj zaangażowanie i przychody z odzyskiwania po przeglądaniu.
- Dodaj Ulubione, aby dać kupującym łatwy sposób na zapisanie krótkiej listy. Monitoruj ponowne wizyty i aktywność dodawania do koszyka.
- Używaj sekcji FAQ, aby odpowiadać na pytania dotyczące dostawy, materiałów lub zwrotów, gdy kupujący przeglądają ofertę. Monitoruj współczynnik odrzuceń i wskaźnik konwersji.
- Jeśli jest dostępne, używaj uwierzytelniania po stronie serwera z Shopify Customer konto API, aby zachować ciągłość dla zalogowanych kupujących i pomóc zmniejszyć liczbę zgłoszeń do pomocy technicznej związanych z logowaniem.
Mierzenie sukcesu
Użyj Analytics > metryka, aby monitorować aktywność Viewed Product. Przejrzyj wyniki działań dalszego etapu w swoich sekwencjach i kampaniach. Użyj pulpitów przychodów z e-commerce, aby śledzić zmiany konwersji i średniej wartości zamówienia (średnia wartość zamówienia) po włączeniu Klaviyo Customer Hub.
Monitoruj wskaźnik konwersji ze stron produktu, wskaźnik dodania do koszyka, sesje z otwarciami Hub (jeśli są instrumentowane), przychody na odbiorcę (przychody na odbiorcę) (RPR) oraz przychody z przeglądania powiązane ze zdarzeniami Viewed Product.
Szybkie kontrole
- Jeśli aktywność „ostatnio oglądane” jest niska, zweryfikuj śledzenie produktów i sprawdź, czy zdarzenia Viewed Product są przypisywane do profili. Sprawdź też śledzenie „ostatnio oglądane” oparte na przeglądarce.
- Jeśli w Hubie widzisz niską aktywność dodawania do koszyka, sprawdź, czy aktywne uzupełnianie danych produktów działa na każdej stronie PDP oraz czy warianty i ceny są poprawne.
- Aby dodać tylko kilka produktów do Ulubionych, umieść sekcję Ulubione w pobliżu głównych wezwań do działania (CTA) na stronie produktu i potwierdź, że
data-product-idpasuje do produktu.
Rozwiązywanie problemów
Objaw: Klaviyo Customer Hub nie wyświetla się na stronie.
Prawdopodobna przyczyna: Skrypt się nie ładuje lub Hub jest ukryty.
Poprawka: Potwierdź, że customerHub.js się ładuje, identyfikator firmy jest ustawiony i Klaviyo Customer Hub jest aktywny. Aby zmienić jego status, przejdź do Klaviyo Customer Hub > Ustawienia > Otwórz edytor i użyj listy rozwijanej statusu.
Objaw: Konsola wyświetla komunikat „Failed to load Klaviyo JS script.”
Prawdopodobna przyczyna: Nieprawidłowy adres URL skryptu lub brak identyfikatora firmy.
Rozwiązanie: Sprawdź https://static.klaviyo.com/onsite/js/<COMPANY_ID>/klaviyo.js i upewnij się, że COMPANY_ID jest uzupełnione.
Objaw: Karta Aktywny produkt nie wyświetla się w Hub na PDP.
Prawdopodobna przyczyna: brakuje wywołania hydracji, uchwyt produktu jest nieprawidłowy lub sprawdzasz kartę produktu czatu na urządzeniu mobilnym.
Poprawka: Na komputerze otwórz Czat z włączonym czatem online. Upewnij się, że pętla oczekiwania działa, i wywołaj window.customerHubApi.hydrateProduct("<handle>") z poprawnym identyfikatorem produktu.
Objaw: Sekcja „Ostatnio wyświetlane” jest pusta.
Prawdopodobna przyczyna: Brakujące lub niepełne śledzenie produktów.
Poprawka: dodaj śledzenie zdarzenia Viewed Product oraz śledzenie przeglądarki trackViewedItem. Zweryfikuj zdarzenia na rozpoznanym profilu i sprawdź ostatnio przeglądane produkty w tej samej przeglądarce.
Objaw: Widżety Ulubione lub FAQ nie wyświetlają się na PDP.
Prawdopodobna przyczyna: brakujący kontener, nieprawidłowy identyfikator produktu, ukryty widżet lub plan, który nie obejmuje tej funkcji.
Poprawka: dodaj <div class="kl-hub-favorites-slot" data-product-id="..."></div> lub <div class="klaviyo-faqs-slot" data-product-id="..."></div> z prawidłowym identyfikatorem produktu. Potwierdź dostęp do funkcji i jej widoczność w Klaviyo oraz wybierz FAQ dla stron produktu. Klaviyo Customer Hub musi być też Live, aby wyświetlił się widżet Ulubione.
Objaw: Kliknięcie ikony konta nie otwiera Hubu.
Prawdopodobna przyczyna: link do konta nie pasuje do obsługiwanego adresu URL konta, jest wykluczony z przejęcia lub Klaviyo Customer Hub jest ukryte.
Poprawka: ustaw Klaviyo Customer Hub na Na żywo, użyj linku do konta kończącego się na /account lub /account/login albo ustaw href="#k-hub". Usuń data-k-hub-ignore tylko z linków, które powinny otwierać Hub.
Objaw: Po wybraniu Shopify Customer konto API kupujący nie są rozpoznawani jako zalogowani w Hubie.
Prawdopodobna przyczyna: Brakująca trasa /api/authenticateCustomerHub lub nieudane żądanie API.
Poprawka: Zaimplementuj przykład Hydrogen (lub odpowiednik w Twoim frameworku), wyślij access_token i company_id do punktu końcowego logowania Klaviyo i zwróć odpowiedź.
Najczęściej zadawane pytania
P: Czy muszę używać Shopify Customer konto API do logowania?
A: Nie. Możesz zamiast tego użyć hasła jednorazowego Klaviyo (OTP). Jeśli już używasz kont Shopify, połącz się przez Shopify Customer Account API, aby zapewnić płynne korzystanie.
P: Jakie trasy witryny sklepowej muszę podać?
A: Dla API konta klienta Shopify podaj ścieżkę logowania i ścieżkę wylogowania. Ścieżka zarządzania kontem i ścieżka zarządzania adresami są opcjonalne na potrzeby głębszego linkowania.
P: Gdzie mogę znaleźć publiczny klucz API sklepu?
O: Użyj publicznego tokena dostępu do swojego sklepu w kanale Headless w Shopify. Skorzystaj z przewodnika konfiguracji Shopify Storefront API, a następnie wpisz publiczny token w polu Klaviyo Klucz publiczny Storefront API.
P: Czy Klaviyo Customer Hub może przejąć moją ikonę konta?
O: Tak. Gdy Klaviyo Customer Hub jest aktywny, linki kończące się na /account lub /account/login mogą automatycznie otwierać Hub. Możesz też skierować link do swojego konta na #k-hub.
P: Czy Shopify Hydrogen jest wymagany?
O: Nie. Przykład uwierzytelniania używa Hydrogen, ale dowolny framework może zaimplementować trasę serwera pod adresem /api/authenticateCustomerHub, która wysyła do Klaviyo token dostępu i company_id.
P: Czy Ulubione i FAQ mogą znajdować się na stronach PDP i w Hubie?
O: Tak. Skonfiguruj ulubione i FAQ w Klaviyo, a następnie dodaj ich kontenerowe divy do stron produktów. Ich widoczność w Hubie i na stronach produktów zależy od wybranych przez Ciebie ustawień.