ファイル経由でカタログや商品を同期

CitrusAdは、ファイルによる商品データの同期に、次の3つのフォーマットタイプをサポートしています。

  • TSV
  • CSV
  • XML.

ここでは、CitrusAdで処理する商品データの各ファイルフォーマットの構造について説明します。

TSV/CSVファイル

TSVファイル中の商品の列とその説明を以下の表に示します。また、この表で、ファイルにて提供する必要のある必須列を指定することもできます。列が必須である場合、その列のすべての値をその行で提供する必要があります。

引用符で囲まれていないTSV

TSVファイルは引用符で囲まれた形式にはできません。TSV経由で同期する場合は、引用符で囲まれていないファイルであることを確認してください。

TSV/CSVファイル中の商品データの列名と説明

列名必須/任意データタイプ説明
product_code必須テキストシステム内で商品を識別するためのコードです。このフィールドは、APIおよびXMLファイルの同期における、gtinおよびitemフィールドと同一です。F153212AN1
name必須テキスト商品の名前です。SS ステッカーTシャツ - キッズ
image_url必須URL商品の画像へのハイパーリンクです。有効なURLである必要があります。https://www.retailer.com/product/1234.jpg
inventory必須数値商品の在庫状況です。値が0である場合、その商品の広告は配信されません。1
description必須テキスト商品の説明です。三つ葉の刺繍に、際立つ白の3本ストライプ。このスポーツスウェットショーツは、Adidas Originalsからの新しい提案です。
KEY (as a value)カテゴリとブロードディスプレイのプレースメントに必要テキストこのタイプのカラムが使用される場合、小売業者は値を提供する必要があります。

TSVファイルには、このようなシンタックスのカラムが複数存在する場合があります。
列名は「brand」、列のセルの値は「green-fairy」とすることができます。これにより、商品に「brand:green-fairy」というフィルタがかかります。
subClassNameクロスセル/アップセルの配置に必要ですテキスト該当する商品が属するサブクラスまたはカテゴリの名称。

サブクラスにより、商品の適切なターゲティングが可能になります。例えば、バターの場合、絆創膏ではなく、パンをターゲットにすることができます。
チーズ
xSellSubClassNameクロスセル/アップセルの配置に必要ですテキスト当該製品が対象にできるサブクラス/カテゴリの名前です。パン、スプレッド、クラッカー
price任意数値商品の価格です。30.00
brand必須テキスト商品のブランドです。Tommy Hilfiger
type必須テキスト商品の種類です。衣料品
retailer_taxonomy拡張アトリビューションに必要です。記号 > と文字の間にスペースを入れないでくださいテキスト商品の個々の小売業者のタクソノミー(分類法)です。男性 > 男性服 > セーター
google_taxonomy以下の場合の拡張アトリビューションに必要です: retailer_taxonomy を提供できない場合テキスト商品におけるGoogleの標準的なタクソノミー (分類法)です。詳細はこちらでご覧いただけます:https://www.google.com/basepages/producttype/taxonomy.en-US.txtアパレル&アクセサリー > 衣料品 > トップス
global_identifier必須テキスト製品のグローバル識別子です。08719108994761
global_identifier_type必須テキストグローバル識別子の種類です。GTIN
custom_payload任意*Base64でエンコードされたバイト配列このフィールドには、広告生成に通されるべきカスタムペイロードが含まれています。このフィールドは、有効なJSONオブジェクトをバイト配列にシリアル化し、Base64エンコードしたものである必要があります。JSONオブジェクトはスキーマに準拠する必要があります。カスタムペイロードのセクションを参照してください。
hfss任意ブール値商品がHFSS対象かどうかを示すために使用されます。その他、CitrusAdのUIでも活用できます。詳細については、HFSSドキュメントをご覧ください。true
seller_id任意テキスト出品者の一意のID。マーケットプレイス出品者のオンボーディングの場合のみ必要です。マーケットプレイス以外の商品については空白のままにすることができます。

seller_idの統合については他にも要件があります。詳細については、 マーケットプレイス出品者IDをご覧ください。
aes-de4-ss

表として表現されるファイルの例を以下に示します。

product_codenameimage_urlinventorydescriptionfilter:Categoryfilter:Sizefilter:Countrygroupspricebrandtyperetailer_taxonomygoogle_taxonomyglobal_identifierseller_idsubClassNamexSellSubClassName
80591101Green Fairyアブサンのギフトパック 500mLhttps://www.retailer.com/product/1234.jpg20このGreen Fairyアブサン&スプーンのギフトパックは、アブサンやカクテルの愛好家に最適な贈り物です。このスプーンの上に角砂糖を置き、その上からアブサンを注いで、本格的に楽しみましょう!ギフト、アルコール類、ギフトパック500mlチェコ共和国ギフト、アルコール類、ギフトパック5.00Green Fairyアルコールギフト > アルコール類 > ギフトパック食品、飲料&タバコ > 飲料 > アルコール飲料 > 酒類&スピリッツ > アブサン85940014430797328s-dmie3-9jdaeギフトパック酒類

📘

TSVファイルは引用符で囲まれた形式にはできません。

XMLファイル

CitrusAdは、商品に関するXML文書を記述するために使用されるタグのリストを定義しています。下の表は、そのタグと説明になります。「item」タグは、XML文書中に商品を記述するために使用されます。他のフィールドのタグは、すべてこのタグの中に記述する必要があります。

XMLタグ必須/任意説明
item必須このタグは、製品を説明するために使用されます。商品の他のすべてのXMLタグは、このタグの中に入っている必要があります。商品に関するXML文書には、itemタグのリストが必要です。このフィールドは、APIおよびTSVファイルの同期におけるgtinおよびproduct_codeフィールドと同一です。
id必須システム内で商品を識別するためのコードです。TSVファイルの product_code に相当します。このフィールドは、APIおよびXMLファイルの同期における、gtinおよびitemフィールドと同一です。
title必須商品の名前です。
image_link必須商品の画像へのハイパーリンクです。有効なURLである必要があります。
brand必須商品のブランドです。
availability必須このタグは、商品の在庫を記述するためのものです。値は数値である必要があります。
description必須このタグは、商品の説明文を記述するためのものです。
price任意このタグは、商品の価格を記述するためのものです。タグ内部の値は数値にする必要があります。
type任意商品の種類です。
retailer_taxonomy拡張アトリビューションに必要です。カテゴリ統合にも必要です。商品の個々の小売業者のタクソノミー(分類法)です。例:男性>男性服>セーター
google_taxonomy以下の場合の拡張アトリビューションに必要です: retailer_taxonomy を提供できない場合商品におけるGoogleの標準的なタクソノミー (分類法)です。詳細はこちらでご覧いただけます:https://www.google.com/basepages/producttype/taxonomy.en-US.txt
global_identifier必須製品のグローバル識別子です。例: 08719108994761
global_identifier_type必須グローバル識別子の種類です。例: GTIN
custom_payload任意*このフィールドには、広告生成に通されるべきカスタムペイロードが含まれています。このフィールドは、有効なJSONオブジェクトをバイト配列にシリアル化し、Base64エンコードしたものである必要があります。JSONオブジェクトはスキーマに準拠する必要があります。
hfss任意商品がHFSS対象かどうかを示すために使用されます。その他、CitrusAdのUIでも活用できます。詳細については、HFSSドキュメントをご覧ください。
seller_id任意出品者の一意のID。マーケットプレイス出品者のオンボーディングの場合のみ必要です。マーケットプレイス以外の商品については空白のままにすることができます。

seller_idの統合については他にも要件があります。詳細については、 マーケットプレイス出品者IDをご覧ください。

タグを使用した有効なXML文書の例を以下に示します。

<rss>
  <item>
      <id>80591011</id>
      <title>Melissa &amp; Doug Dinosaur Stamp Set, 4yrs+</title>
      <description>Imagine a rugged landscape littered with volcanoes, and full of dinosaurs roaming around</description>
      <image_link>https://www.retailer.com/productImages/image1.jpg</image_link>
      <price>&pound;9.99</price>
      <brand>Melissa &amp; Doug</price>
      <product_type>Food Cupboard</product_type>
      <availability>10</availability>
    	<hfss>true</hfss>
    </item>
    <item>
      <id>87086011</id>
      <title>Waitrose Splits Strawberry Ice Lollies</title>
      <description>Strawberry splits; Suitable for vegetarians. Strawberry splits vanilla flavoured ice cream with a fruity strawberry ice coating. Our fundamental belief is that few things in life are more important than the food you buy. Good quality is essential.</description>
			<image_link>https://www.retailer.com/productImages/image2.jpg</image_link>
      <price>&pound;1.25</price>
      <brand>Waitrose</brand>
      <product_type>Frozen Ice Cream Ice Cream Lollies</product_type>
      <availability>20</availability>
      <brand>Waitrose</brand>
      <hfss>false</hfss>
      <seller_id>432un3-sd32s-ssaar</seller_id>
    </item>
</rss>

カスタムペイロード

カスタムペイロードとは?

カスタムペイロードとは、カタログの取り込みから広告配信まで、「そのまま」通されるフィールドのことです。フィールドに変換は適用されません。ただし、JSONスキーマ (https://json-schema.org/) ベースの検証はフィールドに対して行われます。ペイロードの仕様は、以下のリンクから提供されます(JSON スキーマ表記)。

商品広告のレスポンスでは、正確なカスタムペイロードが customPayloadという名前のフィールドでインテグレータに返されます。有効なペイロードの例を以下に示します。

{
  "id": "102013703",
  "upc": "4400000463",
  "name": "Bee Farms Honey - 14.4 Oz",
  "nutrientName": [
    "Kosher"
  ],
  "description": "Honey",
  "brand": "Bee Farms",
  "imageUrl": "https://www.retailer.com/products/1/image.png",
  "productUrl": "https://www.retailer.com/products/1/page.html",
  "aisleId": "1_22_2_3",
  "departmentName": "Breakfast ",
  "aisleName": "Breakfast spreads",
  "shelfName": "Honeu",
  "salesRank": 481,
  "details": "Made with real honey. No high fructose corn syrup. 8 g of while grain per 31 g serving. Per 8 Crackers: 130 calories; 0 g sat fat (% DV); 160 mg sodium (7% DV); 8 g total sugars. Start with: Bee farms honey grahams. Fill grahams with toasted marshmallows. Add milk chocolate squares. For full nutritional information, go to honeymaid.com. Try our other delicious flavors: Grahams made with real cinnamon. Grahams made with real chocolate. 8 g of whole grain per 31 g serving. Nutritionist recommend eating 18 g or more of whole grains throughout the day. 100% Whole Grain: 8 per serving. Eat 48 g or more of whole grains daily. WholeGrainsCouncil.org. Smartlabel. Visit us at: beefarms.com 1-809-622-4726 please have package available. Keep it Going: 100 recycled paperboard. Please recycle this carton. Minimum 35% post-consumer content. Made in Mexico.",
  "averageWeight": 0,
  "displayType": 0,
  "stores": [
    {
      "storeId": "2543",
      "price": 3.99,
      "salePrice": 0.28,
      "pricePer": 4.99,
      "unitOfMeasure": "OUNCE",
      "restrictedFlag": false,
      "sellByWeight": false,
      "promoDescription": "I",
      "promoText": "Club Price: $3.99&lt;BR&gt;SAVE up to: $1",
      "promoType": "P",
      "offerFlag": true
    },
    {
      "storeId": "2544",
      "price": 3.99,
      "salePrice": 0.28,
      "pricePer": 4.99,
      "unitOfMeasure": "OUNCE",
      "restrictedFlag": false,
      "sellByWeight": false,
      "promoDescription": "I",
      "promoText": "Club Price: $3.99&lt;BR&gt;SAVE up to: $1",
      "promoType": "P",
      "offerFlag": true
    }
  ]
}

🚧

ファイルのみ

カスタムペイロードは、ファイル経由で製品を同期している場合にのみサポートされることに注意してください。

広告生成におけるカスタムペイロード

商品広告を返す際、カスタムペイロードは生成された広告の一部として通されます。返された広告ペイロードには、フィールドが追加されています。 customPayload このフィールドにはフィードで提供される情報と同じ仕様のJSONオブジェクトが含まれます。

レスポンス例としては、以下が考えられます。

{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "4400000463",
            "customPayload": {
                "id": "102013703",
                "upc": "4400000463",
                "name": "Bee Farms Honey - 14.4 Oz",
                "nutrientName": [
                  "Kosher"
                ],
                "description": "Honey",
                "brand": "Bee Farms",
                "imageUrl": "https://www.retailer.com/products/1/image.png",
                "productUrl": "https://www.retailer.com/products/1/page.html",
                "aisleId": "1_22_2_3",
                "departmentName": "Breakfast ",
                "aisleName": "Breakfast spreads",
                "shelfName": "Honeu",
                "salesRank": 481,
                "details": "Made with real honey. No high fructose corn syrup. 8 g of while grain per 31 g serving. Per 8 Crackers: 130 calories; 0 g sat fat (% DV); 160 mg sodium (7% DV); 8 g total sugars. Start with: Bee farms honey grahams. Fill grahams with toasted marshmallows. Add milk chocolate squares. For full nutritional information, go to honeymaid.com. Try our other delicious flavors: Grahams made with real cinnamon. Grahams made with real chocolate. 8 g of whole grain per 31 g serving. Nutritionist recommend eating 18 g or more of whole grains throughout the day. 100% Whole Grain: 8 per serving. Eat 48 g or more of whole grains daily. WholeGrainsCouncil.org. Smartlabel. Visit us at: beefarms.com 1-809-622-4726 please have package available. Keep it Going: 100 recycled paperboard. Please recycle this carton. Minimum 35% post-consumer content. Made in Mexico.",
                "averageWeight": 0,
                "displayType": 0,
                "stores": [
                  {
                  "storeId": "2543",
                  "price": 3.99,
                  "salePrice": 0.28,
                  "pricePer": 4.99,
                  "unitOfMeasure": "OUNCE",
                  "restrictedFlag": false,
                  "sellByWeight": false,
                  "promoDescription": "I",
                  "promoText": "Club Price: $3.99&lt;BR&gt;SAVE up to: $1",
                  "promoType": "P",
                  "offerFlag": true
                  },
                  {
                  "storeId": "2544",
                  "price": 3.99,
                  "salePrice": 0.28,
                  "pricePer": 4.99,
                  "unitOfMeasure": "OUNCE",
                  "restrictedFlag": false,
                  "sellByWeight": false,
                  "promoDescription": "I",
                  "promoText": "Club Price: $3.99&lt;BR&gt;SAVE up to: $1",
                  "promoType": "P",
                  "offerFlag": true
                }
              ]
            } ,
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        }
    ],
    "banners": [],
    "products": []
}

🚧

カスタムペイロードは広告生成サービスの追加ワークロードであるため、特に指定がない限り、カスタムペイロードの統合はCitrusAd SLA(サービス品質保証)の対象外となりますので、ご注意ください。