Magento 2.X

Getting Started

What does the extension do?

The PureClarity Magento 2 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
  • Sets up the Zones (BMZs) for the Home Page, Product Page, Basket Page and Order Confirmation Page.

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 Magento Marketplace and downloading the PureClarity Magneto 2 Extension.

Alternatively you can install PureClarity via Composer:

  $ composer require pureclarity/pureclarity-magento-2
  $ php bin/magento module:enable Pureclarity_Core
  $ php bin/magento setup:upgrade
  $ php bin/magento setup:static-content:deploy

Environment Configuration

Once the PureClarity extension has been installed and enabled, navigate to the PureClarity settings page by selecting the PureClarity menu item from the left hand menu. You may need to clear the cache if the item isn’t available. You can also access the setting by navigating to Stores > Configuration > PureClarity > Configuration.

Select “Yes” under Enabled, and paste in your AccessKey, SecretKey and select your specific Region from the drop down. Click [Save Config].

NOTE: If you have multiple stores (e.g. with differing languages) and we have provided you with multiple Access Keys, you can configure each store individually by selecting the Store from the “Store View” drop down at the top of the configurations page, and configuring each store separately.

Data Feeds & Indexing


Before Enabling PureClarity on the front end you must ensure the extension has submitted an initial set of data feeds to PureClarity.

Under normal circumstance, Products and Categories are automatically taken care of for you using the Magento Index Manager. In addition to indexing, nightly feeds keep the system up to date with User data and Brand data.

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 in order to activate the brand recommender and search functionality in PureClarity

The PureClarity Magento extension handles brand feeds through the use of 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 they must be enabled.

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 Data/Feed Indexing section on the PureClarity configurations page. This tells PureClarity to treat all the first level children of this category as brands.

Submitting the first feeds

To kick things off ensure you have saved your settings and then click the [Data Feed] button 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 anytime.

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 Configuration > 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 12 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.

You will be able to tell if the historic sales orders have been imported by going to Analytics -> Merchandising Performance, selecting “Offline Orders” as the channel in the top right corner, and then looking at the past 18 months as a time window. If you have imported historic orders, there will be data appearing there.

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 switching on Merchandizing on your site you need to install BMZs in the relevant areas on your site. This can be done either automatically using the [Install BMZs] button under the “Actions” section on the PureClarity Configuration page (whereby a number of BMZs are strategically placed throughout your site) or installed manually using PureClarity Magento Widgets. We recommend that you initially install your BMZs automatically and then add additional BMZs as Widgets as you grow your PureClarity implementation.

Click the [Install BMZs] button from the “Actions” section to display the Install BMZs popup:

Be sure to select the correct store and current theme of the site that you wish to install BMZs on and click the [Install BMZ Now] button. Once widgets have been created you will be shown a status of the installation, and a list of the unique BMZ Ids that have been created.

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

The list of BMZs installed through the automatic installation process are as follows:


  • HP-01 (
  • HP-02 (content.bottom)
  • HP-03 (content.bottom)
  • HP-04 (content.bottom)

Product Page

  • PP-01 (content.bottom)
  • PP-02 (content.bottom)

Basket Page

  • BP-01 (content.bottom)
  • BP-02 (content.bottom)

Order Confirmation Page

  • OC-01 (content.bottom)
  • OC-02 (content.bottom)

Custom Zones Widgets

You may want to add additional Zones (BMZs) on other areas of your site. This can easily be done by adding Magento Content Widgets.

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

  1. Navigate to Content > Widgets. Click [Add Widget].
  2. Choose “PureClarity BMZ” from the Type drop down.
  3. Choose your current theme from the Design Theme drop down. Click [Continue].
  4. Input a Widget Title such as “PC BMZ SR-01” to represent a Search Results BMZ.
  5. Set where your BMZ will be placed:
    • Add “Layout Update” button
    • Select “Specified Page” from the “Display on” dropdown menu
    • Choose the page where you’d like your BMZ to be displayed. In this example choose “Quick Search Form” and “Before Main Columns” from the Container drop down.

    Now we 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.
  8. 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.
  9. Leave the Fallback Block Id text box blank. You may want to set this to a custom static block in future should you wish. This also applies to any of the widgets that were installed automatically too, just find the widget and edit it. Type in the Id of another static block, and if a BMZ isn’t populated by PureClarity when the page is rendered, your custom static block will be insert instead. Note, you can’t fallback to another BMZ.
  10. BMZ Display Mode: If you want to show a BMZ on a specific device type, this setting tells the BMZ when to render using CSS Media queries. Default will show on all devices.
  11. Applying a margin will set a 10px margin above and below the BMZ content area.
  12. 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.
  13. Click [Save].

Your Custom 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 Zones

If you want to see the location of your Zones 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.

Server Side Mode


PureClarity can operate in two modes:

  • Client Side
  • Server Side

By default, PureClarity uses Client Side. This means that results from PureClarity are injected into the HTML page as it’s loaded.

This is recommended for most set ups and benefits from the added performance of allowing the system to work asynchronously. However, in some circumstances, such as for custom pricing, or for B2B sites, it may be better to use Server Side.

Using Server Side mode changes how Magento and PureClarity communicate with each other. All operations are done by back-end code, and rendered using Magento’s inbuilt widgets.

When in Server Side mode, Product Recommenders use Magento’s own Product List Widget. These templates are similar to Magento’s own Product Listing grid, albeit with minor changes to incorporate PureClarity-specific functionality. If you don’t want to use these inbuilt templates, you can override them by using a template in another custom module, as described below. See Templates for additional information on how to do this.

When Product Recommenders the product Ids returned by PureClarity are passed to the Magento system, so that product data is pulled and built by Magento rather than from PureClarity (as is the case in Client Side mode).

This is useful when a customized Magento installation has modules that, for example, alter product pricing, or have custom functionality that deals with account-specific pricing.

WARNING: The Magento 2 extension currently doesn’t support server-side mode. Please contact our Success Team ( for help on implementating PureClarity Magento 2 Server-Side Mode and we can supply you with a version that does support this required. The following information relates to the extension version that can be supplied by our Success Team.

Enabling Server Side Mode

To enable Server Side mode navigate to the PureClarity Configuration page by selecting PureClarity from the left hand menu. Under the “Advanced” section, select “Yes” from the “Use Server Side Integration” drop down, and click Save Config.

Overriding Server Side Templates

When PureClarity is in Server Side mode, results are rendered using the templates included in the PureClarity extension. However, these can be overwritten by writing your own HTML templates. To do this navigate to the PureClarity Configuration page from the left-hand menu. Under the “Advanced” section, there are fields that enable you to add overrides for Product Recommender, Search Results and Product Listing templates.

To add a new override, use the format [Module]_[Vendor]::grid.phtml.

When overriding PureClarity’s templates it’s important to include the following in your own templates:

PureClarityClickEvents on the mousedown event of the main product container element when overriding the Product Recommender template:

NOTE: You can see examples of the above by viewing the product_recommender.phtml and list.phtml template files under the extensions view > frontend > templates folder.



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 2.X