Skip to main content
Cart SDK는 스토어프런트의 Aftersell Cart를 위한 JavaScript API예요. 카트의 동작 방식을 변경하고, 쇼핑객의 행동에 반응하고, 코드에서 카트의 내용을 읽거나 변경할 수 있어요. SDK 코드는 커스텀 스크립트를 통해 실행하거나, 자체 UI를 렌더링하는 블록의 경우 커스텀 코드 블록의 React 모드를 통해 실행해요.
머천트가 SDK에 요청하는 것들 중 상당수는 이미 설정으로 제공되고 있어요. 스크립트를 작성하기 전에 카트 블록, 마켓/국가/통화별 조건, 또는 카트 설정으로 이미 가능한지 확인해 보세요. 이런 기능들은 카트 리디자인 후에도 계속 작동하지만, 스크립트는 그렇지 않을 수 있어요.

전역 진입점

모든 것은 하나의 전역 객체에서 시작돼요:
이 문서의 모든 스니펫은 window.aftersell.cart를 전체로 작성하기 때문에, 어떤 스니펫이든 붙여넣기만 하면 그 자체로 작동해요. 한 번 별칭을 지정한 뒤(const cart = window.aftersell.cart;) 그 이후로 cart를 사용하는 것도 완전히 유효하며, 카트가 로드되기 전에도 안전해요. 다만 스니펫을 줄여 쓸 때는 그 줄을 꼭 포함하세요. cart만 단독으로 쓰면 cart is not defined 오류가 발생해요.
네 가지 구성 요소가 실제 작업을 담당해요:

Configure

카트의 동작 방식을 설정해요: 드로어가 열리는 시점, 금액 표시 형식, Aftersell이 장바구니 담기를 가로챌지 여부.

Events

일어나는 일에 반응해요: 카트가 로드됨, 상품이 추가됨, 드로어가 열림, 체크아웃이 클릭됨.

Actions

카트를 읽고 변경해요: 카트 열기, 상품 추가, 수량 업데이트, 현재 상태 읽기.

Hooks

카트 자체의 작동 방식을 변경해요: 라인 숨기기 또는 레이블 변경, 순서 재정렬, 추가 데이터 첨부, 장바구니 담기 제어.
스크립트가 장바구니 담기에서 더 이상 실행되지 않는다면 장바구니 담기 가로채기부터 시작하세요. Aftersell이 왜 추가를 대신 처리하는지, 그리고 폼을 제외하는 모든 방법을 설명해요.
그리고 세 가지 작은 멤버가 있어요:

이벤트, 액션, 아니면 훅?

이 세 가지는 혼동하기 쉬운데, 잘못 선택하는 것이 스크립트가 작성자의 의도대로 작동하지 않는 가장 흔한 이유예요: 가장 중요한 차이점: 액션은 쇼핑객의 실제 카트(그리고 총액)를 변경하는 반면, 훅은 렌더링되는 내용만 변경해요. 훅으로 라인을 숨기면 카트와 총액에는 그대로 남아 있고, 액션으로 제거하면 실제로 사라져요.

로드 방식과 시점

카트는 두 단계로 로드되며, SDK는 순서를 신경 쓸 필요가 없도록 설계되어 있어요:
  1. 작은 스텁window.aftersell.cart를 즉시 생성하므로 항상 존재해요.
  2. 전체 SDK가 곧이어 로드되어 스텁을 그 자리에서 업그레이드하므로, 이전에 캡처한 참조도 계속 작동해요.
이에 따라 호출은 두 가지 범주로 나뉘어요:

설정 호출: 즉시 안전

configure(...), events.on(...), 그리고 모든 hooks.register* 호출. 부팅 전에는 버퍼링되었다가 SDK가 로드되면 순서대로 재생돼요. 스크립트 맨 위에 두세요.

액션: ready()를 기다리세요

actions.* 아래의 모든 것. ready() 안이나 이벤트 핸들러 안에서 실행하세요. 너무 일찍 호출하면 콘솔에 경고를 남기고 아무 일도 하지 않아 안전해요: 비동기 액션은 여전히 resolve되므로 .then() 체인이 깨지지 않아요.

ready()

ready()는 첫 번째 카트 로드가 **완료(settle)**되면 resolve되는 Promise를 반환해요. 성공뿐 아니라 실패 시에도 resolve되므로, 불안정한 연결 상태의 쇼핑객이 있어도 스크립트가 멈춰 있는 일이 없어요. 카트가 도착했다고 가정하지 말고 getCart()null인지 확인하세요. 카트가 이미 로드된 후에 ready()를 호출하면 즉시 resolve되므로, 코드 어디에서든 일반적인 “이제 카트가 존재한다”라는 게이트로 안전하게 사용할 수 있어요.
이벤트 핸들러 안에서는 ready()가 필요 없어요. cart_loaded, cart_updated, item_added가 발생하는 시점에는 카트가 이미 로드되어 있어 액션을 안전하게 호출할 수 있어요.

context

window.aftersell.cart.context는 서버에서 렌더링된 구매자 데이터를 담고 있으며, ready() 없이 동기적으로 읽을 수 있어요. 카트가 로드되기 전에 실행되어야 하는 마켓 또는 국가 분기 처리에 사용하세요.
storefront_access_token은 서버가 cart.context에 렌더링하지 않는 유일한 context 필드예요. 카트가 부팅될 때 context에 추가되므로, 스크립트 맨 위에서 읽으면 undefined가 반환돼요. 먼저 window.aftersell.cart.ready()를 await하세요.
마켓, 국가 또는 통화별로 다른 블록 설정을 표시하려면 스크립트 대신 카트 에디터의 조건을 사용하세요. 스크립트가 필요 없어요. 전체 조건 UI는 현재 Rewards에서 제공돼요.

shadowRoot

카트는 shadow root 안에서 렌더링되므로 document.querySelector드로어 내부의 어떤 것도 볼 수 없어요. 카트 안의 요소에 접근하려면 shadow root를 쿼리하세요:
커스텀 CSS에서 사용하는 것과 동일한 공개 cart-external-* 클래스를 대상으로 하세요. 이것들이 지원되는 핸들이에요. cart-internal-* 쌍둥이 클래스는 카트 자체의 내부 구조이므로, 대신 external 클래스를 쿼리하세요.
블록, 설정, 훅으로 해결되지 않을 때만 shadow root를 사용하세요. 훅은 카트 리디자인 후에도 살아남지만, DOM 쿼리는 여러분의 코드가 직접 유지 관리해야 하는 문제가 돼요.
shadow root는 카트가 부팅된 후에만 존재하므로, 스크립트 맨 위가 아닌 ready() 안이나 이벤트 핸들러 안에서 읽으세요.

디버깅

깨진 스크립트가 장바구니 담기나 드로어를 망가뜨려서는 절대 안 되기 때문에, SDK는 실패를 전파하지 않고 내부에 가둬요. 실패가 어디에 표시되는지는 무엇이 깨졌는지에 따라 달라요:

스크립트가 throw할 때

커스텀 스크립트는 첫 번째 오류에서 멈추기 때문에, 그 줄 아래의 모든 configure, events.on, hooks.register*는 실행되지 않아요. 카트는 이를 명시적으로 알려줘요:
분명히 등록한 핸들러가 전혀 실행되지 않을 때 찾아봐야 할 메시지가 바로 이거예요: 아마 그 줄까지 도달하지 못한 거예요. 줄 번호는 실행이 멈춘 최상위 문장의 위치이며, throw한 내부 함수가 아니에요. 브라우저의 스택을 사용할 수 없으면 추측하지 않고 생략돼요. 스크립트는 자체 파일명으로 실행되므로, DevTools에서 aftersell-cart-init.jsaftersell-cart-cart-update.js로 표시돼요. Sources 패널에서 열어 다른 파일처럼 중단점을 설정할 수 있어요.

디버그 채널

훅 실패는 쇼핑객이 절대 볼 수 없도록 의도적으로 콘솔에 표시되지 않아요. 대신 여기로 가요:

다음 단계

Configure

모든 옵션과 각각의 예시.

Events

모든 이벤트, 발생 시점, 그리고 핸들러에서 하지 말아야 할 것.

Actions

모든 액션과 각각의 스니펫.

Hooks

모든 훅과 등록이 조합되는 방식.

Cart 객체

카트와 라인의 구조.

사용 사례

자주 요청되는 사항에 대한 완전하고 실행 가능한 솔루션.