> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 리워드 블록

> Aftersell Cart의 리워드(Rewards) 블록: 티어별 무료 배송, 할인, 무료 선물 — 마켓, 국가, 통화별로 다른 티어를 설정할 수 있어요.

> **리워드(Rewards)** 블록은 쇼핑객이 장바구니에 더 많이 담아 잠금 해제하는 리워드 티어(무료 배송, 주문 할인, 무료 선물)를 향한 진행률 바를 표시해, 다음 리워드에 얼마나 가까운지 보여줌으로써 더 큰 장바구니를 유도하고 조건을 충족한 리워드를 자동으로 부여해요. 티어는 마켓, 국가, 통화별로 다르게 설정할 수 있어요.

<Frame>
  <img src="https://mintcdn.com/aftersell/1Y3gBpUfxv16VGSW/images/aftersell/cart-rewards-block-progress-bar-toward-tiered.png?fit=max&auto=format&n=1Y3gBpUfxv16VGSW&q=85&s=14074a434c0024287bd1dd36051af69b" alt="무료 배송, 무료 선물 등 티어별 리워드를 향한 진행률 바를 보여주는 리워드 블록" width="1412" height="312" data-path="images/aftersell/cart-rewards-block-progress-bar-toward-tiered.png" />
</Frame>

<div id="tier-threshold-validation">
  ## 티어 기준값 검증
</div>

각 조건의 티어 목록에는 최대 **4개**의 티어를 담을 수 있어요 — 여러 마켓, 국가, 통화 조건이 있는 리워드 블록은 조건당 최대 4개를 저장하며, 첫 번째로 일치하는 조건이 표시되기 때문에 한 명의 쇼핑객이 보는 티어는 최대 4개예요. 각 티어의 기준값은 바로 위 티어보다 반드시 커야 해요 — 기준값은 오름차순이어야 해요. 티어의 기준값이 이전 티어의 기준값과 같거나 낮으면, 해당 티어의 기준값 필드에 인라인 오류가 표시되고 문제가 해결될 때까지 **Save** 버튼이 차단돼요. 영향을 받은 티어는 자동으로 펼쳐져 오류가 보이게 돼요.

예를 들어 티어 1이 \$100로 설정되어 있으면 티어 2는 \$101 이상으로 설정해야 해요.

<div id="behavior">
  ## 동작 방식
</div>

* 진행률 계산에서 리워드 선물 라인, 상품 애드온 라인, 배송 보호 라인, 기프트 카드는 합계에서 **제외**되므로, 이러한 항목이 쇼핑객의 리워드 진행률을 부풀리지 않아요.
* 메시지는 다음 티어까지 남은 금액이나 수량을 표시하고, 모든 티어를 달성하면 완료 메시지를 표시해요.
* **무료 선물은 자동으로 부여돼요.** 쇼핑객이 선물 티어에 도달하면 선물이 장바구니에 추가되고, 그 아래로 떨어지면 선물이 제거돼요. 리워드 중첩이 꺼져 있으면 달성한 최상위 티어의 선물만 부여돼요.
* **Add back removed free gifts**는 쇼핑객이 자동으로 부여된 선물을 직접 제거했을 때의 동작을 제어해요. 활성화(기본값)하면 다음 장바구니 업데이트 시 선물이 자동으로 다시 추가돼요. 비활성화하면 제거가 존중되어 해당 세션의 나머지 기간 동안 선물이 장바구니에 남지 않으므로, 쇼핑객이 선물을 거절하기 위해 장바구니와 씨름하지 않아도 돼요.

<div id="settings">
  ## 설정
</div>

| 설정                                         | 제어하는 항목                                                                             | 기본값                     |
| ------------------------------------------ | ----------------------------------------------------------------------------------- | ----------------------- |
| **Rewards calculation**                    | 진행률을 **Cart total (\$)** 또는 **Cart quantity (#)** 중 어느 것으로 측정할지.                    | Cart total (\$)         |
| **Stack rewards across tiers**             | 켜기: 구매자가 잠금 해제한 모든 리워드를 도달한 최고 티어까지 적용해요. 끄기: 잠금 해제된 최고 티어의 리워드만 적용해요.              | 켜짐                      |
| **Add back removed free gifts**            | 구매자가 획득한 무료 선물을 제거한 후 다시 추가해요.                                                      | 켜짐                      |
| **Show tier icons**                        | 티어 아이콘을 바에 표시할지 여부.                                                                 | 켜짐                      |
| **Show tier labels**                       | 바의 각 티어 마커에 레이블 텍스트를 표시할지 여부.                                                       | 꺼짐                      |
| **Text after completing full rewards bar** | 모든 티어를 달성하면 표시되는 서식 있는 텍스트.                                                         | `All rewards unlocked!` |
| **Tiers**                                  | 리워드 티어(아래 참고). 조건당 최대 **4개**이며, 패널에 `n/4` 카운터가 표시되고 최대치에 도달하면 **Add tier**가 비활성화돼요. | 없음                      |

각 **티어**를 펼치면 다음과 같아요:

| 티어 설정                                      | 제어하는 항목                                                                                                 | 기본값                                          |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| **Reward type**                            | **Free shipping**, **Order discount**, 또는 **Free gift**. 변경하면 해당 티어의 제목과 진행률 바 레이블이 새 유형의 기본 문구로 초기화돼요. | Free shipping                                |
| **Threshold (\$)** / **Threshold (items)** | 티어를 잠금 해제하는 장바구니 합계 또는 상품 수량. 레이블은 **Rewards calculation**을 따라요. 최소 `1`.                                | `50`                                         |
| **Discount value type**                    | 주문 할인 전용: **Percentage (%)** 또는 **Fixed amount (\$)**.                                                  | Percentage (%)                               |
| **Percentage off** / **Amount off**        | 주문 할인 전용: 할인 금액. 퍼센트는 100으로 제한돼요.                                                                       | `10`                                         |
| **Title before achieving tier**            | 쇼핑객이 아직 티어에 못 미칠 때 표시되는 서식 있는 텍스트 메시지. `{{amount}}` 토큰을 지원해요.                                           | `You're {{amount}} away from free shipping!` |
| **Progress bar label**                     | 티어 마커에 표시되는 레이블.                                                                                        | `Free shipping`                              |
| **Gift products**                          | 무료 선물 전용: 부여되는 상품/변형으로, 티어당 최대 **3개**예요.                                                                | 없음                                           |

<div id="placement-and-limits">
  ## 배치 및 제한
</div>

* **영역:** 모두(상단, 본문, 하단).
* **최대:** 장바구니 상태당 1개 — 채워진 장바구니와 빈 장바구니 각각 하나씩이에요.
* **상태:** 채워진 장바구니와 빈 장바구니 모두.
* 기본으로 추가되지 않아요. 잠겨 있지 않으므로 제거하거나 숨길 수 있어요.

<div id="per-market-rewards">
  ## 마켓별 리워드
</div>

리워드는 현재 전체 **Conditions** UI를 갖춘 블록이에요: 각각 **Shopify 마켓**, **고객 국가**, **고객 통화**(**In** 또는 **Not in**)를 대상으로 하는 여러 티어 세트를 정의할 수 있어요. 첫 번째로 일치하는 조건이 쇼핑객에게 표시돼요. 일치하는 조건이 없으면 블록은 해당 쇼핑객에게 아무것도 렌더링하지 않아요.

각 조건은 설정 패널의 카드(**When** + 조건)예요. 그 아래 **Display** 섹션에 해당 조건의 티어가 있어요. 구체적인 규칙은 **All buyers** 포괄 조건보다 위에 두세요. 순서는 우선순위이며, 일치하는 모든 조건의 조합이 아니에요.

마지막 조건은 삭제할 수 없어요(항상 하나 이상 필요해요). 에디터 미리보기는 실제 구매자를 평가하지 않으므로, 해당 변형을 미리보려면 패널에서 조건을 선택하세요.

조건이 눈 모양 토글 및 다른 블록과 어떤 관계인지는 [마켓, 국가, 통화별로 표시 또는 숨기기](/ko/aftersell/cart/blocks-overview#show-or-hide-by-market-country-or-currency)를 참고하세요.

<div id="custom-template">
  ## 커스텀 템플릿
</div>

코드(Code) 탭에서 [커스텀 템플릿](/ko/aftersell/cart/custom-templates)을 지원하며, 이 블록의 기본 마크업을 여러분의 JSX로 대체해요. 이 블록이 받는 props는 다음과 같아요.

| Prop                 | 타입            | 용도                                                                       |
| -------------------- | ------------- | ------------------------------------------------------------------------ |
| `milestones`         | `Milestone[]` | 순서대로 정렬된 리워드 티어. 아래를 참고하세요.                                              |
| `rewardsMessageHtml` | `string`      | 살균 처리된 HTML 형식의 진행률 또는 완료 메시지예요.                                         |
| `showIcons`          | `boolean`     | 판매자가 티어 아이콘을 활성화했는지 여부예요.                                                |
| `showTierLabels`     | `boolean`     | 판매자가 티어 바 레이블을 활성화했는지 여부예요.                                              |
| `isLoading`          | `boolean`     | 여기서는 항상 `false`예요: 블록은 로드 중에 기본 제공 스켈레톤을 렌더링하고, 장바구니가 준비된 후에만 템플릿을 호출해요. |

각 `Milestone`:

| 필드                | 타입                     | 용도                                                                   |
| ----------------- | ---------------------- | -------------------------------------------------------------------- |
| `id`              | `string`               | 티어의 안정적인 키. React `key`로 사용하세요.                                      |
| `label`           | `string`               | 일반 텍스트 형식의 티어 레이블이에요.                                                |
| `icon`            | `ReactElement \| null` | 사전 렌더링된 아이콘 요소. 티어에 없으면 `null`이에요. 직접 렌더링하세요: `{m.icon}`.            |
| `isCompleted`     | `boolean`              | 장바구니가 이 티어에 도달했는지 여부예요.                                              |
| `positionPercent` | `number`               | 바에서 **이 티어 자체 구간**이 얼마나 채워졌는지, `0`부터 `100`까지 — 하나의 공유 바 위의 위치가 아니에요. |

```jsx theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
function Rewards(props) {
  return (
    <div>
      <div dangerouslySetInnerHTML={{ __html: props.rewardsMessageHtml }} />

      {props.milestones.map((milestone) => (
        // Each tier gets its own track; positionPercent (0-100) fills that track.
        <div key={milestone.id}>
          <div style={{ background: '#E9E9E9', height: 5 }}>
            <div style={{ width: `${milestone.positionPercent}%`, background: '#000', height: 5 }} />
          </div>
          {props.showIcons && milestone.icon ? milestone.icon : null}
          {props.showTierLabels && milestone.label !== '' ? milestone.label : null}
        </div>
      ))}
    </div>
  );
}
```

`m.icon`은 URL이나 아이콘 이름이 아니라 **사전 렌더링된 요소**이므로, 이미지 요소를 만들려고 하기보다 직접 렌더링하세요.

<Note>
  커스텀 템플릿 내부에서 `milestones`는 절대 비어 있지 않아요. 표시할 티어가 없으면 블록이 아무것도 렌더링하지 않고 템플릿도 전혀 호출되지 않으므로, 빈 상태 분기가 필요 없어요.
</Note>

<div id="design">
  ## 디자인
</div>

설정 패널의 **Design** 섹션에서 이 블록의 스타일을 지정하세요. 이는 전역 디자인 위에 적용되는 블록별 재정의이며, 비워 두면 전역 디자인으로 대체돼요.

<div id="text">
  ### 텍스트
</div>

Design의 **Text** 섹션에서 리워드 텍스트 요소의 타이포그래피를 제어할 수 있어요. **Text element** 선택기로 요소를 전환하세요.

**Message** — 진행률 또는 완료 메시지예요. 커스텀 글꼴 패밀리도 지원해요. 굵기와 텍스트 색상은 (Settings 탭의) 위쪽 리치 텍스트 에디터에서 설정하며, 이곳에서 설정하지 않아요.

| 설정                 | 제어하는 항목        | 기본값     |
| ------------------ | -------------- | ------- |
| **Font**           | 메시지의 글꼴 패밀리예요. | 테마에서 상속 |
| **Size**           | 글꼴 크기예요.       | `14px`  |
| **Line height**    | 줄 높이 배수예요.     | `1.43`  |
| **Letter spacing** | 문자 간 간격이에요.    | Normal  |

**Tier label** — 각 티어 마커에 표시되는 레이블이에요. **Show tier labels**가 활성화된 경우에만 사용할 수 있어요.

| 설정                 | 제어하는 항목                                              | 기본값           |
| ------------------ | ---------------------------------------------------- | ------------- |
| **Text color**     | 티어 레이블의 색상이에요.                                       | 보조 텍스트 색상     |
| **Size**           | 글꼴 크기예요.                                             | `13px`        |
| **Weight**         | 글꼴 굵기예요 — Light, Regular, Medium, Semibold, 또는 Bold. | Regular (400) |
| **Line height**    | 줄 높이 배수예요.                                           | `1.2`         |
| **Letter spacing** | 문자 간 간격이에요.                                          | Normal        |

<Tip>
  장바구니 미리보기에서 텍스트 요소를 직접 클릭하면 해당 요소가 강조되고, 패널에서 해당 컨트롤이 자동으로 열려요.
</Tip>

디자인 설정이 무엇인가요? 자세한 내용은 여기에서 확인하세요: [디자인 설정](/ko/aftersell/cart/design-settings).