Compare+ Plugin Documentation

  • Version: 2
  • Last Modified: 27/01/2014

Thank you for purchasing our Compare+ Price Comparison Plugin. If you have any questions that are beyond the scope of this help file, please feel free to email us on support@awesem.co.uk or visit our Theme Support Forum. Thanks so much!

Test Drive Demo Buy

1 – Compatibility requirements

Processing product feeds is a pretty intensive job and you will need to have a powerful server when you intend to run this plugin with very large XML feeds containing thousands of products. This obviosuly has an impact on performance. Your server might be able to process e.g. 10,000 without any problems but is likely to struggle with a feed that has 40,000 products.

We advise you to start off small and limit the number of products included in a feed at source. Most affiliate networks provide an interface where you can customise your feed and we suggest to include only a couple of categories to start with until you find your server’s limit. There is little point in selecting every single product for an online book retailer as the 100,000+ products are most likely going to exceed your server’s limits.

We also added a limit field in the feed management page so that you have another way of limiting the number of products getting processed. This is a useful feature which you should use when you are setting up your first product feeds and learning your way around the system. Only have a couple

Here is a list of compability requirements for our Compare+ plugin:

  • Compare WordPress theme installed
  • WordPress v3+
  • PHP Version 5 or newer
  • Module libxml
  • Extension xmlreader
  • Extension simplexml
  • Option “allow_url_fopen” set (or adjustable) to 1
  • Option “max_execution_time” set (or adjustable) to 1
  • Option “memory_limit” set (or adjustable) to 512MB or more

Your server compatibility is checked when the plugin is loaded and there might be problems when the minimum requiremens are not met.

system-requirements

Values you can also check if you are on shared hosting to determine how well your site will run:

  • Max script execution time
  • Max script execution time at 100% CPU
  • Max memory per script
2 – Getting started
  1. First of all, you need to make sure that you have our Compare WordPress theme installed as this plugin does not work on its own. You can check this under “Appearance > Themes” in the siderbar.

  2. It is highly recomended that you set WPLANG variable wp-config.php in the root folder of your WordPress installation. Open your wp-config.php file in a text editor and search for define (‘WPLANG’, ”);
    Edit this line according to the language used in your feeds, e.g. for French you need to add define (‘WPLANG’, ‘fr_FR’);

  3. Check your system compatibility by clicking on the plugin menu. Try to address any problems that are being highlighted and you might have to raise these with your hosting provider (→Compatibility requirements)
  4. Now you need to think about your product feeds. Typically, you can find product feeds within the admin area of affiliate networks such as AffiliateWindow, Commission Junction, Tradoubler or Zanox. Alternatively, you could consider feed provider such as Fusepump who offer a number of feeds using the same feed format across different affiliate networks. This has the benefit of only having to set a single parser that you can reuse for all feeds available at Fusepump.

    Please note that Compare+ works for Retail feeds only where you have a product, brand, image, price and deep link URL. Compare+ DOES NOT support travel feeds where you have hotels, rooms and destinations. Similarly, mobile phone tariff feeds are also NOT supported by our Compare+ plugin.

  5. Once you established what feeds you are going to use and where you are going to get them from you can start planning your Product Categories. Each feed and retailer have their own way of naming their categories. In your price comparison you probably what to map these to your own product categories. For example, a retailer might have called a category “Apple Tablets” but you rather call it “iPads”. Product mapping would allow you to do this and you should briefly plan out your desired categories first.
  6. In the WordPress admin sidebar, under Products > Categories, create the product categories you want to appear on your website, e.g. Phones > Smartphones or Tablets > iPads. You need to create top-level categories and then attach a number of sub-categories.

    Please note that products will always get mapped against the sub-category (e.g. Smartphones or iPads) and not against the top-level category (Phones or Tablets).

  7. Next you need to set up the parser for your XML or CSV feed. Typically, you only need to set up one parser per affiliate network as the feeds share the same XML structure. The menu item Compare+ > Parser Management is where you define the structure of the feed. Please refer to the → Parsers section.
  8. Now that you created your first parser you can add a feed that uses this new parser. Under Compare+ > Feed Management you create your first feed (→ Product Feeds). You should consider setting a product limit while testing the feed and learning to understand how the Compare+ Price Comparison system works. To complete feed setup you need to import the products manually by clicking on the “import” link (only required for feed setup).
  9. After the feed has been imported (a couple of seconds or minutes, depending on feed size), go to the Compare+ > Category Mapping menu and click on the Initial Mapping Tool button
  10. Map the categories found in the feed to the categories you have previously created (→ Category Mapping)
  11. Add a second product feed and follow step 6 to 9 again
  12. Go to the Compare+ > Product Mapping menu and click on the Initial Mapping Tool button where you can map products to another product so that the same products but with slightly different names get associated with each other (→ Product Mapping)
  13. Manually import feeds or wait for the next automatic import done by the WordPress cron job
  14. The price comparison system should be up and running now!

Please note that products won’t appear on your website until the category and product have been mapped. However, it is possible to “force” the category and product import. We do not recommend this as you will end up with thousands of produts each listing only a single retailer.

Another point to note is that products with the same EAN number will be associated with each other automatically, but you need to have mapped the category for them to get imported.

3 – Product Feeds

Feeds are essentially a list of products from a merchant or retailer, typically made available by affiliate networks (e.g. Belboon, Tradedoubler, Zanox etc) and sometimes provided directly by the retailer.

Product feeds contain product information such product id, name, deeplink, image URL, category and price. You can download the feed using the download URL provided by the network or retailer. To open the feed you can use a text editor such as Scintilla. For smaller feeds you can also use Internet Explorer as it nicely renders the XML elemets. Once the feed is loaded you can examine the fields and you need to take a note of the field name for the parser setup. (→Pariser Management)

In regards to categories, some feeds provide a list of categories separated by a character (eg: “,” or “>” or “/”). You need to determine if there is a separator and if the sub-category name appears towards the left or the right (left or right).

“Streetwear > Men > Shirts” – the sub-category “Shirts” is on the right.

In Compare+ v1.0.7 we added subfeed functionality which requires Compare v.1.0.10 or later versions.

Our new Subfeed functionality allows you to create a feed that will be linked to its master feed and its products will be attached under the master feed’s retailer name. If the master feed and subfeed contains the same product it will show only once. A master feed cannot be a subfeed of other feed.

Notice: Compare+ uses WordPress cron jobs in order to automaticaly import your feeds, but WordPress triggers the update only when someone visits your website. If your website has no trafic, you should set up your own cron job to ensure that the product database is updated every day. Also note that triggering the cron job does not slow down the session of the user that triggered the cron job. Please refer to the WordPress documentation for further details or have a look at this WP Tuts article.

Feed Management

This screen lists all your feeds set up in your price comparison system. You can manually import, edit or delete your feeds on this screen. In order to add a new product feed, click Add new feed at the top next to the heading.

Here we also display some statistics about your feeds, such as the number of products that have been created, ignored or have failed.

Add Product Feed

Adding a product feed is pretty straightforward and the main thing you need to have is the feed URL. For further information we provide on-screen tooltips on all input fields.

4 – API Setup

The Compare Plus plugin now allows you to import products directly from Amazon via Amazons API and Tradedoubler via the Tradedoubler API.


To take advantage of this for the Amazon API you must first sign up for the Amazon Affiliate Program and also the Amazon Product Advertising API. Once the you have signed up you will receive emails from Amazon detailing how to receive the relevant information they need to setup the API management part of Compare Plus. (You will need to tell Amazon the name of the website you are setting up, Amazon may take upto a day to send you the verification email). Please take care when adding these settings, also please test your site to make sure sales are being tracked and that you are earning from the sales that you make.


One thing to note is that your associate ID must relate to the locale you are pointing to in your feeds. See https://affiliate-program.amazon.com/gp/associates/help/t22/a13 for details.

To setup the API in the plugin you then go through the following steps


  • Navigate to Compare+ >API management
  • Click on Edit And Activate to the right of the Amazon logo.
  • The first tab is Compare API Settings, there is no need to change the settings here as they have been defaulted in for you. Click on the Amazon API Settings tab, this is the first section that needs to be completed.
  • API API Key: This is the Key Amazon describe as the Access key
  • API Secret Key: This is the Key Amazon describe as the secret key **Remember once you have been given your access keys by Amazon you won’t be able to retrieve them again. Therefore please keep these in a safe place.
  • API Feed Location: choose from de, com, co.uk, ca, fr, co.jp, it, cn, es
  • API Associate Tag: This is the code Amazon refer to as your Tracking ID

5 – API Feeds
Once the API has been setup you can then create an API feed. To do so the you must go through the following steps

  • Navigate to Compare+ > Feed Management.
  • Click on the Add API Feed towards the top of the screen.
  • Feed Name
    • Enter a name for the Feed
    • Feed Parser
    • Select the Amazon option
  • API Feed Min Price
    • Input a minimum price
    • Please note if you plan to add a category to the categories field then you cannot enter a minimum price
  • API Feed Max Price
    • Input a maximum price
    • Please note if you plan to add a category to the categories field then you cannot enter a minimum price
  • API Feed Availability
    • If you wish to only retrieve products that are in stock type in the work Available, otherwise leave this field blank.
  • API Feed Keywords
    • Type in the keywords related to the products you are looking to bring back from Amazon. Each keyword should be separated by a comma.
  • API Feed Brand
    • Type in the brand you wish to search for, if there is no specific brand then please leave this field blank.
  • API Feed Condition
    • Please enter one of the following
      • New
      • User
      • Collectible
      • Refurbished
      • All
  • API Merchant ID
    • An optional parameter you can use to filter search results and offer listings to only include items sold by Amazon. By default the Product Advertising API returns items sold by various merchants including Amazon. Use ‘Amazon’ to get only items sold by Amazon.
  • Max Products
    • Enter here a number if you wish to cap the number of products returned from the Amazon API
  • Feed Description
    • Enter a description for your feed. An example might be Amazon Watch’s feed.
  • Categories Separator
    • This can be left blank for the Amazon feed
  • Sub-Category Position
    • This can be left as Right for the Amazon feed
  • Categories included
    • A list of categories on which you would like to search. In a non Amazon feed you can have more than one category, for Amazon you can only specify a maximum of 1.
  • Products to exclude
    • If there are some products you wish not to be retrieved from the Amazon API you can enter their names here. Enter a name one at a time, after each hit Enter to add it to the list.
  • Use default brand name
    • If the products being returned from the API don’t have a brand returned you can tick this box and a further box will appear
  • Default brand name
    • If a product is returned via the API without a brand name this default name will be attached to that product.
  • Use this feed to get master product description
    • As this is a price comparison product you are likely to have many feeds picking up the same product. If you want this feed to provide the master description for a the products it retrieves check this box. You may wish to use this if other feeds do not contain as high quality content as this one does.
  • Force product import
    • We strongly recommend that this is set to no and that you follow the process of mapping all products manually. If this is set to yes all products will be imported without mapping.
  • Force categories import
    • We strongly recommend that this is set to no and that you follow the process of creating and mapping all categories manually. This reduces the likelihood of a rogue feed messing up the data within your site and keeps you in control.
  • Retailer Name
    • Enter the name of the retailer associated with the feed. Each feed in Compare+ should be associated with only one retailer.
  • Retailer slug
    • Enter the friendly name for the retailer entered in the Retailer Name field.
  • Retailer URL
    • Enter the website address of the retailer attached to this feed. This needs to be the full URL including http://.
  • Hit the “Add New Feed” button.


Considerations for the Amazon Feed

Amazon has many many quirks in it’s API, for example each feed you use will only ever return 100 products. Therefore to have more than 100 products returned you may have to create different sub feeds for Amazon each with a different price range.

Also there are various combinations of values which you cannot have, if you include these in your feed you will get an Amazon error when you come to import it. Here are a couple of examples

Amazon error: Your request contained a restricted parameter combination. When SearchIndex equals All, MinimumPrice cannot be present.

This error means you cannot have a Minimum Price selected when you have not chosen any categories in the feed setup. To fix this either delete the minimum price entry in feed management or add a category.

Amazon error: The value you specified for Availability is invalid. Valid values include Available.

This error means that in the Feed Availability field the only option you can enter is Available.


Possible Categories

‘All’,'Apparel’,'Appliances’,'Automotive’,'Baby’,'Beauty’,'Blended’,'Books’,'Classical’,'DVD’,'Electronics’,'Grocery’,'HealthPersonalCare’,'HomeGarden’,'HomeImprovement’,'Jewelry’,'KindleStore’,'Kitchen’,'Lighting’,'Luggage’,'Marketplace’,'MobileApps’,'MP3Downloads’,'Music’,'MusicTracks’,'MusicalInstruments’,'OfficeProducts’,'OutdoorLiving’,'Outlet’,'PetSupplies’,'PCHardware’,'Shoes’,'Software’,'SoftwareVideoGames’,'SportingGoods’,'Tools’,'Toys’,'VHS’,'Video’,'VideoGames’,'Watches’

6 – Parsers

Parsers are required to process information in XML or CSV files and they contain the blue print or template for a given feed. Typically, you need to set up a parser for each affiliate network as each network defines a different XML structure. If you use e.g. Fusepump’s product feeds then you would only have to define one parser which you can reuse across a number of different networks and retailers.
In order to complete the fields you need to look at the feed structure. Product feeds contain product information such product id, name, deeplink, image URL, category and price. You can download the feed using the download URL provided by the network or retailer. To open the feed you can use a text editor such as Scintilla. For smaller feeds you can also use Internet Explorer as it nicely renders the XML elemets. Once the feed is loaded you can examine the fields and you need to take a note of the field name for the parser setup.

Now you can find markup names manually or you can let Compare+ to detect fields automatically for you.

Manually

Automatically

Here is a step-by-step guide you can follow:

  1. Download the feed you want to use onto your computer
  2. Open the downloaded file in a text editor (Scintilla) or Internet Explorer (small feeds only)
  3. Try to find markup names for the follow fields (* required)
    • Parser name*
    • Product container root*
    • Product name*
    • Product category*
    • Product brand*
    • Product price*
    • Product deeplink*
    • Product EAN
    • Product description
    • Product image
    • Product shipping
  4. Save your parser and continue by adding your feed under Feed Management

Or you can use automated markup name detection

  1. Inert the URL of the sample feed
  2. Press “Get file” button
  3. Save your parser and continue by adding your feed under Feed Management

Please note that if you experience problems getting your parsers set up and working, please contact us with details about the feed, URL and the affiliate network.

XML element attributes and nested XML elements

If your XML feed contains attributes or nested XML elements then you can access these values as follows:

  • price@shipping
    <product><price shipping="12.59">

    => 12.59

  • additional/category
    <product><additional><category>Herenkleiding</category>

    => Herenkleiding

  • additional/brand@attribute_brand
    <product><additional><brand attribute_brand="Gaastra">

    => Gaastra

  • additional/images/largeIMG/imageLargeURL/url
    <product><additional><images><largeIMG><imageLargeURL><url>http://www.leerentv...

    => http://www.leerentv…

  • @id
    <product id="35613011"><product_name>My product</product_name>

    => gets the attribute value from root element => 35613011

The following screenshot shows you the XML structure of the John Lewis feed. We would simply have to copy the field names such as title, brand, ean, url, imageUrl, price, description and categoryList into the corresponding fields on the Add a Parser screen above.

The product container root in this example is: product.

XML file with nested XML elements and attributes

  • Nested: product/additional/images/largeIMG/imageLargeURL/url
  • Attribute: product@id

Parser creation with attributes and nested elements

What does the parser do?

Once you have set up your parser and feed, the parser will work as follows:

  • process is triggered manually using Import link on Feed Management screen or automatically by WP cron job
  • parser loops XML / CSV through all products in the feed
  • each product gets added to a raw table
  • each product name is added to the product mapping table
  • each product category is added to the category mapping table
  • any category or product exclusions that have been set will be applied at this stage. Any products matching the exclusions will be deleted from the raw and mapping tables.
  • Parsing step is complete.
  • Next each product will be processed using the following steps:
    • Check if EAN number is set
    • Check if product-level or category-level Force Import is set
    • Check if product-level mapping is set
    • Check if category-level mapping is set
    • If any of the above criteria are matched the product will be created and it will appear on the site
7 – Settings

Force import categories

Choose “force import categories” to import every category from the feed even if no mapping is set up. This is usually not a good idea because it will create a lot unwanted categories. We reccommend that you set this option set to “No”.

Force import products

Choose “force import products” to import every product from the feed even if no mapping is set up. If you want to have a perfect price comparison system, you should keep this option set as “No”, otherwise, you will have a lot of “single” products with only one retailer.

Cron job runs at night only

We recommend that you only run your cron job at night when your site is less busy. The time will be based on your webserver settings. If you set this to ‘Yes’ then the cron job will start at the ‘Cron job starts starts at’ time and ‘Cron job stops at’.

8 – Category Mapping

Before you can start to map your categories you need to create your desired categories withing WordPress. If you have not done this already, go to Products > Categories and your create top-level categories and sub-categories. The sub-categories will be used to match with product categories from the feed. Use the Parent drop-down box to associate your sub-categories with the top-level category. Please note that compre only support one level of sub-categories. Sub-sub-categories are not supported.

As part of the category setup you can also specify the category image and a description (good for SEO!).

Once you have set up your own categories and added a couple of product feeds you will have to map the categories found in the feeds to your own categories. The number of categories per feed depends on the retailer. Some feeds have a handful of categories whereas large online retailers could have hundreds of categories. You only have to do this once for each of your feeds.

We have tried to make the mapping process as simple as possible. We created an easy-to-use Initial Mapping Tool where you can quickly go through all categories found in your feeds and associate them with your own categories using a drop-down box with a number of choices:

  • Do nothing – category will be ignored
  • Add to (→ Exclusions) list – selecting this option will exclude the category during product import
  • Create ‘Sound & Vision’ – creates the category used by the retailer (e.g. Sound & Vision) and it will be created as a new top-level category. After this you will have to go into the category admin screen and give this new top-level category a new parent so that it becomes a sub-category.
  • Select an existing category name from the drop-down box

Please ensure that no feed categories are mapped to a top-level category in WordPress (e.g. Computers in the screenshot above) as only sub-categories are used by the Price Comparison functionality. The Top-level category template simply lists all sub-categories.

Clicking Map Categories at the bottom of the screen creates the category association in the database which will be used by the → parser during the import process.

9 – Product Mapping

To set up a functioning price comparison you need to map products from the different feeds to a master product. All products mapped to a master product will appear within the price comparison table on the master product’s detail page. Under Compare+ > Product Mapping you can see existing product mappings as well as the number of products associated with the mapping. On this screen is also a link to the Initial Mapping Tool where you can map the products with the feed with your master product.

On the Mapping Tool screen you can see a list of product names that have been imported from the product feeds. These products are in the raw table and the products have not been created within the price comparison system yet. These are only suggestions you can use for your search.

For example you could search for ipad to find all ipads in your feeds. You could then map these to e.g. two different products – iPad 2 16 GB and iPad 2 32 GB as we have shown on the search results page below.


On the above screen you can see the product names related to your search, tick corresponding checkboxes and apply a rule from the following options:

  • Add to the exclusions list (→ Exclusions) – the product will simply be ignored during import
  • Create a new product mapping by chosing the master product name.
  • Use an existing product mapping an associate the product with already existing mapped products.

Once your products are mapped, products will be associated with the corresponding product page during the next import. As a result, the mapped product will appear within the price comparison table for the given master product.

10 – Products, Brands and Categories

Once you imported a number of products into your price comparison site you can further customise your site by setting brand, category thumbnails and adding a description for these elements.

Categories

Brands

11 – Automatic Feed Updates

Our automatic feed update is based on WordPress’ built-in “WP-Cron” functionality. We strongly recommend reading this great article about WP-Cron for further information.

12 – Exclusions

Another important menu item is Compare+ > Exclusions where you can add rules to ignore products and categories. During importing, each product or category is checked against these exclusions and products matching the rules will not get imported into the price comparison system. Use this feature when you don’t want certain products to appear on your website by listing the full product name or stop words contained in the product name. Please enter one phrase per line into the text area.

Example: you have a skateboarding website, but your feeds also contains surfing products. Add the word “surf” to the product exclusion textbox and all products containing “surf” will be ignored.

Category exclusions work pretty much the same way as product exclusions but as the name suggests, category names are scanned for your stops words during import instead of product names.

13 – Support

We have set up a dedicated support forum for all Compare and Compare+ related questions which you can consult when you experience any problems using these products. Please try and search our forum using the search function before creating a new thread. We might have already answered a similiar question which means that you can get your answer there in then rather than waiting for us. And it would help us too of course as we can spend more time working on new features.

Before you can use the forum you have to register using your product purchase code.

We are based in London and our typical support hours are between 09:30 and 18:00 GMT. We aim to get back to you within 48 hours after receiving your query and quite often we respond witin a matter of hours. Over a weekend it might take a bit longer, but we will get back to you!

Thank you for using our Compare Price Comparison theme and plugin. We hope that you enjoy working with our product and it has enabled you to operate a successful price comparison website.

We understand that the product might appear daunting and complex at first. We have tried to simply the complexities of managing product feeds so that less technical users are also be able to operate their own price comparison site within the easy-to-use WordPress environment.

We are aware that we have not yet fully achieved our desired level of simplicity and we will continue to work hard in oder to make this product even more simple to use and remove any remaining complexities.

Your feedback is very important to us and please take a few moments to send us your comments (good or bad!), suggestions for further improvement or ideas by email to feedback@awesem.info

Once again, thank you so much for purchasing this plugin. As we said at the beginning, we’re glad to help you if you have any questions relating to this plugin. No guarantees, but we’ll do our best to assist.

— The AWESEM team

AWESEMThemes are created by AWESEM – Experts in all things WordPress, we design and build themes and plugins, create bespoke solutions and customize existing WordPress sites. Our approach is no-nonsense and personal.

Latest Tweets

  • Watch our series of video tutorials designed to guide you through our Compare price comparison theme for WordPress > http://t.co/GpMCcPXlz9 10 months ago

@awesemthemes

Newsletter

* = required field