広告を依頼する

商品広告とバナーが同じエンドポイントで生成されるため、プレースメントのコンテキストが同じ場合は、バナーと同じリクエストで商品広告をリクエストできます。

受け取ることができる商品広告の数は、 maxNumberOfAds パラメータを定義することにより設定されます。受信するバナー広告の数は、 maxNumberOfAds プロパティ（一意のSlotIdごと）で設定可能です。

すべてのバナー広告リクエストには、リクエストしている広告の contentStandardId と bannerSlots が必要です。さらに、バナー呼び出しにはコンテキストの customerId、sessionId、placement、および catalogId.

📘
いくつかの変更があります。
CitrusAdからバナー広告をリクエストする方法が変わりました。すでに統合されている場合は、 bannerSlotIdsというプロパティでリクエストできます。今後はこちらではなく、新しい機能 bannerSlots を使用します。 bannerSlotIds プロパティで広告をリクエストする方法については、このページの一番下までスクロールしてください。
この bannerSlots 機能は2022年9月にリリースされました。

検索プレースメント

検索プレースメントは概して最もリクエストが簡単です。以下の例のように、リクエストで 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", 
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "options": {
   						 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ],           
    "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", 
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ],            
    "maxNumberOfAds": 3
}

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

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

クロスセルカテゴリプレースメントには、カテゴリプレースメントと非常によく似たリクエストがあります。広告をリクエストするカテゴリを正しく指定する必要があります。通常は、このページが開きます。リクエストの 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", 
    "placement": "category-cross-sell",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ],            
    "maxNumberOfAds": 3
}

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

📘
オーガニックとクロスセルのカテゴリターゲティングをマージする場合
オーガニックカテゴリとクロスセルカテゴリの広告リクエストを1つのプレースメントにマージする場合は、マージと配信のロジックを顧客に実装する必要があります。これはインテグレータの担当ですが、CitrusAdにもご相談いただけます。
一般的に、オーガニックプレースメントの後に、オーガニックカテゴリの広告と、位置およびカテゴリのクロスセル広告を表示することをお勧めします。

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

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

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": "home",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 []
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ], 
    "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", 
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ], 
    "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", 
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlots": [
           {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    },
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 2
    }
    ], 
    "maxNumberOfAds": 3
}

bannerSlotIdsパラメータを使用する（レガシー）

すでに統合されている場合は、 bannerSlotIds で広告をリクエストしている可能性があります（ bannerSlotsではなく）。これは文字列の配列で、広告を必要とするバナースロットをここで指定します。今回の改善にて、同じバナースロットで複数の広告をリクエストできるようになりました。これを利用する場合は、統合を上記で説明したメソッド bannerSlots に拡張する必要があります。

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": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
     	 ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlotIds": [
        "<SLOT_ID>","<SLOT_ID>"
    ], 
    "maxNumberOfAds": 3
}

バナー広告レスポンス

すべてのレスポンスは同じJSON形式に従っています。製品広告をリクエストする場合、 ads 配列は、以下の例に従って設定されます。バナーは banners 配列に入るため、広告のあるバナースロットのコンテンツのみが返されます。

{
    "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
        }
    ],
    "banners": [
				{
            "id": "banner_XeemTeq59HapGSp4vccOYfBq_yvc3zMzNjM2",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "imageUrl": "https://cdn.flavedo.io/s/-oW-C3cEViSSO2krWkwOBUXOhvUdhHOySx-YQLGZ1lA=",
            "linkUrl": "https://www.retailer.com/link",
            "altText": "Your local ice cream",
            "text": "",
            "gtins": [
                "7733628",
                "7714107",
                "7163379",
                "7733636",
                "7733657"
            ],
            "expiry": "2021-05-17T01:49:17.75503253Z",
            "tags": {},
            "position": 1
        },
				{
            "id": "banner_A0KA6mNmFs6sZPb_FvwWe5k6x6c3NzMzNjM3",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "imageUrl": "https://cdn.flavedo.io/s/-oW-dfsgrerWkwOBUXOhvUdhHOySx-YQLreGZ1lw=",
            "linkUrl": "https://www.retailer.com/link",
            "altText": "Advertisement for pet food.",
            "text": "",
            "gtins": [
                "16309011",
                "57312011",
                "65250011"
            ],
            "expiry": "2021-05-17T01:49:17.75503253Z",
            "tags": {},
            "position": 2
        }
				],
    "products": [],
     "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

先ほどの id フィールドは、インプレッションおよびクリックレポートで使用されている広告IDです。各ストリングについての詳細は、リファレンスをご覧ください。

マーケットプレイス出品者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": [
				{
            "id": "banner_XeemTeq59HapGSp4vccOYfBq_yvc3zMzNjM2",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "sellerId": "43d-w4-2wcr4",
            "imageUrl": "https://cdn.flavedo.io/s/-oW-C3cEViSSO2krWkwOBUXOhvUdhHOySx-YQLGZ1lA=",
            "linkUrl": "https://www.retailer.com/link",
            "altText": "Your local ice cream",
            "text": "",
            "gtins": [
                "7733628",
                "7714107",
                "7163379",
                "7733636",
                "7733657"
            ],
            "expiry": "2021-05-17T01:49:17.75503253Z",
            "tags": {},
            "position": 1
        },
				{
            "id": "banner_A0KA6mNmFs6sZPb_FvwWe5k6x6c3NzMzNjM3",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "imageUrl": "https://cdn.flavedo.io/s/-oW-dfsgrerWkwOBUXOhvUdhHOySx-YQLreGZ1lw=",
            "linkUrl": "https://www.retailer.com/link",
            "altText": "Advertisement for pet food.",
            "text": "",
            "gtins": [
                "16309011",
                "57312011",
                "65250011"
            ],
            "expiry": "2021-05-17T01:49:17.75503253Z",
            "tags": {},
            "position": 2
        }
				],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

📘
こちらのセクションの文字列について不明な点がある場合は、リファレンスページをご覧ください。

サードパーティのトラッキングタグ

バナー広告の場合、CitrusAdでは、サードパーティのトラッキングタグを小売業者に渡すことができます。これらのタグは、信頼して託したサードパーティによるパフォーマンスを確認するために使用されます。

CitrusAdは、以下のトラッキングタグをサポートしています。

DoubleVerify
DCMクリック
DCMインプレッション
IAS

キャンペーンにトラッキングタグが設定されている場合、そのフィールドは tags オブジェクトの関連フィールドとして表示されます。キャンペーンにタグが設定されていない場合は、 tags オブジェクトは空のままであることに注意してください。

{
    "ads": [],
    "banners": [
				{
            "id": "banner_XeemTeq59HapGSp4vccOYfBq_yvc3zMzNjM2",
            "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
            "slotId": "<SLOT_ID>",
            "imageUrl": "https://cdn.flavedo.io/s/-oW-C3cEViSSO2krWkwOBUXOhvUdhHOySx-YQLGZ1lA=",
            "linkUrl": "https://www.retailer.com/link",
            "altText": "Your local ice cream",
            "text": "",
            "gtins": [
                "7733628",
                "7714107",
                "7163379",
                "7733636",
                "7733657"
            ],
            "expiry": "2021-05-17T01:49:17.75503253Z",
            "tags": {
                "dv": "<script src=\"https://cdn.doubleverify.com/dvtp_src.js?ctx=919421&cmp=1074060503&sid=1073907024&plc=1075810393&adsrv=115&btreg=&btadsrv=&crt=&tagtype=&dvtagver=6.1.src\" type=\"text/javascript\"></script>",
                "dcmClick": "<script ..../>",
                "dcmImpression": "<script.... />",
                "ias": "<script.... />"            }
        }
				],
    "products": [],
     "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

CitrusAdはサーバー間の統合であるため、サードパーティのトラッキングタグでは、小売業者による追加開発が必要になります。この機能を利用する場合は、テクニカルアカウントマネージャーにお問い合わせください。

バナー広告を依頼する

広告を依頼する

📘
いくつかの変更があります。

検索プレースメント

カテゴリプレースメント

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

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

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

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

検索のフィルタリング

位置情報による絞り込み

bannerSlotIdsパラメータを使用する（レガシー）

バナー広告レスポンス

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

📘

サードパーティのトラッキングタグ

広告を依頼する

📘いくつかの変更があります。

検索プレースメント

カテゴリプレースメント

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

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

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

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

検索のフィルタリング

位置情報による絞り込み

bannerSlotIdsパラメータを使用する（レガシー）

バナー広告レスポンス

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

📘

サードパーティのトラッキングタグ

📘
いくつかの変更があります。

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