awoo Datafeed Specification

✨ Preface

Your datafeed (or product catalog) is an essential component of our service. It's the key to unlock a host of benefits: extracting critical features of your products, delivering customized recommendations, displaying relevant search results, and constructing a detailed affinity profile by analyzing your customers' preferences, among others. Sharing your datafeed in the correct format is important for those mentioned benefits.

🔑 Prepare File with EC Platform

Before considering to prepare your own datafeed file, if your EC website is built with those platforms, then you're almost ready to go! awoo has been integrated with those platforms to provide seamless/painless service for our customers. Check preparation method below for each EC platform, and skip rest of the guide!

EC Platform	has been integrated with awoo	provision method
91APP	✅	provided by 91APP
SHOPLINE	✅	provided by SHOPLINE system
Shopify	✅	obtain Shopify Token for awoo
QDM	✅	provided by QDM system
Cyberbiz	✅	provided by Cyberbiz system
Wordpress	✅	install plugin to obtain online product feed for awoo

🔑 Preparing File by Yourself

If you're the one who build their own website, please consider either methods to provide your datafeed file. Also see sections below for datafeed specification and example.

delivery method	format	what you need to provide
URL	XML/CSV	URL of datafeed
FTP	XML/CSV	address, port, login credentials

❗️
While utilizing CSV format
Please ensure that your CSV file is delineated by commas.

❗️
While delivering datafeed file through FTP
Please notice that we'll only retrieve files from the address and update with the latest file (we won't search into subdirectories.) After reading the file, no further actions will be taken, and file will not be deleted.

👍
If you have multiple files
You can bundle multiple files into a .zip file and provide through URL/FTP.

📜 Datafeed Specification

As you're the one who has to prepare their own datafeed file (either in XML or CSV,) having your datafeed in correct format is the essential steps to reap the functionality of awoo AMP. Please read the following section attentively while preparing your datafeed. Let's go through the schema first, then we'll introduce format, sample value, and awoo AMP usage for each field.

Field	required?	XML element name	CSV column name
Product ID	✅	g:id	id
Product Name	✅	g:title	title
Product Description	✅	g:description	description
Product URL	✅	g:link	link
Product URL for Mobile	➖	g:mobile_link	mobile_link
Product Image URL	✅	g:image_link	image_link
Availability	✅	g:availability	availability
Original Price	✅	g:price	price
Sales Price	➖	g:sale_price	sale_price
Brand Name	✅	g:brand	brand
Product Category	✅	g:product_type	product_type
Attributes	➖	g:attributes	attributes
Popularity	➖	<a:popularity></a:popularity>	popularity
Favorited Count	➖	<a:favorite></a:favorite>	favorite
Sales Volume	➖	<a:sales_volume></a:sales_volume>	sales_volume
Review Count	➖	<a:reviewCount></a:reviewCount>	reviewCount
Rating	➖	<a:rating></a:rating>	rating
Created Time	➖	g:product_create_time	product_create_time
Global Trade Item Number	➖	g:gtin	gtin

🚧
Case sensitive!
One must notice that each element name in XML or column name in CSV has to be case consistent with our datafeed schema. Any mismatch will lead to error and misalignment while integrating with awoo AMP.

📘
Swipe the following table to the far right -->
Also see how each field is related to the functionalities of awoo AMP.

Detailed Field Specifications

Field	Format	Sample Value	Relation to awoo AMP
Product ID	[Syntax] • Max 50 characters [Requirement] • If a product has multiple SKUs (e.g., various colors, sizes), please provide a representative product ID	789124
Product Name	[Syntax] • Max 150 characters	Chocolate Milkshake	Product recommendation - AI tagging - Site search
Product Description	[Syntax] • Max 5000 characters [Requirement] • Any HTML tag must be removed	A sweet beverage made by blending milk, ice cream, and flavorings.	AI tagging - Site search
Product URL	[Requirement] • Start with http or https • Use an encoded URL that complies with RFC-2396 or RFC-1738 • Must be only correspond to one Product ID	https://nununi-sdk-demo.myshopify.com//products/6032686	Product recommendation
Product URL for Mobile	[Requirement] • Start with http or https • Use an encoded URL that complies with RFC-2396 or RFC-1738	https://nununi-sdk-demo.myshopify.com/mobile/products/6032686	Mobile popup
Product Image URL	[Requirement] • Start with http or https • Make sure the URL can be crawled by public web server • Use an encoded URL that complies with RFC-2396 or RFC-1738	https://cdn.shopify.com/s/files/1/0580/4749/6346/products/06032686-01_691709af-68a1-4680-bb43-774e9004395d.jpg?v=1676459230	Product recommendation
Availability	[Supported Values] • In stock • Out of stock • Preorder • Backorder	In stock	Product recommendation
Original Price	[Syntax] • Must be numeric • Must be larger than 0 [Requirement] • Complies with ISO 4217	100 TWD	Product recommendation
Sales Price	[Syntax] • Must be numeric • Must be larger than 0 [Requirement] • Complies with ISO 4217	90 TWD	Product recommendation
Brand Name	[Syntax] • Max 70 characters	Milkshake King	Site search
Product Category	[Syntax] • Max 10000 characters [Supported Expression] • "large category>medium category>small category" (with hierarchy) • "single category" (without hierarchy) [Requirement] • If there are multiple categories for a single product, please separated categories by comma	"Dessert>Dairy>Milk" or "Dessert"	awoo page - Tag recommendation - Site search
Attributes	[Syntax] • Array element length limit: 20 • Pipe count limit: 20 • String length limit: 1230 • Single key length limit: 30 • Single value length limit: 60 [Requirement] • If multiple SKUs need to be used for internal site search keywords, please include the SKUs in the attribute information.	CSV sample: [`{"attribute":"model_no:IO476"}`,`{"attribute":"article_number:G15890"}`,`{"attribute":"size:UK 4\\|UK 5\\|UK"}`,`{"attribute":"recommend:new arrival"}`,`{"attribute":"color:black"}`] XML sample: <g:attributes> <g:attribute>gender:male</g:attribute> <g:attribute>color:black\|gold</g:attribute> <g:attribute>category:swimming\|scuba diving</g:attribute> <g:attribute>sku:123456aa\|123456bb</g:attribute> </g:attributes>	Site search
Popularity	[Syntax] • Integer	1000	awoo page - Site search
Favorited Count	[Syntax] • Integer	24	awoo page - Site search
Sales Volume	[Syntax] • Integer	3678	awoo page - Site search
Review Count	[Syntax] • Integer	54	awoo page - Site search
Rating	[Syntax] • Integer	5	awoo page - Site search
Created Time	[Requirement] • Complies with ISO 8601	2022-02-15 9:03:30	awoo page - Site search
Global Trade Item Number	[Syntax] • Max 20 characters [Requirement] • Must apply with GS1 format and follow one of those standard: GTIN-8, GTIN-10, GTIN-12, GTIN-13, GTIN-14, ISBN-10, ISBN-13	"323456789012" (in GTIN-12) or "49123456" (in GTIN-8)

<?xml version="1.0"?>
<rss xmlns:g="http://base.google.com/ns/1.0" xmlns:a="http://www.awoo.org/ns/1.0" version="2.0">
<channel>
<title>example x nununi</title>
<link>https://www.example.com</link>
<description>example product feed</description>


<item>
	<g:id>id00001</g:id>
	<g:title>id00001 Product page's title</g:title>
	<g:description>id00001 Product page's description</g:description>
	<g:link>https:/example.com/product/id00001</g:link>
	<g:image_link>http://lorempixel.com/200/200/fashion/1</g:image_link>
	<g:availability>in stock</g:availability>
	<g:price>240 TWD</g:price>
	<g:sale_price>99 TWD</g:sale_price>
	<g:brand>brand 99</g:brand>
	<g:product_type>Home > Dresses > Maxi Dresses</g:product_type>
	<g:attributes>
		<g:attribute>dimension:spec1|spec2|spec3</g:attribute>
		<g:attribute>dimension2:spec1|spec2</g:attribute>
		<g:attribute>gender:male</g:attribute>
		<g:attribute>color:black|gold</g:attribute>
		<g:attribute>feature:swimming|scuba diving</g:attribute>
	</g:attributes> 
	<a:item_sort_volume>
		<a:popularity>99</a:popularity>
		<a:favorite>99</a:favorite>
		<a:sales_volume>99</a:sales_volume>
		<a:rating>5</a:rating>
		<a:reviewCount>99</a:reviewCount>
	</a:item_sort_volume>
</item>

</channel>
</rss>

Edited by: Justin Sung