Installation & Setup

What does the addon do?

The PureClarity X-Cart addon does the following:

  • Allows you to sign up for a 14 day free trial.
  • Gives you guidance on the initial setup of PureClarity in your store.
  • Sets up the Zones for the Home Page, Product Page, Basket Page and Order Confirmation Page.
  • Ensures data integrity between your store and PureClarity through scheduled feeds and deltas.
  • Tracks events on your stores frontend to ensure up to date information is used in recommendations.

To get started you’ll need to install the addon.

How to install the addon

You can install the addon by visiting the “My addons” menu item in your store’s Admin.

On the addons page, use the search bar at the top of the page to search for “PureClarity” and you’ll see the “PureClarity Personalisation” Addon listed.

Click the “Install addon” tickbox and then click the Apply changes button on the right-hand side of the page. This will install the PureClarity addon in your store.

Once the installation process is finished, return to your Admin area and you will see a new menu item under the “Content” menu. This is where you can set up an Account for your free trial.

Setting up an account

When you click the PureClarity menu item under the “Content” menu, you’ll be taken to the PureClarity Dashboard page.

Signup from within X-Cart

If you do not yet have an account with us you can sign up, by clicking the “Sign up” button. When you click the signup button on the PureClarity Dashboard, the signup form appears.

It requires you to fill in some basic details that we need to set up your account within PureClarity.

When you submit the form, the request will be submitted to PureClarity and processed as soon as possible, usually within a couple of minutes.

If you stay on the waiting page your X-Cart site will be configured as soon as it is processed, but you can also navigate away and come back later as a background process will check the progress of your application and configure your X-Cart site once it’s complete.

Already have an account

If you already have an account with us, you can fill in the details on the dashboard page after install:

You’ll need the following details from your account:

  1. AccessKey
  2. SecretKey

You can find these under the My Account > Integration menu within the PureClarity admin site.

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

You’ll also need to choose the region (USA / Europe / UK) that your application is on.

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 support@pureclarity.com.

Automatic configuration

Once PureClarity has set up your account, or you provided your account details, then your X-Cart store will have the following automatically happen:

  • PureClarity addon settings are configured:
    • Module Enabled.
    • Access Key.
    • Secret Key.
    • Daily Feeds Enabled.
    • Deltas Enabled.
  • Data Feeds requested:
    • Product.
    • Category.
    • User.
    • Historic order information.

Completed setup display

Once the PureClarity signup has completed and your store is configured, the dashboard page will change to show the next steps to take, information about data feeds and links to help & documentation

Getting started

STEP 1 – Style your templates

Step 1 – Style your templates using the Recommender Designer within the PureClarity Admin area

Click here to find out about the Recommender designer

STEP 2 – Go live

Step 2 – By default, Zones are only shown to admin users on the frontend. When you are ready, press the “Go live” button to show Zones to all customers.

Pressing the “Go live” button will disable “Admin only” mode of the module, which means all customers will be able to see the PureCalrity Zones. This can be re-enabled at any time by changing the flag on the settings page. See the Environment & Credentials section for more information.

The PureClarity addon comes with 10 default Zones that you can choose to enable on the Settings page. These are as follows:

Home Page

  • HP-01
  • HP-02
  • HP-03
  • HP-04

Product Page

  • PP-01
  • PP-02

Basket Page

  • BP-01
  • BP-02

Order Confirmation Page

  • OC-01
  • OC-02

If you click on the “Set up zones” button, you will be taken to the relevant section of the settings page.

Install custom Zones

You may want to add additional Zones on other areas of your site. This can easily be done by using the template editor in X-Cart. See the Zones section of this documentation for more information.

STEP 3 – Customize your campaigns

Step 3 – Customize your Campaigns and Segments within the PureClarity Admin Area to optimize the performance of your Zones

The PureClarity Academy has documentation on how to manage Zones, Campaigns, Segments and the strategies you can use to improve the performance of your personalization.

Data feeds

Types of data feed

“Data Feeds” is the mechanism by which Data is sent data from your store to PureClarity. The data feed cron processes within the addon generate the data for each type of feed.

NOTE: Feeds and Deltas are submitted using scheduled tasks. Please ensure these are enabled. See the X-Cart scheduled task documentation for more information

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 > Data Feeds to see a list of the feeds along with their import statuses. If there are any issues with the feeds, see the F.A.Q section.

There are 5 types of feeds that the X-Cart addon can send:


This feed will contain data for all visible & enabled products in your store. It will send data for all product attributes and will send default pricing.


This feed will contain data for all visible & enabled categories in your store. It will send data for all category attributes.


This feed contains data for all X-Cart Customers within your store. It will send basic information about each customer that can then be used to Segment them within PureClarity.


When enabled, this feed will send “Brand” information. 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. See the “Enabling Brand feed” section for more information.

Order history

A set of data regarding the last 12 months of orders, including which customers ordered what products. 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 should only be imported only once. If orders are imported a second time they are dropped by the system to avoid duplicate data.

When are feeds run?

Daily Feed

By default, Product, Category and User feeds are run nightly at 3 am. This is done via a cron process and full feeds of each type are sent.


The PureClarity addon has a mechanism called “Deltas” to handle Product & Category data changes. When a Product or Category is changed within X-Cart, a record of the ID that has changed is made in a database table and a cron process runs every minute to collate and send the updated data to PureClarity. This means that changes within X-Cart should be reflected in PureClarity within minutes. This is enabled by default.


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

1) On the PureClarity Dashboard page within X-Cart, click the “Run Feeds Manually” button within the “Data Feeds” panel.

This will bring up the feed selection popup:

Choose types of feeds you want to send, then click the “Run feeds now” button. This will request that the selected feeds are run as soon as possible. A cron process runs every minute to check for these requests and then generates and sends the feeds to PureClarity.

Feed status on dashboard

A panel on the dashboard page gives you an overview of the status of each of the types of feed.

Not Sent

If no feeds have yet been sent from your store, then this status will show.

Waiting for feed run to start

If feeds have been requested, but the cron job that runs them has not started yet, then this status will show.

In Progress: x% / Waiting for other feeds to finish

If the feed runner cron job has started and is processing a feed, then this status will show.

Last sent – yyyy-mm-dd hh:mm:ss

Once feeds have run successfully, this status will show.

Error, please see logs for more information

If an error occurs when transmitting the feed to PureClarity, then this status will show. See the troubleshooting section for more info.

Not Enabled

If PureClarity is disabled on your store, or the Brand feed is not set up, then “Not Enabled” will show.

How to enable the Brand feed

The PureClarity X-Cart Addon handles Brand feeds through the use of 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 Brand Feed section on the PureClarity settings page. This tells PureClarity to treat all the first-level children of this Category as Brands.


How to install custom Zones

In PureClarity Admin

1. Under Settings > Zones create the Zone for the relevant page type. e.g. to add a “Home Page” Zone, Select “Homepage” in the “Select zone” dropdown.
2. In the Campaigns section, create a new Campaign for the new Zone

In X-Cart

1. Log in to your Admin Area as a user with editing permissions.
2. Go to the frontend and to the page you want to add the Zone to.
3. Click “Template Editor” at the bottom of the page.

4. Enable “pick templates from page” so that you can click on the area you want to insert the Zone

5. When you’ve clicked the template on the page, insert the html in the template that appears at the bottom of the page, for example:

<div data-pureclarity="bmz:BMZ-ID"></div>

The BMZ-ID should match the Zone ID you created in the PureClarity admin.

NOTE: Zone HTML should be added to templates that are specific to the page you’re adding them on. If you add them to generic areas of the site, they may appear on all pages.

6. Press the save button at the top-right hand side of the template editor.

Your new Zone should start displaying once.

NOTE: Custom Zones will not show debug mode, you will need to inspect the source of the page to determine if your custom Zones are embedded properly.

How to debug Zones

If you want to see the location of the default Zones when they’re not being populated, navigate to the PureClarity configuration page and set the “Enable Debug Mode” in the Zones section to “On”. Zones will then be rendered with their name and id.


Environment & Credentials

By default, when you sign up or configure from the dashboard page, your account details will be populated here already. But should you need to change them for any reason, you can use this section of the settings page.

Enable PureClarity Personalisation

If you need to turn PureClarity off for any reason, you can do so by changing this setting to “Off”. This will stop the PureClarity addon from displaying Zones on the frontend, stop sending daily feeds and stop Deltas from sending Product & Category updates.

Access Key

The Access Key for your PureClarity application. You can find this under the My Account > Integration menu within the PureClarity admin site.

Secret Key

The Secret Key for your PureClarity application. You can find this under the My Account > Integration menu within the PureClarity admin site.


The Region for your PureClarity application. This should always be the same as what was chosen during the signup process.

Show to Admin users only

If you set “Show to Admin users only” to “On” then only users who have administrator permissions will be able to see zones on the frontend of the site. This is useful when you are placing a custom Zone or previewing how the Zones will look on your site.


Send Nightly Feeds

This setting controls whether feeds are sent on a nightly basis (at 3 am). Setting this to “Off” will disable the nightly feeds.

Send Deltas

This setting controls whether deltas are sent when products and Categories are changed. Setting this to “Off” will disable the deltas.

Brand Feed

Enable Brand Feed

This setting enables/disables the Brand feed. For more informaiton, see the Brand feed section.

Brand Feed Parent Category

This setting determines which category is used to send brands to PureClarity. For more information, see the Brand feed section.

Product Feeds

Exclude out of stock Products

If you want to exclude out of stock products from the product feed, you can do so via this setting.


Enable Zone Debug

If you want to enable Zone Debug, set this to “on”. For more information, see the “How to debug Zones” section.

Enable Zone [Zone-ID]

You can use each of these settings to enable/disable each of the default Zones. For more information, see the “Setting up Zones within X-Cart” section.

Product attributes

Additional product information

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

Go to Catalogue > Products and select a Product to edit. Scroll down towards the bottom of the page and in the PureClarity section you’ll see the PureClarity attributes you can set against the product:

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 Product Feed

Set this to yes to stop a product from sent in the feed at all.

Exclude from recommenders

Set this to yes to stop a product from being included in PureClarity recommenders, but still sent to PureClarity in the feed. You may want to do this for small priced items.

Show in recommenders for set time period

Set this to yes and a start/end date will appear underneath. Use these dates to determine a date range during which the product will appear in recommenders.

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.

Category Attributes

Additional category information

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:

Exclude from PureClarity Category Feed

Set this to yes to stop a category from being sent in PureClarity Category feed.

Exclude from PureClarity Recommenders

Set this to yes to stop a category from being included in PureClarity recommenders, but still sent to PureClarity in the Feed.

Exclude Products in this Category from the PureClarity Product Feed

Set this to yes to stop any products in this Category from being sent in the Product Feed.



Here are some Troubleshooting tips for our X-Cart addon

Why are my feeds failing?

  • Ensure your server can talk to the PureClarity servers and your AccessKey, SecretKey and Region is correct.
  • Note: Feeds and Deltas are submitted using scheduled tasks. Please ensure these are enabled. See the X-Cart scheduled task documentation for more information
  • Check the X-Cart error logs in [path/to/xcart]/var/log/
  • Check the X-Cart Database > pureclarity_state table for any error logs in rows with the name [feedtype]_feed_error

Why are the Zones 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 Zones show the Zone Ids on the front end.
  • If Zones are being rendered, but are still not being populated by PureClarity, ensure that the Zones are configured in the PureClarity admin console, under settings. Check that you have active merchandising campaigns set up.

My products/categories aren’t updating.

  • Ensure that Daily and Index feeds are enabled on the PureClarity Configuration page.
  • Ensure that your Deltas are enabled and that your Cron jobs are running.
  • Ensure Scheduled Tasks are enabled. See the X-Cart scheduled task documentation for more information

How do I show Customer-Specific Prices?

At present PureClarity does not support customer-specific pricing out of the box, but you can intercept the HTML from the PureClarity using the callback feature. See the “Callback events” section in our bespoke integration documentation

We also support Membership pricing in Product feeds, by default, Membership-specific pricing is sent to PureClarity as part of the Product Feed.