CitrusAdは、ファイルによる商品データの同期に、次の3つのフォーマットタイプをサポートしています。
- TSV
- CSV
- XML.
ここでは、CitrusAdで処理する商品データの各ファイルフォーマットの構造について説明します。
TSV/CSVファイル
TSVファイル中の商品の列とその説明を以下の表に示します。また、この表で、ファイルにて提供する必要のある必須列を指定することもできます。列が必須である場合、その列のすべての値をその行で提供する必要があります。
引用符で囲まれていないTSV
TSVファイルは引用符で囲まれた形式にはできません。TSV経由で同期する場合は、引用符で囲まれていないファイルであることを確認してください。
TSV/CSVファイル中の商品データの列名と説明
列名 | 必須/任意 | データタイプ | 説明 | 例 |
---|---|---|---|---|
product_code | 必須 | テキスト 最大50文字 | システム内で商品を識別するためのコードです。このフィールドは、APIおよびXMLファイルの同期における、gtinおよびitemフィールドと同一です。 | F153212AN1 |
name | 必須 | テキスト 最大150文字 | 商品の名前です。 | SS ステッカーTシャツ - キッズ |
image_url | 必須 | URL 最大2048文字 | 商品の画像へのハイパーリンクです。有効なURLである必要があります。 | https://www.retailer.com/product/1234.jpg |
inventory | 必須 | 数字 32ビット符号なし整数を推奨 | 商品の在庫状況です。値が0である場合、その商品の広告は配信されません。 | 1 |
description | 必須 | テキスト 最大5000文字 | 商品の説明です。 | 三つ葉の刺繍に、際立つ白の3本ストライプ。このスポーツスウェットショーツは、Adidas Originalsからの新しい提案です。 |
KEY (as a value) | カテゴリとブロードディスプレイのプレースメントに必要 | テキスト 列あたり最大1000 文字 | このタイプのカラムが使用される場合、小売業者は値を提供する必要があります。 。 TSVファイルには、このようなシンタックスのカラムが複数存在する場合があります。 | 列名は「brand」、列のセルの値は「green-fairy」とすることができます。これにより、商品に「brand:green-fairy」というフィルタがかかります。 |
subClassName | 非推奨。商品のクロスセル/アップセルの配置に必要です。 | テキスト 最大750文字 | 該当する商品が属するサブクラスまたはカテゴリの名称。 サブクラスにより、商品の適切なターゲティングが可能になります。例えば、バターの場合、絆創膏ではなく、パンをターゲットにすることができます。 | チーズ |
xSellSubClassName | 非推奨。商品のクロスセル/アップセルの配置に必要です。 | テキスト 最大750文字 | 当該製品が対象にできるサブクラス/カテゴリの名前です。 | パン、スプレッド、クラッカー |
price | 任意 | 数字 小数点以下2桁を推奨 | 商品の価格です。 | 30.00 |
brand | 必須 | テキスト 最大70文字 | 商品のブランドです。 | Tommy Hilfiger |
type | 必須 | テキスト 最大750文字 | 商品の種類です。 | 衣料品 |
retailer_taxonomy | 拡張アトリビューションに必要です。記号 > と文字の間にスペースを入れないでください | テキスト 最大750文字 | 商品の個々の小売業者のタクソノミー(分類法)です。 | 男性 > 男性服 > セーター |
google_taxonomy | 以下の場合の拡張アトリビューションに必要です: retailer_taxonomy を提供できない場合 | テキスト 最大750文字 | 商品におけるGoogleの標準的なタクソノミー (分類法)です。詳細はこちらでご覧いただけます:https://www.google.com/basepages/producttype/taxonomy.en-US.txt | アパレル&アクセサリー > 衣料品 > トップス |
global_identifier | 必須 | テキスト 最大50文字 | 製品のグローバル識別子です。 | 08719108994761 |
global_identifier_type | 必須 | テキスト | グローバル識別子の種類です。 | GTIN |
custom_payload | 特に明記されていない限り必要ありません。 | Base64でエンコードされたバイト配列 | このフィールドには、広告生成に通されるべきカスタムペイロードが含まれています。このフィールドは、有効なJSONオブジェクトをバイト配列にシリアル化し、Base64エンコードしたものである必要があります。JSONオブジェクトはスキーマに準拠する必要があります。 | カスタムペイロードのセクションを参照してください。 |
hfss | 任意 | ブール値 | 商品がHFSS対象かどうかを示すために使用されます。その他、CitrusAdのUIでも活用できます。詳細については、HFSSドキュメントをご覧ください。 | true |
seller_id | 任意 | テキスト 最大50文字 | 出品者の一意のID。マーケットプレイス出品者のオンボーディングの場合のみ必要です。マーケットプレイス以外の商品については空白のままにすることができます。 seller_idの統合については他にも要件があります。詳細については、 マーケットプレイス出品者IDをご覧ください。 | aes-de4-ss |
表として表現されるファイルの例を以下に示します。
product_code | name | image_url | inventory | description | filter:Category | filter:Size | filter:Country | groups | price | brand | type | retailer_taxonomy | google_taxonomy | global_identifier | seller_id | subClassName | xSellSubClassName |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
80591101 | Green Fairyアブサンのギフトパック 500mL | https://www.retailer.com/product/1234.jpg | 20 | このGreen Fairyアブサン&スプーンのギフトパックは、アブサンやカクテルの愛好家に最適な贈り物です。このスプーンの上に角砂糖を置き、その上からアブサンを注いで、本格的に楽しみましょう! | ギフト、アルコール類、ギフトパック | 500ml | チェコ共和国 | ギフト、アルコール類、ギフトパック | 5.00 | Green Fairy | アルコール | ギフト > アルコール類 > ギフトパック | 食品、飲料&タバコ > 飲料 > アルコール飲料 > 酒類&スピリッツ > アブサン | 8594001443079 | 7328s-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 | 必須 最大50文字 | 商品の画像へのハイパーリンクです。有効なURLである必要があります。 |
brand | 必須 最大70文字 | 商品のブランドです。 |
availability | 必須 32ビット符号なし整数推奨 | このタグは、商品の在庫を記述するためのものです。値は数値である必要があります。 |
description | 必須 最大5000文字 | このタグは、商品の説明文を記述するためのものです。 |
price | 任意 小数点以下2桁を推奨 | このタグは、商品の価格を記述するためのものです。タグ内部の値は数値にする必要があります。 |
type | 任意 最大750文字 | 商品の種類です。 |
retailer_taxonomy | 拡張アトリビューションに必要です。カテゴリ統合にも必要です。最大750文字。 | 商品の個々の小売業者のタクソノミー(分類法)です。例:男性>男性服>セーター |
google_taxonomy | 以下の場合の拡張アトリビューションに必要です: retailer_taxonomy 提供できません最大750文字 | 商品におけるGoogleの標準的なタクソノミー (分類法)です。詳細はこちらでご覧いただけます:https://www.google.com/basepages/producttype/taxonomy.en-US.txt |
global_identifier | 必須 最大50文字 | 製品のグローバル識別子です。例: 08719108994761 |
global_identifier_type | 必須 | グローバル識別子の種類です。例: GTIN |
custom_payload | 特に明記されていない限り必要ありません。 | このフィールドには、広告生成に通されるべきカスタムペイロードが含まれています。このフィールドは、有効なJSONオブジェクトをバイト配列にシリアル化し、Base64エンコードしたものである必要があります。JSONオブジェクトはスキーマに準拠する必要があります。 |
hfss | 任意 | 商品がHFSS対象かどうかを示すために使用されます。その他、CitrusAdのUIでも活用できます。詳細については、HFSSドキュメントをご覧ください。 |
seller_id | 任意 最大50文字 | 出品者の一意のID。マーケットプレイス出品者のオンボーディングの場合のみ必要です。マーケットプレイス以外の商品については空白のままにすることができます。 seller_idの統合については他にも要件があります。詳細については、 マーケットプレイス出品者IDをご覧ください。 |
タグを使用した有効なXML文書の例を以下に示します。
<rss>
<item>
<id>80591011</id>
<title>Melissa & 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>£9.99</price>
<brand>Melissa & 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>£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<BR>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<BR>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<BR>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<BR>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(サービス品質保証)の対象外となりますので、ご注意ください。