훅 - Aftersell & Upcart Docs

이벤트가 장바구니에 반응하게 하고 액션이 장바구니를 변경하게 한다면, 훅은 장바구니 자체의 동작 방식을 바꿔요: 라인이 어떻게 렌더링되는지, 어떤 데이터를 갖는지, 장바구니 담기 시 무슨 일이 일어나는지 말이에요. 훅은 window.aftersell.cart.hooks 아래에 있어요.

훅은 쇼핑객이 보는 것을 변경하고, 액션은 장바구니에 담긴 것을 변경해요. 변환으로 무료 선물 라인을 숨기면 장바구니와 합계에는 그대로 남아요. removeItem으로 제거하면 실제로 빠져요.

훅은 설정용 호출이므로 스크립트 맨 위에서 등록해도 안전하며, ready()를 기다릴 필요가 없어요. 장바구니의 Initialization 스크립트에서 등록하세요(커스텀 스크립트 참고).

등록 작동 방식

모든 훅은 register* 메서드예요. 함수를 전달해 호출하면 여러분의 함수를 제거할 수 있는 등록 해제 함수를 반환해요.

const off = window.aftersell.cart.hooks.registerSkipAddToCartRule((form) =>
  form.hasAttribute('data-skip-aftersell')
);

// later: off();

등록은 누적 방식이므로 여러분의 함수는 다른 모든 함수와 함께 실행돼요. 페이지에 있는 스크립트가 여러분의 것만이 아닌 경우가 많기 때문에 중요해요: 구독 앱, 번들 앱, 테마 자체가 모두 같은 훅에 등록할 수 있어요. 어느 것도 여러분의 것을 대체할 수 없고, 여러분이 등록한 것이 이후에 로드되는 무언가에 의해 조용히 삭제될 수도 없어요.

훅	하는 일	여러 개가 등록된 경우
`registerLineTransform`	개별 라인을 숨기거나 레이블을 변경해요.	등록 순서대로 모두 실행돼요.
`registerLineComparator`	렌더링되는 라인 순서를 변경해요.	타이브레이커로 조합돼요.
`registerCartEnricher`	각 라인에 추가 Storefront 데이터를 첨부해요.	모두 실행되며, 각 `id`는 자체 네임스페이스예요.
`registerSubscriptionOptionsTransform`	라인의 판매 플랜을 숨기거나 이름을 변경해요.	모두 실행되며, 패치는 플랜별, 필드별로 병합돼요.
`registerDefaultSubscriptionOptionSelector`	미리 선택될 플랜을 결정해요.	`null`이 아닌 첫 번째 답이 이겨요.
`registerSkipAddToCartRule`	특정 폼이 장바구니를 우회하도록 허용해요. 장바구니 담기 가로채기를 참고하세요.	`true`를 반환하는 규칙이 하나라도 있으면 건너뛰어요.

예외를 던지거나 함수가 아닌 훅은 건너뛰고, 나머지는 계속 실행되며 장바구니는 계속 작동해요. 하나의 깨진 통합이 장바구니 담기, 구독 선택기, 정렬을 망가뜨릴 수 없어요. 반대로 여러분의 깨진 훅은 조용히 실패해요: 브라우저 콘솔에 아무것도 표시되지 않아요. 이러한 실패가 어디에서 드러나는지는 디버깅을 참고하세요.

registerLineTransform

registerLineTransform(fn)은 모든 장바구니 라인이 렌더링되기 전에 실행돼요. 쇼핑객의 장바구니에 실제로 담긴 것은 건드리지 않고 라인을 숨기거나 표시 방식을 변경하는 데 사용하세요. 함수는 읽기 전용 라인과 setter들을 받아요. 등록 해제 함수를 반환해요.

Setter	효과
`setHidden(bool)`	드로어에서 라인을 숨겨요. 장바구니와 합계에는 그대로 남아요.
`setTitle(string)`	표시되는 제목을 변경해요.
`setVariantTitle(string \| null)`	표시되는 변형 레이블을 변경해요.
`setInternalProperties(obj)`	렌더링 전용 속성을 병합해요. Shopify에 절대 저장되지 않아요. 번들 라인 그룹화에 사용돼요.

// Hide free gift lines from the drawer. The cart total is unaffected.
const off = window.aftersell.cart.hooks.registerLineTransform((line) => {
  if (line.finalLinePrice === 0) {
    line.setHidden(true);
  }
  if (line.sellingPlan) {
    line.setVariantTitle(`Delivered ${line.sellingPlan.name.toLowerCase()}`);
  }
});

// later: off();

변환은 렌더링되는 내용만 변경해요. 가격, 수량, 라인 정체성은 변경할 수 없어요. 그런 경우에는 액션을 사용하세요.

용도: 구매 사은품 라인이나 앱이 삽입한 라인 숨기기, 구독 라인의 레이블 변경, 할인 상품 태그하기, 쇼핑객이 개별적으로 관리하면 안 되는 번들 구성 요소 숨기기예요. setInternalProperties는 번들 그룹화의 핵심 setter예요: 각 라인에 표준 번들 속성을 찍는 것이 서드파티 앱의 개별 장바구니 라인을 하나의 상품으로 렌더링하는 방법이에요. 다른 앱의 번들 라인 그룹화하기를 참고하세요.

registerLineComparator

Array.prototype.sort가 기대하는 것과 같은 형태의 비교자예요. 숨기기와 이름 변경 이후에 실행되므로 변환된 라인을 보게 돼요.

// Subscriptions first, then everything else.
window.aftersell.cart.hooks.registerLineComparator((lineA, lineB) => {
  return (lineB.sellingPlan ? 1 : 0) - (lineA.sellingPlan ? 1 : 0);
});

비교자는 타이브레이커로 조합돼요: 0이 아닌 값을 처음 반환하는 비교자가 그 쌍을 결정하고, 나머지는 동점일 때만 참조돼요. 의견이 없는 쌍에는 0을 반환하세요. 그래야 순서를 강제하는 대신 다음 비교자에게 결정을 넘겨요. 용도: 구독이나 고가 상품을 맨 위로 올리기, 무료 선물과 애드온을 맨 아래로 내리기, 스폰서 상품을 첫 번째로 유지하기예요.

registerCartEnricher

registerCartEnricher(registration)은 Shopify Storefront API에서 추가 상품 또는 변형 데이터를 가져와 일치하는 각 장바구니 라인의 line.metadata[id]에 첨부해요. Aftersell의 코드 변경 없이 메타필드, 태그 등 Storefront API가 노출하는 모든 것을 표시하는 데 사용하세요.

필드	타입	설명
`id`	`string`	결과의 네임스페이스로, `line.metadata[id]`에 저장돼요. 고유해야 하며, 같은 `id`로 두 번째 등록하면 무시돼요.
`onType`	`'Product'` 또는 `'ProductVariant'`	프래그먼트가 대상으로 하는 노드예요. 조인 키(상품 ID 대 변형 ID)이기도 해요.
`fragment`	`string`	Storefront 쿼리에 삽입되는 GraphQL 필드 선택(바깥 중괄호 없음). 중괄호 짝이 맞아야 해요.

등록 해제 함수를 반환해요. 장바구니가 로드되거나 변경될 때마다 Aftersell은 장바구니의 모든 상품 또는 변형에 대해 프래그먼트를 가져와 결과를 첨부해요. 가져오기는 논블로킹이에요: 장바구니가 즉시 렌더링되고, 데이터가 도착하면 cart_updated가 다시 발생해요. 느리거나 실패하는 프래그먼트가 장바구니를 지연시키거나 망가뜨리는 일은 없어요.

window.aftersell.cart.hooks.registerCartEnricher({
  id: 'pricing',
  onType: 'ProductVariant',
  fragment: `
    anchorPrice: metafield(namespace: "custom", key: "anchor_price") { value }
    subscriberPrice: metafield(namespace: "custom", key: "subscriber_price") { value }
  `,
});

// Read it once the data arrives.
window.aftersell.cart.events.on('cart_updated', (state) => {
  state.items.forEach((line) => {
    const anchor = line.metadata.pricing?.anchorPrice;
    if (anchor) console.log(line.title, 'anchor price', anchor.value);
  });
});

인리치먼트는 비동기이므로 항상 읽기를 가드하세요. 첫 번째 가져오기가 resolve될 때까지 line.metadata.pricing은 undefined이고, metadata 자체의 기본값은 {}예요. 용도: 모든 라인에 메타필드(배송 예정일, 성분 목록, “별도 배송” 플래그, 로열티 배수)를 가져와 커스텀 코드 블록으로 렌더링하는 데 사용하세요. 장바구니 라인에 메타필드 데이터 표시하기를 참고하세요.

각 id가 자체 네임스페이스이므로 여러 인리처가 문제없이 공존하며, 데이터가 절대 충돌하지 않아요.

강화된 값은 Storefront API에서 그대로 반환되며 살균 처리되지 않아요. 원시 HTML이 아니라 텍스트로 렌더링하세요.

registerSubscriptionOptionsTransform

라인에서 제공되는 판매 플랜을 숨기거나 이름을 변경해요. 함수는 읽기 전용 옵션과 setter들을 받으며, 아무것도 반환하지 않아요.

Setter	효과
`setHidden(bool)`	선택기에서 플랜을 숨겨요.
`setName(string)`	표시되는 플랜 이름을 변경해요.

window.aftersell.cart.hooks.registerSubscriptionOptionsTransform((options, context) => {
  // context: { productId, variantId }
  options.forEach((option) => {
    if (option.discountPercent === 0) option.setHidden(true);
    option.setName(option.name.replace('Every ', ''));
  });
});

반환 목록이 아니라 setter인 이유는 여러 스크립트가 공존할 수 있게 하기 위해서예요. 이 훅이 배열을 반환한다면, 플랜 하나에만 관심 있는 변환도 자연스럽게 options.filter(...)를 작성해 다른 모든 앱의 플랜을 조용히 삭제하게 될 거예요. setter를 사용하면 자신의 편집만 기술할 수 있어요: 패치는 플랜별, 필드별로 병합되고, 같은 플랜의 같은 필드에 대한 실제 충돌은 마지막에 쓴 쪽이 이겨요. 예외를 던지는 변환은 아무것도 기여하지 않으며, 다른 변환은 계속 적용돼요. 모든 변환은 반쯤 패치된 뷰가 아니라 원본 옵션을 보므로, 등록 순서가 읽는 내용에 영향을 주지 않아요.

플랜 순서는 Shopify가 반환한 그대로 유지되므로 변환으로 순서를 변경할 수 없어요. 어떤 플랜이 먼저 제공될지(그리고 일회성 구매 업그레이드 버튼이 어떤 플랜을 구독할지) 제어하려면, 선택한 플랜을 맨 앞으로 올리는 registerDefaultSubscriptionOptionSelector를 사용하세요.

플랜을 추가하거나 가격을 변경할 수도 없어요: discountPercent에는 setter가 없어요. Shopify가 결제 시 인정하지 않을 플랜은 선택기 안의 깨진 약속에 불과하기 때문이에요.

registerDefaultSubscriptionOptionSelector

라인에서 미리 선택될 플랜을 결정해요. 플랜 id를 반환하거나, 넘어가려면 null을 반환하세요.

window.aftersell.cart.hooks.registerDefaultSubscriptionOptionSelector((options) => {
  const best = options
    .slice()
    .sort((optionA, optionB) => optionB.discountPercent - optionA.discountPercent)[0];
  return best ? best.id : null;
});

사용 가능한 플랜의 id를 처음 반환하는 selector가 이기므로, 추측하는 대신 관심 없는 라인에는 null을 반환하세요. 그래야 재정의하는 대신 다음 selector에게 결정을 넘겨요. 라인의 어떤 플랜과도 일치하지 않는 id는 null과 동일하게 처리되어 마찬가지로 넘어가므로, 오래된 id가 선택기를 비워 버릴 수 없어요. 함수는 (options, context)를 받으며, 옵션 변환과 같은 context예요.

registerSkipAddToCartRule

true를 반환하면 특정 상품 폼이 Aftersell을 완전히 우회하고 정상적으로 장바구니에 추가하도록 허용해요. 자체 리디렉션이나 처리가 필요한 폼에 유용해요.

window.aftersell.cart.hooks.registerSkipAddToCartRule((form) =>
  form.hasAttribute('data-skip-aftersell')
);

true가 하나라도 있으면 건너뛰므로, 규칙을 좁게 유지해 소유한 특정 폼만 매칭하고 나머지에는 false를 반환하세요. 규칙은 등록 순서로 평가되고 첫 번째 true에서 멈추므로 규칙에 부작용을 넣지 마세요: 여러분의 규칙이 실행되는지 여부는 이전에 등록된 것에 달려 있어요.

폼의 마크업을 제어할 수 있다면 훅이 전혀 필요 없어요: <form>에 aftersell-cart-skip-atc 클래스를 추가하면 Aftersell이 건드리지 않아요. 마크업을 편집할 수 없거나, 결정이 코드만 아는 무언가에 달려 있을 때 이 훅을 사용하세요.

용도: 자체 리디렉션이 필요한 예약 주문 또는 견적 폼, 구독 앱의 커스텀 플로우, 결제로 바로 이동해야 하는 “바로 구매” 버튼이에요. 페이지 전체의 가로채기를 끄려면 대신 skip_add_to_cart_interceptor를 사용하세요. 하지만 지정한 폼에만 적용되는 이 훅이 더 권장돼요.

다음 단계

Cart 객체: 변환이 받는 라인의 구조예요.
이벤트: 구독할 수 있는 모든 것이에요.
액션: 장바구니 읽기와 변경이에요.
사용 사례: 일반적인 요청에 대한 완전한 솔루션이에요.

시작하기

홈 페이지

모범 사례

구매 후 업셀

장바구니

체크아웃 업셀 (Shopify Plus)

감사 페이지

제품 페이지 업셀

Rokt Thanks

전략

분석 및 추적

연동

Aftersell MCP

요금 및 계정

문제 해결

훅

등록 작동 방식

registerLineTransform

registerLineComparator

registerCartEnricher

registerSubscriptionOptionsTransform

registerDefaultSubscriptionOptionSelector

registerSkipAddToCartRule

다음 단계

​등록 작동 방식

​registerLineTransform

​registerLineComparator

​registerCartEnricher

​registerSubscriptionOptionsTransform

​registerDefaultSubscriptionOptionSelector

​registerSkipAddToCartRule

​다음 단계

등록 작동 방식

registerLineTransform

registerLineComparator

registerCartEnricher

registerSubscriptionOptionsTransform

registerDefaultSubscriptionOptionSelector

registerSkipAddToCartRule

다음 단계