Feeding data to Hello Retail: Best Practices
Best practice example
As a general principle, the Hello Retail solution can only be as good as the supplied data allows. Therefore it is important, that you provide product information in a structured fashion that enables us to read and use it “as is”. In order to make this process as seamless and error-free as possible, you should use the following standard:
The product feed should contain ALL of the products that Hello Retail should be able to handle.
- Example: If your shop contains 2000 products, and if Hello Retail is to be able to make meaningful product recommendations, then all of these 2000 products need to be present in the feed.
- Example: If your shop contains 2000 products, and 500 of these have variations (different size, color etc.), and if Hello Retail are to make these either searchable or available as recomendations to other products, then all masterproducts as well as their variations should be present in the feed.
- Example: If you shop has 2000 products and all of these have variations, BUT you only want Hello Retail to show and recommend the master-products, the feed should only contains these products and not their variations.
Product changes on the site should be reflected in the feed. The needed update frequency will vary from shop to shop, depending on individual requirements, but we will read the feed accordingly, after which the information will be updated on our side also.
The urls of the individual product should be EXCACTLY the same as can be seen on the site – so if you have special redirect/replace-rules for how urls behave in browser, these should be considered when giving us the feed.
- Example: If a given product url is defined as www.example.com/men/shirts/blaa--skjorte.html in shop system but is “seen” as www.example.com/bla-skjorte.html (either in browser, in open graph tags, in canonical tags or similar), then it is the second version of url, that should be made available to us in the feed.
Metadata about the product should ideally be the same as is used on the site, and not necessarily as it might be defined in your shop database.
- Example: A shirt has been assigned the following categories in shop system: “Female”, “Denim”, and “New arrivals” – but on site you navigate to the product through “For Women” > “Practical outfit” > “Shirts”, then it’s the second version that should be made available to us in the feed.
If a given product can be reached through different categorical paths, then ALL of these should be present in the feed, in the following structure (Here we use an example where the product resides in different categories, and we indicate the hierarchies like this):
<hierarchies> <hierarchy> <category>Frontpage</category> </hierarchy> <hierarchy> <category>Female</category> <category>Denim</category> <category>New arrivals</category> </hierarchy> <hierarchy> <category>For Women</category> <category>Practical outfit</category> <category>Shirts</category> </hierarchy> <hierarchy> (...) </hierarchy> </hierarchies>
If you have different currencies on the same site (and want Hello Retail to display different prices depending on user’s selection), we would also like to have this included in the feed, in a unique tag for each currency.
So the structure of the feed overall, should follow this format:
<products> <product> <url>http://www.example.com/pathToProductOnSite.html</url> <title> (title of product) </title> <imgurl>http://www.example.com/pathToProductImageOnSite.jpg</imgurl> <price>149.00</price> <oldPrice>219.00</oldPrice> <productnumber>106076</productnumber> <hierarchies> <hierarchy> <category>Frontpage</category> </hierarchy> <hierarchy> <category>Female</category> <category>New arrivals</category> </hierarchy> <hierarchy> <category>For Women</category> <category>Practical outfit</category> <category>Shirts</category> </hierarchy> <hierarchy> (...) </hierarchy> </hierarchies> <keywords> (data that should be available for search) </keywords> <instock>true</instock> <description> (description here...) </description> <brand> (optional, but preferred if used by shop) </brand> </product> <product> (...) </product> </products>
We also would like to have the purchased products returned to Hello Retail through a conversion span, on the checkout page. This will enable us to map sales to actual products, which can be used as a basis of Hello Retail product recommendations. The required format is as follows:
<span class="addwish-conversion" style="display:none;" data-ordernumber="20323" data-total="6198.45" data-email="firstname.lastname@example.org" > <span class="addwish-product" data-unit-price="1699.95" data-url="http://example.com/shop/UltraBlender-2000.html" data-productnumber="10-800-1234" ></span> <span class="addwish-product" data-unit-price="149.95" data-url="http://example.com/shop/NoFall-Solid.html" data-productnumber="8-304-9876" ></span> </span>
In addition to sales being made AFTER Hello Retail was present on your site, we can also include purchases made before this time, by reading an order-feed, in the following format:
<orders> <order> <ordernumber>12345</ordernumber> <date>2016-09-30 15:47:46</date> <total>1542.95</total> <product>the product number of product X (same as is used in product feed)</product> <product>the product number of product Y (same as is used in product feed)</product> <product>the product number of product Z (same as is used in product feed)</product> <!-- More product numbers... --> </order> <!-- More orders... --> </orders>
In order for Hello Retail business to be able to see what customers add to the basket/cart, you should set up cart tracking, find more info about that here.
Empty search page
If Hello Retail is to make a search function on your site, we need a url to a page without any content (so, header, footer and possible navigational tools will typically be the same as on other pages on site, but should contain a region where Hello Retail can injects search results)
Additional information on site
- Alternative product id’s. Sometimes, the add-to-basket method uses a different value than the productnumber mentioned previously, which might be a shop-specific product ID. If that is the case on your site, you should make the product ID available to us.
- Inserting elements on your site. Ideally the sites markup should enable Hello Retail to look for specific classes and ids, when choosing where to place elements, or where to pull additional data from. If for some reason that is not the case, we would ask you to add empty elements to your page for us to place the Hello Retail content into.