CitrusAd는 파일을 통한 제품 데이터 동기화를 위한 세 가지 형식 유형을 지원합니다.
- TSV
- CSV
- XML.
이 섹션에서는 CitrusAd에서 처리하는 제품 데이터에 대한 각 파일 형식의 구조에 대해 설명합니다.
TSV/CSV 파일
아래의 표는 TSV/CSV 파일에 있는 제품의 열 이름과 설명입니다. 이 표에서는 파일에 제공되어야 하는 필수 열도 지정되어 있습니다. 열이 필요한 경우 열의 모든 값이 행에 제공되어야 합니다.
따옴표가 없는 TSV
TSV 파일은 따옴표 형식일 수 없습니다. TSV를 통해 동기화 시 따옴표가 없는 파일을 동기화해야 합니다.
TSV/CSV 파일에 있는 제품 데이터의 열 이름 및 설명
열 이름 | 필수/선택 | 데이터 유형 | 설명 | 예시 |
---|---|---|---|---|
product_code | 필수 입력 항목입니다 | 텍스트 최대 50자 | 시스템에서 제품을 식별하기 위한 코드입니다. 이 필드는 API 및 XML 파일 동기화의 gtin 및 항목 필드와 동일합니다. | F153212AN1 |
name | 필수 입력 항목입니다 | 텍스트 최대 150자 | 제품의 이름입니다. | SS 스티커 티 - 아동 |
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) | 카테고리 및 넓은 디스플레이 게재위치에 필요합니다. | 텍스트 : 열당 최대 1,000자 | 이 유형의 열이 사용되는 경우 소매업체는 다음에 대한 값을 제공해야 합니다. . 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를 통합하기 위한 추가 요건이 있습니다. 자세한 내용은 Marketplace sellerId를 참조하십시오. | 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 Absinth 선물 팩 500mL | https://www.retailer.com/product/1234.jpg | 20 | 이 Green Fairy Absinth와 스푼 기프트 팩은 압생트나 칵테일 애호가를 위한 완벽한 선물입니다. 숟가락에 각설탕을 올리고 압생트를 부으면 제품의 풍미를 제대로 느낄 수 있습니다! | 선물, 주류, 선물 팩 | 500ml | 체코 공화국 | 선물, 주류, 선물 팩 | 5.00 | Green Fairy | 주류 | 선물 > 주류 > 선물 팩 | 음식, 음료 및 담배 > 음료 > 주류 > 술 및 스피릿 > 압생트 | 8594001443079 | 7328s-dmie3-9jdae | 기프트 팩 | 주류 |
TSV 파일은 따옴표 형식을 취할 수 없습니다.
XML 파일
CitrusAd는 제품에 대한 XML 문서를 설명하는 데 사용되는 태그 목록을 정의했습니다. 아래의 표는 태그와 태그 설명을 나타냅니다. '항목' 태그는 XML 문서에서 제품을 설명하는 데 사용됩니다. 다른 필드에 필요한 다른 모든 태그는 이 태그 안에서 작성되어야 합니다.
XML 태그 | 필수/선택 | 설명 |
---|---|---|
item | 필수 입력 항목입니다 | 이 태그는 제품을 설명하는 데 사용됩니다. 제품에 대한 다른 모든 XML 태그는 이 태그 안에 포함되어야 합니다. 제품에 대한 XML 문서에는 항목 태그 목록이 포함되어야 합니다. 이 필드는 API와 TSV 파일 동기화의 gtin 및 product_code 필드와 동일합니다. |
id | 필수 입력 항목입니다 | 시스템에서 제품을 식별하기 위한 코드입니다. (TSV 파일 내 다음에 해당: product_code ) 이 필드는 API 및 XML 파일 동기화의 gtin 및 항목 필드와 동일합니다. |
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를 통합하기 위한 추가 요건이 있습니다. 자세한 내용은 Marketplace sellerId를 참조하십시오. |
태그가 있는 유효한 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
}
]
}
파일 전용
사용자 정의 페이로드는 파일을 통해 제품을 동기화하는 경우에만 지원됩니다.
광고 생성 시 사용자 정의 페이로드
제품 광고 반환 시 사용자 정의 페이로드는 생성된 광고의 일부로 스레드됩니다. 반환된 페이로드에는 피드에 제공된 정보와 동일한 사양을 준수하는 JSON 오브젝트를 포함하는 추가 필드 customPayload
가 포함됩니다.
예시 응답은 다음과 같습니다.
{
"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의 적용을 받지 않습니다.