CitrusAd hỗ trợ ba loại định dạng để đồng bộ hóa dữ liệu sản phẩm bằng tệp:
- TSV
- CSV
- XML.
Phần này mô tả cấu trúc của từng định dạng tệp cho dữ liệu sản phẩm mà chúng tôi xử lý trong CitrusAd.
Tệp TSV/CSV
Bảng dưới đây minh họa tên cột và mô tả các cột cho các sản phẩm trong tệp TSV. Trong bảng này, chúng tôi cũng chỉ định các cột bắt buộc phải cung cấp trong tệp TSV. Khi một cột được yêu cầu, tất cả các giá trị trong cột cần được cung cấp trong các hàng của nó.
️ TSV không có trích dẫn
Tệp TSV không thể ở định dạng được trích dẫn. Khi đồng bộ hóa qua TSV, hãy đảm bảo bạn đồng bộ hóa các tệp không được trích dẫn.
Tên cột và mô tả dữ liệu sản phẩm trong tệp TSV
| Tên cột | Bắt buộc/không bắt buộc | Loại dữ liệu | Mô tả | Ví dụ |
|---|---|---|---|---|
product_code | Bắt buộc | Văn bản Tối đa 50 ký tự | Mã để xác định sản phẩm trong hệ thống của bạn. Trường này giống với trường gtin và trường mục trong đồng bộ hóa tệp API và XML. | F153212AN1 |
name | Bắt buộc | Văn bản Tối đa 150 ký tự | Tên của sản phẩm. | SS Sticker Tee - Trẻ em |
image_url | Bắt buộc | Url Tối đa 2048 ký tự | Siêu liên kết dẫn đến hình ảnh của sản phẩm. Phải là URL hợp lệ. | https://www.retailer.com/product/1234.jpg |
inventory | Bắt buộc | Số khuyến nghị số nguyên không dấu 32 bit | Số lượng trong kho của sản phẩm. Nếu giá trị là 0, quảng cáo sản phẩm sẽ không được phân phát cho sản phẩm này. | 1 |
description | Bắt buộc | Văn bản Tối đa 5000 ký tự | Mô tả của sản phẩm. | Với hình thêu hoa ba lá và ba sọc viền ngoài màu trắng tương phản, quần short nỉ thể thao là một sản phẩm mới đến từ Adidas Originals. |
KEY (as a value) | Bắt buộc đối với danh mục và vị trí hiển thị rộng | Văn bản Tối đa 1000 ký tự cho mỗi cột | Nếu sử dụng loại cột này thì nhà bán lẻ phải cung cấp một giá trị cho . Tệp TSV có thể chứa một số cột có cú pháp này. | Tên cột có thể là “brand” và giá trị của ô trong cột có thể là “green-fairy”. Từ đó, sản phẩm có thể xuất hiện bộ lọc "brand:green-fairy". |
subClassName | Không được chấp nhận. Bắt buộc đối với các vị trí bán kèm/bán thêm | Văn bản Tối đa 750 ký tự | Tên của phân lớp/danh mục sản phẩm có liên quan. Các phân lớp cho phép nhắm mục tiêu sản phẩm tốt hơn, ví dụ: một sản phẩm bơ có thể nhắm mục tiêu đến bánh mì, nhưng sẽ không nhắm mục tiêu đến băng cá nhân. | Phô mai |
xSellSubClassName | Không được chấp nhận. Bắt buộc đối với các vị trí bán kèm/bán thêm | Văn bản Tối đa 750 ký tự | Tên của các lớp con/danh mục mà sản phẩm có liên quan có thể nhắm mục tiêu đến các sản phẩm bên trong. | Bánh mì, Mứt, Bánh quy giòn |
price | Tùy chọn | Số Khuyến nghị 2 chữ số thập phân | Giá của một sản phẩm. | 30,00 |
brand | Bắt buộc | Văn bản Tối đa 70 ký tự | Nhãn hiệu của sản phẩm. | Tommy Hilfiger |
type | Bắt buộc | Văn bản Tối đa 750 ký tự | Loại sản phẩm. | Quần áo |
retailer_taxonomy | Bắt buộc đối với phân bổ nâng cao. Không được có khoảng cách giữa các ký tự > các ký tự | Văn bản Tối đa 750 ký tự | Phân loại sản phẩm của nhà bán lẻ cá nhân của bạn. | Nam > Quần áo nam > Áo len |
google_taxonomy | Bắt buộc đối với phân bổ nâng cao nếu không cung cấp retailer_taxonomy được | Văn bản Tối đa 750 ký tự | Phân loại tiêu chuẩn về sản phẩm của của Google. Có thể tìm hiểu thêm thông tin ở đây: https://www.google.com/basepages/producttype/taxonomy.en-US.txt | Trang phục và phụ kiện > Quần áo > Áo |
global_identifier | Bắt buộc | Văn bản Tối đa 50 ký tự | Mã nhận dạng chung cho sản phẩm. | 08719108994761 |
global_identifier_type | Bắt buộc | Văn bản | Loại mã nhận dạng chung. | GTIN |
custom_payload | Không bắt buộc trừ khi được khuyến nghị. | Mảng byte được mã hóa Base64 | Trường này chứa một tải trọng dữ liệu tùy chỉnh và tải trọng này sẽ được chuyển đến quá trình tạo quảng cáo. Trường này phải chứa một đối tượng JSON hợp lệ được xếp tuần tự thành một mảng byte và được mã hóa Base64. Đối tượng JSON phải tuân theo một lược đồ. | Xem phần tải trọng tùy chỉnh. |
hfss | Tùy chọn | Boolean | Dùng để cho biết liệu sản phẩm có phải là HFSS hay không. Loại dữ liệu này sẽ được tận dụng nhiều hơn trong Giao diện người dùng của CitrusAd. Xem Tài liệu HFSS để biết thêm thông tin. | true |
seller_id | Tùy chọn | Văn bản Tối đa 50 ký tự | Id không trùng lặp của người bán. Chỉ bắt buộc nếu đang hỗ trợ người bán trên thị trường trong những bước đầu tiên. Có thể để trống cho các sản phẩm không có trên thị trường. Khi tích hợp seller_id, phải chú ý đến một số yêu cầu bổ sung, vui lòng tham khảo sellerId cho sàn thương mại để biết thêm thông tin. | aes-de4-ss |
Bên dưới là một tệp ví dụ dưới dạng bảng:
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 | Gói quà tặng Green Fairy Absinth 500mL | https://www.retailer.com/product/1234.jpg | 20 | Gói quà tặng Green Fairy Absinth & Spoon này là món quà hoàn hảo cho người yêu thích rượu hoặc cocktail. Đặt một viên đường lên thìa và đổ tinh dầu apxin lên trên để uống loại rượu này đúng chuẩn! | Quà tặng, Đồ uống có cồn, Gói quà tặng | 500ml | Cộng hòa Séc | Quà tặng, Đồ uống có cồn, Gói quà tặng | 5.00 | Green Fairy | Rượu | Quà tặng > Rượu > Gói quà | Thực phẩm, Đồ uống và thuốc lá > Đồ uống > Đồ uống có cồn > Rượu và rượu mạnh > Absinthe | 8594001443079 | 7328s-dmie3-9jdae | Gói quà tặng | Rượu |
Tệp TSV không thể ở định dạng được trích dẫn.
Tệp XML
CitrusAd đã xác định một danh sách các thẻ dùng để mô tả tài liệu XML cho các sản phẩm. Dưới đây là danh sách các thẻ kèm theo mô tả chi tiết. Thẻ "item" dùng để mô tả sản phẩm trong tài liệu XML. Tất cả các thẻ khác cho các trường khác cần phải được viết bên trong thẻ này.
| Thẻ XML | Bắt buộc/không bắt buộc | Mô tả |
|---|---|---|
item | Bắt buộc | Thẻ này dùng để mô tả sản phẩm. Tất cả các thẻ XML khác cho sản phẩm phải nằm trong thẻ này. Tài liệu XML cho các sản phẩm phải chứa danh sách các thẻ mặt hàng. Trường này giống với trường gtin và product_code trong đồng bộ hóa tệp API và TSV. |
id | Bắt buộc | Mã để xác định sản phẩm trong hệ thống của bạn. Tương đương với product_code trong tệp TSV. Trường này giống với trường gtin và trường mục trong đồng bộ hóa tệp API và XML. |
title | Bắt buộc | Tên của sản phẩm. |
image_link | Bắt buộc Tối đa 50 ký tự | Siêu liên kết dẫn đến hình ảnh của sản phẩm. Phải là URL hợp lệ. |
brand | Bắt buộc Tối đa 70 ký tự | Nhãn hiệu của sản phẩm. |
availability | Bắt buộc Khuyến nghị số nguyên không dấu 32 bit | Thẻ này để mô tả khoảng không quảng cáo của một sản phẩm. Giá trị phải là số. |
description | Bắt buộc Tối đa 5000 ký tự | Thẻ này là để mô tả phần mô tả của một sản phẩm. |
price | Không bắt buộc Khuyến nghị 2 chữ số thập phân | Thẻ này dùng để mô tả giá sản phẩm. Nếu bên trong thẻ có giá trị thì giá trị đó phải là một số. |
type | Không bắt buộc Tối đa 750 ký tự | Loại sản phẩm. |
retailer_taxonomy | Bắt buộc đối với phân bổ nâng cao. Cũng bắt buộc với tích hợp danh mục. Tối đa 750 ký tự | Phân loại sản phẩm của nhà bán lẻ cá nhân của bạn. ví dụ: Nam>Quần áo nam>Áo len |
google_taxonomy | Bắt buộc đối với phân bổ nâng cao nếu không cung cấp retailer_taxonomy không thể được cung cấpTối đa 750 ký tự | Phân loại tiêu chuẩn về sản phẩm của của Google. Có thể tìm hiểu thêm thông tin ở đây: https://www.google.com/basepages/producttype/taxonomy.en-US.txt |
global_identifier | Bắt buộc Tối đa 50 ký tự | Mã nhận dạng chung cho sản phẩm. ví dụ: 08719108994761 |
global_identifier_type | Bắt buộc | Loại mã nhận dạng chung. ví dụ: GTIN |
custom_payload | Không bắt buộc trừ khi được khuyến nghị. | Trường này chứa một tải trọng dữ liệu tùy chỉnh và tải trọng này sẽ được chuyển đến quá trình tạo quảng cáo. Trường này phải chứa một đối tượng JSON hợp lệ được xếp tuần tự thành một mảng byte và được mã hóa Base64. Đối tượng JSON phải tuân theo một lược đồ. |
hfss | Tùy chọn | Dùng để cho biết liệu sản phẩm có phải là HFSS hay không. Loại dữ liệu này sẽ được tận dụng nhiều hơn trong Giao diện người dùng của CitrusAd. Xem Tài liệu HFSS để biết thêm thông tin. |
seller_id | Không bắt buộc Tối đa 50 ký tự | Id không trùng lặp của người bán. Chỉ bắt buộc nếu đang hỗ trợ người bán trên thị trường trong những bước đầu tiên. Có thể để trống cho các sản phẩm không có trên thị trường. Khi tích hợp seller_id, phải chú ý đến một số yêu cầu bổ sung, vui lòng tham khảo sellerId cho sàn thương mại để biết thêm thông tin. |
Dưới đây là ví dụ về tài liệu XML hợp lệ với các thẻ:
<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>
Tải trọng tùy chỉnh
Tải trọng tùy chỉnh là gì?
Tải trọng tùy chỉnh là các trường được xâu chuỗi "nguyên trạng" từ công đoạn nhập danh mục đến phân phát quảng cáo. Không áp dụng quy tắc biến đổi cho trường này. Tuy nhiên, việc xác thực dựa trên Lược đồ JSON (https://json-schema.org/) được thực hiện trên trường này. Thông số của tải trọng dữ liệu được cung cấp trong liên kết bên dưới (ký hiệu Lược đồ JSON):
Trong phản hồi quảng cáo sản phẩm, tải trọng tùy chỉnh chính xác được trả về cho bên tích hợp trong trường có tên là customPayload. Dưới đây là ví dụ của một tải trọng hợp lệ:
{
"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
}
]
}
Chỉ tệp tin
Vui lòng lưu ý rằng tải trọng tùy chỉnh chỉ được hỗ trợ khi đồng bộ hóa sản phẩm qua tệp tin.
Tải trọng tùy chỉnh trong quá trình tạo quảng cáo
Khi trả về quảng cáo sản phẩm, tải trọng tùy chỉnh được chuyển qua dưới dạng một phần của quảng cáo đã tạo. Tải trọng quảng cáo trả về sẽ chứa một trường customPayload bổ sung mà trường này có chứa một đối tượng JSON có cùng đặc điểm kỹ thuật như thông tin được cung cấp trong nguồn cấp dữ liệu.
Câu trả lời ví dụ có thể là:
{
"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": []
}
Vì tải trọng tùy chỉnh là khối lượng công việc bổ sung của dịch vụ tạo quảng cáo nên xin lưu ý rằng các tiện ích tích hợp tải trọng tùy chỉnh sẽ không tuân theo SLA của CitrusAd, trừ khi có quy định khác.