> 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/feature-integrations/suggested-keywords.md).

# 추천 키워드

**추천 키워드**는 카탈로그의 **상품 코드**에 **검색어**를 연결합니다. 광고주가 캠페인을 작성할 때 해당 검색어는 추가한 상품에 대한 **타겟팅**(검색 키워드 선택) 중에 표시됩니다. 광고주는 맞춤 키워드만 직접 입력하는 대신 추천 키워드 중에서 선택할 수 있으며, 이를 통해 사이트의 검색 인덱싱 방식 및 캠페인에서 SKU를 쿼리에 매핑하려는 방식과의 일치성을 향상시킵니다.

<figure><img src="/files/6xSznnKa1jWPbkV0Ka1E" alt="" width="100%"><figcaption></figcaption></figure>

**추천 키워드는 두 가지 방식으로 제공될 수 있습니다.**

1. **Epsilon AI 생성 키워드** — Epsilon 귀하를 대신하여 상품-키워드 쌍을 생성, 분류 및 로드합니다. 이 경로가 유일한 소스인 경우 이러한 추천을 위해 별도의 키워드 파일을 유지 관리할 **필요가 없습니다**. 생성에는 상품 및 카탈로그 컨텍스트, 쇼퍼 검색 동작 및 **리테일러 비즈니스 규칙**(예: 브랜드 정복 및 기타 프로그램 제약 조건)에 맞춘 시그널이 사용됩니다.
2. **리테일러 관리 TSV 피드** — 귀하는 각 `product_code` 를 하나 이상의 `search_term` 값에 매핑하는 파일을 동기화하며, 선택적으로 순위 및 유형을 포함할 수 있습니다. 상품별 추천 키워드는 귀하가 관리합니다.

리테일러는 **Epsilon 생성된 키워드만**, **이 파일만** 또는 **둘 다**(예: 기존 목록에 **겹쳐서 표시되는** AI 제안, 또는 기존 승인이 신중하게 처리되도록 출시 중에 조율된 **교체**).

다음의 경우 Epsilon 가 귀하의 프로그램에 **AI 추천 키워드**를 제공하고 리테일러 TSV 피드가 **필요 없는** 경우 \*\*[3단계: AI 추천 키워드 활성화(베타)](#step-3-activate-ai-suggested-keywords-beta)부터 시작하세요. 파일을 통해 키워드를 유지 관리하거나 보완하는 경우에만[2단계: TSV 파일 생성](#step-2-optional-build-the-tsv-file-retailer-supplied-path)\*\*을 사용하세요.

### 추천 키워드를 사용하는 이유는 무엇인가요?

* 광고주가 의도가 높고 상품에 정확하게 부합하는 검색어를 사용하도록 유도합니다.
* 가이드 없이 광고주가 떠올리지 못할 수 있는 검색어를 노출합니다.
* 프로그램 규칙을 준수하면서 가치 있는 키워드에 대한 경쟁을 유도합니다.
* AI 생성이 활성화된 경우 수동 파일 작업을 줄입니다.

**이 가이드에서 다루는 내용**

* 전제 조건 및 엔드투엔드 흐름
* 읽기/유효성 검사 흐름을 위한 API 인증
* 단계별 AI 활성화(베타) 및 선택적 TSV 구현
* 샌드박스 테스트, 고라이브 체크리스트, 문제 해결

### 게재 규칙

광고주가 캠페인에 **추천** 키워드를 추가하면 **해당 키워드에 연결된 상품만** 일치하는 고객 검색어에 게재될 수 있습니다.

UI에는 어떤 상품이 어떤 추천 키워드에 매핑되는지 표시됩니다.

<figure><img src="/files/yfW0JZzS6RjYxPEeyGoo" alt="" width="100%"><figcaption></figcaption></figure>

광고주가 선택한 **맞춤** 검색어는 일반적으로 지면 규칙에 따라 캠페인 상품 전체에 적용되는 반면, **추천** 선택 사항은 \*\*리테일러 / Epsilon매핑을 사용하여 자격을 제한합니다.

## 전제 조건

시작하기 전에 이 체크리스트를 사용하세요.

* [ ] 카탈로그 동기화를 포함하여 Epsilon Retail Media에 온보딩되었거나(또는 진행 중인) **리테일러**.
* [ ] 키워드를 검증할 캠페인 UI 및 API에 대한 **샌드박스 액세스**(귀하의 프로그램에서 이용 가능한 경우).
* [ ] **TSV 전달의 경우:** Epsilon\*\*, 및 팀이 개체를 업로드하는 데 사용할 수 있는 자격 증명(방법 확인 완료: Epsilon—보통 서비스 계정 키 또는 연합 액세스). 자격 조건을 설정하는 단계만 진행하는 경우, 키워드를 제공한다면 이는 활성화 프로세스의 일부로 처리됩니다.
* [ ] 파일 업로드, API 점검 실행, 그리고 Epsilon 와의 수집 일정 및 전환 조율을 담당할 **기술 담당자**.
* [ ] **릴리스 인지:** 제안에 대한 키워드별 상품 적격성에는 플랫폼이 필요합니다(위의 제공 규칙 참조).

***

## 통합 흐름 개요

1. 귀하는 키워드가 공급되는 방식을 Epsilon 와 확인합니다:Epsilon 생성\*\*, **TSV 파일**, 또는 **둘 다**.
2. 파일을 제공하는 경우, 다음에서 프로비저닝한 GCS 버킷에 업로드하세요: Epsilon.
3. Epsilon 기능을 활성화하고 (파일의 경우) 파일을 수집합니다. **AI** 키워드의 경우, Epsilon 규칙, 선택적 덮어쓰기(overlay) 대 대체(replace), 스테이징 검증에 대해 협의합니다.
4. 데이터는 플랫폼에 **제안된 키워드**로 로드됩니다.
5. 광고주에게 출시하기 전에 UI에서 직접 샌드박스의 내용을 **확인**합니다.
6. 운영 환경에서 **라이브로 전환**하고 광고주 팀에 제안된 키워드를 사용할 수 있음을 알립니다.

***

## 단계별 구현 가이드

### 1단계: 공급 모델 확인 - Epsilon

목적\
**AI 전용**으로 요구 사항을 충족할 수 있는 경우 파일 파이프라인 구축을 피하거나, Epsilon 가 목록을 덮어쓰거나 대체해 주는 경우 작업 중복을 방지합니다.

**수행해야 할 작업**

* 결정: **AI 전용**, **TSV 전용**, 또는 **둘 다**.
* 기존의 제안된 키워드 데이터에 대한 **덮어쓰기(overlay)** 대 **대체(replace)** 여부를 확인합니다.
* 존재하는 **게재위치**를 확인합니다 (`ORGANIC` 전용 대 함께 `CROSS_SELL` / `SUBSTITUTE`).

***

### 2단계: AI 제안 키워드 활성화

**목적**\
TSV를 유지 관리할 필요 \*\*없이 Epsilon생성되고 규칙으로 필터링된 키워드를 플랫폼에 가져옵니다.

**수행해야 할 작업**

1. **Engage Epsilon와 협력** — 구체적인 **비즈니스 규칙**(예: 브랜드 침투/conquesting)과 이미 제안된 키워드를 동기화 중인 경우 새 데이터가 기존 목록과 연관되는 방식(**덮어쓰기** 대 **대체**)을 제공합니다.
2. 샌드박스에서 테스트\*\* — 다음과 협력합니다: Epsilon **스테이징/샌드박스**에서 키워드를 로드하거나 검토합니다. 캠페인 UI에서 **타겟팅**의 Dry-run을 실행합니다. 상품을 선택하고 제안된 문구가 올바른지 확인합니다.
3. 프로덕션\*\* — 승인 후, Epsilon 프로덕션을 활성화합니다. **귀사**는 광고주 팀에 제안된 키워드가 적용되었음을 알립니다(활성화되면 UI에 표시됨).

**AI 키워드 제안 작동 방식**

1. **상품 이해** - 모델링은 상품 의도, 리테일러 컨텍스트 및 언어를 사용합니다.
2. **키워드 생성** - 해당 이해를 바탕으로 후보 키워드가 생성됩니다.
3. **분류** - 광고 및 검색 데이터를 사용하여 키워드를 선택하므로 프로그램 규칙(예: 브랜드 콘퀘스팅 또는 상품 성분 타겟팅과 같은 리테일러별 정책)이 준수됩니다.
4. **UI용 로드** — 상품–키워드 쌍은 캠페인 설정의 **제안된 키워드** 플로우에서 사용하는 동일한 시스템에 저장됩니다.

**거버넌스**

* 승인 동작(**자동 vs 수동 리테일러 검토**)은 다음 파트너와 합의한 **프로그램 구성**에 따라 달라집니다. Epsilon.
* **광고 쿼리 이력**이 거의 없는 경우, 생성 결과가 실제 쇼핑객 언어와 일치하도록 **온사이트 오가닉 검색 요청의 짧은 샘플**(예: 약 **7일**)을 공유하도록 요청받을 수 있습니다.
* **매우 큰 카탈로그**는 모든 SKU 대신 **최근 광고 활동**(예: 약 **지난 90일**)이 있는 상품으로 생성 범위를 제한할 수 있습니다. 다음 파트너와 확인하세요. Epsilon.
* \*\*AI 생성 제안 키워드(베타)\*\*는 현재 **오가닉** 검색 사용 사례에 중점을 두고 있으며, 추가 지면 유형에 대한 지원이 확장될 수 있습니다.

**유효성 검사**

* 제안된 키워드는 범위 내 상품에 대해 샌드박스 **타겟팅**에 나타납니다.
* 승인 동작(자동 vs 수동 검토)은 프로그램 구성과 일치합니다.

**일반적인 오류**

| 오류                           | 해결 방법                                          |
| ---------------------------- | ---------------------------------------------- |
| 키워드가 브랜드 또는 정책에 맞지 않는 것으로 보임 | 다음 파트너와 비즈니스 규칙을 다듬고 Epsilon 샌드박스 검토를 다시 실행합니다 |
| 대형 카탈로그에 대한 제안이 없거나 거의 없음    | 최근에 광고된 SKU로 생성이 제한되어 있는지 확인합니다                |

***

### (2단계를 위한 선택 사항): TSV 파일 작성(리테일러 제공 경로)

**목적**\
신뢰할 수 있는 **product\_code → search\_term** 행(및 선택적 순위/유형)을 제공합니다.

**수행해야 할 작업**

* 상품 및 키워드 연결에 대한 탭으로 구분된 파일을 생성합니다.
* **UTF-8** 인코딩 및 **LF** 줄 바꿈을 사용합니다.
* 피드 사양에서 사용하는 필드 이름과 일치하는 헤더 행을 포함합니다. 최소한 다음이 필요합니다. `product_code`, `search_term`, `search_term_type`. 참조: [데이터 모델 및 필드 정의](#data-models--field-definitions).
* 사용 편의성을 위해 **상품당 약 \~20개의 제안된 키워드**를 유지합니다.
* 반복 `product_code` 여러 용어에 대해 여러 줄에 배치합니다. 사용법: `**search_term_type`지면 종류가 여러 개인 경우 \*\*를 사용합니다.
* 파일을 검증한 다음 GCS 버킷에 전달합니다. Epsilon 제공합니다.

**참고:** 리테일러 피드를 동기화할 때, Epsilon Retail Media 드롭용 **GCS 버킷**을 프로비저닝합니다. 플랫폼 운영이 구성을 완료해야 하므로 활성화까지 처리 시간이 소요됩니다.

**예시 파일(스니펫)**

```
product_code	search_term	search_term_rank	search_term_type
abc123	cereal	1	ORGANIC
abc123	cereals	2	ORGANIC
12345	milk	1	CROSS_SELL
```

유효성 검사

* 텍스트 편집기에서 엽니다. 필드는 **탭**으로 구분되며, 검색에 방해되는 CR 전용 줄 바꿈이 없어야 합니다.
* 여러 개를 무작위로 점검합니다 `product_code` 값이 **카탈로그** 피드에 존재합니다.

**일반적인 오류**

| 오류              | 해결 방법                                   |
| --------------- | --------------------------------------- |
| 탭 대신 CSV 쉼표 사용됨 | TSV로 다시 내보내기                            |
| 잘못된 상품 ID       | 다음 항목과 맞춤 `gtin` / `item` 카탈로그 동기화에 사용됨 |
| SKU당 줄 수가 너무 많음 | 가장 가치가 높은 용어로 축소                        |

***

### 3단계: UI에서 제안 사항 확인

**목적**\
프로덕션 전 마지막 매핑 문제를 찾아냅니다.

**수행해야 할 작업**

* **샌드박스**에서 캠페인을 생성하거나 편집하고, 제안된 키워드를 지원하는 지면을 선택하고, 상품을 추가하고, **타겟팅** / 키워드 선택을 엽니다.
* 상품별 제안된 문구와 **맞춤 설정** vs **제안됨** 동작이 예상과 일치하는지 확인합니다(**개요**의 \*\*게재 규칙 참조).
* **제안됨** 선택 시 적격 상품이 피드 또는 AI 파이프라인에 연결된 상품으로 제한되는지 확인합니다.

**유효성 검사**

* 샌드박스 UI에서 파일 또는 AI 파이프라인의 키워드에 연결된 상품에 대한 제안 키워드가 나타납니다.
* 제안 사항이 지면 및 카탈로그 기댓값에 부합합니다.

**일반적인 오류**

| 오류                 | 해결 방법                              |
| ------------------ | ---------------------------------- |
| 하나의 카탈로그에만 제안이 나타남 | 다른 카탈로그를 백필하거나 캠페인 카탈로그 범위를 조정합니다  |
| 잘못된 지면 유형이 표시됨     | TAM이 지면 ↔ 검토 `search_term_type` 구성 |

***

## 데이터 모델 및 필드 정의

### TSV (리테일러 파일)

| 필드                 | 유형  | 필수 항목 | 설명                                             | 허용되는 값                                                                 |
| ------------------ | --- | ----- | ---------------------------------------------- | ---------------------------------------------------------------------- |
| `product_code`     | 문자열 | 예     | 리테일러 상품 식별자; 카탈로그와 동일함 `gtin` / `item` 해당하는 경우 | 비어 있지 않아야 함; 동기화된 카탈로그에 존재해야 함                                         |
| `search_term`      | 문자열 | 예     | SKU에 제안된 키워드 또는 문구                             | UTF-8 텍스트; 제어 문자 제외                                                    |
| `search_term_rank` | 정수  | No    | 상대적 관련성; **1**이 가장 높음                          | 양의 정수; 낮을수록 높은 우선순위                                                    |
| `search_term_type` | 문자열 | No    | 행을 **placement** 종류에 매핑                        | `ORGANIC`, `CROSS_SELL`, `SUBSTITUTE`; 생략 시 기본값으로 처리됨 `ORGANIC` 생략된 경우 |
| (줄 바꿈)             | —   | —     | 파일 형식                                          | LF\*\*; 파일 인코딩 \*\*UTF-8                                               |

### 게재위치 유형 및 `search_term_type`

`search_term_type` 게재위치 유형과 일치함: **ORGANIC**, **CROSS\_SELL** 및 **SUBSTITUTE**.

대부분의 리테일러 프로그램은 표준 검색 결과 광고에 단일 **organic search** 게재위치를 사용합니다. **CROSS\_SELL** 및 **SUBSTITUTE**는 검색 페이지(또는 관련 인벤토리)에서 서로 다른 서빙 의도를 가진 **별도의 게재위치**입니다. 동일한 오가닉 옥션의 단순한 추가 컬럼이 아닙니다. 담당 테크니컬 어카운트 매니저가 네임스페이스에 어떤 게재위치가 있는지 확인해 드립니다.

**게재위치 유형이 다른 점**

* **Organic** — 상품에 대한 구매자의 검색 의도와 일치하는 광고(예: "콜라" 검색 시 콜라 상품).
* **Cross-sell** — 보완적 의도(예: "콜라" 검색 시 피자).
* **Substitute** — 유사 상품 의도(예: "콜라" 검색 시 다른 콜라 변형 상품).

**게재위치 유형당 하나의 피드를 동기화**하거나 **단일 파일에 유형을 결합**할 수 있습니다(다른 `product_code` 으로 반복 `search_term_type`). 담당 테크니컬 어카운트 매니저가 각 영역별로 올바른 제안 유형이 표시되도록 게재위치를 구성합니다. 제안된 키워드는 **게재위치별로 표시하거나 숨길 수 있습니다**.

한 상품에 대해 결합된 유형:

| product\_code | search\_term | search\_term\_rank | search\_term\_type |
| ------------- | ------------ | ------------------ | ------------------ |
| 12345         | cookies      | 1                  | ORGANIC            |
| 12345         | cookie       | 2                  | ORGANIC            |
| 12345         | milk         | 1                  | CROSS\_SELL        |

**참고:** 대부분의 프로그램은 **organic** 검색 게재위치만 사용합니다. `CROSS_SELL` 및 `SUBSTITUTE` 은 동일한 오가닉 슬롯의 "추가 컬럼"이 아니라 **추가 게재위치**에 해당합니다. 운영 중인 게재위치가 무엇인지 담당 테크니컬 어카운트 매니저와 확인하세요.

### 다중 카탈로그

가능한 경우 네임스페이스의 **모든** 카탈로그에 걸쳐 제안된 키워드를 구현하세요(피드, AI 생성 또는 둘 다에서 가져온 경우 모두 해당). 이렇게 하면 하나의 카탈로그에만 제안이 있고 다른 카탈로그에는 없을 때 발생하는 브랜드 혼란을 줄일 수 있습니다.

다중 카탈로그 캠페인의 경우 한 카탈로그에만 데이터가 있다면, 제안된 선택 항목에 의존하는 캠페인은 해당 카탈로그에서만 완전히 작동합니다.

\##

***

## 테스트, 샌드박스 및 라이브 배포

**샌드박스 / 테스트 환경**

* 캠페인 **타겟팅** 단계에서 UI 제안을 검증합니다.

**샘플 테스트 케이스**

| 테스트        | 단계                          | 예상 결과                                |
| ---------- | --------------------------- | ------------------------------------ |
| UI 제안 표시됨  | 샌드박스 캠페인에 상품 추가; **타겟팅** 열기 | 상품별로 제안된 키워드가 나타남                    |
| 서빙 규칙      | 상품 하위 집합에 연결된 제안 키워드 선택     | 해당 검색어에는 연결된 상품만 노출 자격이 있음           |
| 다중 카탈로그 범위 | 네임스페이스의 카탈로그 전체에서 UI 확인 반복  | 데이터가 있는 모든 카탈로그에 제안이 존재함(또는 문서화된 범위) |

라이브 배포 체크리스트

* [ ] 오류 없이 TSV가 수집됨(파일 경로를 사용하는 경우) 또는 AI 파이프라인 승인 완료(베타를 사용하는 경우)
* [ ] 대표 상품에 대해 샌드박스 UI에서 제안된 키워드가 표시됨
* [ ] 다중 카탈로그 네임스페이스의 모든 카탈로그에 범위가 적용됨(또는 문서화된 범위)
* [ ] 운영 환경 활성화 전 또는 활성화 시점에 광고주 전달 사항 송부됨
* [ ] 파트너 API가 운영 환경에서 예상된 행을 반환함(표본 점검)

***

## 문제 해결 및 FAQ

**문제:** UI에 제안이 전혀 나타나지 않습니다.\
**가능한 원인:** 수집이 활성화되지 않았거나, 카탈로그가 잘못되었거나, 지면이 구성되지 않았습니다.\
해결 방법:\*\* 다음 담당자에게 확인하세요: Epsilon GCS 수집 또는 AI 파이프라인이 활성화되어 있는지 확인하고, 다음 항목에 대한 지면 매핑을 확인하세요: `search_term_type`.

**하나의 TSV를 여러 지면 유형에 사용할 수 있나요?**\
네. 반복하세요 `product_code` 다른 항목을 포함한 여러 줄에 `search_term_type` 값. 담당 기술 계정 관리자(Technical Account Manager)가 지면별로 노출될 유형을 구성합니다.

**한 네임스페이스에 여러 카탈로그가 있는 경우는 어떻게 되나요?**\
가능한 경우 모든 카탈로그에 추천 키워드를 적용하세요. 추천 선택 항목에 의존하는 캠페인은 데이터가 있는 카탈로그에서만 완전히 작동합니다.

**지원팀에 문의할 때 포함할 사항:**

* 네임스페이스 및 카탈로그 ID
* 샘플 `product_code` 및 예상 결과 `search_term`

<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/feature-integrations/suggested-keywords.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.