헤드리스로 클라비요 고객 허브를 설정하는 방법 Shopify

예상 7분 읽기

업데이트 2026년 3월 13일 PM 10:00 EST

Klaviyo 고객 허브를 헤드리스 Shopify 스토어에 연결합니다. 로그인, 표면 위젯(즐겨찾기, FAQ), 활성화/최근 본 제품 환경을 활성화하여 참여 유도 및 전환을 강화하세요.

클라비요 고객 허브를 헤드리스( Shopify ) 스토어에 연결하고 로그인 방법을 선택한 다음 허브를 게시하여 쇼핑객이 사이트 전체에서 액세스할 수 있도록 합니다.

현재 Shopify용 클라비요 고객 허브는 표준 스토어 및 Shopify 헤드리스를 지원합니다. WooCommerce의 경우 https://help.klaviyo.com/hc/ko-kr/articles/47792369863451 으로 이동합니다.

클라비요 고객 허브 기능에 대한 피드백은 이메일(customerhub@klaviyo.com)로 보내주세요.

시작하기 전에 알아야 할 것

전제 조건

스토어프론트 API(Shopify의 헤드리스 관리자에서 공개 액세스 토큰/스토어프론트 API 공개 키)에 액세스할 수 있는 헤드리스 Shopify 스토어프론트입니다.
Klaviyo 회사 ID (온사이트 자바스크립트 로더에서 사용).
쇼핑객 로그인 결정: Shopify 고객 계정 API 또는 Klaviyo 일회용 비밀번호(OTP).
1. 기존 계정을 사용하는 경우 스토어의 로그인, 로그아웃, (선택 사항) 계정 관리 및 주소 관리 경로를 준비합니다.
스토어 코드를 편집하고 변경 사항을 배포할 수 있습니다.
설정할 수 있는 사람: 클라비요 고객 허브 설정을 편집하고 위젯을 게시할 수 있는 계정 역할이 필요합니다(소유자, 관리자 또는 콘텐츠 및 API 키에 대한 쓰기 권한이 있는 사용자 지정 역할).

개요

클라비요 고객 허브는 쇼핑객이 계정 작업과 유용한 쇼핑 도구에 더 빠르게 액세스할 수 있는 사이트 전체 오버레이입니다. 헤드리스 Shopify 의 경우 Klaviyo의 온사이트 스크립트에 연결하고 로그인 방법(고객 계정 API 또는 Klaviyo OTP)을 선택한 후 선택적으로 추가합니다:

활성 제품: 쇼핑객이 허브 내에서 보고 있는 제품을 표시합니다.
최근 보기: Klaviyo의 트래킹을 사용하여 최근에 본 제품 목록입니다.
즐겨찾기 및 자주 묻는 질문 위젯: PDP와 허브 내부에서 렌더링합니다.

제품 검색과 빠른 결제를 유도하고 전환율과 생애 가치를 향상시키는 페이지 내 지원 계층을 원하는 경우 클라비요 고객 허브를 사용하세요.

설치

1 - 클라비요 고객 허브 설정 구성하기

먼저 클라비요 고객 허브 시작하기를 따라 다른 설정과 마찬가지로 온보딩 마법사를 완료합니다. 이 작업이 완료되면 클라비요 고객 허브 > 설정으로 이동합니다. 헤드리스 Shopify 구성 섹션이 표시됩니다.

헤드리스 Shopify 구성을 토글한 다음 Shopify의 헤드리스 관리자(공개 액세스 토큰)에서 스토어프론트 API 공개 키를 붙여넣습니다.

구매자 로그인에서 Shopify 고객 계정 API(모든 스토어 앱에서 Shopify 로그인을 공유할 수 있도록 권장) 또는 Klaviyo 일회용 비밀번호(OTP, Klaviyo에서만 작동하며 다른 앱에 쇼핑객을 로그인하지 않음)를 선택합니다.

Shopify 고객 계정 API 을 선택하는 경우 스토어 로그인, 로그아웃 및 계정관리/주소 관리 경로(허브와 사이트 간 리디렉션에 사용)(선택 사항)도 입력합니다.

게시 가시성: 클라비요 고객 허브를 라이브로 설정합니다.

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 - 클라비요 고객 허브에 활성 제품 표시

제품 세부 정보 페이지(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 - 클라비요 고객 허브에서 최근 본 제품 활성화

본 제품 추적을 구현하여 허브가 최근에 본 항목을 채울 수 있도록 하고 Klaviyo 의 다른 곳에서 지표를 사용할 수 있도록 합니다. 다음 트래킹 스니펫을 스토어에 직접 추가할 수도 있으며, 자세한 지침은 Klaviyo 개발자 문서에서 확인할 수 있습니다: 사전 구축된 Klaviyo 연동 없이 전자상거래 플랫폼 통합하기.

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 - 즐겨찾기 위젯 추가(권장)

즐겨찾기와 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 블록 추가(권장)

즐겨찾기를 추가하는 것과 마찬가지로 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를 추가하면 허브 서랍에도 표시됩니다.

이 도움말 문서가 유용했나요?

이 형식은 도움말 문서 피드백 용도로만 사용하세요. 지원 팀에 문의하는 방법.

Klaviyo에서 자세히 살펴보기

커뮤니티

동료, 파트너, Klaviyo 전문가와 연결되어 영감을 받고 인사이트를 공유하며, 모든 궁금한 사항에 대해 답을 얻으세요.

커뮤니티 방문

파트너

특정 작업을 도와주거나 지속적인 마케팅 관리를 위해 Klaviyo 인증 전문가를 고용하세요.

파트너 고용하기

지원

계정을 통해 지원에 액세스하세요.

이메일 지원 (무료 체험 및 유료 계정) 연중무휴 24시간 사용 가능

채팅/가상 비서
사용 가능 여부는 위치 및 요금제 유형에 따라 다름

로그인