고객 허브 자바스크립트 API 참조

학습 내용

window.customerHubApi JavaScript API를 사용해 자체 스토어프런트 코드에서 Klaviyo 고객 허브 또는 독립형 Klaviyo 웹 채팅을 제어하는 방법을 알아보세요. 경험을 열고 닫고, 특정 화면으로 이동하고, 쇼핑객을 대신해 채팅 메시지를 전송하고, 장바구니 담기 같은 이벤트를 수신할 수 있어요.

시작하기 전에 알아야 할 것

필요한 사항은 다음과 같습니다.

• 스토어프런트에 Klaviyo 고객 허브가 설정되고 로드되어 있어야 해요. 헤드리스 또는 커스텀 스토어프런트를 사용 중이라면 먼저 Headless Shopify로 Klaviyo 고객 허브를 설정하는 방법을 따라 해주세요. 여기에는 이 API를 사용할 수 있게 해주는 온사이트 로더를 추가하는 방법이 포함돼 있어요.
• 스토어프론트 코드를 편집하고 배포할 수 있는 기능입니다.

고객 허브 API는 무엇인가요?

스토어프런트에서 Klaviyo 고객 허브 또는 독립형 Klaviyo 웹 채팅이 로드될 때마다, Klaviyo는 전역 window 객체에 window.customerHubApi(으)로 작은 JavaScript API를 연결해요. 이를 사용하면 자체 코드에서 경험을 열고, 닫고, 상호작용할 수 있어요. 예를 들어 커스텀 버튼, 배너 또는 제품 페이지에서 사용할 수 있어요.

if (window.customerHubApi) {
  window.customerHubApi.open();
}

방법

open(route?)

고객 허브 서랍을 엽니다.

• route (string, optional) — 열 때 이동할 경로예요. 생략하면 허브는 마지막으로 표시했던 화면에서 열려요.

// Open the Hub on its default screen
window.customerHubApi.open();

// Open the Hub directly to a specific screen
window.customerHubApi.open('/orders');

사용 가능한 경로

close()

Klaviyo 고객 허브 서랍을 닫아요. 허브는 현재 화면에 그대로 유지되므로, open() (경로 없음)으로 다시 열면 고객이 중단했던 지점으로 돌아가요.

window.customerHubApi.close();

sendChatMessage(message)

채팅 화면 에서 고객 허브를 열고 고객을 대신하여 메시지를 제출합니다. "이 제품에 대해 채팅" 또는 "도움 받기" 버튼에 유용합니다.

• message (string) ― 전송할 메시지예요.

window.customerHubApi.sendChatMessage('I have a question about my order.');

로그인이 필요한 경우: 스토어에서 고객이 채팅 전에 로그인해야 하는 경우(그리고 AI 에이전트가 활성화되지 않은 경우), 고객이 채팅 화면으로 이동하여 먼저 로그인합니다. 메시지는 일시적으로 저장되며 로그인이 완료되면 자동으로 전송됩니다. 로그인이 완료되지 않으면 저장된 메시지는 약 10분 후에 만료됩니다.

getActiveConversationId()

서랍에서 진행 중인 활성 대화의 conversationId을(를) 반환해요. 진행 중인 대화가 없으면 null을(를) 반환해요.

window.customerHubApi.getActiveConversationId();

이벤트를 청취하세요.

window.customerHubApi.events Klaviyo 고객 허브 내에서 발생하는 이벤트를 구독할 수 있어요.

addtocart

고객이 허브 내에서 장바구니에 제품을 추가할 때 발생합니다. 스토어프론트 장바구니를 동기화하는 데 사용하세요.

window.customerHubApi.events.addEventListener('addtocart', (event) => {
  // event.detail.items is an array of { variantId, quantity }
  event.detail.items.forEach((item) => {
    console.log('Added to cart:', item.variantId, 'x', item.quantity);
  });
});

전체 예시

허브를 열고 메시지를 제출하는 '이 제품에 대해 채팅' 버튼과 쇼핑객이 허브에서 품목을 추가할 때 스토어프론트 장바구니를 동기화하는 청취자:

<button id="ask-about-product">Ask us about this product</button>

<script>
  document
    .getElementById('ask-about-product')
    .addEventListener('click', () => {
      if (window.customerHubApi) {
        window.customerHubApi.sendChatMessage(
          'I have a question about this product.'
        );
      }
    });

  // Sync the storefront cart when a customer adds an item from the Hub
  if (window.customerHubApi) {
    window.customerHubApi.events.addEventListener('addtocart', (event) => {
      refreshStorefrontCart(event.detail.items);
    });
  }
</script>

추가 자료