パートナーAPI
APIリファレンス

商品広告を依頼する

広告を依頼する

すべての商品広告リクエストで、コンテキストのplacement、catalogId、および顧客に表示したいmaxNumberOfAdsが必要です。また、リクエストにはコンテキストのcustomerIdおよびsessionIdを含める必要があります。

検索プレースメント

検索プレースメントは概して最もリクエストが簡単です。ここでは、以下の例のように、リクエストでsearchTermを指定する必要があります。

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    
}

カテゴリプレースメント

カテゴリプレースメントでは、リクエストでproductFiltersを指定する必要があります。以下は、カテゴリフィルタの送信先の例です。

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
}

追加のカテゴリが閲覧されるようになったら、それに応じてAPIコールを更新する必要があります。

📘

ベストプラクティス

顧客がより詳細なカテゴリをブラウズする際のために、最低レベルのカテゴリをEpsilon Retail Mediaへの広告リクエストに送信することをお勧めします。

L1 + L2 + L3の3レベルでチェーンリクエストを指定するのではなく、L3カテゴリのみを指定します。

クロスセルカテゴリプレースメント

クロスセルカテゴリプレースメントには、カテゴリプレースメントと非常によく似たリクエストがあります。広告をリクエストするカテゴリを正しく指定する必要があります。通常は、このページが開きます。リクエストのproductFiltersでカテゴリを指定してください。以下は、カテゴリフィルタの送信先の例です。

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-cross-sell",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

追加のカテゴリが閲覧されるようになったら、それに応じてAPIコールを更新する必要があります。

📘

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

オーガニックカテゴリとクロスセルカテゴリの広告リクエストを1つのプレースメントにマージする場合は、マージと配信のロジックを顧客に実装する必要があります。これはインテグレータの担当ですが、Epsilon Retail Mediaにもご相談いただけます。

一般的に、オーガニックプレースメントの後に、オーガニックカテゴリの広告と、位置およびカテゴリのクロスセル広告を表示することをお勧めします。

ブロードマッチプレースメント

ホームやチェックアウトページなどのブロードプレースメントでは、リクエストでproductFiltersを指定する必要はありません。小売業者が指定したいフィルタ（提供中、新規など）は、productFiltersで指定することで、要件に当てはまる広告のみが配信されるようになります。

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

拡張機能をリクエストする

検索、カテゴリ、およびブロードマッチのプレースメントでは、ユーザーエクスペリエンスを向上させるために、以下の機能拡張の導入を検討されることをお勧めします。

リクエストのページネーション

商品広告を生成する際にmemoryTokenが届くので、これを送信すれば、すでに配信済みの広告を除外するよう要求することができます。このmemoryTokenを以降の広告リクエストで送信すると、Epsilon Retail Mediaは同じコンテキストですでに配信された広告を広告レスポンスから除外します。

Please review Pagination prior to implementing.

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",
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0=",
    "options": {
                         "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3    
}

検索のフィルタリング

顧客が検索をフィルタリングする場合、コンテキストを拡張してproductFiltersを指定できます。以下は、顧客がカテゴリを「食器棚」、食事制限を「グルテンフリー」でフィルタリングする場合の例です。この原則は、どのカテゴリにも、ブロードマッチのプレースメントにも当てはまります。

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",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

位置情報による絞り込み

カタログでロケーションフィルタを同期している場合、コンテキストを拡張してproductFiltersで顧客のストアロケーションを提供できます。

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",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "maxNumberOfAds": 3
}

商品広告レスポンス

すべての商品広告レスポンスは、同じJSON形式に従っています。商品広告は、以下の例のように、ads配列で返されます。

{
    "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": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

idフィールドは、インプレッションおよびクリックレポートで使用されている広告IDです。positionフィールドは、Epsilon Retail Mediaペイロードの位置を定義します。各ストリングについての詳細は、リファレンスをご覧ください。

📘

固定テナントプレースメントが正しく表示されるよう、positionフィールドを読み、尊重する必要があります。

マーケットプレイス出品者ID

マーケットプレイス出品者をオンボーディングしている場合は、広告ごとに追加のsellerIdがレスポンスに表示される場合があります。これは、提供されているキャンペーンを所有するチームがUIで出品者IDを設定している場合にのみ表示されます。以下の例は、sellerIdのある広告とない広告を示しています。

{
    "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",
            "sellerId": "2834-ascre-2wcr4",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}
📘

If you’re unsure about the strings in this section, please visit the Product ad reference page.

デジタルサービス法

Epsilon Retail Media assists retailers in meeting their European Union (EU) Digital Services Act (DSA) obligations. The DSA establishes a unified set of rules across the EU, targeting the regulation of online content, transparent advertising, and disinformation. For more information, see Digital Services Act.

広告リクエストの例

{
    "placement": "search-only",
    "catalogId": "zesty-fruits-catalog",
    "searchTerm": "lime",
    "maxNumberOfAds": 5,
    "options": {
   			    "filterMode": "AndOr",
    			"includeAdvertiserInfo": true,
     },
}

広告レスポンスの例

{
  "ads": [
    {
      "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
      "gtin": "7733636",
      "discount": {
        "amount": 0,
        "minPrice": 0,
        "maxPerCustomer": 0
      },
      "expiry": "2021-05-12T04:17:50.400902957Z",
      "position": 1,
      "metadata": {
        "advertiserInfo": {
       "advertiser": "Bob's advertising agency",
          "onBehalfOf": "Brand company inc",
        }
      }
    },
    ....
  ],
  "banners": [],
  "products": [],
  "memoryToken": "85ykKVv-………"
}

更新： 2か月前

更新： 2か月前