Skip to main content

​
Zones

​
Adding Zones To Your Pages

Zones, also known as Merchandising Zones, are areas on the site that render PureClarity content such as a product recommender, an image, a carousel or custom HTML. Each Zone is an HTML <div> element with a reference to a zone ID, as a data attribute. The zone ID is a unique ID that references each zone configured in PureClarity for each page type. For example on the home page a zone with ID HP01 may represent as a banner image. A page can have multiple zones. Below shows an example of a <div> element tagged with a zone ID: 
<div data-pureclarity="zone:<ID>;">&nbsp;</div>
Replace <ID> with the ID of the zone. For example: 
<div data-pureclarity="zone:HP-01;">&nbsp;</div>
When rendering content PureClarity will not update any existing content of the <div> if there is nothing to show. This allows sites to benchmark PureClarity or just show content from PureClarity for a particular Campaign.

​
Search Zones

There are 2 types of search specific zones, zones on the search results page and zones that can appear in an autocomplete drop down box. For zones on the search results page PureClarity uses a query string value in the URL to determine what the user searched for. For example, given the URL: www.yoursite.com/search?term=jar The ‘jar’ was searched, and PureClarity gets this value by looking at the query parameter ‘term’. This query parameter can be set in the PureClarity Admin console under Configuration > Settings. As autocomplete search implementations from site to site can vary significantly the autocomplete zone setup is a little more involved. For a full explanation of how to implement the autocomplete recommender please see the section on Personalized Recommendations in Autocomplete below.

​
Dynamic Zone Loading

When a page loads PureClarity will return the zones for that page, and inject content. Sometimes however you may need to dynamically load zone content later on, after a page has already loaded. An example would be loading the content of a specific zone that is in a category menu structure as a user hovers over it. As different categories are shown your site could dynamically load context aware zones for the specific category being viewed. In this way you can show personalized content for each user for each category they look at in the menu. The PureClarity getzone function can be used to request one or more zones at anytime. Note that this will only return a result object and so your site will be responsible for adding the HTML to the page. Below is JavaScript example code that will call PureClarity, with a context data object, and execute a callback function for you to process the result as you wish: 
_pc('getzone', { zone: 'PP-01', product_id: 'P12345' }, function(err, result) {
  // err is null if all ok
  // result is a hashmap of IDs with Html (eg. var html = result['HP-01'])
});
The getzone function supports an additional context property called requesttype. This can be set to ‘model’, ‘html’ or ‘both’ to retrieve data model as well as html in the result.

​
Personalised Recommendations In Autocomplete

If you want to provide personalization in an autocomplete drop down (instant search) on your site then this section will detail the steps required. Because there are lots of different autocomplete solutions on the market the exact way you integrate PureClarity will differ from one site to the next. The basic approach is to use Dynamic Zone Loading as a user types their search term into the search box. This will require adding some custom JavaScript to your site. We suggest the following approach:
  • In PureClarity setup an autocomplete recommender (AC-01).
  • Set it to be an ‘AI Recommender’.
  • When you setup a zone (such as AC-01) in the PureClarity Admin you can choose the minimum and maximum number of results you want to show. Set these based on the design of your autocomplete.
  • You can create a custom template for the autocomplete if the results should be rendered differently to other recommenders on your site by using the Template management area in the Admin console.
  • On your site, hook into the appropriate search hooks, such as when a user is typing into the search box. When a search has been made make the following request to PureClarity using the Dynamic Zone Loading method passing in the search term:
_pc('getzone',  { zone: 'AC-01', autocompleteterm: 'jar' }, function(err,zones){

  // result is a hashmap of IDs with Html (eg. var html = result['AC-01'])
});
  • In the callback event update the appropriate element on your page with the HTML content from PureClarity. This is likely to be a drop down box under the search input.
PureClarity allows you to make up to 8 zone requests per page load. Each additional set of 8 zone requests after this are counted as an additional page view, which is taken from your monthly page view charge. We suggest you use a timeout (i.e. the setTimeout() function), for approximately 200ms after the user has keypressed before requesting the zone from PureClarity to limit the amount of calls made. If the user enters another character before then, you can reset the timer (i.e. using the clearTimeout() function). This way a request is only sent to PureClarity after the user has stopped typing thus reducing the amount of requests made. This approach is in line and made easier with off the shelf autocomplete libraries such as JQuery Autocomplete widget. As the request to PureClarity will be made in parallel to the search engine/provider – the results will be displayed independently to the request to PureClarity. This will ensure the speed of loading your search results will not be impacted. Search results may appear before the results from PureClarity have been shown. You may want to use a UI element to indicate that content is loading (a spinner for example), and place the results from PureClarity in a fixed size element so when the elements are loaded the results from the search are not moved.