Headless Shopify로 Klaviyo 고객 허브 설정하기
Klaviyo 고객 허브를 헤드리스 Shopify 스토어프런트에 연결하세요. 로그인을 활성화하고, 위젯(즐겨찾기, FAQ)을 노출하며, 활성/최근 본 상품 경험을 강화해 참여 유도와 전환을 높이세요.
학습 내용
Klaviyo 고객 허브를 헤드리스 Shopify 스토어프런트에 연결하고, 로그인 방법을 선택한 다음, 쇼핑객이 사이트 전체에서 액세스할 수 있도록 허브를 게시할 거예요.
Shopify용 Klaviyo 고객 허브는 현재 표준 스토어프런트와 Shopify Headless를 지원해요. WooCommerce의 경우 https://help.klaviyo.com/hc/en-us/articles/47792369863451 로 이동해 주세요.
Klaviyo 고객 허브 기능에 대한 피드백은 customerhub@klaviyo.com으로 이메일을 보내 주세요.
시작하기 전에 알아야 할 것
필수 항목
- Storefront API에 액세스할 수 있는 헤드리스 Shopify 스토어프론트(Shopify 헤드리스 관리자에서 공개 액세스 토큰/Storefront API 공개 키).
- 온사이트 JavaScript 로더에서 사용하는 Klaviyo 회사 ID 입니다.
- 쇼퍼 로그인 결정: Shopify Customer Account API 또는 Klaviyo 일회용 비밀번호(OTP).
- 기존 계정을 사용하는 경우 스토어프런트의 로그인, 로그아웃, (선택 사항) 계정 관리 및 주소 관리 경로를 준비해 주세요.
- 스토어프런트 코드를 편집하고 변경 사항을 배포할 수 있어요.
- 설정할 수 있는 사람: Klaviyo 고객 허브 설정을 편집하고 위젯을 게시할 수 있는 계정 역할이 필요해요(소유자, 관리자 또는 콘텐츠 및 API 키에 대한 쓰기 권한이 있는 사용자 지정 역할).
개요
Klaviyo 고객 허브는 사이트 전체에 표시되는 오버레이로, 쇼핑객이 계정 작업과 유용한 쇼핑 도구에 더 빠르게 액세스할 수 있도록 해줘요. 헤드리스 Shopify의 경우, Klaviyo의 온사이트 스크립트를 연결하고 로그인 방법(고객 계정 API 또는 Klaviyo OTP)을 선택한 다음, 선택적으로 다음을 추가할 수 있어요:
- 활성 제품: Hub에서 쇼핑객이 보고 있는 제품을 표시해요.
- 최근 본 항목: Klaviyo의 트래킹을 사용해 최근에 본 제품 목록을 표시해요.
- 즐겨찾기 및 FAQ 위젯: PDP와 허브 내에서 렌더링돼요.
페이지 내 지원 레이어로 상품 탐색을 유도하고 더 빠른 결제를 지원해 전환과 생애 가치를 개선하고 싶을 때 Klaviyo 고객 허브를 사용하세요.
설치
1 - Klaviyo 고객 허브 설정 구성
먼저 Klaviyo 고객 허브 시작하기 를 따라 다른 설정과 마찬가지로 온보딩 마법사를 완료하세요. 완료되면 Klaviyo 고객 허브 > 설정으로 이동하세요. 헤드리스 Shopify 구성 섹션이 표시됩니다.
Headless Shopify 구성을 켠 다음, Shopify Headless 관리자(공개 액세스 토큰)에서 Storefront API 공개 키를 붙여넣으세요.
Shopper login에서 Shopify Customer Account API(권장, 모든 스토어프론트 앱이 Shopify의 로그인을 공유할 수 있음) 또는 Klaviyo 일회용 비밀번호(OTP, Klaviyo에서만 작동하며 쇼퍼가 다른 앱에는 로그인되지 않음)를 선택해 주세요.
Shopify Customer Account API를 선택하는 경우 스토어프론트의 로그인, 로그아웃, 그리고 선택 사항인 계정 관리/주소 관리 경로(허브와 사이트 간 리디렉션에 사용됨)도 입력하세요.
게시 공개 범위: Klaviyo 고객 허브를 라이브로 설정하세요.
2 - Klaviyo 고객 허브 JavaScript 로드(개발자 안내)
팁: 이미 Klaviyo 온사이트 기능을 실행 중이라면 로더가 이미 설정되어 있을 수 있어요. 두 번째 스크립트를 추가하기 전에 확인하세요.
다음 로더가 포함된 /public/customerHub.js(또는 이에 상응하는 파일)를 생성하세요(COMPANY_ID를 Klaviyo 공개 API 키(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);온사이트 스크립트는 모든 페이지에서 로드돼요. 콘솔 메시지를 확인하세요: “Klaviyo JS script loaded successfully.” 루트 레이아웃(예: root.tsx)에서 로더를 포함하세요:
// root.tsx
return (
<html>
<body>
<script src="/customerHub.js" defer></script>
</body>
</html>
)이 단계 후 window.customerHubApi 는 Hub가 실행되는 페이지에서 사용할 수 있습니다.
3 - Klaviyo 고객 허브에서 활성 제품 표시
현재 제품이 Hub에 표시되도록 제품 상세 페이지(PDP)에 hydrate 호출을 추가하세요:
<!-- 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>활성화한 경우, 이제 Hub의 "채팅" 탭에서 쇼핑객이 보고 있는 PDP에 대한 추가 제품 카드가 표시됩니다.
4 - Klaviyo 고객 허브에서 최근 본 제품 활성화하기
Hub에서 최근 본 항목을 채울 수 있고 Klaviyo의 다른 곳에서 이 지표를 사용할 수 있도록 Viewed Product 트래킹을 구현하세요. 다음 트래킹 스니펫은 스토어프런트에 직접 추가할 수도 있으며, 지침은 Klaviyo 개발자 문서에서 확인할 수 있어요: 사전 구축된 Klaviyo 연동 없이 전자상거래 플랫폼 연동하기.
5 - 계정 링크 탈취 활성화
스토어프런트 헤더의 계정 아이콘을 클릭해 Klaviyo 고객 허브가 열리게 하려면, /account가 포함된 링크를 참조하는 기존 a 태그가 이미 있어야 해요(이 경우 자동으로 대체해 드려요). 또는 아이콘 링크가 #k-hub를 가리키도록 수동으로 정의하여 서랍을 열 수도 있어요.
6 - 고객 계정 API 인증으로 Klaviyo 고객 허브 설정(권장)
기존 스토어프론트의 고객 계정 및 인증 설정을 사용하려면, Klaviyo 고객 허브에서 로그인한 쇼퍼의 액세스 토큰을 서비스로 안전하게 전달하는 처리를 담당할 새 API 경로를 스토어프론트에 추가해야 해요. 중요한 점은 새 API 경로에 이름이 지정되어 있고 ‘/api/authenticateCustomerHub’로 접근할 수 있어야 한다는 거예요.
참고: 다음 코드 조각 예시는 Shopify의 Hydrogen 프레임워크용이에요. 더 맞춤화된 스토어프론트는 추가적인 해결 방법이 필요할 수 있지만, 일반적인 접근 방식은 여기에서 설명할게요.
// ./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});
}
}이 구성이 완료되고 Klaviyo 설정에서 스토어프론트 라우트도 정의되면, Klaviyo 고객 허브는 기존 인증 설정에 연결하고 기존 고객 계정으로 원활하게 진입할 수 있는 시작점을 제공할 수 있어요.
7 - 즐겨찾기 위젯 추가(권장)
즐겨찾기와 FAQ는 모두 Klaviyo 고객 허브 서랍 내에서 작동합니다. 하지만 추가 참여 유도를 위해 PDP에도 이러한 위젯을 추가할 수 있어요.
PDP 및 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}
/>
)쇼핑객은 이제 PDP에서 즐겨찾기에 추가를 클릭할 수 있으며, 해당 항목은 Hub의 즐겨찾는 항목에 표시돼요.
8 - FAQ 블록 추가(권장)
즐겨찾기를 추가하는 것과 마찬가지로, FAQ 블록을 추가하는 것은 제품 페이지에 제품 ID를 전달하는 div를 추가하기만 하면 간단히 완료돼요. 그러면 Klaviyo에서 편집하고 디자인할 수 있는 FAQ가 렌더링돼요.
Klaviyo에서 디자인한 제품별 FAQ 블록을 추가하세요:
// products.tsx
// Example:
const gid = "gid://shopify/Product/12345";
const productId = gid.split('/').pop();
return (
<div className="klaviyo-faqs-slot" data-product-id={productId} />
)FAQ 칩/버튼은 설정되어 있는 경우 이제 PDP에서 렌더링되어야 하며, Klaviyo에서 편집할 수 있어요.
모범 사례
- 검증 후에만 프로덕션에 게시 — QA가 완료될 때까지 스테이징을 숨겨 두고, 완료되면 라이브를 설정해 Hub를 노출하세요. 영향: 지원 문제 감소, 가치 실현까지의 시간 단축.
- PDP에서는 항상 활성 제품을 하이드레이션하세요 ― Hub에서 제품 컨텍스트가 보이도록 유지하고 장바구니 추가를 유도해요. 영향: 전환율, 재구매율.
- Viewed Product 트래킹을 일찍 구현하세요 ― Recently viewed에 데이터를 채우고, 탐색 기반 플로우를 사용할 수 있어요. 영향: 탐색 복구에서 참여 유도와 매출이 증가해요.
- 즐겨찾기 추가 ― 마찰이 적은 저장 동작과 지속적인 후보 목록을 만들어요. 영향: 재방문, 장바구니 추가.
- FAQ로 반대 의견에 대응하기 — 배송, 소재 또는 반품 관련 질문에 인라인으로 답변해 이탈을 줄이세요. 영향: 전환율.
- 가능한 경우 Customer Accounts API를 사용하는 서버 측 인증을 선호 하세요. 로그인한 쇼퍼의 연속성이 개선됩니다. 영향: 경험 품질, 지원 문의 감소.
성공 측정
결과 확인 위치: 분석 > 지표에서 Viewed Product 활동과 이후의 플로우/캠페인 성과를 모니터링하세요. Klaviyo 고객 허브를 활성화한 후 전환과 평균 주문 금액 변화를 추적하려면 전자상거래 수익 대시보드를 사용하세요. 확인해야 할 주요 지표: PDP의 전환율, 장바구니 추가율, 허브 열기 세션(계측된 경우), 수신자당 수익(RPR), Viewed Product 이벤트에 연결된 탐색 기반 수익을 확인하세요. 빠른 수정 체크리스트: 최근 본 항목 활동이 낮나요? Viewed Product 트래킹 스니펫이 정상적으로 실행되고 이벤트가 프로필에 귀속되는지 확인하세요. 허브에서 장바구니 추가가 낮나요? 모든 PDP에서 활성 제품 하이드레이션이 실행되고, 같은 이메일의 다른 버전/가격이 정확한지 확인하세요. 즐겨찾기 추가가 적나요? 즐겨찾기 슬롯을 핵심 PDP CTA 근처로 옮기고 data-product-id가 제품과 일치하는지 확인하세요.
문제 해결
증상: Klaviyo 고객 허브가 사이트에 표시되지 않습니다.
가능성이 높은 원인: 스크립트가 로드되지 않거나 Hub가 숨김 상태예요.
수정: customerHub.js가 로드되는지(콘솔 확인) 확인하고, 회사 ID가 설정되어 있으며, Klaviyo 고객 허브 표시 상태가 Live 인지 Klaviyo 고객 허브 > Settings에서 확인하세요.
증상: 콘솔에 “Klaviyo JS 스크립트를 로드하지 못했습니다.”라고 표시돼요.
가능성이 높은 원인: 스크립트 URL이 올바르지 않거나 회사 ID가 누락되었어요.
해결 방법: https://static.klaviyo.com/onsite/js/<COMPANY_ID>/klaviyo.js를 확인하고, COMPANY_ID가 채워져 있는지 확인해 주세요.
증상: PDP의 Hub에 활성 Product 카드가 표시되지 않아요.
가능한 원인: hydrateProduct가 호출되지 않았거나 제품 핸들이 잘못되었습니다.
수정: 대기 루프가 실행되도록 하고 window.customerHubApi.hydrateProduct("<handle>")를 호출하세요. 올바른 제품 핸들과 함께요.
증상: 최근 조회한 섹션이 비어 있어요.
가능한 원인: Viewed Product 트래킹이 구현되지 않았습니다.
해결: 개발자 가이드의 Viewed Product 트래킹 스니펫을 추가하고 Klaviyo에서 이벤트를 확인하세요.
증상: 즐겨찾기 또는 FAQ 위젯이 PDP에 렌더링되지 않아요.
가능성이 높은 원인: 컨테이너가 누락되었거나 속성이 잘못되었어요.
해결 방법: 올바른 제품 ID와 함께 <div class="kl-hub-favorites-slot" data-product-id="..."> 및/또는 <div class="klaviyo-faqs-slot" data-product-id="...">를 추가하세요.
증상: 계정 아이콘을 클릭해도 허브가 열리지 않아요.
가능성이 높은 원인: 헤더 링크가 /계정 또는 #k-hub를 가리키지 않아요.
수정: 계정 앵커가 /account(자동 인수)를 사용하도록 하거나 href="#k-hub"로 설정하세요.
증상: 허브 내에서 쇼핑객이 로그인한 상태로 인식되지 않아요.
가능성이 높은 원인: /api/authenticateCustomerHub 경로가 누락되었거나 API 요청이 실패했어요.
수정: Hydrogen 예시(또는 사용 중인 프레임워크의 동등한 방식)를 구현하고, access_token과 company_id를 Klaviyo의 로그인 엔드포인트로 전송한 다음, 응답을 반환하세요.
자주 묻는 질문
Q: 로그인에 Shopify Customer Accounts API를 꼭 사용해야 하나요?
A: 아니요. 대신 Klaviyo 일회용 비밀번호(OTP)를 사용할 수 있어요. 이미 Shopify 계정을 사용 중이라면 Customer Accounts API를 통해 연결하여 원활한 경험을 제공하세요.
Q: 제공해야 하는 스토어프론트 라우트는 무엇인가요?
A: 기존 계정을 사용하는 경우 로그인 및 로그아웃 라우트를 제공하세요. 계정 관리 및 주소 관리는 더 심층적인 링크를 위해 선택 사항이에요.
Q: Storefront API 공개 키는 어디에서 찾을 수 있나요?
A: Shopify의 Headless 관리자에서 Storefront API > Public access token (Storefront API public key라고도 함) 아래에 있어요.
Q: Klaviyo 고객 허브가 제 계정 아이콘을 대신할 수 있나요?
A: 네. 헤더의 계정 링크가 /account를 사용하면 Klaviyo 고객 허브가 자동으로 열릴 수 있으며, #k-hub로 연결되도록 지정할 수도 있어요.
Q: Shopify Hydrogen이 필수인가요?
A: 아니요. 인증 예시는 Hydrogen을 사용하지만, 어떤 프레임워크든 /api/authenticateCustomerHub에서 액세스 토큰과 company_id를 Klaviyo로 POST하는 서버 경로를 구현할 수 있어요.
Q: 즐겨찾기와 FAQ를 PDP와 Hub 내부에 둘 수 있나요?
A: 네. PDP에 해당 컨테이너 div를 추가하면 Hub 서랍에도 표시돼요.