In this article you will read about:
- Supplying the data
- Valid feed format
- Existing product feeds
- Delivering the feed
- Deciding which data to send
- Feed content
- Associated products
- Incremental feeds
- Content feeds
- Feed generation tools
- Examples
Supplying the data
In order to set up Spotler Activate Search, it requires a data feed that contains as much meta-data as possible. This feed has to contain all the data you want to search and filter on. The feed also has to contain all the information you want to show to your user.
We will describe the fields that are required, the format the feed has to be in and how you can deliver your feed to us.
Valid feed format
Spotler Activate Search only supports XML encoded with UTF-8. For files larger than 10MB, we recommend sending them in a compressed GZIP format.
If your web server automatically uses GZIP to compress its output, no further actions are required. For XML files that are compressed by an application, the URL should end with '.gz'. If the URL already contains a GET parameter, then the 'extension' can be supplied by using an extra parameter.
For example:
http://www.example.com/feed/export.php?type=xml&compress=1&extension=.gz
Existing product feeds
If your site already contains a data feed with meta-data, this feed could already be compatible with Spotler Activate Search. Spotler Activate Search can re-use lots of pre-existing data feeds. An example of this is the feed generated for Google Merchant Center or Amazon.
Keep in mind these feeds only contain the meta-data for the platform they’re made for. To use Spotler Activate Search to full potential, we recommend extending the feed with additional data.
Delivering the feed
Your feed has to be hosted on an HTTP server that can be reached from the Internet.
It’s possible to use HTTP with SSL encoding. Spotler Activate Search supports Basic and Digest HTTP authentication. This can be used to secure your feed, so non-authorized users cannot access it.
At the moment Spotler Activate Search does not support any push methods, where the client pushes the feed to Spotler Activate Search. This may change in the future.
Deciding which data to send
There are lots of different kinds of information you may want to be adding to add to the feed. This could be for adding search terms, qualities to filter on, attributes to sort by, or display in the product tiles.
- What filters are you using on your product overview pages?
- What information are you using for your menu structure?
- What information are you showing on your product detail pages?
- What business rules does your organisation use in adding and structuring your catalogue?
- What fields would I like to contribute to the priority of my ranking? You could think of fields like stock status, review scores, profit percentage, or return rate.
Feed structure XML
The supplied XML file should adhere to a couple of requirements:
- You can use your own names when naming the fields, as long as each corresponding field uses the same name. For example: <item>
- All meta-data for an item should be on the first level of the XML file under the item node. Exceptions to this rule are nodes that contain multiple values, like colors, sizes, or categories. These values can be stored in a sub node.
- Each item has to contain a unique ID field. The ID may contain alphanumeric characters. If a product has multiple variations, each variation of the product should have its own unique ID. This can be done by appending the variation name to your primary product ID. When you have more than one feed, the ID will need to be unique for all feeds of your Spotler Activate Search project.
- The use of HTML in your data is not supported. Although Spotler Activate Search will do its best to clean-up your data, it's best to remove all HTML from your data feed.
- Date values should use the RFC3339 format. All timings should be in the UTC time zone.
Example: 2012-02-31T15:00:00Z - Each item should at least contain an ID, title, and URL.
- Only use absolute URL's; include the protocol and domain name.
Example: http://www.example.com/article-1.html - URL's and values containing markup should be contained in CDATA nodes.
- Floating point numbers (like prices) should use a dot for the decimal. Example: 9.99
- Although XML attributes are technically valid, Spotler Activate Search won't be able to extract any information from them. If there is relevant information in the attribute, please substitute it by an XML element.
- To show the price of a product you need at least the price for which it is sold. This field needs to be used for basic field ‘Price’. If your product is discounted you can link a price attribute from the feed to the basic field ‘Normal price’, that will then show striked-trough. You can find the basic fields settings via: https://my.sooqr.com/data/data-fields/basicfields
- If meta-data is not available for a particular item, you can remove the data-node from the output for this item. This will also reduce the size of the feed.
- Spotler Activate Search is able to combine content and products. However, you will have to add an additional node to distinguish between the types of items.
Example:<type>product</type> or <type>CMS</type>Although it is possible to add content items to the product feed, it is recommended to keep these in a separate feed. - We recommend validating your XML file before uploading it to Spotler Activate Search, to avoid faulty data. You can validate XML files at online validation tools, like: The W3C Markup Validation Service.
Feed content
The feed contains all the information that Spotler Activate Search will use for searches. Each separate result you want to show to your users should be a separate item in your feed. He item can be anything from a news article to a product.
The feed may contain more information than required. Information that is not used by Spotler Activate Search will be ignored, but we recommend keeping the feed as small as possible. This will improve the index time and refresh time of your feed, and speed of the results.
When you are creating your feed, please think about the use of your Spotler Activate Search tool. What do you want to be found and what would you like to show? This will further determine the structure of your feed.
The following examples are based on a web shop that supplies multiple products. Each product can have multiple variations. The way you want the variations to be shown, determines how your feed should be set up.
- If each variation differentiates based on only one variable or has multiple variables that are not linked to each other, then the product should only be in your feed once. The variables can be supplied by using multiple values for a node. For example:
<colors>
<color>Blue</color>
<color>Green</color>
<color>Red</color>
</colors>
<sizes>
<size>S</size>
<size>M</size>
<size>L</size>
</sizes>
- If a product has variables that are only available in a specific combination, then each combination must be a separate 'product' in the feed. This would also be the case if a product variation has a different URL or image.
For example:
<color>Blue</color>
<size>XXL</size>
Associated products
A product can have multiple variations, as previously shown. For example, the T-shirts sizes and colors. If these products all belong to the same parent product, we can specify that these products are variations.
The parent product, in this context, is the product as it is shown on your product overview pages. This is what the customer clicks on to navigate to the product detail page. The child product, by contrast, is the specific combination of characteristics selected on the product detail page, that lead to a purchasable product variation. An example of this is shown below, in the XML example.
This is done by adding an Association ID. It’s also required to indicate which product is the parent of this group. In the example below, the product with ID 12 is the parent of group 12345, which the product with ID 13 is also in. For example:
Parent product:
<id>12</id>
<assoc_id>12345</assoc_id>
<is_parent>1</is_parent>
<title>Hawkeye Aviators</title>
Child products:
<id>13</id>
<assoc_id>12345</assoc_id>
<is_parent>0</is_parent>
<title>Hawkeye Aviators Black M</title>
<color>Black</color>
<size>M</size>
Incremental feeds
A data feed may contain values that change often, like stock-status and price. If you want to update these values more than once a day, you should use an incremental feed. This feed only contains a part of the complete data feed and will be updated more often. You should always check that the field names and the unique ID correspond with the data in the main feed to make sure it’ll update the correct fields.
In an incremental feed, you have to provide the IDs of items you want to change the information of. IDs of items that are not being adjusted should not be added to the feed.
To remove an item using your incremental feed, simply provide only the item ID attribute and no other attribute in the incremental feed. Spotler Activate Search will see the empty item and remove it from your Spotler Activate Search.
Incremental feeds
Are also know as "delta feeds" or "delta update feeds".
Content feeds
In addition to feeds containing product information, you may wish to add a feed containing content page information. Examples of such pages could be contact detail pages, frequently asked questions, blog articles, or an “about us” page. This information can be conveyed to Spotler Activate Search using content feeds, also known as CMS feeds.
These feeds follow grossly the same structure as product feeds do, with the exception of product-related data such as price, brand, and category, which content feeds do not include. In using a content feed together with a product feed, it is important to keep in mind that the IDs still need to be unique between feeds. In most cases, this can be resolved by prefixing the IDs in your content feed with “cms-“ or “content-“. Furthermore, the field labels for the fields in the content feeds need to be exactly the same as in your product feed. For example, if the label for the title field in your product feed is “title”, it should be “title” in your content feed as well, and not “name” or “heading”. This is because they would otherwise be indexed as separate fields, leading to issues in searching, filtering, sorting, and display issues in the product overlay.
Additionally, if you have grouping activated, it is important to include a unique association ID for each individual content item as well. This is to ensure that the content items will not be grouped under one item, as would be the case if no association ID is provided to the content items. As each content item will have a unique association ID, however, it is not necessary to add an is_parent-field to the content feed; as every association group will only contain one item, it will always be the one shown in Spotler Activate Search.
Feed generation tools
Most CMS platforms offer tools to generate data feeds, several of which have an extension designed specifically for Spotler Activate Search integration. Below is an overview of tools we suggest for generating feeds per platform, as well as some platform-independent tools. Do note that there are many feed generation tools out there, many of which are capable of generating an XML feed suited for use with Spotler Activate Search.
Platform | Suggestions |
---|---|
Magento 2 | Sooqr Connect by Magmodules |
CCV-shop | Spotler Activate Search by Webshopkoppelingen.nl |
Lightspeed | Manual guide by Lightspeed |
Logic4 | Sooqr/Spotler Activate Search by Logic4 |
OpenCart | Syndication |
Prestashop | Spotler Activate Search by Gett |
Shopify | FeedGeni, DataFeedWatch |
Shoptrader | Support page by Shoptrader (Dutch) |
Shopware 5 | Spotler Activate Search by Sition |
Shopware 6 | Product Feed Generator, manual guide by p16r |
WooCommerce | Product Feed PRO, CTX Feed |
Platform-independent tools | Channable, Koongo, EffectConnect |
Examples
Valid XML product feed
<?xml version="1.0" encoding="utf-8"?>
<items>
<item>
<content_type>product</content_type>
<id>337</id>
<mpn>ace000</mpn>
<title>Aviator Sunglasses</title>
<description><![CDATA[The Aviator sunglasses.]]></description>
<link><![CDATA[http://demo.sooqr.com/sunglasses.html]]></link>>
<image><![CDATA[http://demo.sooqr.com/ace000a_1.jpg]]></image>>
<price>250.00</price>
<normal_price>275.00</normal_price>
<currency>usd</currency>
<gender>Male</gender>
<brand>Sooqr</brand>
<stock>7.0000</stock>
<in_stock>1</in_stock>
<material>solid rock</material>
<category0>Accessories</category0>
<category1>
<node>Eyewear</node>
</category1>
<assoc_id>5</assoc_id>
<is_parent>1</is_parent>
</item>
<item>
<content_type>product</content_type>
<id>338</id>
<mpn>ace001</mpn>
<title>Jackie O Round Sunglasses</title>
<description><![CDATA[The Jackie-O sunglasses.]]></description>
<link><![CDATA[http://demo.sooqr.com/jackie-o.html]]></link>>
<image><![CDATA[https://demo.sooqr.com/ace001_1.jpg]]></image>>
<price>225.00</price>
<normal_price>275.00</normal_price>
<magento_store>default</magento_store>
<currency>usd</currency>
<gender>Female</gender>
<brand>Jackie-O</brand>
<stock>19.0000</stock>
<in_stock>1</in_stock>
<country_of_origin>Malaysia</country_of_origin>
<category0>Accessories</category0>
<category1>
<node>Eyewear</node>
<node>Summer</node>
</category1>
<assoc_id>5</assoc_id>
<is_parent>0</is_parent>
</item>
</items>
Valid incremental feed
<?xml version="1.0" encoding="utf-8"?>
<items>
<item>
<content_type>product</content_type>
<id>337</id>
<price>200.00</price>
<normal_price>275.00</normal_price>
<stock>2.0000</stock>
<in_stock>1</in_stock>
</item>
<item>
<content_type>product</content_type>
<id>338</id>
<price>195.00</price>
<normal_price>275.00</normal_price>
<stock>7.0000</stock>
<in_stock>1</in_stock>
</item>
<item>
<id>339</id>
</item>
</items>
Valid content feed
<?xml version="1.0" encoding="utf-8"?>
<channel>
<title>Content feed</title>
<link><![CDATA[https://magento-demo.sooqr.com/sooqrcontentfeed]]</link>>
<pubDate>Fri, 18 Nov 2016 11:58:26 UTC</pubDate>
<items>
<item>
<content_type>content</content_type>
<id>cms-337</id>
<title>Contact us!</title>
<description><![CDATA[You can reach us via phone, email, WhatsApp, and LinkedIn.]]></description>
<content>Page</content>
<link><![CDATA[http://demo.sooqr.com/contact_us.html]]</link>>
<image><![CDATA[http://demo.sooqr.com/contactus.jpg]]</image>>
<assoc_id>1005</assoc_id>
</item>
<item>
<content_type>content</content_type>
<id>cms-338</id>
<title>Frequently asked questions</title>
<description><![CDATA[Many of our customers have asked these questions. Perhaps they can help you answer yours!]]></description>
<content>Forum</content>
<link><![CDATA[http://demo.sooqr.com/faq.html]]</link>>
<image><![CDATA[https://demo.sooqr.com/faq.jpg]]</image>>
<assoc_id>1006</assoc_id>
</item>
</items>
</channel>