Best practices¶

The data feed is one of the main parts of the Voyado Elevate integration. The quality will impact the available features, as well as the quality and performance of Voyado Elevate. This page targets both retailers and integrators and contains best practices and guidelines regarding the data feed, as well as how they are leveraged in Voyado Elevate.

Implementing every guideline is not needed to build a great solution, but the more implemented practices, the better the end user experience will be. Follow the listed best practices as closely as possible, and for those outside of reach, don't worry. Voyado Elevate does a lot of automatic data processing to make the best of it!

Integration time savings

Some guidelines relates to data normalization and asset handling which needs to be addressed by retailers if to be implemented. Have guidelines and data accessibility assessed by retailers when needed.
Many content related best practices can be implemented iteratively, enabling going live as fast as possible with room for additional improvements.
Use the Data feed checklist when building the data feed.

Natural key mapping¶

The keys of the product groups, products, and variants should have a natural mapping to something comprehensible on the retailer side. Ideally something like an article number or codes that are both used internally and externally as identifiers for products and product groups. The keys provided in the feed must match the keys provided in the order notifications. For variant keys, SKU numbers should be used.

Feature

If a visitor search exactly matches a key the visitor will be directed to the corresponding product page.
Variant keys as SKU numbers enables an integration with Voyado Engage.

Release dates¶

The release date of a product indicates how new a product is considered to be. The release date should correspond to when the product is made available for purchase. Release dates are highly recommended to be provided in the feed when possible.

Feature

Newness of a product is considered when ranking products.
The NEW product badge can be used when a release date is provided.
Products can be sorted by newness.
Dynamic product selections can be created based on newness.

Cost¶

Supplying the cost of products allows Elevate to optimize on profit as well as present profit metrics in statistics interfaces. The cost can be supplied either as an attribute on variants in the data feed, or it can be notified at time of purchase in the order notification. A retailer should select the approach that is easiest for them to supply cost information to Elevate.

Note

Cost is expected to be a non-zero value smaller than the selling price. Purchases not meeting this requirement will be ignored during profit calculation.

Feature

Profit optimization as business objective, optimizing all product listings towards profit.
Profit as an included aspect in various statistics

Images¶

The recommendations listed below regards image management and image creation. These can favorably be considered when taking new pictures of products as well.

Missing images¶

If an image is missing, do not provide an actual image of something indicating a missing image, e.g. let the provided image URL point to a 404. Images that are missing will be handled by the image analysis, and custom images for indication of missing images should be handled through a client side action.

Feature

Products with broken imagery are automatically buried.

Multiple product images¶

Supply all available images for each product and differentiate images by supplying image tags. Image tags will facilitate merchandisers to differentiate between image types such as primary, full, front, back, side, and detail images.

Feature

Providing multiple images enables product card features in the Experience app such as alternate images on hover and showing image galleries.

Providing multiple enables automatic image fallback for broken or missing images.

Multiple image resolutions¶

Supply all relevant resolutions of each image. It is highly recommended to supply images in resolutions suitable for thumbnails, mobile listings, as well as for desktop listings. Even if you plan to resize the images dynamically, Elevate needs high resolutions for image analysis and low/mid resolution (larger than 100 and smaller than 1000 pixels wide) for rendering products in the app. Widths can be provided if they are known otherwise widths will appear after a while when our image analyzer have ran.

Image type separation¶

For retailers with highly structured image assets, advanced image imports including image type information (especially for cutouts) is recommended. A cutout image is an isolated image of solely the product, typically with a single color background.

Feature

Performance gains with a faster color analysis of new collections as cutout images can be analyzed significantly faster than other image types.

Cutout guidelines¶

Cutout images refers to images where only the product is represented, e.g. without a model or other additional products. If there are multiple cutout images for each product to choose from, select the ones that best adheres to the recommendations below.

Portraits the entire product as accurately as possible.
Avoid sharp edges in the background.
Avoid shadows on the products.
Homogeneous background colors for all products. Images are however not required to all have the same background color.

Feature

Product colors are automatically extracted and allows Elevate to retrieve a very complex view of the colors, with detailed nuances as well as the color distribution. This in turn enables a very powerful color search, color filtering, and precise color swatches.

Cutout imagery provides the fastest and often the most accurate color distributions.

Consistent image ratio¶

All images provided should ideally have the exact same ratio. The height of the rendered product cards will be the same to avoid alignment issues, meaning that inconsistent image ratios will lead to clipping.

Clean imagery¶

Keep the images clean and separate from functionality and information that belongs elsewhere. Avoid overlays, badges, padding, etc. built into the images.

Providing metallic colors¶

Provide metallic properties in color_default for products that are Gold or Silver. Metallic properties cannot be found through color analysis and must be tagged manually.

Feature

Correct presentation of products with metallic properties.

Providing regular colors¶

For retailers with extremely high product turnover, providing colors manually can be beneficial to ensure products are provided with a color prior to the color analysis is completed. Colors can also be manually set if the automatic color analysis should happen to be unsatisfactory for specific products.

Colors must be provided as exactly Gold, Silver, Multi, or a valid RGB hex code. When used, always strive to provide as detailed nuances as possible. Multiple colors can be provided and will be considered to be an evenly distributed color representation.

Feature

Performance gains with initial color values supporting color search, color filtering, and color swatches available before the automatic color analysis is completed. Will be replaced with more accurate representations by the automatic color analysis unless using color_override, which is not replaced by the color analysis.

Text attributes¶

Product titles¶

Do not include the brand (or other redundant information) in the product title. Brands can be presented and styled separately in product cards. Product titles should ideally be kept short as long titles may be clipped for mobile visitors.

Displaying the color of a product in the product title is often not necessary as it is displayed in the image. One exception where it is useful is if the retailer has a set of specialized custom colors that are well known among the visitors. In this case, place the color name at the end of the title. Placing the color in another position will result in that the title flickers when the visitor hovers over the different colors.

Clara T-shirt - spirit green
Clara T-shirt - dreamy pink
Clara T-shirt - real teal

Categories¶

Use the categories attribute to define a products place in a product-based categorization hierarchy. Each level in the hierarchy is defined by the greater than-sign, >.

<categories>yardwork > gardening tools > chain saws</categories>

For more information, see Categories.

Custom attributes¶

Custom attributes are used to enhance search, to provide facet and filter options for both search and navigation, and as a basis for creating product selections.

Provide any non-standard data that is useful for search, facets, filters, or product selections as custom attributes. Standard attributes include department, price, size, color, categories, and brand. Examples of useful custom attributes include season, style, material, product_shape, category, buttoning, neck_type, sleeve_length, etc. Note that the standard attribute categories is primarily for specifying the product-based categorization of a product. Custom attributes are preferred to be used for category related product selections or filters.
Use typed custom attributes to enable type specific features, such as range facets for length and number type attributes.
Use the json type attribute when you have purely presentational data that is unsuitable for search and filters.
Send as structured data when possible. "A short summer party dress" can be used in more ways when also provided as additional separate attributes rather than only in a single description, e.g. dress_length: short, occasion: party and season: summer.
Provide as high granularity as possible of available values. Supply both Pants and Capri pants or Leggings as opposed to only Pants when available.
Normalize values. Avoid having "Long dress", "long dress", and "Long dresses" in different products, when describing the same property.
Use custom attribute values that are not often changed for product selections.
Supply display names in the data feed for custom attribute values where identifiers are not human friendly. The following illustrates the syntax of the category Jackets with an external id 361: <category name="Jackets">361</category>.
When there is a pipe, (|), that is a part of for example a category name, such as Activities | Hiking | Shoes, do not forget to escape any pipe characters. If not, the contents of the attribute will not be interpreted correctly. This includes, but is not limited to, Product type extraction and Facets.
Custom attribute names should be in English and consistently named across markets.
The name of the custom attribute is not considered for search or classification. Therefore, it's important to avoid attributes like windproof with the value true. Instead, use an attribute called features with the value windproof.

Product selections and stable values¶

A product selection is a defined set of products. Product selections are used in boost, bury, and pages nodes and are often rule-based. The rules consists of including or excluding products where an attribute has a specific value. The attribute values are treated as identifiers, meaning that only products with those attribute values are included in the selection. If the attribute values on the products change, the products will no longer be part of the selection.

Keep track of changes

It is important to keep in mind what fields are used in a product selection and when/if they are changed. It is important that these values are stable and not changed often.

Departments¶

Make sure department values in products are stable and not changed often. Common department values for fashion are Women, Men, and Kids. For a single department retailer, all products should have the same department value, or consider switching to well-defined categories.

Using departments is optional. If you don't have departments, use categories instead.

Content¶

Provide content items for vital pages of high client interest. Typical pages recommended to include are: Returns, Shipping, Delivery, Contact, and Stores. Use the Search phrase report in the Experience app to keep track of popular search phrases.

Sizes and fraction handling¶

State fractions with a single character. For the shoe size 42 and a half, use 42 ½ or 42½.

Supported fractions: ½, ⅓, ⅔, ¼, and ¾.

Using product list templates¶

While only tangentially related to the data feed, it is highly recommended to use a template to control which imported attributes Elevate should return in requests to the Storefront API. This is useful to reduce response sizes, or when you wish to include attributes that would not be included by default, such as custom attributes.

Data feed check-list¶

The following check-list should be used when creating the data feed.

Premium integration

Items marked as Premium are dependent on retailer data that in some cases are difficult to access. These can be seen as guidelines for future retailer data curation projects, when not possible to implement right away.