> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/catalog/selection.md).

# 카탈로그 셀렉션

조건에 맞는 카탈로그 아이템을 골라 메시지에 불러오는 셀렉션을 알아봅니다.

셀렉션은 카탈로그에서 조건에 맞는 아이템을 골라 오는 규칙입니다. 필터, 정렬, 결과 개수를 한 번 저장해 두면 메시지가 발송될 때마다 그 규칙으로 아이템을 골라 옵니다.

아이템 ID를 알고 있으면 `catalog_items` 태그로 아이템을 직접 불러올 수 있습니다. 셀렉션은 아이템 ID를 미리 정할 수 없을 때 사용합니다. 예를 들어 "할인 중인 상품을 가격이 낮은 순으로 5개"처럼 조건으로 아이템을 고를 수 있습니다.

#### 이렇게 활용할 수 있어요 <a href="#use-cases" id="use-cases"></a>

| 업종       | 활용 예시                                 |
| -------- | ------------------------------------- |
| 커머스      | 할인 중인 상품 중 할인율이 높은 순서대로 3개를 소개하는 메시지  |
| 컨텐츠와 미디어 | 사용자가 좋아하는 장르의 신작을 최신순으로 추천하는 메시지      |
| O2O와 매장  | 사용자가 사는 지역의 매장 중 이번 주 이벤트를 진행하는 매장 안내 |

{% hint style="info" %}
**시작 전 준비물**

셀렉션을 만들려면 먼저 카탈로그와 아이템이 준비되어 있어야 합니다. 카탈로그를 만드는 방법은 [카탈로그 생성하기](https://docs.hackle.io/catalog/create.md)를 참고하세요.
{% endhint %}

## 셀렉션 구성 <a href="#selection-structure" id="selection-structure"></a>

셀렉션은 아래 항목으로 구성됩니다.

<table><thead><tr><th width="140">항목</th><th>설명</th></tr></thead><tbody><tr><td><strong>이름</strong></td><td>메시지에서 셀렉션을 부를 때 쓰는 이름입니다. 영문, 숫자, 하이픈(-), 밑줄(_)만 쓸 수 있습니다. 한 카탈로그 안에서 이름이 겹칠 수 없으며, 만든 뒤에는 바꿀 수 없습니다.</td></tr><tr><td><strong>설명</strong></td><td>셀렉션의 용도를 적어 두는 칸입니다. 언제든 고칠 수 있습니다.</td></tr><tr><td><strong>필터</strong></td><td>아이템을 고르는 조건입니다. 최대 10개까지 추가할 수 있고, 모든 조건을 만족하는 아이템만 결과에 담깁니다.</td></tr><tr><td><strong>정렬</strong></td><td>결과 아이템의 순서입니다. 필드 하나를 골라 오름차순이나 내림차순으로 정렬합니다. 기본값은 정렬하지 않음입니다.</td></tr><tr><td><strong>결과 개수</strong></td><td>메시지에 불러올 아이템의 최대 개수입니다. 1~50 사이로 정하며 기본값은 5개입니다.</td></tr></tbody></table>

셀렉션은 카탈로그마다 최대 30개까지 만들 수 있습니다.

## 셀렉션 만들기 <a href="#create-selection" id="create-selection"></a>

{% stepper %}
{% step %}

### 셀렉션 탭 열기 <a href="#open-selection-tab" id="open-selection-tab"></a>

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2Fgit-blob-4c8b11080e96a0e7e8d2de88351eb3ef8bc575d1%2Fselection_step1_create.png?alt=media" alt=""><figcaption></figcaption></figure>

셀렉션을 만들 카탈로그의 상세 화면에서 \*\*셀렉션\*\* 탭을 열고 \*\*생성하기\*\*를 클릭합니다.
{% endstep %}

{% step %}

### 이름과 설명 입력 <a href="#enter-name-and-description" id="enter-name-and-description"></a>

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2Fgit-blob-694ec5a6bc57f2bde6ac5859eabe26066c3bf542%2Fselection_step2_name.png?alt=media" alt=""><figcaption></figcaption></figure>

셀렉션의 이름과 설명을 입력합니다. 이름은 만든 뒤에 바꿀 수 없으니 메시지에서 알아보기 쉬운 이름으로 정하세요. 예: \`on\_sale\_top5\`
{% endstep %}

{% step %}

### 필터 추가 <a href="#add-filters" id="add-filters"></a>

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2Fgit-blob-069dfeb60903bf4699fbc51a11c737e04ddb81ab%2Fselection_step3_filters.png?alt=media" alt=""><figcaption></figcaption></figure>

조건으로 쓸 필드와 연산자를 고르고 값을 입력합니다. 필드 타입별로 쓸 수 있는 연산자는 \[필터 연산자]\(#filter-operators)를 참고하세요.
{% endstep %}

{% step %}

### 정렬과 결과 개수 설정 <a href="#set-sort-and-result-count" id="set-sort-and-result-count"></a>

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2Fgit-blob-8e259f52cf37929db9186cb155de3a1d72377be1%2Fselection_step4_sort.png?alt=media" alt=""><figcaption></figcaption></figure>

정렬 기준이 될 필드와 방향을 고르고, 불러올 아이템의 최대 개수를 정합니다.
{% endstep %}

{% step %}

### 결과 미리보기 후 저장 <a href="#preview-and-save" id="preview-and-save"></a>

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2Fgit-blob-2b9b5017ec8219d88ca5ee1ee7358e24770be5d1%2Fselection_step5_preview.png?alt=media" alt=""><figcaption></figcaption></figure>

미리보기로 어떤 아이템이 골라지는지 확인한 뒤 저장합니다. 필터 값에 개인화 변수를 넣었다면 미리보기에서 속성 값을 직접 입력해 결과를 확인할 수 있습니다.
{% endstep %}
{% endstepper %}

## 필터 연산자 <a href="#filter-operators" id="filter-operators"></a>

필드 타입에 따라 쓸 수 있는 연산자가 다릅니다.

<table><thead><tr><th width="120">필드 타입</th><th>연산자</th></tr></thead><tbody><tr><td>String</td><td>다음 중 하나, 다음 중 하나가 아닌, 존재하는, 존재하지 않는</td></tr><tr><td>Number</td><td>다음 중 하나, 다음 중 하나가 아닌, 큰, 크거나 같은, 작은, 작거나 같은, 존재하는, 존재하지 않는</td></tr><tr><td>Time</td><td>다음과 같은 날짜, 다음 날짜 이후, 다음 날짜를 포함한 그 이후, 다음 날짜 이전, 다음 날짜를 포함한 그 이전, 존재하는, 존재하지 않는</td></tr><tr><td>Boolean</td><td>참인, 거짓인</td></tr></tbody></table>

* 셀렉션에서 사용 중인 필드는 삭제할 수 없습니다. 필드를 삭제하려면 그 필드를 쓰는 셀렉션의 필터와 정렬에서 먼저 빼 주세요.

### 필터 값에 개인화 변수 사용 <a href="#personalization-variables-in-filters" id="personalization-variables-in-filters"></a>

필터 값에 Liquid 문법으로 사용자 속성, 이벤트 속성, API 속성을 넣을 수 있습니다. 발송 시점에 사용자마다 그 값으로 필터를 계산하므로, 같은 셀렉션으로도 사용자마다 다른 아이템을 보여 줄 수 있습니다.

예를 들어 `genre` 필드에 **다음 중 하나** 연산자를 고르고 값에 아래처럼 입력하면, 사용자가 좋아하는 장르의 아이템만 골라 옵니다.

```liquid
{{ user_properties["favorite_genre"] }}
```

## 메시지에서 셀렉션 사용하기 <a href="#use-selection-in-messages" id="use-selection-in-messages"></a>

메시지 본문에 `catalog_selection_items` 태그를 넣으면 셀렉션의 결과가 `items` 변수에 담깁니다.

{% code overflow="wrap" %}

```liquid
{% catalog_selection_items <카탈로그명> <셀렉션명> %}
```

{% endcode %}

결과 아이템은 셀렉션에 설정한 정렬 순서대로 담기므로 `for` 태그로 순서대로 출력할 수 있습니다.

{% code overflow="wrap" %}

```liquid
{% catalog_selection_items Products on_sale_top5 %}{% for item in items %}{{ item.name }} {{ item.price | number_with_delimiter }}원
{% endfor %}
```

{% endcode %}

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2Fgit-blob-7ebd20fa01cf945a8a15cd68cbf239dc7ce5a551%2Fselection_usage.png?alt=media" alt=""><figcaption></figcaption></figure>

셀렉션 필터 중 하나라도 계산할 수 없으면 결과가 0개로 처리됩니다. 이때도 메시지는 발송되므로 `if` 태그로 대체 문구를 준비해 두세요. 태그의 자세한 동작과 예시는 [Liquid를 이용한 고급 개인화](https://docs.hackle.io/crm-marketing/message-personalization/liquid-template-reference.md#catalog_selection_items)를 참고하세요.

셀렉션은 푸시, 카카오, 문자, 웹훅 채널에서 사용할 수 있습니다.

## 환경별 셀렉션 관리 <a href="#selection-by-environment" id="selection-by-environment"></a>

셀렉션을 만들면 운영 환경과 개발 환경에 같은 내용으로 함께 만들어집니다. 이후 필터, 정렬, 결과 개수는 환경마다 따로 고칠 수 있습니다. 개발 환경에서 조건을 바꿔 결과를 확인한 뒤 운영 환경에 같은 조건을 반영하는 방식으로 사용할 수 있습니다.

## 셀렉션 삭제하기 <a href="#delete-selection" id="delete-selection"></a>

셀렉션 상세 화면에서 셀렉션을 삭제할 수 있습니다. 삭제하면 운영 환경과 개발 환경의 셀렉션이 함께 지워집니다. 카탈로그를 삭제하면 그 카탈로그의 셀렉션도 모두 삭제됩니다.

{% hint style="warning" %}
**사용 중인 메시지가 있는지 먼저 확인하세요.**

셀렉션을 사용 중인 캠페인이 있는 상황에서 셀렉션을 삭제할 경우, 셀렉션 결과 없이 메시지가 발송될 수 있어요.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hackle.io/catalog/selection.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
