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
Aby przekazać opinię na temat funkcjonalności Klaviyo Customer Hub, wyślij e-mail na adres customerhub@klaviyo.com.
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.
- Kto może to skonfigurować: Potrzebna jest rola na koncie, która pozwala edytować ustawienia Klaviyo Customer Hub i publikować widżety (właściciel, administrator lub rola niestandardowa z dostępem do zapisu w obszarze Treści i kluczy API).
Przegląd
Klaviyo Customer Hub to nakładka obejmująca całą witrynę, która zapewnia kupującym szybszy dostęp do działań na koncie i przydatnych narzędzi zakupowych. W przypadku headless Shopify łączysz skrypt onsite Klaviyo, wybierasz metodę logowania (Customer konto API lub Klaviyo OTP) i 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 Ulubione i FAQ: wyświetlają się na stronach 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 skorzystaj z Pierwszych kroków z Klaviyo Customer Hub i ukończ kreator wdrażania — tak jak w przypadku każdej innej konfiguracji. Gdy to będzie gotowe, przejdź do Klaviyo Customer Hub > Ustawienia. Zobaczysz sekcję konfiguracji Shopify bez interfejsu użytkownika.
Włącz przełącznik Konfiguracja bezgłowego Shopify, a następnie wklej publiczny klucz Storefront API z bezgłowego panelu administratora Shopify (Public access token).
W sekcji Logowanie kupującego wybierz Shopify Customer Customer Konto API (zalecane, aby wszystkie aplikacje storefront mogły współdzielić logowanie Shopify) lub Klaviyo One Time Password (OTP, działa tylko z Klaviyo i nie zaloguje kupujących do żadnych innych aplikacji).
Jeśli wybierzesz Shopify Customer Account API, wprowadź też ścieżki do: Logowania, Wylogowania oraz opcjonalnie Zarządzania kontem/Zarządzania adresami (używane do przekierowań między Hubem a Twoją witryną).
Widoczność publikacji: ustaw Klaviyo Customer Hub na Na żywo.
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);Skrypt onsite wczytuje się na każdej stronie. Wyszukaj komunikat konsoli: „Skrypt Klaviyo JS został pomyślnie wczytany.” W głównym układzie (np. root.tsx), uwzględnij moduł ładujący:
// root.tsx
return (
<html>
<body>
<script src="/customerHub.js" defer></script>
</body>
</html>
)Po tym kroku window.customerHubApi staje się dostępny na stronach, na których działa Hub.
3 – Pokaż aktywny produkt w Klaviyo Customer Hub
Dodaj wywołanie hydrate na stronie szczegółów produktu (PDP), aby bieżący produkt pojawiał się w 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>Teraz Hub powinien wyświetlać dodatkową kartę produktu dla PDP, które kupujący(-a) ogląda na karcie „Czat”, jeśli jest to włączone.
4 – Włącz ostatnio wyświetlane produkty w Klaviyo Customer Hub
Wdróż śledzenie Wyświetlono produkt, aby Hub mógł wypełniać elementy Ostatnio wyświetlone i aby można było używać tej metryki w innych miejscach w Klaviyo. Poniższe fragmenty śledzenia można też dodać bezpośrednio do Twojego sklepu. Instrukcje znajdziesz tutaj w dokumentacji Klaviyo Developers: Integracja platformy e-commerce bez gotowej integracji Klaviyo.
5 — Włącz przejęcie linku do konta
Aby Klaviyo Customer Hub otwierał się po kliknięciu ikony konta w nagłówku witryny sklepu, musisz mieć już istniejący znacznik a, który odwołuje się do linku z /account (w takim przypadku automatycznie go podmienimy). Możesz też ręcznie zdefiniować link ikony tak, aby wskazywał na #k-hub, aby otworzyć wysuwany panel.
6 – Skonfiguruj Klaviyo Customer Hub z uwierzytelnianiem API Customer Accounts (zalecane)
Aby móc korzystać z istniejących kont klientów i konfiguracji uwierzytelniania w swoim sklepie, Klaviyo Customer Hub będzie wymagać dodania do sklepu nowej trasy API, która będzie bezpiecznie przekazywać do naszych usług token dostępu zalogowanego kupującego. Ważne jest to, aby nowa trasa API miała nazwę i była dostępna pod ścieżką „/api/authenticateCustomerHub”.
Uwaga: poniższy przykładowy wycinek kodu źródłowego dotyczy frameworka Shopify Hydrogen; bardziej niestandardowe sklepy mogą wymagać dodatkowego obejścia, jednak ogólne podejście zostanie tu przedstawione.
// ./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 to zostanie skonfigurowane, a także gdy w ustawieniach Klaviyo zostaną zdefiniowane trasy witryny sklepu, Klaviyo Customer Hub będzie mógł połączyć się z istniejącą konfiguracją uwierzytelniania i zapewnić płynny punkt wejścia do istniejących kont klientów.
7 — Dodaj widżet Ulubione (zalecane)
Zarówno Ulubione, jak i FAQ będą działać w szufladzie Klaviyo Customer Hub. Możesz jednak dodać te widżety także na stronach PDP, aby zwiększyć zaangażowanie.
Aby dodać punkt wejścia Ulubione na stronach PDP i w Hubie:
// 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}
/>
)Kupujący mogą teraz kliknąć Dodaj do ulubionych na stronach PDP; produkt pojawi się w Ulubionych produktach w Hubie.
8 – Dodaj bloki FAQ (zalecane)
Podobnie jak dodawanie Ulubionych, dodawanie bloków FAQ jest tak proste jak dodanie elementu div na stronie produktu z przekazanym jego identyfikatorem produktu, aby wyrenderować FAQ, które możesz edytować i projektować w Klaviyo.
Dodaj blok FAQ dotyczący konkretnego produktu, który zaprojektujesz w 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} />
)Żetony/przyciski FAQ powinny się teraz wyświetlać na stronach PDP, jeśli są skonfigurowane, i można je edytować w Klaviyo
Najlepsze praktyki
- Publikuj w środowisku produkcyjnym dopiero po weryfikacji — utrzymuj środowisko staging ukryte do momentu zakończenia QA; następnie ustaw Live, aby udostępnić Hub. Wpływ: mniej zgłoszeń do pomocy technicznej, szybszy czas do uzyskania wartości.
- ZAWSZE NAWADNIAJ AKTYWNY PRODUKT NA PDP — utrzymuje widoczny kontekst produktu w Hub i zachęca do dodania do koszyka. Wpływ: wskaźnik konwersji, wskaźnik powtórnych zakupów.
- Wdróż wcześnie śledzenie Viewed Product — wypełnia sekcję Ostatnio wyświetlane i odblokowuje sekwencje oparte na przeglądaniu. Wpływ: zaangażowanie i przychody z odzyskiwania przeglądania.
- Dodaj do ulubionych — tworzy łatwą akcję zapisywania i trwałą listę skróconą. Wpływ: ponowne wizyty, dodawanie do koszyka.
- Wykorzystaj sekcję FAQ do odpowiedzi na obiekcje — odpowiadaj na pytania dotyczące wysyłki, materiałów lub zwrotów bezpośrednio w treści, aby zmniejszyć liczbę porzuceń. Wpływ: wskaźnik konwersji.
- Jeśli to możliwe, wybieraj uwierzytelnianie po stronie serwera z Customer Accounts API — poprawia ciągłość dla zalogowanych kupujących. Wpływ: jakość doświadczenia, odciążenie wsparcia.
Mierzenie sukcesu
Gdzie wyświetlać wyniki: Użyj Analityka > Metryki, aby monitorować aktywność Viewed Product oraz dalszą skuteczność sekwencji/kampanii. Korzystaj z pulpitów przychodów e-commerce, aby śledzić zmiany konwersji i średniej wartości zamówienia po włączeniu Klaviyo Customer Hub. Kluczowe metryki do obserwowania: wskaźnik konwersji z PDP, wskaźnik dodania do koszyka, sesje z otwarciami Hub (jeśli zaimplementowano instrumentację), przychody na odbiorcę (przychody na odbiorcę) oraz przychody oparte na przeglądaniu powiązane ze zdarzeniami Viewed Product. Lista kontrolna szybkich poprawek: Niska aktywność Recently viewed? Sprawdź, czy fragment kodu śledzenia Viewed Product działa i czy zdarzenia są przypisywane do profili. Niski poziom dodawania do koszyka z Hub? Upewnij się, że hydratacja aktywnego produktu działa na każdej stronie PDP oraz że warianty/ceny są poprawne. Mało dodań do Favorites? Przenieś slot Ulubione bliżej głównych wezwań do działania na PDP i potwierdź, że data-product-id pasuje 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.
Rozwiązanie: Potwierdź, że customerHub.js się ładuje (sprawdź konsolę), identyfikator firmy jest ustawiony oraz widoczność Klaviyo Customer Hub ma status Live w sekcji Klaviyo Customer Hub > Settings.
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: nie wywołano hydrateProduct lub użyto nieprawidłowego uchwytu produktu.
Poprawka: Upewnij się, że pętla oczekiwania działa, i wywołaj window.customerHubApi.hydrateProduct("<handle>") z prawidłowym identyfikatorem produktu (handle).
Objaw: Sekcja „Ostatnio wyświetlane” jest pusta.
Prawdopodobna przyczyna: Nie wdrożono śledzenia Viewed Product.
Poprawka: Dodaj fragment kodu śledzenia Viewed Product z przewodnika dla deweloperów i zweryfikuj zdarzenia w Klaviyo.
Objaw: Widżety Ulubione lub FAQ nie wyświetlają się na PDP.
Prawdopodobna przyczyna: Brak kontenera lub nieprawidłowy atrybut.
Rozwiązanie: Dodaj <div class="kl-hub-favorites-slot" data-product-id="..."> i/lub <div class="klaviyo-faqs-slot" data-product-id="..."> z prawidłowym identyfikatorem produktu.
Objaw: Kliknięcie ikony konta nie otwiera Hubu.
Prawdopodobna przyczyna: Link w nagłówku nie prowadzi do /konto ani #k-hub.
Poprawka: Upewnij się, że kotwica konta używa /account (auto‐takeover) lub ustaw href="#k-hub".
Objaw: Klienci 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 do logowania muszę używać interfejsu API Shopify Customer Accounts?
O: Nie. Zamiast tego możesz użyć Hasło jednorazowe Klaviyo (OTP). Jeśli korzystasz już z kont Shopify, połącz się przez API kont klientów, aby zapewnić płynne działanie.
P: Jakie trasy witryny sklepowej muszę podać?
O: Jeśli używasz istniejących kont, podaj ścieżki dla Zaloguj się i Wyloguj się; Zarządzaj kontem i Zarządzaj adresami są opcjonalne w przypadku głębszego linkowania.
P: Gdzie mogę znaleźć publiczny klucz API sklepu?
A: W administratorze Headless Shopify w sekcji Storefront API > Public access token (nazywanej także Storefront API public key).
P: Czy Klaviyo Customer Hub może przejąć moją ikonę konta?
A: Tak. Jeśli link do konta w nagłówku korzysta z /account, Klaviyo Customer Hub może otwierać się automatycznie; możesz też wskazać go 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?
A: Tak. Dodaj odpowiednie kontenerowe elementy div na stronach PDP; pojawią się również w szufladzie Hub.