> 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/ja/feature-integrations/suggested-keywords.md).
# 推奨キーワード
**推奨キーワード**は、カタログ内の**検索用語**と**商品コード**を結び付けます。広告主がキャンペーンを作成する際、追加した商品に対する**ターゲティング**（検索キーワードの選択）時にそれらの用語が表示されます。広告主はカスタムキーワードを文字入力するだけでなく、推奨キーワードから選択できるため、サイトの検索インデックス作成方法や、キャンペーンでSKUをクエリにマッピングさせる方法との整合性が向上します。
**推奨キーワードの提供方法は2つあります:**
1. **Epsilon AIが生成したキーワード** — Epsilon AIがあなたに代わって商品とキーワードのペアを生成、分類、読み込みます。このパスが唯一のソースである場合、それらの推奨事項用に個別のキーワードファイルを管理する**必要はありません**。生成には、商品およびカタログのコンテキスト、ショッパーの検索行動、および**リテーラーのビジネスルール**（ブランドコンクエストやその他のプログラム制約など）に沿ったシグナルが使用されます。
2. **リテーラー管理のTSVフィード** — 各 `product_code` を1つ以上の `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には、どの商品がどの推奨キーワードにマッピングされているかが表示されます:
広告主が選択した**カスタム**検索用語は、通常、掲載枠ルールに従ってキャンペーン商品全体に適用されます。**推奨**された選択項目は、\*\*リテーラー / Epsilonのマッピングを使用して対象資格を制限します。
## 前提条件
開始する前にこのチェックリストを使用してください。
* [ ] カタログ同期を含め、**リテーラー**が Epsilon Retail Mediaにオンボーディング済み（または進行中）であること。
* [ ] キーワードを検証するキャンペーンUIおよびAPIへの**サンドボックスアクセス**（プログラムで利用可能な場合）。
* [ ] **TSV配信の場合:** Epsilonによって**プロビジョニングされた**GCSバケット（またはパス）、およびチームがオブジェクトのアップロードに使用できる認証情報（方法は Epsilonと確認済み — 多くの場合、サービスアカウントキーまたは統合アクセス）。なお、スコープの検討のみを行っている場合、キーワードを提供するのであれば、これは有効化プロセスの一部として処理されます。
* [ ] ファイルのアップロード、APIチェックの実行、およびの調整ができる**技術担当者** Epsilon 取り込みスケジュールと切替時。
* [ ] **リリースに関する注意事項:** サジェストに対するキーワード単位の商品適格性には、プラットフォームが必要です（上記の配信ルールを参照）。
***
## 連携フローの概要
1. 以下について確認します： Epsilon キーワードの提供方法：Epsilon 生成\*\*、**TSVファイル**、または**両方**。
2. ファイルを提供する場合は、によって割り当てられたGCSバケットにアップロードします Epsilon.
3. Epsilon 機能を有効にし、（ファイルの場合）ファイルを撮り込みます。**AI**キーワードの場合、 Epsilon ルール、オプションのオーバーレイと置換の比較、およびステージング検証について調整します。
4. データはプラットフォームに**サジェストキーワード**として格納されます。
5. 広告主への公開前に、UI上で直接サンドボックス内で**検証**します。
6. 本番環境で**本番公開**し、サジェストキーワードが利用可能になったことを広告主チームに伝えます。
***
## ステップ別実装ガイド
### ステップ 1: 以下の提供モデルを確認します： Epsilon
目的\
**AIのみ**でニーズを満たせる場合にファイルパイプラインの構築を回避する、あるいは以下が Epsilon リストをオーバーレイ/置換してくれる場合に作業の重複を回避する。
**必要な対応**
* 判定: **AIのみ**、**TSVのみ**、または**両方**。
* 既存の推奨キーワードデータに対する**オーバーレイ**と**置換**のどちらにするか確認する。
* どの**配置**が存在するか確認する（`ORGANIC` のみ、または `CROSS_SELL` / `SUBSTITUTE`).
***
### ステップ2: AI推奨キーワードの有効化
**目的**\
TSVをメンテナンスすること**なく**、 Epsilon生成およびルールフィルタリングされたキーワードをプラットフォームに取り込む。
**必要な対応**
1. **Engage Epsilonとの連携** — 具体的な**ビジネスルール**（ブランドコンクエストなど）を提供し、すでに推奨キーワードを同期している場合は新規データを既存リストにどう関連付けるかを指定する（**オーバーレイ**か**置換**か）。
2. サンドボックスでのテスト\*\* — Epsilon と協力して、**ステージング/サンドボックス**でキーワードをロードまたは確認する。キャンペーンUIで**ターゲティング**の予行演習を行う: 商品を選択し、推奨フレーズが正しく表示されることを確認する。
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).
* 使いやすさのため、**1商品あたり\~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` カタログ同期で使用されている |
| 1 SKUあたりの行数が多すぎる | 最も価値の高い語句に絞り込む |
***
### ステップ 3: UIで提案内容を確認する
**目的**\
本番公開前に土壇場のマッピング問題を検出します。
**必要な手順**
* **サンドボックス**でキャンペーンを作成または編集し、提案キーワードをサポートする配信枠を選択し、商品を追加して、**ターゲティング** / キーワード選択を開きます。
* 商品ごとの提案フレーズを確認し、**カスタム**と**提案**の動作が予期した通りであるか確認します（**概要**の \*\*配信ルール を参照）。
* **提案**された選択によって、対象となる商品がフィードまたはAIパイプラインでリンクされているものに制限されることを確認します。
**検証**
* サンドボックスUIで、ファイルまたはAIパイプラインでキーワードにリンクされている商品に対して提案キーワードが表示されます。
* 提案が配信枠およびカタログの想定に一致していること。
**よくあるエラー**
| エラー | 修正方法 |
| ------------------- | --------------------------------------- |
| 1つのカタログにしか提案が表示されない | 他のカタログをバックフィルするか、キャンペーンのカタログ範囲を調整する |
| 誤った配信枠タイプが表示されている | TAMが配信枠 ↔ をレビューする `search_term_type` 設定 |
***
## データモデルとフィールド定義
### TSV（リテールメディアファイル）
| フィールド | タイプ | 必修 | 説明 | 許容される値 |
| ------------------ | ------- | -- | --------------------------------------------- | ------------------------------------------------------------------------- |
| `product_code` | string | はい | リテールメディアの商品識別子。カタログと同じ `gtin` / `item` 該当する場合 | 空以外。同期されたカタログ内に存在する必要があります |
| `search_term` | string | はい | SKUに対して提案されるキーワードまたはフレーズ | UTF-8テキスト。制御文字を避けてください |
| `search_term_rank` | integer | No | 相対的な関連性。**1**が最高です | 正の整数。値が小さいほど＝優先度が高くなります |
| `search_term_type` | string | No | 行を\*\* placement \*\*の種類にマッピングします | `ORGANIC`, `CROSS_SELL`, `SUBSTITUTE`。デフォルトは以下として扱われます： `ORGANIC` 省略された場合 |
| (改行コード) | — | — | ファイル形式 | LF\*\*、ファイルエンコーディング \*\*UTF-8 |
### Placementの種類と `search_term_type`
`search_term_type` 配置タイプと一致します：**ORGANIC**、**CROSS\_SELL**、および **SUBSTITUTE**。
ほとんどのリテールメディアプログラムでは、標準の検索結果広告に単一の **organic search** 配置を使用します。**CROSS\_SELL** と **SUBSTITUTE** は、検索ページ（または関連インベントリ）上の**個別の placement** であり、配信意図が異なります。これらは同じオーガニックオークション内の単なる追加列ではありません。テクニカルアカウントマネージャーが、お客様のネームスペースにどの配置が存在するかを確認します。
**配置タイプの違い**
* **Organic** — 商品に対する買い物客の検索意図にマッチした広告（例：「コーラ」でのコーラ商品）。
* **Cross-sell** — 補完的な意図（例：「コーラ」でのピザ）。
* **Substitute** — 類似商品の意図（例：「コーラ」での別のコーラバリエーション）。
**配置タイプごとに1つのフィード**を同期するか、**1つのファイルでタイプを組み合わせる**ことができます（異なる `product_code` で繰り返し `search_term_type`）。テクニカルアカウントマネージャーが配置を設定し、面ごとに正しい提案タイプが表示されるようにします。提案されたキーワードは**配置ごとに表示または非表示**にすることができます。
1つの商品に対して組み合わされたタイプ：
| 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` は**追加の placement** に対応しており、同じオーガニック枠内の「追加列」ではありません。運用する placement についてはテクニカルアカウントマネージャーにご確認ください。
### 複数のカタログ
可能であれば、ネームスペース内の**すべて**のカタログで提案されたキーワードを実装してください（フィード、AI生成、またはその両方のいずれからであっても）。これにより、1つのカタログに提案があり、他のカタログにはない場合のブランドの混乱を軽減します。
複数カタログのキャンペーンで、1つのカタログのみにデータがある場合、提案された選択に依存するキャンペーンは、そのカタログでのみ完全に動作します。
\##
***
## テスト、サンドボックス、および本番移行
**サンドボックス / テスト環境**
* キャンペーンの **Targeting** ステップでUIの提案を検証します。
**テストケースのサンプル**
| テスト | 手順 | 期待される結果 |
| ------------ | ---------------------------------------- | --------------------------------------------- |
| UIの提案が表示される | サンドボックスキャンペーンで商品を追加し、**Targeting** を開きます | 商品ごとに提案されたキーワードが表示されます |
| 配信ルール | 商品のサブセットにリンクされている提案されたキーワードを選択します | リンクされた商品のみがその用語の対象となります |
| 複数カタログのカバレッジ | ネームスペース内のカタログ全体でUIチェックを繰り返します | データが存在するすべてのカタログに提案が表示されます（またはスコープが文書化されています） |
本番移行チェックリスト
* [ ] TSVがエラーなしで取り込まれた（ファイルパスを使用している場合）か、AIパイプラインが承認された（ベータ版を使用している場合）
* [ ] 代表的な商品について、サンドボックスUIで提案されたキーワードが表示される
* [ ] 複数カタログのネームスペースにおいて、すべてのカタログにカバレッジがある（またはスコープが文書化されている）
* [ ] 本番有効化の前または有効化時に広告主へ連絡が送信された
* [ ] Partner APIが本番環境で期待される行を返す（スポットチェック）
***
## トラブルシューティングとFAQ
**問題:** UIに提案が表示されない。\
**考えられる原因:** 取り込みが有効になっていない、カタログが間違っている、または placement が設定されていない。\
解決策:\*\* 以下で確認してください： Epsilon そのGCS取り込みまたはAIパイプラインがアクティブであること。配置のマッピングを確認してください: `search_term_type`。
**複数の配置タイプに1つのTSVを使用できますか？**\
はい。繰り返し `product_code` を異なる `search_term_type` 値で複数行に記述します。テクニカルアカウントマネージャーが、配置ごとにどのタイプを表示するかを設定します。
**1つのネームスペースに複数のカタログがある場合はどうなりますか？**\
可能であれば、すべてのカタログに推奨キーワードを実装してください。推奨された選択に依存するキャンペーンは、データが存在するカタログでのみ完全に動作します。
**サポートにお問い合わせの際は、以下を含めてください:**
* ネームスペースとカタログID
* サンプル `product_code` および期待される結果 `search_term`
---
# 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/ja/feature-integrations/suggested-keywords.md?ask=&goal=
```
`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.