4. Feed - General Requirements and Additional Parameters

Product feed is one of the key components of the personalization platform integration. Recommendations are built based on the product feed. The quality of recommendations directly depends on the quality of the product feed and the amount of information conveyed in it. During the integration process, we will assist you in creating an optimal set of fields that will provide users with high-quality product recommendations within any of the strategies.

Product feed is uploaded to Gravity Field as a file. The file should be available for download via a direct link. The recommended feed format is CSV; however, other formats (like JSON or XML) can also be used but do require writing a parser function in Go language. The parcer will be required for product feeds consisting of multiple files.

CSV Limitations

1. The CSV file delimiter is a comma;

2. The price delimiter in the CSV file is a period (value type - float);

3. The maximum number of characters in a column is 1000;

4. The feed is limited to 1000 columns;

5. Column names must be in lowercase, with only "_" as a special character allowed;

6. If the value contains a comma, the entire value must be enclosed in double quotes ("value");

7. The image_url property must contain an image in the standard size as on category pages (this image will be displayed in recommendation widgets);

8. image_url cannot contain empty values. If there is no image for a specific product, a link to a placeholder image must be provided;

9. All fields with boolean values, except for in_stock, must be filled in the true/[empty] format for correct affinity calculation.

10. Fields with the lng parameter (used for multilingual/multilocal setup) cannot be used for affinity calculation.

When updating the feed, it is only possible to add columns and not delete them. If a feed with a missing column is sent to the system, synchronization will fail.

The feed format must comply with RFC 4180. In particular, with the value escaping format specified in the standard.

Mandatory feed columns

Mandatory columns description

Property	Description	Type	Example
sku*	Unique product identifier	string (up to 256 characters)	12378
group_id*	Identifier of group of products that differ in some product attributes (variants of a single product)	string (up to 256 characters)	124578
name*	Product name	string (up to 1000 characters)	Dresses
url*	Product page URL	string (up to 1000 characters)	https://site.com/clothes/women/dresses/12447
price*	Product Price	float	50.00
in_stock*	Product availability	boolean	true / false
image_url*	Product image URL	string (up to 1000 characters)	https://site.com/image.jpg
categories*	The categories associated with the product from general to specific	String (separator "|" with no extra spaces, up to 1000 characters)	Clothes|Women|Dressses
keywords (optional but strongly recommended)	Additional product information separated by "|". Filling in this property is necessary for calculating product similarity (only for the Similarity strategy). Keywords should be specified from general to specific. When checking for matches, the system removes the last word if the entire set does not match. For example, if the keyword set is "Outerwear|Women|Coat|Black" - if there are no products with the exact same set of keywords, the system will search for products with keywords "Outerwear|Women|Coat" and so on until only the first keyword remains.	String (up to 1000 characters)	brand|style|season

General Description of Additional Column Types

In addition to the mandatory feed columns, there are four additional types of data that can expand your capabilities and improve the quality of recommendations.

1. Data for Visualization of Recommendations: this often includes product rating, review count, or the price of a product before discount.

2. Data Required for Proper Functioning of Recommendations: if, for instance, the cart addition method works with an identifier different from the SKU, this identifier must be added to the feed.

3. Data for Additional Logic in Recommendation Algorithms: for example, if you need to display only products that are available for a credit purchase, an indicator of credit availability for that product should be added to the feed.

4. Data for Affinity Calculation: It's recommended to select product properties that influence users’ buying behavior, are filled for most products (or at least for key categories), and have a limited number of possible values. For instance, for a clothing online store, suitable properties could include "season," "style," "color," and "brand." Unsuitable properties might include "size" (if sizes are not standardized across the site), "country of production," and "fastening type." There's a limit of 10 columns with data for affinity calculation in a feed.

Handling Product Availability in the Feed

We recommend including all products available to users on the website/app in the feed, even those that are out of stock. This enables strategies that offer users alternatives for products currently unavailable.

However, in cases where users potentially have access to all historical products, including those that were discontinued many years ago, it's advisable to limit the inclusion of out-of-stock items in the feed to the last 6 months since they went out of stock.

Additional Feed Parameters and Examples by Verticals

The following parameters are commonly used by our clients, and we've gathered them in the documentation to facilitate feed creation for those new to personalization.

Property	Description	Type	Example
old_price	Strikethrough price for discounted items, only filled for products with a discounted price. NB!: 'price' ≠ 'old_price'.	float	75.00
review_count	Number of reviews for the product.	string	15
rating	Product rating (typically from 0 to 10, equivalent to a scale of 0 to 5 stars with a half-star increment).	string	4
is_sale	If the product is part of a sale.	boolean	true
sale_badge_url	If badges are present on the site, provide the badge image URL.	string	https://site.com/img.png
is_bestseller	If the product is a bestseller.	boolean	true
bestseller_badge_url	If there are badges for bestsellers on the site, provide the badge image URL.	string	https://site.com/badge_img.png
is_new	If the product is new.	boolean	true
new_badge_url	URL of the badge image if a badge is displayed for the product.	string	https://site.com/badge_img.png
in_stock_status	Relative inventory level of the product.	string	low/medium/high
margin_group	Product's margin group.	string	low/medium/high
product_accessory	Field distinguishing between products, accessories for other products, and services provided by the store. Aids in accurate cross-sell recommendations.	string	product/accessory/service
brand	Brand of the product's manufacturer.	string	Samsung

You can also read more about examples of feeds by verticals:

Fashion

Electronics

Telecom

Banking and Fintech

eGroceries

Pets Supplies

DIY

Feed Workflow in Standard Integration

In the context of a standard integration, working with the feed is an iterative process that consists of the following stages:

1. Preparing a Brief Feed Specification: In this step, we create a brief document outlining the information expected in the feed. The list of expected columns is constructed from mandatory columns, columns recommended for the client's vertical, and specific columns recommended for the client. The list includes as much data as possible based on our knowledge of the client and agreed-upon use cases. Often, it's acceptable to start with a feed that doesn't contain all the expected columns and add additional data later as the work progresses.

2. Validating the Feed: The received feed is validated against the general requirements outlined in the documentation and the specifications from the brief. The validation generates a document which suggests recommended changes. In some cases, this stage might involve multiple iterations, addressing issues such as feeds not meeting basic requirements or unexpected values in certain columns (e.g., 10,000 different values in the "color" field due to various spellings, languages, or encodings for the same color).

3. Loading the Feed and Widget Development: Once the feed is technically ready for upload to the platform, it is loaded into the interface, and a task is set for a test widget development. During this phase, additional nuances might be identified, which could lead to the need for adding or modifying columns in the feed.

4. Launching Personalization Cases: With the finalized feed loaded into the platform, you can start launching recommendation widgets and other personalization use cases. However, there are scenarios where additional columns might need to be added to the feed:

   1. Certain personalization cases require additional data, which can potentially lead to feed modifications.

   2. New data might become available for the business, which could be useful, for example, for calculating user affinities.

   3. We periodically revisit the feed and provide suggestions to clients for adding specific information to enhance the platform's capabilities and recommendation algorithms.

Creating the ideal feed is a creative process involving multiple stakeholders on both the Gravity Field and client sides. It's based on a deep understanding of the product assortment, user behavior, and the continuous enrichment of the product database.

A feed switches from the 'Active' status to 'Paused' after three unsuccessful synchronization attempts due to unavailability of the feed or after one unsuccessful synchronization attempt in case of incorrect feed structure.