> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/ko/brand-pages/brand-page-retailer-integration-guide/module-capabilities.md).

# 모듈 기능

본 문서는 사용 가능한 모든 모듈 유형, 해당 필드, 제약 조건 및 구성 옵션을 설명합니다. 각 모듈이 지원하는 사항과 브랜드가 브랜드 페이지 콘텐츠를 생성할 때 구성할 수 있는 사항에 대해 소매업체용 참조서로 사용하세요.

***

## 모듈 유형 한눈에 보기

| 모듈      | 목적                                   |
| ------- | ------------------------------------ |
| 히어로 배너  | 헤드라인, 자막, CTA가 포함된 전체 너비 미디어         |
| 이미지     | 옵션으로 캡션, 대체 텍스트, 링크가 포함된 단일 이미지      |
| 텍스트     | 헤드라인, 태그라인, 본문 문구 또는 사용자 지정 다중 행 텍스트 |
| 분할 레이아웃 | 이미지 및/또는 텍스트 모듈을 포함하는 2열 또는 누적 레이아웃  |
| 이미지 갤러리 | 옵션으로 섹션 제목, 설명, CTA가 포함된 이미지 그리드     |
| 필터 메뉴   | 라벨이 지정된 필터 항목의 탐색 모어                 |
| 상품 그리드  | 옵션으로 필터링 및 CTA가 포함된 큐레이팅된 상품 그리드     |

## 공통 필드 (모든 모듈)

모든 모듈은 다음의 시스템 관리 필드를 공유합니다. 브랜드는 이를 직접 설정하지 않습니다.

| 필드                          | 설명                                    |
| --------------------------- | ------------------------------------- |
| `id`                        | 자동 생성되는 고유 식별자                        |
| `brandPageModuleTemplateId` | 콘텐츠를 소매업체의 모듈 템플릿에 연결합니다.             |
| `order`                     | 페이지의 표시 위치 (드래그 앤 드롭으로 관리됨)           |
| `optionality`               | 전체 모듈이 필수인지 또는 건너뛸 수 있는지 여부 (소매업체 정의) |

## 1. 히어로 배너

배경 이미지, 오버레이, 헤드라인 텍스트 및 콜투액션(CTA)을 결합한 전체 너비 배너입니다. 일반적으로 브랜드 페이지의 첫 번째 모듈입니다.

### 미디어

| 필드     | 필수 여부?             | 제약 조건                                                               |
| ------ | ------------------ | ------------------------------------------------------------------- |
| 이미지    | 필수                 | 형식: `GIF`, `JPG`, `PNG`, `SVG` · 최소 크기: 소매업체 정의 · 최대 파일 크기: 소매업체 정의 |
| 대체 텍스트 | 필수 또는 옵션 (소매업체 정의) | 접근성을 위한 설명 텍스트                                                      |

{% hint style="info" %}
비디오 지원은 계획되어 있으나 아직 제공되지 않습니다. 현재는 이미지만 허용됩니다.
{% endhint %}

### 오버레이

소매업체는 이 모듈에서 오버레이를 사용할 수 있는지 여부를 정의합니다.

| 설정               | 동작                              |
| ---------------- | ------------------------------- |
| `disabled`       | 오버레이 없음 — 색상 레이어 없이 이미지가 표시됨    |
| `optional` (허용됨) | 브랜드가 오버레이 활성화 또는 비활성화를 선택할 수 있음 |
| `required`       | 오버레이가 항상 표시됨; 브랜드가 이를 끌 수 없음    |

오버레이가 활성화되면 브랜드가 배경 스타일을 선택합니다. 소매업체는 제공되는 스타일을 제어합니다.

| 스타일        | 설명                |
| ---------- | ----------------- |
| `gradient` | 이미지로부터의 그라데이션 페이드 |
| `solid`    | 텍스트 뒤의 단색 블록      |

두 옵션을 동시에 사용할 수 있도록 할 수 있습니다.

### 텍스트 콘텐츠

| 필드         | 필수 여부?                   | 제약 조건                           |
| ---------- | ------------------------ | ------------------------------- |
| 헤드라인       | 필수                       | 최대 글자 수: 소매업체 정의                |
| 서브헤드라인     | 옵션                       | 최대 글자 수: 소매업체 정의                |
| CTA 버튼 텍스트 | 필수, 옵션 또는 비활성화 (소매업체 정의) | 최대 글자 수: 소매업체 정의                |
| CTA 링크 URL | 필수, 옵션 또는 비활성화 (소매업체 정의) | 최대 글자 수: 소매업체 정의 · 유효한 URL이어야 함 |

{% hint style="info" %}
CTA 텍스트와 CTA 링크는 함께 구성됩니다. CTA가 비활성화되면 두 필드 모두 나타나지 않습니다. CTA 버튼 없이 CTA 링크만 있거나 그 반대의 경우는 불가능합니다.
{% endhint %}

### 텍스트 정렬

소매업체는 어떤 정렬 옵션을 사용할 수 있는지 정의합니다. 가능한 값: `left`, `center`, `right`. 브랜드는 제공된 세트에서 선택합니다.

## 2. 이미지

선택적 캡션, 대체 텍스트 및 링크 대상을 포함하는 단일 이미지입니다.

### 이미지 업로드

| 필드     | 필수 여부?             | 제약 조건                                                               |
| ------ | ------------------ | ------------------------------------------------------------------- |
| 이미지    | 필수                 | 형식: `GIF`, `JPG`, `PNG`, `SVG` · 최소 크기: 소매업체 정의 · 최대 파일 크기: 소매업체 정의 |
| 대체 텍스트 | 필수 또는 옵션 (소매업체 정의) | 접근성을 위한 설명 텍스트                                                      |

### 캡션

| 필드 | 필수 여부? | 제약 조건                   |
| -- | ------ | ----------------------- |
| 캡션 | 옵션     | 최대 글자 수: 리테일러 정의 · 단일 행 |

{% hint style="info" %}
캡션 제공 여부는 리테일러가 정의합니다. 리테일러가 캡션을 활성화하지 않은 경우 해당 필드가 표시되지 않습니다.
{% endhint %}

### 링크

각 이미지는 선택적으로 대상에 링크될 수 있습니다. 브랜드는 다음 세 가지 링크 유형 중 하나를 선택합니다.

| 링크 유형     | 설명                                  |
| --------- | ----------------------------------- |
| `image`   | 링크 없음 — 이미지가 비상호작용적임                |
| `url`     | 선택 시 맞춤 URL로 이동합니다                  |
| `product` | 특정 상품 상세 페이지로 이동합니다(상품 선택기를 통해 선택함) |

### 추가 텍스트 행

일부 이미지 모듈은 이미지와 함께 추가 라벨이 지정된 텍스트 행을 지원합니다(예: 이미지 아래 또는 위에 렌더링되는 제목 또는 설명). 이용 가능 여부, 라벨, 글꼴 크기 및 각 행의 필수/선택 여부는 모두 리테일러가 정의합니다.

## 3. 텍스트

단일 행 및 여러 행 변형을 지원하는 유연한 텍스트 모듈입니다.

### 변형

리테일러는 모듈이 사용하는 변형을 정의합니다.

| 변형         | 설명                                         |
| ---------- | ------------------------------------------ |
| `headline` | 눈에 띄는 단일 텍스트 행 — 크고 굵게 표시됨                 |
| `tagline`  | 단일 보조 행 — 헤드라인보다 작음                        |
| `body`     | 본문 문구의 단일 블록 — 텍스트 영역으로 렌더링됨               |
| `lines`    | 각각 고유한 글꼴 크기 및 선택성을 가진 여러 개의 이름이 지정된 텍스트 행 |

### 필드 — 단일 행 변형 (`headline`, `tagline`, `body`)

| 필드  | 필수 여부? | 제약 조건                         |
| --- | ------ | ----------------------------- |
| 텍스트 | 필수     | 최대 글자 수: 리테일러 정의 (전체 필드에 적용됨) |

### 필드 — 여러 행 변형 (`lines`)

각 행은 리테일러에 의해 독립적으로 정의됩니다.

| 필드    | 필수 여부?                 | 제약 조건                                           |
| ----- | ---------------------- | ----------------------------------------------- |
| 행 텍스트 | 필수 또는 선택 (행별, 리테일러 정의) | 최대 글자 수: 리테일러 정의 (행별로 적용됨)                      |
| 행 URL | 옵션                     | 다음 항목이 활성화된 행에서만 사용 가능: `isHyperlink` 이(가) 활성화됨 |

### CTA

| 필드         | 필수 여부?                   | 제약 조건          |
| ---------- | ------------------------ | -------------- |
| CTA 버튼 텍스트 | 필수, 옵션 또는 비활성화 (소매업체 정의) | —              |
| CTA 링크 URL | 필수, 옵션 또는 비활성화 (소매업체 정의) | 유효한 URL이어야 합니다 |

{% hint style="info" %}
CTA 선택성은 텍스트와 URL 모두에 함께 적용됩니다. 비활성화된 경우 두 필드 모두 표시되지 않습니다.
{% endhint %}

### 정렬

리테일러 정의. 가능한 값: `left`, `center`, `right`. 모듈의 모든 텍스트에 적용됩니다.

### 최대 너비

리테일러는 텍스트 블록이 렌더링될 수 있는 너비를 제한하는 `maxWidth` 제약 조건을 설정합니다(예: `600px` or `80%`). 이는 디스플레이 제약 조건이며 콘텐츠 제약 조건이 아닙니다.

## 4. 분할 레이아웃

열이나 행으로 정렬된 두 개 이상의 하위 모듈을 보유하는 레이아웃 컨테이너입니다. 하위 항목은 **Image** 및/또는 **Text** 모듈입니다. 중첩은 최대 2단계까지 지원되지만 루트 수준에서는 분할 레이아웃을 중첩할 수 없습니다.

### 레이아웃 옵션

| 레이아웃      | 옵션                                                           |
| --------- | ------------------------------------------------------------ |
| `columns` | 나란히 배치. 비율: `50:50`, `33:67`, or `67:33` (제공되는 비율은 리테일러가 정의) |
| `rows`    | 수직으로 쌓임                                                      |

### 간격

하위 항목 간의 간격은 리테일러의 스타일 가이드 간격 스케일에서 가져와 리테일러가 정의합니다.

### 하위 항목

| 속성         | 값                                                             |
| ---------- | ------------------------------------------------------------- |
| 허용되는 하위 유형 | `Image`, `Text`                                               |
| 하위 항목 수    | 리테일러 정의 (`numChildren`)                                       |
| 중첩         | 하위 분할 레이아웃 자체에 다음이 포함될 수 있습니다: `Image` 및 `Text` 모듈 (최대 깊이: 2) |

{% hint style="info" %}
중요

히어로 배너, 이미지 갤러리, 필터 메뉴 또는 상품 그리드를 분할 레이아웃 내에 배치할 수 없습니다.
{% endhint %}

## 5. 이미지 갤러리

선택적 섹션 헤더, 설명 및 하단 CTA가 포함된 이미지 그리드입니다.

### 섹션 헤더

| 필드    | 필수 여부?                   | 제약 조건 |
| ----- | ------------------------ | ----- |
| 섹션 제목 | 필수, 옵션 또는 비활성화 (소매업체 정의) | —     |
| 섹션 설명 | 필수, 옵션 또는 비활성화 (소매업체 정의) | —     |

### 갤러리 레이아웃

중단점별 리테일러 정의:

| 속성     | 설명                             |
| ------ | ------------------------------ |
| 열      | 모바일, 태블릿, 데스크톱의 열 수(리테일러가 정의함) |
| 이미지 높이 | 중단점별 픽셀 또는 백분율 높이(리테일러가 정의함)   |
| 간격     | 이미지 간의 간격(리테일러 스타일 가이드 기준)     |

### 이미지

| 속성       | 제약 조건                                         |
| -------- | --------------------------------------------- |
| 최소 이미지 수 | 리테일러가 정의함(최소 이 수만큼 추가해야 함)                    |
| 최대 이미지 수 | 리테일러가 정의함(이 수를 초과할 수 없음)                      |
| 형식       | `GIF`, `JPG`, `PNG`, `SVG`                    |
| 최소 차원    | 리테일러가 정의함                                     |
| 최대 파일 크기 | 리테일러가 정의함                                     |
| 대체 텍스트   | 이미지별 필수 또는 선택 사항(리테일러가 정의함)                   |
| 이미지별 캡션  | 선택 사항, 최대 글자 수: 리테일러가 정의함                     |
| 이미지별 링크  | `image` (없음) · `url` · `product` — 이미지 모듈과 동일 |

### 이미지별 추가 텍스트 줄

이미지 모듈과 동일 — 리테일러가 정의한 레이블, 글꼴 크기 및 줄별 선택 사항입니다.

### CTA(갤러리 하단)

| 필드         | 필수 여부?                                | 제약 조건          |
| ---------- | ------------------------------------- | -------------- |
| CTA 버튼 텍스트 | 필수, 옵션 또는 비활성화 (소매업체 정의)              | —              |
| CTA 링크 URL | 필수, 옵션 또는 비활성화 (소매업체 정의)              | 유효한 URL이어야 합니다 |
| CTA 정렬     | `left`, `center`, `right` (리테일러가 정의함) | —              |

## 6. 필터 메뉴

레이블이 지정된 필터 항목의 가로 탐색 바입니다. 쇼핑객이 페이지의 콘텐츠를 필터링(예: 카테고리 또는 하위 카테고리별)할 수 있도록 하는 데 사용합니다.

### 항목

| 속성      | 제약 조건                                    |
| ------- | ---------------------------------------- |
| 최소 항목 수 | 리테일러가 정의함(최소 이 수만큼 추가해야 함)               |
| 최대 항목 수 | 리테일러가 정의함(이 수를 초과할 수 없음)                 |
| 레이블 텍스트 | 최대 글자 수: 소매업체 정의                         |
| 필터 값    | 필터링 로직에 사용되는 내부 값입니다. 최대 글자 수: 리테일러가 정의함 |

### 정렬

리테일러 정의. 가능한 값: `left`, `center`.

필터 항목의 순서를 변경할 수 있습니다. 레이블은 쇼핑객에게 보이는 것이고, 값은 필터로 적용되는 것입니다. 두 항목이 동일한 문자열일 필요는 없습니다.

## 7. 상품 그리드

선택적 섹션 헤더, 필터링 및 CTA가 포함된 브랜드 선택 상품의 큐레이팅된 그리드입니다.

### 섹션 헤더

| 필드    | 필수 여부?                   | 제약 조건 |
| ----- | ------------------------ | ----- |
| 섹션 제목 | 필수, 옵션 또는 비활성화 (소매업체 정의) | —     |
| 섹션 설명 | 필수, 옵션 또는 비활성화 (소매업체 정의) | —     |

### 상품

| 속성      | 제약 조건                    |
| ------- | ------------------------ |
| 최소 상품 수 | 리테일러가 정의함                |
| 최대 상품 수 | 리테일러가 정의함                |
| 상품 소스   | 브랜드 카탈로그의 상품 선택기를 통해 선택됨 |
| 표시 순서   | 모듈 내에서 드래그 앤 드롭          |

### 상품 카드 CTA

리테일러는 각 상품 카드에 CTA 버튼을 표시할지 여부를 결정합니다.

| 설정    | 동작                                 |
| ----- | ---------------------------------- |
| 비활성화됨 | 상품 카드에 CTA 버튼 없음                   |
| 활성화됨  | CTA 버튼이 표시됨, 리테일러가 버튼 레이블 텍스트를 설정함 |

{% hint style="info" %}
활성화되면 그리드의 모든 상품 카드가 동일한 CTA 레이블(브랜드가 아닌 리테일러가 설정)을 공유합니다.
{% endhint %}

### 필터링

리테일러는 선택적으로 상품 그리드에 대한 페이지 내 필터링을 활성화할 수 있습니다.

| 설정                  | 설명                            |
| ------------------- | ----------------------------- |
| `enabled`           | 쇼핑객이 상품 그리드를 필터링할 수 있음        |
| `showActiveFilter`  | 현재 활성화된 필터를 강조 표시함            |
| `showResultCount`   | 활성 필터와 일치하는 결과 수를 표시함         |
| `emptyStateMessage` | 필터와 일치하는 상품이 없을 때 표시되는 맞춤 메시지 |

{% hint style="info" %}
필터링은 필터 메뉴 모듈과 함께 작동합니다. 상품에 설정된 필터 값은 필터 메뉴의 필터 항목 값과 일치해야 합니다.
{% endhint %}

### CTA(그리드 하단)

| 필드         | 필수 여부?                                | 제약 조건          |
| ---------- | ------------------------------------- | -------------- |
| CTA 버튼 텍스트 | 필수, 옵션 또는 비활성화 (소매업체 정의)              | —              |
| CTA 링크 URL | 필수, 옵션 또는 비활성화 (소매업체 정의)              | 유효한 URL이어야 합니다 |
| CTA 정렬     | `left`, `center`, `right` (리테일러가 정의함) | —              |

## 제약 조건 참조

### `ContentLimit` — 텍스트 필드 제약 조건 모델

| 값                       | 의미                                                    |
| ----------------------- | ----------------------------------------------------- |
| `disabled`              | 이 템플릿에서는 필드를 사용할 수 없습니다.                              |
| `allowed` + `maxChars`  | 필드는 선택 사항입니다. 작성하는 경우 다음을 초과할 수 없습니다. `maxChars` 글자 수 |
| `required` + `maxChars` | 필드를 채워야 합니다. 다음을 초과할 수 없습니다. `maxChars` 글자 수          |

### `ImageConstraints` — 이미지 업로드 제약 조건 모델

| 속성                | 설명                                                              |
| ----------------- | --------------------------------------------------------------- |
| `altOptionality`  | `required` or `allowed`                                         |
| `minWidth`        | 최소 이미지 너비(픽셀 단위)(선택 사항)                                         |
| `minHeight`       | 최소 이미지 높이(픽셀 단위)(선택 사항)                                         |
| `maxFileSizeMb`   | 최대 파일 크기(메가바이트 단위)(선택 사항)                                       |
| `acceptedFormats` | 다음의 하위 집합: `GIF`, `JPG`, `PNG`, `SVG` (선택 사항 — 설정하지 않으면 모두 허용됨) |

### `CtaConfig` — 클릭 유도문구 제약 조건 모델

| 속성            | 설명                                  |
| ------------- | ----------------------------------- |
| `optionality` | `required` · `allowed` · `disabled` |
| `alignment`   | `left` · `center` · `right`         |

## 소매업체 정의 항목과 고정 항목 비교

| 구성                                 |       소매업체가 설정함      |        플랫폼에 의해 고정됨        |
| ---------------------------------- | :------------------: | :-----------------------: |
| 모듈을 건너뛸 수 있는지 여부                   |           ✅          |                           |
| 최대 글자 수 제한                         |           ✅          |                           |
| 이미지 최소 크기 및 최대 파일 크기               |           ✅          |                           |
| 허용되는 이미지 형식                        | ✅ (플랫폼 지원 항목의 하위 집합) |                           |
| CTA가 필수인지, 선택 사항인지, 또는 비활성화되었는지 여부 |           ✅          |                           |
| 오버레이 사용 가능 여부(Hero)                |           ✅          |                           |
| 제공되는 텍스트 정렬 옵션                     |           ✅          |                           |
| 열 비율 옵션(분할 레이아웃)                   |           ✅          |                           |
| 최소/최대 이미지 수(이미지 갤러리)               |           ✅          |                           |
| 최소/최대 상품 수(상품 그리드)                 |           ✅          |                           |
| 사용 가능한 모듈 유형                       |                      |      ✅ (7가지 유형, 고정됨)      |
| 지원되는 미디어 유형(Hero)                  |                      |    ✅ (이미지만 해당, 동영상 계획됨)   |
| 이미지 링크 유형                          |                      | ✅ (image · url · product) |
| 분할 레이아웃 최대 중첩 깊이                   |                      |          ✅ (깊이 2)         |
| 분할 레이아웃 허용 하위 유형                   |                      |    ✅ (Image 및 Text만 해당)   |

<br>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.citrusad.com/retail-media-interface/integration/ko/brand-pages/brand-page-retailer-integration-guide/module-capabilities.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.