Magento 1.X

Getting Started

What does the extension do?

The PureClarity Magento 1 extension does the following:

  • Creates all the links to product, category, user & brand data
  • Allows you to submit data feeds and historic order data feeds
  • Ensures data integrity between your store and PureClarity through cron jobs

To get started you’ll need to create a PureClarity Application Account.

Create a PureClarity Application Account

You can sign up for a new account by clicking here and following the steps to create your admin account.

Once you’re in you’ll need to get the following keys which you’ll add to the Magento extension:

  1. AccessKey
  2. SecretKey

You can find these under the My Account > Integration menu.

If you have multiple language stores you will need an application per store, and thus multiple Application Access Keys. Please contact our Support Team to create additional PureClarity accounts for you at

NOTE: For security reasons it’s important to not share the SecretKey with anyone.

Install the Extension

You can install the extension by visiting the GitHub page for our extension and downloading the latest release:

PureClarity for Magento 1 GitHub

Once downloaded, you will need to extract the files into your Magento 1 installation directory.

Environment Configuration

Once the PureClarity extension has been installed, navigate to the PureClarity settings page by hovering over the System menu item from the top bar menu. Then click Configuration, right at the bottom. Finally, scroll down until you see PURECLARITY configuration on the left-hand menu bar:

Go ahead and click that.

This takes you to six config areas.

First, expand the Environment tab and click ‘Yes’ on the Enabled menu.

Then, expand the Credentials tab. Here, paste in your AccessKey, SecretKey and select your specific Region from the drop down. Click [Save Config].

If you have multiple stores (e.g. with differing languages), contact us to provide you with multiple Access Keys.

You can configure each store individually by selecting the store from the Current Configuration Scope drop down at the top left of the configurations page, and configuring each store separately.

Data Feeds

Brand Feeds

If you’d like to enable PureClarity with Brand information you will need to configure, enable and submit brand feeds. This could also be a Vendor or Manufacturer. A brand under most circumstances requires a name and an image to activate the brand recommender and search functionality in PureClarity. As Magento does not support Brands, PureClarity uses categories for brands.

You can configure this in the Catalog section on the top menu bar:

From there, select ‘Manage Categories’.

The PureClarity Magento extension handles brand feeds using Magento categories. This is done by creating a parent category, for example with the name “Brands”, that will have a list of subcategories for each of your brands. This will allow you to give each brand a name, an image and add the products that belong to that brand. The parent category and subcategories can be set to hidden from menus, but note that “Is Active” must be set to “Yes”.

Once your brand categories are configured and you’ve added your products to them, you can set the parent category, such as Brands, under the “Brand Parent Category” drop down box under the PureClarity configurations page you navigated to earlier. This tells PureClarity to treat all the first level children of this category as brands.

Before enabling PureClarity on the front end you must ensure the extension has submitted an initial set of data feeds to PureClarity. This is documented below.

To keep your data in sync, you can use the Daily Feed, which sends the feed to PureClarity once a day. You might also consider turning on the Delta feed, which enables any changed you make to products to be sent along to PureClarity within a matter of minutes.

Submitting the first feeds

To kick things off ensure you have saved your settings and then click the [Run Feed…] button under the Actions tab to display the PureClarity Data Feed popup. From here we can manually generate and submit the data feeds:

Select the Website and Store you’d like to submit a data feed to, ensure Products, Categories, Brands and Users are checked, and click the [Run selected feed generations now] button.

For now, leave the “Import Historic Sales Orders” unchecked, this is discussed below.

You will see a status progress for the data feed creation and submission process.

NOTE: As outlined above changes to data are updated automatically by the PureClarity extension. However, should you wish to manually submit a full feed to PureClarity you can follow this process at any time.

Once the feeds have been generated, they will be submitted to PureClarity. To see when the data has been processed you can log into the PureClarity admin console, select Settings > Feed Management to see a list of the feeds along with their import statuses. If there are any issues with the feeds, see the TroubleShooting Guide.

See the Advanced Configuration for more information on configuring what is sent as part of the product and category feed.

Historic Sales Orders

Following the same initial import process for Products, Categories, Brands and Users, you can also import the last 6 months of orders into PureClarity. This helps to activate and kick start the data that PureClarity collects by allowing the system to begin mining common purchase patterns and associating buying activities to users.

Orders can only be imported only once. If orders are imported a second time they are dropped by the system so as to not duplicate data.

Go Live with PureClarity

To go live with PureClarity, the next time you do a release on your site, you can make sure the site has the PureClarity plugin on it, ensure that the plugin has the same AccessKey and ScretKey as your current staging site, and then run a product feed once the keys are on the live site, so that PureClarity knows about the products on your live site – including links.

Congratulations! PureClarity is now installed, configured and initialised and is ready to be switched on!



Zones, or to give them their longer name ‘Behavioral Merchandizing Zones’ or BMZs, are content areas that display PureClarity Banners, Images and intelligent Product, Category & Brand Recommenders.

Before using PureClarity you need to install Zones in the relevant areas on your site. This can be done manually using PureClarity Magento Widgets.

Navigate to CMS -> Widgets. Click the Add New Widget Instance button, in orange on the top right.

Pick the type to be a PureClarity BMZ, then select the theme you want to use.

Click continue.

From there, be sure to select the correct store of the site that you wish to install BMZs.

NOTE: Each BMZ Id references the corresponding BMZ Id/Zone Name within the PureClarity Admin console, and allows you to configure what is displayed in that area.

As an example of how to add your own BMZ widgets to your site, let’s add a BMZ to the Search Results Page from beginning to end.

    1. Navigate to CMS > Widgets. Click [Add New Widget Instance].
    2. Choose “PureClarity BMZ” from the Type drop down.
    3. Choose your current theme from the Design Theme drop down.
    4. Input a Widget Instance Title such as “PC BMZ SR-01” to represent a Search Results BMZ. Click [Save and Continue Edit].
    5. Choose the page where you’d like your BMZ to be displayed. In this example we choose “All Pages” and “Left Column” from the Block reference.Now we need to configure the BMZ specific values:
    6. Select “Widget Options” from the left menu.
    7. Enter SR-01 into the BMZ Id box.
NOTE: It’s important that this Id matches a corresponding BMZ Id configured in the PureClarity admin console. You can see the configured BMZs by going to the PureClarity admin console and navigating to Configuration > BMZs. For this example select “Search Results” from the drop down to view a list of BMZs that are available. You can BMZs by clicking the [Add New BMZ] button and setting a Name and an Id. Add SR-01 if it’s not listed
  1. Applying a margin will set a 10px margin above and below the BMZ content area.
  2. CSS Custom Class: You can add your own css classes that will be added to the BMZ html element for greater control of how it’s displayed.
  3. Click [Save].

Your PureClarity BMZ Widget is now configured, and can be seen on the search results page!

NOTE: When adding new widgets you may need to clear the Magento cache to see it appear.

See debugging BMZs in the advanced section to help see your BMZ if nothing appears.

Feeds & Indexing

Product Data Options

You can augment each product with additional information, sent in the data feed, to control how PureClarity displays products.

Go to Catalog > Manage Products and select an item to edit. On the lefthand menu bar, click PureClarity:

When editing a product open the PureClarity section to see the properties that can be set.

Search Tags

Search Tags are used in recommenders based on Search. You can add search tags to products, e.g. ‘Summer’, to boost the relevance of products based on visitors’ search terms. Enter a comma separated list of words or phrases that you’d like to be sent to PureClarity as Search Tags.

Exclude from recommenders

Set this to yes to stop a product from being included in PureClarity Recommenders. You may want to do this for small priced items.

New arrival

Set if a product should be treated as a new arrival by PureClarity. This enhances recommenders and helps to target customers by showing hot new arrival products that may interest them.

On offer

Set if a product should be treated as an on-offer product. This enhances recommenders and helps to target customers by showing them products that are on promotion. PureClarity will do this automatically if products are on sale, however, you may want to override this if a product doesn’t currently have a special price, but you’d like it to be treated as a promoted product.

Image Overlay

You can set an additional overlay image to be placed over the product listing display. This could include an image such as On Offer or Free Delivery.

To set the image, upload an image under the “Images and Videos” section under a product’s properties, and select the “PureClarity Overlay Image” as the image role by selecting the image and selecting the option from the Role list.

You can add additional text to be sent with the product to PureClarity that can be used within the PureClarity template.

Category Options

You can set an additional option for PureClarity against each category. To do this go to the PureClarity section on a categories properties page. The options available are:

PureClarity Image

This allows you to set an additional category image should you wish to set one specifically for PureClarity category recommenders. To use this, you will need to alter the PureClarity template under the PureClarity admin console. In the most common cases PureClarity will work and use the categories’ standard image.

Exclude from Recommenders

Set this to yes to stop a category from being included in PureClarity Recommenders.

Placeholder Images

You can set fallback image URLs to be used where a product, category or brand doesn’t have any images set. To do this navigate to the PureClarity Configuration Page from the left hand menu, and set each URL using the text boxes under the “Placeholder images” section.

Debugging BMZs

If you want to see the location of your BMZs but they’re not being populated, navigate to the PureClarity Settings page and set the “Debug Mode” under the Advanced section to “Yes”. BMZs will be populate with their name and id.



Here are some Troubleshooting tips for our Magento 1.x FAQs.

Why are my feeds failing?

  • Ensure your server can talk to the PureClarity servers and your AccessKey, SecretKey and Region is correct.
  • You can activate Debugging under System > Configuration > Developer > Debug and enable “Log Settings”. See the var/debug.log for additional information as to why the feed may not be working.

Why are the BMZs not showing?

  • Check that everything is enabled, and they are being rendered to the screen. Enable Debugging by switching Debug Mode from the Advanced section on the PureClarity Configuration page, to see if the BMZs show the BMZ Ids on the front end.
  • If BMZs are being rendered, but there are still not being populated by PureClarity, ensure that the BMZs are configured in the PureClarity admin console, under settings. Check that you have active merchandising campaigns set up.
  • If the BMZs are not being rendered at all, check that other types of Widget can be displayed on the site (e.g. a CMS Static Block). If not, there is likely to be an issue with the theme. Try removing any content from the Layout and Default fields at System > Configuration > General > Design, and re-testing a basic Widget against different themes you have listed. If the Widget now displays, it indicates an issue with the theme you were using. An alternative approach to displaying BMZs would be to embed them directly within the theme.

My products/categories aren’t updating.

  • Ensure that Daily and Index feeds are enabled on the PureClarity Configuration page.
  • Ensure that your Index Management contains the PureClarity Indexes, and that your indexing Cron jobs are running.

How do I show Customer Specific Prices?

At present PureClarity only support customer specific pricing in Server Side Mode and the PureClarity Magento 1.x extension does not support server-side method. Read the Server Side Mode section for further information.

  Magento 1.X