パートナーAPI
ガイド

カテゴリプレースメントを使用して商品広告を生成

本ドキュメントでは、指定したカテゴリに基づいて商品広告を生成する方法について、包括的なガイドを提供します。各APIリクエストには、次のようなコンテキストに関する詳細が含まれている必要があります。

  • customerId
  • sessionId
  • プレースメント
  • catalogId
  • productFilters
  • 表示する広告の最大数

前提条件

検索プレースメント用の商品広告をリクエストする前に、以下の手順を完了する必要があります。

商品カタログを追加する

商品がカタログに追加され、Epsilon Retail Mediaプラットフォームと同期されていることを確認します。

キャンペーンを作成し、カテゴリを設定する

キャンペーンを作成し、カテゴリを設定していることを確認します。詳細については、「手順4：ターゲット基準を設定する」をご参照ください。

APIキーとベースURLを取得する

  1. 有効なAPIキーが必要になります。APIキーを取得するには、次の手順を実行します。

    1. EpsilonのRetail Mediaチームアカウントにログインします。

    2. ページの右上に移動し、ドロップダウンメニューをクリックします。

    3. ドロップダウンメニューから[統合設定]を選択します。

    4. APIキータブをクリックします。シークレットAPIキーは最初は非表示になっています。表示するには、[表示]ボタンをクリックします。表示されたら、シークレットAPIキーをコピーします。このキーをAPI呼び出しを行うために使用します。

  2. APIエンドポイントのベースURLが必要になります。たとえば、https://staging-test.citrusad.com/v1/ads/generate HTTP/1.1. ベースURLについては、テクニカルアカウントマネージャーに確認してください。

カテゴリプレースメントの広告を生成する

商品広告を生成するには、以下の手順を実行してください。

HTTPリクエスト

エンドポイント：/v1/ads/generate

メソッド：POST

ヘッダー：

  • accept: application/json
  • コンテンツタイプ：application / json
  • 認証：Basic <API_KEY>

リクエスト指標

リクエスト本文は、次のフィールドを含むJSONオブジェクトである必要があります。カテゴリプレースメントを指定するには、リクエスト本文にproductFiltersを含める必要があります。

対象type説明
customerId文字列、必須顧客用の一意の識別子。これは小売業者から提供されます。
sessionId文字列、必須セッション用の一意の識別子。これは帰属表示に必要であり、小売業者によって提供されます。
placement文字列、必須広告が表示されるコンテキスト（例：「カテゴリ」）。カテゴリのプレースメントを「カテゴリ」に設定します。
catalogId文字列、必須商品のフィルタリング元となる商品カタログ用の一意の識別子。catalogIDは、EpsilonのRetail Media UIまたは小売業者から取得できます。
productFilters配列、必須カテゴリフィルターを含む配列。
maxNumberOfAds整数、必須表示する広告の最大数。
optionsオブジェクト、オプションAdditional options such as filtering modes AndOr. If specified, the system will use both "AND" and "OR" conditions to narrow down the search results

リクエスト例

JSONリクエストは、「Cupboard/Snacks」カテゴリに関連する広告のカテゴリプレースメントを指定するために使用されます。顧客ID、セッションID、カタログID、フィルタリングオプションが含まれ、広告の最大数は3に設定されます。

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

クロスセルカテゴリプレースメントの広告を生成する

クロスセルカテゴリプレースメントは通常のカテゴリープレースメントと似ていますが、特にクロスセル商品の広告に対象を絞って使用されます。クロスセルのシナリオでは、ユーザーが現在閲覧しているカテゴリに基づいて補完的な商品を推奨することを目的にしています。

広告を生成するカテゴリを正確に指定する必要があります。このカテゴリは通常、ユーザーが現在閲覧しているページに表示されています。

リクエスト例

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "category-cross-sell",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

オーガニックとクロスセルのカテゴリターゲティングを結合する

オーガニック広告（表示されているカテゴリに関連する広告）とクロスセル広告（関連するカテゴリや商品の広告）を1つの広告プレースメントにまとめることを目的とする場合は、この結合を自分で行う必要があります。これには、両方のタイプの広告を結合して一緒に表示するロジックを記述することが含まれます。

ベストプラクティス：

  • 最初はオーガニック広告：現在のカテゴリに関連する広告（オーガニック広告）を最初に表示します。
  • 2番目にクロスセル広告：次に、オーガニック広告の後に関連カテゴリまたは商品の広告（クロスセル広告）を表示します。

カテゴリベースの広告ターゲティングのベストプラクティス

ユーザーがさまざまなカテゴリ間を移動する場合、現在表示されているカテゴリを反映するようにAPI呼び出しを更新することが重要です。そうすることで、表示される広告がユーザーの閲覧しているコンテキストに関連したものであり続けることが保証されます。

広告リクエストで最も具体的な（最下位の）カテゴリをEpsilon Retail Mediaプラットフォームに送信することをお勧めします。最も深いカテゴリレベルをターゲットにすると、ユーザーにとってより関連性が高く、正確にターゲットを絞った広告が提供されます。

シナリオ例

ユーザーは一般的なカテゴリから閲覧を開始し、より具体的なサブカテゴリに移動します。

最初のAPI呼び出し

ユーザーが「ホーム」カテゴリを閲覧している場合：

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Home"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

更新済みのAPI呼び出し

ユーザーが [ホーム > 家具]とサブカテゴリに移動すると、次のようになります。

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Home/Furniture"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

最終的なAPI呼び出し

ユーザーがさらに[ホーム > 家具 > 椅子]とサブカテゴリを移動すると、次のようになります。

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9",
    "dtmCookieId": "AAAF8xLBTA968AB6TOthAAAAAAE",
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Home/Furniture/Chairs"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

ユーザーが閲覧している最も具体的なカテゴリを反映するようにAPI呼び出しを更新することで、配信された広告の関連性が高いことを確認できます。複数のカテゴリレベル（L1 + L2 + L3）にわたって連鎖したリクエストを指定する代わりに、最も深いレベル（L3）のカテゴリレベルを指定することが推奨されます。

次の手順

更新： 19日前