헤드리스로 클라비요 고객 허브를 설정하는 방법 Shopify
Klaviyo 고객 허브를 헤드리스 Shopify 스토어에 연결합니다. 로그인, 표면 위젯(즐겨찾기, FAQ), 활성화/최근 본 제품 환경을 활성화하여 참여 유도 및 전환을 강화하세요.
학습 내용
클라비요 고객 허브를 헤드리스( Shopify ) 스토어에 연결하고 로그인 방법을 선택한 다음 허브를 게시하여 쇼핑객이 사이트 전체에서 액세스할 수 있도록 합니다.
클라비요 고객 허브는 현재 Shopify 헤드리스를 포함한 Shopify 스토어를 지원합니다. 추가 전자상거래 플랫폼 지원은 요금제입니다.
클라비요 고객 허브 기능에 대한 피드백은 이메일(customerhub@klaviyo.com)로 보내주세요.
시작하기 전에 알아야 할 것
전제 조건전제 조건
⚠️ 참고: 계속 진행하기 전에 담당 담당자, CSM 또는 Klaviyo 지원팀에 문의하여 Klaviyo 계정에 대해 헤드리스 Shopify 지원을 사용하도록 설정해야 필요한 구성에 액세스할 수 있습니다. 지원팀에 문의하는 방법
- 스토어프론트 API(Shopify의 헤드리스 관리자에서 공개 액세스 토큰/스토어프론트 API 공개 키)에 액세스할 수 있는 헤드리스 Shopify 스토어프론트입니다.
- Klaviyo 회사 ID (온사이트 자바스크립트 로더에서 사용).
- 쇼핑객 로그인 결정: Shopify 고객 계정 API 또는 Klaviyo 일회용 비밀번호(OTP).
- 기존 계정을 사용하는 경우 스토어의 로그인, 로그아웃, (선택 사항) 계정 관리 및 주소 관리 경로를 준비합니다.
- 스토어 코드를 편집하고 변경 사항을 배포할 수 있습니다.
- 설정할 수 있는 사람: 클라비요 고객 허브 설정을 편집하고 위젯을 게시할 수 있는 계정 역할이 필요합니다(소유자, 관리자 또는 콘텐츠 및 API 키에 대한 쓰기 권한이 있는 사용자 지정 역할).
개요
개요
클라비요 고객 허브는 쇼핑객이 계정 작업과 유용한 쇼핑 도구에 더 빠르게 액세스할 수 있는 사이트 전체 오버레이입니다. 헤드리스 Shopify 의 경우 Klaviyo의 온사이트 스크립트에 연결하고 로그인 방법(고객 계정 API 또는 Klaviyo OTP)을 선택한 후 선택적으로 추가합니다:
- 활성 제품: 쇼핑객이 허브 내에서 보고 있는 제품을 표시합니다.
- 최근 보기: Klaviyo의 트래킹을 사용하여 최근에 본 제품 목록입니다.
- 즐겨찾기 및 자주 묻는 질문 위젯: PDP와 허브 내부에서 렌더링합니다.
제품 검색과 빠른 결제를 유도하고 전환율과 생애 가치를 향상시키는 페이지 내 지원 계층을 원하는 경우 클라비요 고객 허브를 사용하세요.
설치
설치
1 - 클라비요 고객 허브 설정 구성하기1 - 클라비요 고객 허브 설정 구성하기
먼저 클라비요 고객 허브 시작하기를 따라 다른 설정과 마찬가지로 온보딩 마법사를 완료합니다. 이 작업이 완료되면 클라비요 고객 허브 > 설정으로 이동합니다. 헤드리스 Shopify 구성 섹션이 표시됩니다.
Shopify의 헤드리스 관리자(공개 액세스 토큰)에서 스토어프론트 API 공개 키를 붙여넣습니다.
구매자 로그인에서 Shopify 고객 계정 API(모든 스토어 앱에서 Shopify 로그인을 공유할 수 있도록 권장) 또는 Klaviyo 일회용 비밀번호(OTP, Klaviyo에서만 작동하며 다른 앱에 쇼핑객을 로그인하지 않음)를 선택합니다.
Shopify 고객 계정 API 을 선택하는 경우 스토어 로그인, 로그아웃 및 계정관리/주소 관리 경로(허브와 사이트 간 리디렉션에 사용)(선택 사항)도 입력합니다.
게시 가시성: 클라비요 고객 허브를 라이브로 설정합니다.
2 - 클라비요 고객 허브 자바스크립트 로드(개발자 지침)
2 - 클라비요 고객 허브 자바스크립트 로드(개발자 지침)
팁: 이미 Klaviyo 사이트 기능을 실행하고 있다면 로더가 설치되어 있을 수 있습니다. 두 번째 스크립트를 추가하기 전에 확인합니다.
다음 로더를 사용하여 /public/customerHub.js(또는 이와 동등한 파일)를 생성합니다(회사 ID라고도 하는 Klaviyo 공개 API 키로 COMPANY_ID를 대체):
// customerHub.js // TODO: 구성 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 스크립트가 성공적으로 로드되었습니다." 루트 레이아웃(예: root.tsx)에 있습니다, 로더를 포함합니다:
// root.tsx return ( <html> <body> < script src="/customerHub.js" defer></script> </body> </html> )
이 단계가 끝나면 window.customerHubApi 허브가 실행되는 페이지에서 사용할 수 있게 됩니다.
3 - 클라비요 고객 허브에 활성 제품 표시
3 - 클라비요 고객 허브에 활성 제품 표시
제품 세부 정보 페이지(PDP) 에 하이드레이트 호출을 추가하여 현재 제품이 허브에 표시되도록 합니다:
<!-- 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>
이제 허브는구매자가 보고 있는 PDP에 대한 추가 제품 카드를 "채팅" 탭에 표시합니다(활성화한 경우).
4 - 클라비요 고객 허브에서 최근 본 제품 활성화
4 - 클라비요 고객 허브에서 최근 본 제품 활성화
본 제품 추적을 구현하여 허브가 최근에 본 항목을 채울 수 있도록 하고 Klaviyo 의 다른 곳에서 지표를 사용할 수 있도록 합니다. 다음 트래킹 스니펫을 스토어에 직접 추가할 수도 있으며, 자세한 지침은 Klaviyo 개발자 문서에서 확인할 수 있습니다: 사전 구축된 Klaviyo 연동 없이 전자상거래 플랫폼 통합하기.
5 - 계정 링크 인수인계 활성화
5 - 계정 링크 인수인계 활성화
Klaviyo의 클라비요 고객 허브가 스토어 헤더에서 계정 아이콘을 클릭하여 열리려면 /계정 링크를 참조하는 기존 a-태그가 이미 있어야 합니다(이 경우 자동으로 교체해 드립니다). 또는 서랍을 열기 위해 #k-hub를 가리키도록 아이콘 링크를 수동으로 정의할 수도 있습니다.
6 - 고객 계정 API 인증으로 클라비요 고객 허브 설정(권장)
기존 상점의 고객 계정 및 인증 설정을 사용하려면 클라비요 고객 허브에서 로그인 쇼핑객의 액세스 토큰을 당사 서비스에 안전하게 전달할 수 있는 새로운 API 경로를 상점 페이지에 추가해야 합니다. 중요한 것은 새 API 경로의 이름과 도달률이 '/API/authenticateCustomerHub'로 지정된다는 점입니다.
참고: 다음 코드 조각 예시는 Shopify의 수소 프레임워크에 대한 것으로, 사용자 지정 상점이 더 많을 경우 몇 가지 추가 해결 방법이 필요할 수 있지만 일반적인 접근 방식은 여기에 설명되어 있습니다.
// ./app/routes/API.authenticateCustomerHub.js
// 할 일: 구성
const COMPANY_ID = '';
export async 함수 action({context}) {
// 상점의 컨텍스트에서 고객 계정 API Client를 가져옵니다
const {customerAccount} = 컨텍스트;
try {
// 현재 고객의 액세스 토큰 가져오기
const accessToken = await customerAccount.getAccessToken();
if (!accessToken) {
반환 새 응답(JSON.stringify({message: 'User not logged in'}), {
status: 200,
});
}
// 클라비요 고객 허브에 액세스 토큰 보내기 API
const response = await fetch(
'https://atlas-app.services.klaviyo.com/api/onsite/headless-shopify-login',
{
메소드: 'POST',
헤더: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
access_token: accessToken,
company_id: COMPANY_ID,
}),
},
);
const responseData = await response.text();
// 동일한 상태 코드를 가진 클라비요 고객 허브의 실제 응답을 반환합니다
return new Response(responseData, {
status: response.status,
헤더: {
'Content-Type':
response.headers.get('content-type') || 'application/json',
},
});
} catch (error) {
return new Response(null, {status: 500});
}
}
이 설정과 Klaviyo설정에 정의된 상점 경로가 구성되면 클라비요 고객 허브는 기존 인증 설정에 연결하여 기존 고객 계정에 대한 원활한 진입 지점을 제공할 수 있습니다.
7 - 즐겨찾기 위젯 추가(권장)7 - 즐겨찾기 위젯 추가(권장)
즐겨찾기와 FAQ는 모두 클라비요 고객 허브 서랍 내에서 작동합니다. 그러나 추가 참여를 유도하기 위해 PDP에도 이러한 위젯을 추가할 수 있습니다.
PDP와 허브 내부에 즐겨찾기 항목 지점을 추가하려면 다음과 같이 하세요:
// products.tsx // 예제 식별자: // id: gid://Shopify/Product/12345 // data-product-id: 12345 const gid = "gid://Shopify/Product/12345"; const productId = gid.분할('/').pop(); 반환 ( < div className="kl-hub-favorites-slot" data-product-id={productId} /> )
이제 쇼핑객은 PDP에서 즐겨찾기에 추가를 클릭하면 해당 품목이 허브의 즐겨찾기에 표시됩니다.
8 - FAQ 블록 추가(권장)
8 - FAQ 블록 추가(권장)
즐겨찾기를 추가하는 것과 마찬가지로 FAQ 블록을 추가하는 것은 제품 페이지에 제품 ID가 전달된 div를 추가하여 Klaviyo 에서 편집 및 디자인할 수 있는 FAQ를 렌더링하는 것만큼 간단합니다.
Klaviyo 에서 디자인한 제품별 FAQ 블록을 추가합니다:
// products.tsx // 예시: const gid = "gid://Shopify/Product/12345"; const productId = gid.분할('/').pop(); 반환 ( < div className="klaviyo-faqs-slot" data-product-id={productId} /> )
FAQ 칩/버튼이 설정되어 있고 다음에서 편집할 수 있는 경우 이제 PDP에서 렌더링됩니다. Klaviyo
모범 사례
모범 사례
- 검증이 완료된 후에만 프로덕션에 게시 - QA가 완료될 때까지 스테이징을 숨김 상태로 유지한 다음, 라이브가 허브를 노출하도록 설정하세요. 효과: 지원 문제 감소, 가치 실현 시간 단축.
- 항상 PDP에서 활성 제품을 업데이트하여 허브에 제품 컨텍스트를 표시하고 장바구니에 추가를 유도합니다. 영향: 전환율, 재구매율.
- 조회한 제품 트래킹 조기 구현 - 최근에 본 제품을 표시하고 찾아보기 기반 플로우를 잠금 해제합니다. 영향: 참여 유도 및 브라우징 회복을 통한 수익 창출
- 즐겨찾기 추가 - 마찰이 적은 저장 작업과 지속적인 후보 목록을 생성합니다. 영향: 반복 방문, 장바구니에 추가.
- 이의제기 FAQ를 사용하여 배송, 자재 또는 반품 관련 질문에 인라인으로 답변하여 반품 취소를 줄이세요. 영향: 전환율
- 가능한 경우 고객 계정 API를 사용한 서버 측 인증 선호 - 로그인한 쇼핑객의 연속성을 향상시킵니다. 영향: 경험 품질, 지원 편향.
성공 측정
성공 측정
결과를 볼 수 있는 위치: 애널리틱스 > 지표를 사용하여 조회된 제품 활동 및 다운스트림 플로우/캠페인 성과를 모니터링합니다. 전자상거래 수익 대시보드를 사용하여 클라비요 고객 허브 활성화 후 전환 및 평균 주문 금액 변화를 추적하세요. 주목해야 할 주요 지표: PDP에서의 전환율, 장바구니에 추가하기 비율, 허브가 열린 세션(계측된 경우), 수신자당 수익(재구매율), 조회된 제품 이벤트에 연동된 검색 기반 수익입니다. 빠른 수정 체크리스트: 최근에 본 활동이 적나요? 조회된 제품 트래킹 스니펫이 실행되고 이벤트가 프로필에 어트리뷰션되는지 확인합니다. Hub의 장바구니에 추가가 적나요? 모든 PDP에서 활성 제품 수화 기능이 실행되고 동일한 이메일의 다른 버전/가격이 올바른지 확인하세요. 즐겨찾기가 거의 추가되지 않았나요? 즐겨 찾기 슬롯을 핵심 PDP CTA 근처로 이동하고 데이터-제품 ID가 제품과 일치하는지 확인합니다.
문제 해결
문제 해결
증상: 클라비요 고객 허브가 사이트에 나타나지 않습니다.
가능한 원인: 스크립트가 로드되지 않거나 허브가 숨겨져 있습니다.
수정: 고객 허브가 로드되고(콘솔 확인), 회사 ID가 설정되어 있으며, 클라비요 고객 허브 가시성이 클라비요 고객 허브 > 설정에서 라이브인지 확인합니다.
증상: 콘솔에 " Klaviyo JS 스크립트를 로드하지 못했습니다."라는 메시지가 표시됩니다.
가능한 원인입니다: 스크립트 URL이 잘못되었거나 회사 ID가 누락되었습니다.
수정: https://static.Klaviyo.com/onsite/js/<COMPANY_ID>/Klaviyo.js 및 COMPANY_ID가 채워져 있는지 확인합니다.
증상: PDP의 허브에 활성 제품 카드가 표시되지 않습니다.
가능한 원인: 하이드레이트제품이 호출되지 않았거나 잘못된 제품 핸들입니다.
수정: 대기 루프가 실행되는지 확인하고 window.customerHubApi.hydrateProduct("<handle>" )를 호출합니다. 올바른 제품 핸들을 사용하세요.
증상: 최근에 본 섹션이 비어 있습니다.
가능한 원인: 조회된 제품 추적이 구현되지 않았습니다.
수정: 개발자 가이드에서 조회된 제품 트래킹 스니펫을 추가하고 Klaviyo 에서 이벤트를 확인합니다.
증상: 즐겨찾기 또는 FAQ 위젯이 PDP에서 렌더링되지 않습니다.
가능한 원인: 컨테이너가 누락되었거나 속성이 잘못되었습니다.
수정: <div class="kl-hub-favorites-slot" data-product-id="..."> 및/또는 <div class="klaviyo-faqs-slot" data-product-id="..."> 에 올바른 제품 ID를 추가합니다.
증상: 계정 아이콘을 클릭해도 허브가 열리지 않습니다.
가능한 원인입니다: 헤더 링크가 /계정 또는 #k-hub를 가리키지 않습니다.
수정: 계정 앵커가 /계정(자동 인수인계)을 사용하거나 href="#k-hub" 을 설정했는지 확인합니다.
증상: 쇼핑객이 허브 내에서 로그인한 것으로 인식되지 않습니다.
가능한 원인: API/authenticateCustomerHub 경로가 누락되었거나 API 요청에 실패했습니다.
수정: Hydrogen 예제(또는 이에 상응하는 프레임워크)를 구현하고 Klaviyo의 로그인 엔드포인트로 access_token 및 company_id를 전송한 후 응답을 반환합니다.
자주 묻는 질문
자주 묻는 질문
질문: 로그인 시 Shopify 고객 계정 API를 사용해야 하나요?
A: 아니요. 대신 Klaviyo 일회용 비밀번호(OTP)를 사용할 수 있습니다. 이미 Shopify 계정을 사용 중이라면 고객 계정 API 을 통해 연결하여 원활한 환경을 만드세요.
질문: 어떤 스토어 경로를 제공해야 하나요?
A: 기존 계정을 사용하는 경우 로그인 및 로그아웃 경로를 제공하고, 계정 관리 및 주소 관리는 더 깊은 연동을 위해 선택 사항입니다.
질문: 스토어프론트 API 공개 키는 어디에서 찾을 수 있나요?
A: Shopify의 헤드리스 관리자 아래 스토어프론트 API > 공개 액세스 토큰 ( 스토어프론트 API 공개 키라고도 함)에서 확인할 수 있습니다.
질문: 클라비요 고객 허브가 내 계정 아이콘을 대신할 수 있나요?
A: 예. 헤더의 계정 링크가 /계정을 사용하는 경우 클라비요 고객 허브가 자동으로 열리거나 #k-hub를 가리킬 수도 있습니다.
Q: Shopify Hydrogen은 필수인가요?
A: 아니요. 인증 예시에서는 Hydrogen을 사용하지만, 모든 프레임워크는 /API/authenticateCustomerHub에서 액세스 토큰과 company_id를 Klaviyo 에 게시하는 서버 경로를 구현할 수 있습니다.
질문: 즐겨찾기와 FAQ를 PDP와 허브 내부에 표시할 수 있나요?
A: 예. PDP에 각 컨테이너 div를 추가하면 허브 서랍에도 표시됩니다.