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

カタログと商品

CitrusAdと連携するためには、少なくとも1つの商品カタログが必要です。

カタログとは？

カタログとは、商品とその属性をグループ化したもので、最も一般的には、インテグレータのサイトの全商品を1つのカタログにまとめるために使用されます。

カタログは、キャンペーン作成時に広告主が選択します。そのキャンペーンは、選択した商品のカタログ内でしか実行されません。すべての製品をインテグレータの単一のカタログにグループ化して、広告主が簡単に選択できるようにするのが一般的な方法です。

カタログを複数作成すると、異なる小売店や国別に対象の商品を分類し、キャンペーンのターゲティングに利用できます。

📘

複数のカタログを作成する場合は、テクニカルアカウントマネージャーに連絡して、ベストプラクティスについて相談してください。そこで、ターゲティングを実施するためのより良い方法が特定される場合があります。

🚧

ネットワークネームスペースに統合する場合、単一のカタログを作成する必要があります。

商品とは？

商品とは、インテグレータのサイトにある個々のGTINです。CitrusAdと同期された商品は、個々の識別値と属性と同期されます。商品には、現在の製品カタログの各GTIN/SKUを表示する必要があります。

商品は、キャンペーン作成時に広告主が選択します。この場合、広告主が選択したカタログに関連する商品のみが選択可能なものとして表示されます。商品を使用して、2つ以上の商品GTINを表すことは避けてください。同じ商品のバリエーションは、別の商品としてリストする必要があります。例えば、同じ飲料の200ml、600ml、2Lのバリエーションは、既存のインテグレータのベストプラクティスに合わせ、CitrusAdでは3種類の商品とみなされます。

商品フィルタの説明

商品フィルタは、 imageUrl や名前などのプロパティを含むほか、主に広告生成のために使用されます。CitrusAdに広告をリクエストする際は、関連するページ情報を含むデータを送信し、各ページに関連する広告が提供されるようにします。

フィルタの構成はインテグレータ次第ですが、最も重要なことは、これらの商品フィルタが広告生成コンテキストで送信されることです。商品フィルタは、広告生成で要求されるものと正確に一致する必要があります。

次を含むコンテキストの例： 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"
                             },
    "maxNumberOfAds": 3
}

このコンテキストは、関連する配列のすべてのフィルタを含む商品の広告のみを返します。

📘

カテゴリの最低入札価格を利用する場合は、キャンペーンを作成する広告主が理解しやすい、ユーザーフレンドリーなカテゴリにする必要があります。例えば、「category:12」よりも、「category:Keyboards」の方がわかりやすいでしょう。

画像および商品名の提供

CitrusAdは、CitrusAdポータルでキャンペーンを作成する際に、商品画像と商品名の情報を検索できるようにする必要があります。これらの値は、以下の例のようにフォーマットされたタグの中でCitrusAdに送信できます。

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 ""imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0"
            ]
        }
    ]
}

これらは、以下の例のように、商品選択を含むCitrusAdポータルのさまざまな領域で見ることができます。

1581

参考画像