Compare+ Plugin Documentation
The Compare+ Plugin is an extension to the Compare WordPress theme which allows for the automated import and mapping of pretty much any XML / CSV affiliate data feed, we also now hook up to the Amazon and Tradedoubler API’s. With product, brand and category mapping tools refining and managing your price comparison site has never been easier.
Version: 2.8
Last Modified:27/04/2017
Contents
1 – Compatability Requirements
- 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. 
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
- 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.
- 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’);
- 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)
- 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.
- 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.
- 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).
- 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.
- 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).
- 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
- Map the categories found in the feed to the categories you have previously created (→ Category Mapping)
- Add a second product feed and follow step 6 to 9 again
- 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)
- Manually import feeds or wait for the next automatic import done by the WordPress cron job
- 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
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. 
Always Import Products If EAN Exists
There is a feature set against each feed which allows all products within a feed to be forced to import if they have an EAN. This is useful as previously the only option for products to be forced into Compare was to force all products. However, products with an EAN will automatically be mapped to other previously imported products with the same EAN, but with this option products with no EAN and no mapping would be imported but not mapped to the correct master products. With this new option this problem no longer exists.
In Stock Options
Many different feeds use different values to indicate if an item is currently in stock, it may be that they say 1 for yes and 0 for no, or yes for yes and no for no (Some feeds even sometimes say yes and sometimes say 1). We also realize that the user may not want their site to contain products that are not currently in stock. To combat this we have implemented a new feed option which allows the user to set a list of allowed terms to reflect if an item is in stock. If this is left blank then all items will be imported, if it contains yes and 1 then all items where the in stock value in the feed is yes or 1. When you come to upgrading your Compare+ version, we strongly recommend that you take a full backup of all your files and database in case you experience any problems and you need to roll back. In case you’ve made your own customisations to Compare+ then you can use a tool such as WinMerge to compare your customised version against the original Compare+ version. You would then have to manually merge in your changes so that these are not lost when you upgrade.
4 – API Setup
- 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
- 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
- Please enter one of the following
- 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
Automatically 
Here is a step-by-step guide you can follow:
- Download the feed you want to use onto your computer
- Open the downloaded file in a text editor (Scintilla) or Internet Explorer (small feeds only)
- 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
- Save your parser and continue by adding your feed under Feed Management
Or you can use automated markup name detection
- Inert the URL of the sample feed
- Press “Get file” button
- 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:
- [email protected]
<product><price shipping="12.59">
=> 12.59
- additional/category
<product><additional><category>Herenkleiding</category>
=> Herenkleiding
- additional/[email protected]_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: [email protected]
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
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.
Conjoined Categories
It has come to our attention that the categories offered within feeds do not always offer the level of granularity that would be ideal for a targeted comparison site. We have now implemented a new feature called conjoined categories which allows the user, when setting up a parser, to join two data elements together to create a brand new category. An example of when this may be useful is as follows:
- A user wished to create a Comparison website for clothes.
- They wish to have two high level categories, Male and Female
- They find a feed from a preferred retailer
- Within the feed there are categories such as Hats, Gloves, Tops, Trousers etc.
- Within this feed there is also a data item for Gender
- Previously it would not have been possible to force the category mapping of Hats into 2 different categories Male>Hats and Female>Hats. Now, the user can change the category data item in the Parser Management screen to be Gender**Hats. Two asterisks (**) is the syntax you need to use between the first data item you wish to use as part of the conjoined category and the second.
- When the products import this will import as if the categories in the feed had been gender specific. All that remains is for the user to map the imported Male Hats category to the Male>Hats compare category and imported Female Hats category to the Female>Hats category and voilà!
9 – Product Mapping
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.
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.
Wild Card Product Mapping
Across many different feeds various products can be named slightly differently. Also, not all feeds contain an EAN to make the mapping process simple. We have now introduced the concept of wildcards to the product mapping process. An example of when this may be useful would be as follows:
-
- A user has two feeds within their sites, neither of these feeds contains the EAN
- Feed A contains the product with the name Generic Product A
- Feed B contains the product with the name Gen Product A
- In the product mapping screen you can now create a mapping that looks like this Gen% Product A
- % is the wildcard you use for the piece of the product name that changes. This will then map both of the products to the master product name.
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
WP-Cron Jobs can however have issues, a good example of this would be the following: “Dave has a site which Compares mobile phones called, www.thesuperfantasticmobilephonecomparisonwebsite.com. Dave wants the updates to his site to happen at 2am in the morning but he has no traffic until at least 2pm in the afternoon. Compare Plus would not be able to update his feeds as there are no visitors to trigger the WP-Cron job.” With this and other WP-Cron job issues which can be caused by configuration settings and other plugins interfering with the WP-Cron the solution is to use an external cron service such as https://www.setcronjob.com. Here the user can create an account. 
Activate the account and then login and click the big green “Create CronJob” button. The settings screen will then appear asking the user what URL (website address) they would like to call and how often to call it. There are various other options available but they are not needed for this task. 
In the URL to call field the user should enter the following URL replacing the website address with the one for their website. http://www. thesuperfantasticmobilephonecomparisonwebsite.com/wp-cron.php?doing_wp_cron Next to the “When to call” text box the user should click on the blue details button. This will then let them set which minutes, hours, days etc the cron should run. It should be remembered that it’s best for the cron to run when the site doesn’t have many visitors as the cron running can slow down the site. Also each time the cron runs only one feed gets updated, so if the site has 10 feeds ideally it should be run 10 times a day to make sure the feeds stay up to date. 
The user should then click the “Save CronJob” button at the bottom of the page. Note: as can be seen from the pricing page here https://www.setcronjob.com/prices the free account is only suitable for very small feeds which complete within 15 seconds. The user will need to upgrade to a better account if the feed takes longer than this to import. Note: the user should also disable WP-Cron Jobs by changing their wp-config file adding the following line to the top of the page. define(‘DISABLE_WP_CRON’, true);