パートナーAPI
ガイド

検索プレースメントを使用して商品広告を生成

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

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

前提条件

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

商品カタログを追加する

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

キャンペーンを作成し、検索用語を設定する

キャンペーンを作成し、検索用語を設定していることを確認します。詳細については、「手順4b：検索用語を設定する」をご参照ください。

商品広告のターゲットとする（含める、除外する）検索用語を定義します。広告には、完全一致、フレーズ一致、除外検索用語を指定できます。

  • 完全一致:
    • キーワードと完全に一致する検索用語を絞り込みます。
    • 例：キーワードが「青いランニングシューズ」の場合、広告は、他の単語を入力せずに「青いランニングシューズ」と正確にその順序で入力したユーザーにのみ表示されます。
  • フレーズ一致：
    • キーワードと完全に一致する検索用語を絞り込みます。
    • フレーズの前または後に追加の単語が含まれる検索に対して広告を表示できます。
    • 例：キーワードが「青いランニングシューズ」の場合、広告は、他の単語を入力せずに「青いランニングシューズ」と正確にその順序で入力したユーザーにのみ表示されます。
    • 詳細については、フレーズ一致検索用語を参照してください。
  • 除外検索用語
    • キャンペーンから特定の単語やフレーズを除外します。
    • 関連性のない検索に広告が表示されないようにします。
    • 例：新車広告に「中古」を除外検索用語として追加すると、中古車を探しているユーザーに広告が表示されなくなります。

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オブジェクトである必要があります。

対象type説明
customerId文字列、必須顧客用の一意の識別子。これは小売業者から提供されます。
sessionId文字列、必須セッション用の一意の識別子。これは帰属表示に必要であり、小売業者によって提供されます。
dtmcookieid文字列、必須dtmCookieIdは、貴社のEpsilonのファーストパーティCookieから取得されます。これにより、ユーザーインタラクションの正確な追跡と帰属が可能になります。
placement文字列、必須広告が表示されるコンテキスト（例：「検索」）。
catalogId文字列、必須商品のフィルタリング元となる商品カタログ用の一意の識別子。catalogIDは、EpsilonのRetail Media UIまたは小売業者から取得できます。
maxNumberOfAds整数、必須表示する広告の最大数。
searchTerm文字列、検索プレースメントに必須カタログ内で検索する用語。
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.

リクエスト例

このリクエストは、検索用語chocolateに関連する最大3つの広告を生成するために使用されます。これらの広告は、特定の顧客（customerId: "wertg5432a"）とセッション（sessionId: "ec9-4e07-881d-3e9"）の検索結果に掲載されます。この広告は、カタログIDが「628dbe95-2ec9-4e07-881d-3e9f92ab2e0b」で識別されるカタログから生成され、追加のフィルタリングオプションが指定されています（フィルターモード：「AndOr」）。

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": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "options": {
   						 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3    
}

レスポンス例

📘

商品広告のレスポンスを受信すると、通常、レスポンスにはこの例のGTINなどの商品コードが含まれます。小売業者は、広告レスポンスに記載されている商品コードを使用して、商品の表示に必要なメタデータを検索する必要があります。

この例では、"gtin": "024100191345"が商品コードです。小売業者は、このGTINを使用して、特定のスポンサー商品を識別し、表示します。

{
    "ads": [
        {
            "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
            "gtin": "7733636",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400902957Z",
            "position": 1
        },
        {
            "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4",
            "gtin": "7733628",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        },
        {
            "id": "display_xNeShqidaMuEqiJ0zNdt-Gzygjs3NzE0MTA3",
            "gtin": "7714107",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400912929Z",
            "position": 3
        },
        {
            "id": "display_3rGiryPskhQusmsf43nghbQwnqo3NzMzNjU3",
            "gtin": "7733657",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400917769Z",
            "position": 4
        }
    ],
    "banners": [],
    "products": [],
}

次の手順