Bespoke Integration

GETTING STARTED

OVERVIEW

This guide takes you through the 5 steps to implement PureClarity on your site using the bespoke implementation approach.

Before you begin, PureClarity provides a number of Plug-ins that will automatically undertake a number of these steps. Please check out our integration page to see if we have a plug-in for your ecommerce platform.

1: PLANNING

The first decision before implementing PureClarity is whether you will adopt the client-side or server-side implementation method. The Client-side method is our recommended approach, however server-side may give you more control for complex installations.

For more information see the Implementation Methods below.

To get the best out of PureClarity you need to consider the most optimal placement of the merchandising zones. To help you decide we have provided a best practice guide on where to place these zones.  We recommend you review them before adding the PureClarity elements to your site as described below in step 2.

For more information see our guide on the Optimal Placement of Zones.

NOTE: 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.

2: IMPLEMENTATION

There are 3 main stages to implementing PureClarity into your ecommerce platform:

  1. Add the PureClarity JavaScript Snippet (PCJS) master function to each page.
  2. Add event tracking, to track user activity such as product views and add to basket.
  3. Add Merchandising Zones, to display PureClarity content, such as product recommenders or banner images.

The PureClarity JavaScript Snippet (PCJS) master function manages PureClarity’s interaction with the site, keeps track of sessions and assists with debugging, and depending on your implementation type (Server/Client) the script may be responsible too for sending tracking events to PureClarity.  The PCJS master function Javascript snippet needs to be at the top every page on the website, ideally after the closing <head> tag. This is detailed in PCJS Master Function section.

Event tracking is needed in order to send user activity to PureClarity, such as product views, basket content, orders placed, currency changes and customer login & logout. Depending on the implementation type the approach varies. For client-side implementations events are added using Javascript and the PCJS master function. For server-side implementations your ecommerce platform will be responsible for sending events as HTTP requests. The approach to adding event tracking to your site is outlined in the relevant implementation sections.

Zones are areas on the site that display PureClarity content to your users. Similar to event tracking, described above, the approach varies depending on your implementation type. For client-side implementations <div> elements on your site are tagged with specific attributes, and the PureClarity Javascript takes care of the rest injecting HTML onto the page. For server-side implementations HTTP requests are made to PureClarity to retrieve data and then you will need to render HTML around the data models returned. The approaches are outlined in the relevant implementation sections.

3: DATA FEEDS

Feeds are required to tell PureClarity about your data. You will need to build and test them. Feeds include a mandatory product feed & non-mandatory category, brand, user and order history data feeds.

Submission and feed management can be found in the PureClarity Admin console under ‘Settings > Feed Management’ or via our API.

For more information see: Data Feeds

4: TEMPLATES

Following on from Step 2 if you opt for client-side implementation you can edit the look and feel of the HTML that is returned from PureClarity. This HTML and CSS is generated by PureClarity using the Template Management system, and can be managed and edited in the admin console under ‘Settings’. See the Templating section for further information about how to style the look and feel of the various PureClarity content types.

For server-side implementations, the styling and HTML will be controlled by your platform, from the data model returned from PureClarity. This is explained in further detail in the Server-side implementation section.

5: HISTORICAL ORDER DATA

Once you’re ready to start to use PureClarity it is advisable to upload 6 months of past order history to kick-start the AI’s learning and increase the relevancy of recommendations.

For more information on creating this data see the: Historic Order Feed section.

You can also use this method to provide a daily feed of orders that are generated offline (e.g. phone and in store orders). PureClarity’s machine learning will use this data to adapt its recommendation results.  This is optional.

Now, you’re ready to go live!

Need further help?

If you have issues while implementing PureClarity, Developer Debug Mode may help you to debug the problem. Alternatively if you have any questions you can contact our support team by emailing support@pureclarity.com

IMPLEMENTATION METHODS – CLIENT VS SERVER

A key decision to make before you begin the implementation is whether you are going to use the client-side or server-side integration approach. If you are using a plugin developed by PureClarity for your e-commerce platform then this is not relevant to you. Refer to the documentation for your plugin.

Regardless of the approach taken you will need to generate and send the data feeds to PureClarity. These tell PureClarity about the products on your site, as well as historic orders and your customers.

Once PureClarity has information about your ecommerce store you will need to decide how your store will communicate with PureClarity. “Client-side” is the approach to take in almost all circumstances. In this mode you will “mark up” areas on your site where you want PureClarity to show content. You will need the PCJS Master Function on your site. This Javascript will be responsible for examining the page and injecting the relevant content into any zones that are on the page. It will also handle sending tracking events to PureClarity to record the activity of the users.

For some implementations the approach of letting PureClarity render all HTML is not viable, or doesn’t give enough control over what is displayed to users. For example if the pricing of products is custom per user and has very complex logic, or if some products cannot always be shown to some users, then you may want PureClarity, for example, to return recommender data to your server, where you are more in control of the product display. For complex situations like this you can use our “server-side” approach.

At this point it is worth pointing out that because of our callback feature – there are very few situations where server-side is the correct approach. We advise you to contact our support team before embarking on a server-side implementation if you have any questions.

In a “server-side” implementation your ecommerce system will make calls directly to PureClarity – often before a page is loaded. You will be responsible for building HTML from the results PureClarity returns. Server-side allows you to potentially integrate PureClarity into your existing pipelines – for example feeding the JSON results into your own templating system.

The drawbacks of server-side:

  • More code intensive – may take longer to implement
  • Increased latency on initial page load
  • You can’t use the PureClarity templating system for data returned server-side
  • You have to handle setting client cookies, and other variables, so PureClarity can identify the customer and ensure a customer falls into the correct segment.

A quick summary:

Client-side: With the client-side approach HTML is generated by PureClarity for zones. You can change the HTML and the CSS style using Template Management in the admin console. This is the quickest route to implementing the software and the recommended method.

Server-side: The server-side approach provides an API that produces a stream of products, brands and categories for zones.  This approach is more code intense but gives you flexibility if you have bespoke requirements not supported by the client-side method. Use this method if you have custom pricing or product visibility rules – for example on a complex B2B site.

LANGUAGE AND LOCALIZATION

PureClarity can support multiple languages. To support multiple languages you need a separate store view for each language. For example, a zone on the Spanish site can differ from that on the English site.

Also, PureClarity can support multiple currencies within a single instance. See Currency Tracking for more details.

Please speak to your Success Manager to setup your instance with the language required.

PCJS MASTER FUNCTION

The PureClarity JavaScript Snippets (PCJS) master function assists with tracking events, session management and debugging PureClarity within your website. The PCJS master function JavaScript snippet needs to be added to the top of every page on the website, ideally after the closing <head> tag.

Each PureClarity installation has a unique access key. You will need to replace <access_key> within the code snippet. Your API Access Key can be found in the Admin console under My Account > Integrations.

Below is the Javascript snippet to copy:

<script type="text/javascript">
 (function(w, d, s, u, f) {
   w['PureClarityObject'] = f;
   w[f] = w[f] || function() {(w[f].q = w[f].q || []).push(arguments)};
   var p = d.createElement(s), h = d.getElementsByTagName(s)[0];
   p.src = u;p.async=1;h.parentNode.insertBefore(p, h);
 })(window, document, 'script', '//pcs.pureclarity.net/<access_key>/cs.js', '_pc');
</script>
NOTE: You will have different access keys for each store view.

DEVELOPER DEBUG MODE

Once you have PureClarity integrated and the master function is on all your pages you can use the developer debug bar to help ensure zones are being detected, view any data associated with them and ensure tracking events are working correctly and being passed to PureClarity.

To activate the debug bar, ensure you are logged into the PureClarity Admin console, and then on your website add the following query string parameter to the end of the URL:

pc_debug=true

For example: www.yoursite.com/shop?pc_debug=true

The PureClarity Debug Bar will appear showing a number of selectable tabs at the top.

The first tab  shows the status of the PureClarity integration, and will only show if you’re logged into the admin at the same time and PureClarity is active, and have the correct store view selected in the admin. The Template Preview mode tells you whether any templates on the site are in Preview mode (explained in further detail below).

The Events tab shows all the events sent from the site to PureClarity on the current page, and the responses from PureClarity. This is useful to see, for example, if on a product page the product view tracking event is being sent with the correct Id.

The Zones tab gives you an overview of all the zones that are active on the page. It shows what context information is being sent to PureClarity (such as the product Id associated with a zone) and also shows whether PureClarity understood the request.

Finally the Previews tab shows you which, if any, templates are being previewed, what type of template it is, and what version it is. This developer debug, when active, enables templates marked as “in preview” to be used rather than the current live template to assist with styling. Only you will see templates in preview and not your customers.

Further information on editing and previewing templates see the Templating section.

NOTE: If you are using server-side integration, zones may be rendered on the server and thus may not be detectable by the developer debug system. More information about this is outlined in the server-side implementation section in this guide.

CLIENT-SIDE IMPLEMENTATION

OVERVIEW

Once you have decided where you will be placing all your zones on your site you can follow this section to help add tracking events and zones to your pages.

EVENT TRACKING

Tracking events are required in order to send user activity to PureClarity which in turn allows PureClarity to learn about them and thus fit them into PureClarity customer segments allowing personalized and relevant merchandising zones to be displayed within your site.

As outlined in the PCJS Master Function section the standard master function snippet has to be added to every page for tracking events to work:

<script type="text/javascript">
 (function(w, d, s, u, f) {
   w['PureClarityObject'] = f;
   w[f] = w[f] || function() {(w[f].q = w[f].q || []).push(arguments)};
   var p = d.createElement(s), h = d.getElementsByTagName(s)[0];
   p.src = u;p.async=1;h.parentNode.insertBefore(p, h);
 })(window, document, 'script', '//pcs.pureclarity.net/<access_key>/cs.js', '_pc');

 _pc('page_view', { page_type: 'homepage' });

</script>

Among other things the PCJS Master Function adds the _pc() global function to the site which is what we use to add tracking events. As shown above the _pc(‘page_view’, {…} ) is the first tracking event to be called, and is different for each page in order to add context to what the user is viewing.

PAGE VIEW TRACKING EVENT

The page_view event can take an optional “context data” object as the second argument, and is used to tell PureClarity which page the user is currently viewing along with contextual information about the page, such as the Id of a product being viewed. This page type and context information is used by PureClarity to influence which zones are returned and what content they may display based on the context. A page_view tracking event with context data takes the following form:

_pc('page_view', {...} );

For example, on a product page the context data object could be set as follows:

_pc('page_view', { page_type: 'product_page', id: 'abc123' } );

This tells PureClarity to add context to the merchandising zones and thus affects what content is returned.

The possible context data options and page_types for page view tracking event are detailed in the API Tracking Reference section.

GENERAL TRACKING EVENTS

All tracking events are added to the site using the _pc() JavaScript global function. Similarly to the page view tracking event, the following example shows how this should be formatted:

_pc(tracking_event_name, context_data);

…where tracking_event_name is the name of the event to be tracked, and the context_data is a JavaScript context data object with specified properties. The data context object is different for different events. An example of a product view tracking event would be placed on the page like so:

 _pc('product_view', { id: 'abc123' } );

For a full list of tracking events that need to be implemented see the API Tracking Events reference section.

CALLBACK EVENTS

Your own JavaScript function can be called once PureClarity has returned results and rendered zones on the page. This is useful should you wish to manipulate the content or styling of what is returned. For example you could use JQuery to set “live stock” alerts for products in a recommender.

The following shows how to implement a callback event:

_pc('callback_event', function(){     
  console.log('PureClarity Callback!');
});

PRE-RENDER CALLBACK EVENTS

Sometimes you might need to initialise the contents of a zone before they are displayed, for example if you are using a custom slider for a product recommender and you want to only initialize it if content is returned. PureClarity supports this by providing the prerender_callback_event. To implement this use the following code snippet:

_pc('prerender_callback_event', function(){
  console.log('PureClarity Callback!');
});

The lifecycle of both the prerender_callback_event and the callback_event is as follows:

  1. PureClarity loads the content into the HTML DIV element. (If there is no content to show, then PureClarity will not alter the content of the HTML DIV).
  2. The prerender_callback_event function is then called.
  3. PureClarity sets the ‘display’ style of the HTML DIV element to ‘block’
  4. PureClarity calls the callback_event..

For most sites, the callback_event will be enough. If you want to perform some initialisation before the zone content is made visible then set the style of the block to ‘hidden’ and then subscribe to the prerender_callback_event.

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:HP01;">&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 context string has the required zone Id as well as additional context data for the zone, in this example, the product Id of the page that is being viewed.

Multiple zones can be requested at the same time by providing “zones” rather than “zone” as an array of Ids:

_pc('getzone', { zones: ['PP-01', 'PP-02'], 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'])
});
TIP:  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.

PERSONALIZED 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.

HTML TEMPLATES

There are several PureClarity templates that you can configure or override. It is important to remember that a single zone can show different recommenders, images or even HTML at different times for different users so you’ll need to style each type. The default templates are:

  • Product Recommender
  • Brand Recommender
  • Category Recommender
  • Image Carousel
  • Static Image

The HTML and CSS that is rendered and injected onto the page by PureClarity can be edited in the Admin Console.  You can find this under Settings > Templates. See the Templating section for further information.

SERVER-SIDE IMPLEMENTATION

OVERVIEW

This section walks you through the necessary steps to add PureClarity to your site using the server-side method.

Unlike the client-side method, requests to PureClarity are made on the server, rather than the client’s browser. This requires the PureClarity API to be called directly from your server-side code.

URL ENDPOINT

The PureClarity endpoint for all server-side calls is determined by your applications region:

https://<region-domain>/api/serverside

Where the region specified domain is one of the following:

Region Endpoint
EU https://api-eu-w-1.pureclarity.net/api/serverside
US https://api-us-e-1.pureclarity.net/api/serverside
NOTE: All requests must be a HTTPS POST request and the Content-Type header should be set to application/json.

HTTP REQUEST

REQUEST PAYLOAD

As part of the HTTPS POST to PureClarity the following properties can be sent in the body as a JSON object. The following properties are valid:

Property Type Description Example Required
appId string Your store views unique access key. This can be found in the PureClarity Admin console. “abc123” Yes
secretKey string The secret key provided for all store view level calls. This can be found in the PureClarity Admin console. “abc123” Yes
currentUrl string The page url that the user is currently on. “http://www.yoursite.com/shop/product/abc123” Yes
userAgent string The users browser User Agent string, in all request headers sent by their browser. “Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)” Yes
ip string The users IP address. “208.67.222.222” Yes
visitorId string The user’s unique PureClarity Visitor ID. This is stored as a browser cookie and set by PureClarity. Discussed further below. “user123” Yes – if present
sessionId string The user’s unique PureClarity Session ID, that represents their current visit. This is set by PureClarity and is stored as a browser cookie. Discussed further below. “sess123” Yes – if present
referer string The referer value from the users browser header. This is the page that the user has come from, not this current page. “http://www.yoursite.com/shop/” Recommended
currency string Set’s the currency of the products to be returned. The value should be a valid ISO currency code. If not present the default currency configured in PureClarity will be used. Only products that have been sent to PureClarity with this currency price will be returned. “USD”
events array An array of tracking event objects. See below

 

EVENT TRACKING

Each “track event” is sent as an object as part of the “events” array property in the main request body. An event object is made up of two properties:

Property Type Description Example Required
name string The identifier of the track event. “page_view” or “product_view” Yes
data object The contextual data that accompanies the tracking event. { “id”: “abc123” } Determined by event type

Below is an example of a payload with a product_view track event sent when a user is viewing a particular product with Id P1234. See the events property in particular:

{
  "appId": "abc123",
  "secretKey": "xyz123",
  "currentUrl": "https://www.yoursite.com/shop/product/P1234",
  "userAgent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
  "ip": "206.67.222.222",
  "visitorId": "user123",
  "sessionId": "sess123",
  "referer": "https://www.yoursite.com/searchresults?term=jar",
  "events": [
    {
      "name": "page_view",
      "data": {
        "page_type": "product_page",
        "id": "P1234"
      }
    },
    {
      "name": "product_view",
      "data": {
        "id": "P1234"
      }
    }
  ]
}

It’s important to note that the page_view tracking event is required to return the zone data for that page. If the page_type property is omitted a page impression will still be recorded in PureClarity however the response will contain no merchandising zones.

For a full list of tracking events that need to be implemented please see the API Tracking Reference for full details.

COOKIES AND DOMAINS

You will need to pass the PureClarity visitor ID and PureClarity session ID in each request to PureClarity. These are stored as cookies in the users browser.

The main PureClarity Master script that is on the page will set these cookies when visitors use the site, and they will be available for you server-side to read at the beginning of each request to pass into each request, as outlined above.

The cookies to read and pass to PureClarity are as follows:

pc_v_<access_key>: The PureClarity user Id
pc_sessid_<access_key>: The PureClarity session Id.

You will need to replace <access_key> within the name. Your API Access Key can be found in the Admin console under My Account > Integrations.

If the cookies are empty then nothing should be sent for those values as part of the request. In this situation the response will contain new values for the missing values. These will then need to be set by your implementation as pc_v_<access_key> and pc_sessid_<access_key> cookies.

The expiry of the pc_v_<access_key> cookie should be set to unlimited and the pc_sessid_<access_key> cookie should be set to expire after 5 minutes. PureClarity client script manages the ongoing session period while the user is on the site and active.

If you are developing an e-commerce site that does not have JavaScript (for example a mobile application) then the PureClarity Master script will not be available. In this scenario it is the responsibility of the application to manage the lifecycle of the visitor and session identifiers and pass them to PureClarity in every server side request.

NOTE: If using the developer debug mode sessions can time out. This is because normally the PureClarity client script running on the site will send a poll event to keep the session alive. During testing the client script may not be running. A side effect of when a session has expired and requests are sent, is that merchandising areas may not be returned populated correctly. The solution for this is to clear cookies and (if in account mode) log in via the website.

CUSTOMER LOGIN AND LOGOUT

When the customer_details track event, as detailed in the API Tracking Reference section is sent to PureClarity a new visitor ID may be returned in the response and thus the pc_v_<access_key> cookie needs setting to the new ID. This is because PureClarity may have identified the customer from a login event and now requires the pc_v_<access_key> cookie to be set to the correct ID so that all ONGOING activity is attributed to the correct user.

If a customer logs out of your site, the pc_v_<access_key> cookie must be cleared. A new one will be returned in your next request to PureClarity. If the pc_v_<access_key> cookie is not cleared by your site PureClarity will assume the same user is still using the site and any activity afterwards will continue to be attributed to that user.

HTTP RESPONSE

The response to the HTTP Request will be a JSON object that represents the result from PureClarity. The following properties may be present:

Property Type Description
visitorId string The user’s unique PureClarity visitor ID. This should be set as the pc_v_<access_key> cookie in the users browser. The expiry of the pc_v_<access_key> cookie should be set to unlimited.
sessionId string The user’s unique PureClarity session ID for the current visit. This should be set as the pc_sessid_<access_key> cookie in the users browser. The expiry of the pc_sessid_<access_key> cookie should be set to 5 minutes.
zones object An object that contains the result for each zone on the requested page.  Each key property name, with an object that represents the zone content data.
errors Array of strings Contains each error that occurred should there be any issues.

The zones property will be an object where each property will have the ID as the name. For example:

{
  "visitorId": "user123",
  "sessionId": "sess123",
  "zones": {
       "HP01": {
           "type": "staticimage",
           … other type specific properties ...
       }
   }
}
NOTE: As explained above, the page_type property has to be set as part of the page_view track event for zones to be returned in the response. See the Events section for more details.

As shown in the example above, each zone will contain an attribute called type. This defines the content type of content that is being returned, along with other properties for this type.

See the Objects & Properties section for details on the properties that are available for each content type that is set against each zone.

GDPR – ANONYMIZING USERS

OVERVIEW

PureClarity provides an API to allow you to request that PureClarity anonymizes the data it holds for a given user. This API works in the same way as the Forget button on the User Explorer in the PureClarity Admin.

HTTP REQUEST

To anonymize a user you can make a HTTPS POST request to the PureClarity API endpoint:

https://<region-domain>/api/user/forget

See the URL Endpoint section for further details of what should be used for the <region-domain> value. The JSON body of the request should contain:

{   
    "AccessKey": "abc123",
    "SecretKey": "xyz123",
    "Identifier": "user567"
}

AccessKey is your unique access key for the store view and SecretKey is your secret access key. Remember to never disclose your SecretKey, and only ever send to PureClarity in the body of a secure request.

The identifier is the unique identifier used to identify the user/account on your site. This should be the same identifier your site sends in customer_detail and order_track events as well as in the user feeds.

Once submitted PureClarity will schedule a task to remove all potentially identifiable data about the user including any email address associated with the user. For security reasons all forgotten email addresses are stored securely as a hashed value which means that the system can tell if the email address has already been forgotten without identifying the original email address. Once a user has been forgotten there is no way to store data again for this user. PureClarity will also never send them any emails.

API TRACKING REFERENCE

OVERVIEW

This section details all the tracking events that can be sent to PureClarity and are relevant to both client-side and server-side modes.

Each tracking event is listed along with description and the context data that can be passed with it.

For client-side implementations use the global _pc(tracking_name, tracking_context_data) function.

For server-side implementations pass the data as outlined in the server-side implementation section.

PAGE_VIEW EVENT

The page view tracking event is used to record a page view with PureClarity and to tell PureClarity what page the user is viewing, along with context data.

WARNING:  Context data is important for PureClarity to be able to determine the correct zone and thus recommendations to show.

Context data – (OBJECT):

Property Type Description Example
page_type string Specifies the page type so PureClarity knows which zones to load. The list of possible page types are outlined below in this section. “homepage”
product_id string Specifies the product context of the current page. Used to load recommenders relevant to a product page. The Id should match the Id used in the product feed. “P41923”
category_id string Specifies the category context of the current page. Should be set on product listing pages. The Id should match the Id sent in the category feed. “3841”
brand_id string Specifies the brand context of the current page. Used to set the context of a brand page. This Id should match the Id sent in the brand feed. “23”

The following page types that map to zones that have been configured in the PureClarity Admin console are valid for the page_type property:

  • homepage
  • search_results
  • category_listing_page
  • product_listing_page
  • product_page
  • added_to_basket
  • basket_page
  • order_complete_page
  • my_recommendations
  • my_account
  • content_page
  • landing_page

CURRENCY EVENT

Tells PureClarity what currency is the users preference, and thus controls what currency is returned in product recommenders. The currency code must be a valid ISO 4217 currency code, (e.g. “USD”, “GBP” etc.). Prices in the currency must already be stored against the products as part of the data feed before sending the event.

WARNING:  This applies to client-side mode only. See server-side documentation on information on how to the currency as part of the main request model.
NOTE: PureClarity will not do exchange rate price conversion. The price for each currency supported by the site needs to be sent in the feed. See Data Feeds for more details.
WARNING:  If this is not sent, the default currency set against your store view will be used. Also if currency is set, only products with that currency, sent in the product feed, will be shown.
TIP:  If using server-side mode you will want to send this at the start of each new session if not displaying the default currency.

Context data – (STRING): ISO Currency code (e.g. “USD”)

PRODUCT EVENTS

product_view

Tells PureClarity that the user has viewed a product with the given Id.

Context data – (OBJECT):

Property Type Description Example
id string Specifies the product that has been viewed “P41923”

product_rate

Tells PureClarity that a user has rated a product with a given rating and is thus used as part of the top rated product recommender.

Context data – (OBJECT):

Property Type Description Example
id string Specifies the product that has been rated “P41923”
rating number The rating that the user has given 3

BASKET EVENTS

set_basket

Sets the contents of the users basket in its entirety. This event is useful for PureClarity to associate strong buying signals for a given product for the user. Note, the context is an array of basket products.

TIP:  Send an empty array to clear the basket.

Context data – (ARRAY<object>):

Property Type Description Example
id string The product Id of the item in the basket. “P41923”
qty number The amount of this product that is in the basket 2
unitprice number The price of a single unit 29.95

CUSTOMER EVENTS

customer_details

Used when a customer logs in on the site or the site is aware of who the customer is, such as when a user registers on the site.

Context data – (OBJECT):

Property Type Description Example Required
userid string A unique ID for the user “USR123” Y*
email string The users email address “fred@smith.com” Y*
accid string If the user is part of business account this value can be used to ensure customer specific account pricing, and personalization at the account level rather than the user level. “ACCID1” Y*
groupid string Optional user group. Used to support price banding (prices per user group) “group10” N
firstname string First name of the user “Fred” N
lastname string Last name of the user “Smith” N
title string The prefix of the user. “Mr” N

At least one of email, userid or accid must be sent:

  • If accid is sent, then userid will be ignored – as all subsequent events will be tracked against the account.
  • If userid is sent, then this will be taken as an identifier for the user across the site. Use this same identifier when the user logs in; makes an order; or in any offline orders that are submitted.
  • If neither accid or userid is sent, then email will be used as the unique identifier for the user. This should be used whenever the user logs in; makes an order; or in any offline orders that are submitted.
  • If accid or userid is set – and email is set as well – then the email address will just be stored against the user. It will be used if any Triggered Emails are sent.
  • Best practice is to send the userid (or accid if using accounts). This is because it will remain unique to that user – email addresses may well be changed over time.
  • The Id should match the Id sent in the user feed.
NOTE: If you are passing groupid, then this must match one of the groups sent in the GroupPricing field in the Product Feed.

customer_logout

Tells PureClarity that the current user has logged out.

WARNING:  This applies to client-side mode only. See server-side documentation on information on how to log a user out by clearing the pc_v_<access_key> cookie.

Context data: N/A

ORDER TRACKING EVENTS

order

PureClarity needs to track order activity so that it can determine customers purchasing habits and trends to personalize recommendations. This should ideally be placed on the final step of the checkout process once the order has been successfully submitted.

WARNING:  Each unique order Id can only be sent once. Orders reusing an Id will be dropped.

Context data – (OBJECT):

Property Type Description Required Example
orderid string Unique order number of this order Y “O123”
ordertotal number Total order value in base currency.
NOTE: Values should have no currency symbol or comma separators. This value can either be ex-VAT or VAT depending on the site. Decimal separator must be a . and NOT and ,
Y 22.80
title string The customer title or salutation.

Mr, Mrs, Miss, Ms, Dr, etc..

N “Mr”
firstname string First name of the customer N “Fred”
lastname string Last name of the customer N “Smith”
zipcode string The zipcode of the delivery address N “90210”
postcode string The postcode of the delivery address N “YO10 6RB”
dob string Date of Birth of the Customer (Format YYYY-MM-DD) N “1978-07-02”
userid string The customers unique user id See below “USR123”
email string The customers email address See below “fred@Smith.com”
accid string The business account id of the customer See below “ACCID123”
groupid string Optional user group. Used to support price banding (prices per user group) N “group10”
items ARRAY<object> An object array of the items Y See below

At least one of email, userid or accid must be sent:

  • If accid is sent, then userid will be ignored – as all subsequent events will be tracked against the account.
  • If userid is sent, then this will be taken as an identifier for the user across the site. Use this same identifier when the user logs in; makes an order; or in any offline orders that are submitted.
  • If neither accid or userid is sent, then email will be used as the unique identifier for the user. This should be used whenever the user logs in; makes an order; or in any offline orders that are submitted.
  • If accid or userid is set – and email is set as well – then the email address will just be stored against the user. It will be used if any Triggered Emails are sent.
  • Best practice is to send the userid (or accid if using accounts). This is because it will remain unique to that user – email addresses may well be changed over time.
  • The Id should match the Id sent in the user feed.
NOTE: If you are passing groupid, then this must match one of the groups sent in the GroupPricing field in the Product Feed.

Items – (ARRAY<object>):

Property Type Description Mandatory? Example
id string The Id of the product Y “P1234”
qty number The quantity of this item that has been ordered Y 2
unitprice number The unit price of one item.
NOTE: Values should have no currency symbol or comma separators. This value can either be ex-VAT or VAT depending on the site. Decimal separator must be a . and NOT and ,
Y 11.40

DATA FEEDS

OVERVIEW

PureClarity accepts a JSON based data feed format which contains all products in the e-commerce system and includes product information such as the product Id, name, image URL and prices. When a full feed is submitted it is used as the latest full version of all products that are currently live and available to customers. I.e. any products not sent in a new feed will no longer be used by PureClarity.

As well as the full product feed, you can also send record deltas, which are updates to individual records that PureClarity knows about.

Please note that there are limits to the frequency you can send both full feeds and product deltas to PureClarity. Please see the Product Updates section on our pricing page for more information.

SUBMITTING DATA FEEDS

There are three ways of submitting feeds to PureClarity:

  • Via an HTTP call to PureClarity, passing the URL where PureClarity can download it.
  • Securely submitting a feed via SFTP.
  • Securely streaming feeds as batches to PureClarity via HTTPS

Once a feed has been submitted you can see the progress of processing under Settings > Feed Management in the PureClarity Admin console.

Below details the 3 ways of submitting a data feed.

SUBMITTING VIA HTTP CALL

You can make a HTTPS POST request to PureClarity passing the URL where PureClarity can download a full JSON feed as part of the querystring. The endpoint is:

https://<region-domain>/api/productfeed

See the URL Endpoint for the <region-domain> value.

The required parameters to be sent in the JSON body are:

Field Description
appkey Access Key for the store view.
secretkey Secret Key for the store view.
url Url of where PureClarity can upload the feed. Note that the feed is not consumed immediately, so the feed should be available at this location for the next 24hrs.

SUBMITTING USING SFTP

You can submit feeds securely via SFTP. Endpoints are region specific and are as follows:

Region Endpoint Port
EU sftp-eu-w-1.pureclarity.net 2222
US sftp-us-e-1.pureclarity.net 2222


To authenticate, the username is your store view Access Key and the password is the Secret Key. These can be found in the Admin console under My Account > Integrations. Ensure that the Secret Key is never revealed.

Once a feed has been submitted you can see the progress of processing under Settings > Feed Management in the PureClarity Admin console.

SUBMITTING USING HTTP STREAM REQUESTS

For systems that cannot submit using an SFTP server PureClarity can receive feeds via multiple HTTP requests. Using this API you can send the feed in multiple API calls to build up a complete JSON object inside of PureClarity. This is done by appending strings to a remote file on the PureClarity server. You first send a create command with an opening JSON bracket, followed by an append command building up the items, finishing with a close command and appending a close JSON bracket. Once the close command is received PureClarity will begin processing the feed.

The three endpoints are as follows:

  • https://<region-domain>/feed-create
  • https://<region-domain>/feed-append
  • https://<region-domain>/feed-close

The <region-domain> for the streaming API uses HTTPS and is as follows:

Region Endpoint Port
EU https://sftp-eu-w-1.pureclarity.net 443
US https://sftp-us-e-1.pureclarity.net 443
NOTE: Each request must be a HTTPS POST.

Each of the three calls should contain a JSON body with the following 4 properties:

Property Description
accessKey The store view Access Key.
secretKey The store view Secret Key.
feedName A unique identifier for the feed. This should be the same for each of the 3 calls.
payLoad The next part of the string that builds up the feed file.

Start of feed: /feed-create

This indicates to PureClarity that a new feed is being sent. You should include the start of the feed in the payLoad if required. Typically you would send over the opening brace of the JSON feed in the payLoad along with the start  of property array that will hold the items. For example:

“{“

WARNING:  This is a string that is being sent, and not a JSON object.

If you send another request to feed-create before you have completed a feed with an existing feedName it will be reset to the contents of the new payLoad and previous appends will be overwritten.

Data in the feed: /feed-append

Use consecutive calls to the append endpoint to send parts of the feed, such as the header for the item array, followed by multiple calls containing the items, followed by another call to end the array.

For example, the header for a products feed may look like:

“‘Products’: [“

Then the addition of products:

‘{“Id”:”prod123″,”Title”:”A sample product”,”Prices”:[“3.99 GBP”,”4.99 USD”]},’

NOTE: Take care to ensure commas are not appended to the last item. Remember these strings are appending to a file on the server to generate valid JSON.

Finally you need to close this section of the feed:

“]”

TIP:  You can repeat the above to include other sections for the feed if required (i.e. categories and brands) although these can also be sent as separate feeds.

The details of what data to send for the various feeds is discussed later.

End of feed: /feed-close

Use this call once you are ready to submit the feed to PureClarity for processing. You can include the final part of the feed in the request if required. Once PureClarity has received this it will process the file.

Typically you would send over the closing brace of the JSON feed in the payLoad:

“}”

PRODUCT FEED

The JSON product feed contains all current live product data, including account specific pricing, that PureClarity uses to display products. This section outlines what data should be included in the JSON data.

WARNING:  The maximum size of a product feed is 250Mb.

This method uses the following JSON representation for products:

{
  "Products": [
    { <product 1 data> },
	...
    { <product n data> }
  ]
}
NOTE: Account specific prices can be set on a per account per product basis. See B2B Account Pricing for more information.

STANDARD PROPERTIES

Each product can have the following standard properties:

Name Type Description Example Required
Id string This is the unique Id of the product. For example, this could be the Sku. The Id must be unique across the product data feed. “23” Y
Sku string Optional Sku of the product if this is different to the product Id. “PC093673” N
Title string The name of the item as it will appear on the website. “Awesome Jeans” Y
Description string A short, non-formatted description of the item. This field should not contain any HTML. Made of 100% denim with added stretch for comfort. N
Categories ARRAY<string> An array of category IDs that the product is associated with. If the product exists in multiple categories send them all. These should match the IDs sent in the category feed.

Categories should be set to an empty array (e.g. [ ] ), if not set for a record. Do not set to an empty string.

[“Cat1234”, “6712”, “Hats”] Y
Link string A relative or absolute URL pointing to the products page.

If using an absolute URL, specify the URL without a protocol. E.g. // instead of http:// or https://

“//www.website.com/products/P1” Y
Image string An absolute URL pointing to the image of the product.

It is best to reference an image which has the suitable dimensions as part of the template design.

If possible, specify the URL without a protocol. E.g. // instead of http:// or https://

“//www.website.com/thumbnail/image1.jpg” Y
ImageOverlay string A relative or absolute URL pointing to an overlay image to display in the corner of items, such as an “on offer” badge.

It is best to reference an image which has the suitable dimensions to the template design.

If possible, specify the URL without a protocol

e.g. // instead of http:// or https;//

“//www.website.com/thumbnail/on-offer.jpg” N
Brand string Optional brand identifier. This should be the same as the ID included in the brand feed. Used to show brand information in the search auto-complete, and can be used in the templates. “Aspire” N
SearchTags ARRAY<string> Optional array of text to help PureClarity find products as part of search specific recommenders and for use with segment rule building. [“PartCodeA”, “partCodeB”] N
AssociatedSkus ARRAY<string> An optional array associated skus. For example if the product is made up of variant products (i.e. a configurable product) this can be provided which will help in search recommenders or allow for tracking products where a particular variant has been bought, and thus the variant sku has been sent in the tracking event.. [“sku1”, “sku2”] N
AccountInclusions ARRAY<string> Set of accounts where this product should be visible. If set, then the product will only be visible for these accounts. If no account information is present then these will be hidden from the user.

This attribute is only valid for B2B sites where account information is being sent.

It is mutually exclusive to AccountExclusions and a record with both is invalid.

[“acc1”, “acc2”] N
AccountExclusions ARRAY<string> Set of accounts where this product should be hidden. If set then the product will only be hidden for these accounts. If no account information is present or the account is not excluded then these will be visible to the user.

This attribute is only valid for B2B sites where account information is being sent.

It is mutually exclusive to AccountInclusions and a record with both is invalid.

[“acc1”, “acc2”] N
ExcludeFromRecommenders boolean If present, and set to true then this product will be hidden from all recommenders.

This can be useful to hide products that you never want to promote (such as a free catalogue) or to fulfil regulatory requirements.

Default value is false.

true N
NOTE: Set empty array fields to empty array brackets (e.g. [ ]) not empty strings.

PRICE & AVAILABILITY

The following properties show the prices and availability.

Attribute Type Description Example Required
Prices ARRAY<string> Array of prices for the item. Use multiple entries for different currencies. [“3.49 GBP”, “4.99 USD”] Y
SalePrices ARRAY<string> Array of sale prices for the item. Use multiple entries for different currencies. [“2.49 GBP”, “3.99 USD”] N
GroupPrices MAP Map of user group identifiers to the prices for each of these groups. See below N
NoDefaultPriceForAccounts boolean Controls whether to use the products “default” price when no account price is found for an account. Default (if not present) is “false”, meaning that if the site passes through an account id that doesn’t have a price defined for this product, then the price of the product defined in the product and variants will be used. If it is true, then if the site passes through an account id that doesn’t have a price defined for this product, then the product will be hidden from the user.

This attribute is only valid for B2B sites where account information is being sent.

true

false

N
OnOffer boolean Used by some recommenders to identify “on sale” items. false

true  

N
NewArrival boolean Used by some recommenders to identify “new items”. false

true  

N

GroupPrices is a feature of PureClarity to allow price banding. This means that users can be shown a different price from the default price depending on their user group. Users can be placed into a user group by sending the groupid property in the customer_details or order_track event. The group can also be passed over in the User Feed.

The structure of GroupPrices is a map where the keys are the user group identifiers, mapping to an object with the Prices and SalePrices for each group. If Prices or SalePrices are not passed, then the default Prices or SalePrices for the product will be used for the group. In the example below, the product would have different prices for group1 and group2. Group1 has different prices and sale prices, whereas group2 has the default prices for the product but has different sale prices.

{
  "GroupPrices": {
    "group1" : {
      "Prices" : ["10.99 GBP","12.99 USD"],
      "SalePrices" : ["9.99 GBP","11.99 USD"]
    },
    "group2" : {
      "SalePrices" : ["8.99 GBP","10.99 USD"]
    }
  }
}

START & END DATE

Start and end dates can optionally be specified to control when products are visible on your site. This allows you to include new products in your feeds before they are allowed to be purchased. In the active time range the products will be visible on your site. If no start or end date is specified then the product will always be visible. You can specify just a StartDate, just an EndDate or both.

Attribute Description Example Required
StartDate Used to control when a product will start to be shown on your site. If the current time is before StartDate, then it won’t be shown. Format is an ISO 8601 formatted date (see below). 2016-12-25T09:00:00Z N
EndDate Used to control when a product will stop being shown on your site. If the current time is after EndDate, then it won’t be shown. Format is an ISO 8601 formatted date (see below). 2016-12-25 09:00:00 N

The StartDate and EndDate need to be an ISO 8601 formatted date. If there is no timezone information present, then the time is assumed to be in the timezone of your site. This time zone can be altered by your Success Manager. Below lists some examples of valid date/time formats:

Format Description
2016-12-25 Only the date passed in. Time will be assumed to be midnight.
2016-12-25 09:00:00 Time is taken as 9am on 25th December in the timezone of the site
2016-12-25T09:00:00 Time is taken as 9am on 25th December in the timezone of the site. (Optional ‘T’ to separate the time)
2016-12-25T09:00:00Z Time is taken as 9am UTC on 25th December.

CUSTOM ATTRIBUTES

Custom attributes can be sent as part of the feed and stored for use in templates. Custom attributes can also have multiple values. Include the options as an array, e.g.:  

PowerSource:["Mains","Battery"]

B2B ACCOUNT PRICING

Account Price Record is used for variable pricing for account customers.  This is more common for B2B sites or those sites that use account specific pricing.  This is an optional section in the PureClarity product feed format. The account price record can be included in the product feed along with the products array, or alternatively it may be sent as a Product Delta.

{
  "Products": [ {<product1>}, . . . ., {<productN>} ],
  "AccountPrices": [ {<price>}, . . . ., {<priceN>} ],
}

Where each Price record is in the format:

{
  "AccountId": <string>,
  "Id": <string>,
  "Prices": [<same as in Prices record>],
  "SalePrices": [<same as in Prices record>]
}

CATEGORY DATA FEED

This feed contains data about each category including the category name, image and URL. Categories can appear in category recommenders and are associated with products for analytical purposes, as well as used for creating rules against segments.

The JSON body for categories is defined as follows:  

{
  "Version":2,
  "Categories": [ {<category1>}, . . . ., {<categoryN>} ]
}

Each category  can contain the following properties:

Name Type Description Example Required
Id string This should be the unique category Id. Id’s are required to be unique across all records. “a124” Y
DisplayName string This is the name that will be displayed for each category in recommenders. “Sale” Y
Image string An absolute URL pointing to the location of the image. This image is used when displaying category recommenders.

If possible, specify the URL without a protocol

e.g. // instead of http:// or https://

“//files.website.com/categories/C1” N
Link string This can be a relative or absolute URL pointing to category listing page. If using an absolute URL, specify the URL without a protocol

e.g. // instead of http:// or https://

“//www.website.com/categories/C1” Y
ParentIds ARRAY<string> The Id’s of the parent categories for this category. This means that a category can exist in more than one parent category, for example a category of “Shirts” could be in both of the categories “Mens” and “Sale” [“a124″,”a125”] Y*
Description string A short, non-formatted description of the category. This field should not contain any HTML “Mens clothing” N

*If this is not possible then the field can be set to an empty array. This field is required so that PureClarity can correctly infer the hierarchy. Note that certain recommenders may not work if the field is not included.

BRAND DATA FEED

This feed contains the image to use for each brand and an optional link to a brand product page. The brand feed is required to allow for rich brand recommenders. If a feed is not provided PureClarity will not be able to display them. The format is as follows:

{
  "Version":2,
  "Brands": [ {<brand1>}, . . . ., {<brandN>} ]
}

The following properties are defined below:

Name Type Description Example Required
Id string This is a unique Id which is used to identify a brand. Each brand Id should be unique. “B125” Y
DisplayName string This is the name that will be Displayed on the brand recommenders “Nike” Y
Image string An absolute URL pointing to the image to display in recommenders.

It is best to reference an image which has the suitable dimensions to display in brand recommenders.

If possible, specify the URL without a protocol E.g. // instead of http:// or https://

“//files.website.com/thumbnail/image1.jpg” Y*
Description string The description of a brand can be displayed in recommenders. N
Link string To allow brand recommenders to display brands that can be linked off to a brand page you should provide this field.

This can be a relative or absolute URL pointing to a brand listing page. If using an absolute URL, specify the URL without a protocol

e.g. // instead of http:// or https://

“//www.website.com/brands/B1” N

*If this is not possible then the field can be left out. This field is required so that PureClarity can display the brand logo (or other relevant image) in brand recommenders. Note that certain recommenders may display a blank image if this is not included. These recommenders can be modified via the template editor or disabled in the admin.

USER DATA FEED

The User Data Feed can hold detailed information about a user that PureClarity can use to define customer segments. There are a few standard fields such as UserId and FirstName but you can provide any number of Custom Fields as part of the feed, e.g. Marketing Preferences or any personal information known.  You are able to create customer segments for each custom field sent in the user feed.

NOTE: PureClarity will either update the information for an existing user or will add a new user if PureClarity has no information for that user.
WARNING:  Please note that there are certain types of information that are you are not allowed to send to us under our Terms and Conditions. These are classes of data that under GDPR would be classed as Special Category Data.

Restricted data includes:

  • Race
  • Ethnic origin
  • Politics
  • Religion
  • Trade union membership
  • Genetics
  • Biometrics (where used for ID purposes)
  • Health
  • Sex life or Sexual orientation
  • Offences

The format of the feed is as follows:

{
  "Users": [ {<user1>}, . . . ., {<userN>} ]
}

The following properties make up the user data:

Name Type Description Example Required
UserId string Unique User Id. This should be the same identifier sent to PureClarity in the tracking events (customer_details and order_track).   “USR123” Y
GroupId string Optional user group. Used to support price banding (prices per user group) “group1” N
Email string Customer’s email address “fred@smith.com” N
FirstName string Customer’s first name “Fred” N
LastName string Customer’s last name “Smith” N
Title string Mr, Mrs, Miss, Ms, Dr, etc.. “Mr” N
DOB string Date of Birth
NOTE: PureClarity derives ‘Age’ from DOB for Behavioral Profiling.
Date “DD/MM/YYYY” N
Gender string Male or Female “M” or “F” N
City string Location of City or Town “City” N
State string Users location state “State” N
Country Users country “UK” N
CustomField A custom field, e.g. Marketing Preference, etc… String, Number, Boolean or Array N

Custom fields can also be sent. These can be of type String, Number, Boolean or Array of strings. For example “VIPCustomer”: true.

In this example “News” is a customer field to determine if a person has signed up to the newsletter and “HasChildren” if a person has indicated they have any Children.

{
  "Users":  [ 
    {
      "UserId": "02345",
      "Email":  "fred@smith.com",
      "FirstName": "Fred",
      "LastName": "Smith",
      "Salutation": "Mr",
      "DOB": "12/1/1988",
      "Gender": "M",
      "Country": "UK",
      "News": "Y",
      "HasChildren": "N"
    },
    {
      "UserId": "02346",
      "Email":  "jane.brown@outlook.com",
      "FirstName": "Jane",
      "LastName": "Brown",
      "Salutation": "Ms",
      "DOB": "12/1/1978",
      "Gender": "F",
      "Country": "UK",
      "News": "Y",
      "HasChildren": "Y"
    }
  ]
}

HISTORIC ORDER FEED / OFFLINE ORDERS

To help kick start PureClarity’s AI learning it is recommended that you upload at least 6 months of historic order data prior to go-live.

To do this you can send a CSV file to your success manager who will arrange for the initial upload. As this exercise takes time, please ensure you submit this at least 2 days prior to your planned go live.

Note that PureClarity will ignore any orders older than 1 year.

If your site handles orders in another channel to the website, then these orders can be sent on a daily basis to PureClarity so that the customers experience on the website is correct.

These daily order files can be uploaded via the Admin area, or via the SFTP server.

WARNING:  Each unique order Id can only be sent once. Orders reusing an Id will be dropped.

CSV FORMAT FOR ORDER FILES

The header order of each column is not important – but the field names are.

The data required is:

Field Description
OrderID Used to map order lines together
AccountId Unique Identifier for an Account (See below)
UserId Unique Id of the user (See below)
Email Email address of the user (See below)
DateTime Date/Time the order was made. This needs to be an ISO 8601 formatted date (see below)
ProdCode Product Id. This must match the Id of a product in the data feed.
Quantity Number of items of ProdCode in the order
UnitPrice Price of a single ProdCode. Used to provide a basic order total in the admin for historical orders.
NOTE: Values should have no currency symbol or comma separators. This value can either be ex-VAT or VAT depending on the site. Decimal separator must be a . and NOT and ,
LinePrice Price of the orderline (Quantity * UnitPrice). Used to provide a basic order total in the admin for historical orders.
NOTE: Values should have no currency symbol or comma separators. This value can either be ex-VAT or VAT depending on the site. Decimal separator must be a . and NOT a ,
WARNING:  Either “Unit Price” or “Line Price” must be specified but not both.

The date/time stamp the order was made needs to be an ISO 8601 formatted date. If there is no timezone information present, then the time is assumed to be in the timezone of your site. This time zone can be altered by your Success Manager.

Some examples of valid date/time formats:

Format Description
2016-12-25 Only the date passed in. Hourly data is not used by PureClarity for offline/historical orders – but they can be included to make importing your data easier.
2016-12-25 09:00:00 Order is taken as 9am on 25th December in the timezone of the site
2016-12-25T09:00:00 Order is taken as 9am on 25th December in the timezone of the site. (Optional ‘T’ to separate the time)
2016-12-25T09:00:00Z Order is taken as 9am UTC on 25th December.

At least one of Email, UserId or AccountId must be sent. This should match the identifier that would be used if the order had been placed on the website so that the data is tracked against the correct user/account.

  • If AccountId is sent, then UserId will be ignored – the order will be stored against the account.
  • If UserId is sent, then the order will be stored against the user.
  • If neither AccountId or UserId is sent, then Email will be used as the unique identifier for the user. This should only be done if Email address is used to identify users in the tracking events (Order and Login).
  • If AccountId or UserId is set – and Email is set as well – then the email address will just be stored against the user/account. It will be used if any Triggered Emails are sent.
  • Best practice is to send the UserId (or AccountId if using accounts). This is because it will remain unique to that user – email addresses may well change over time.

DELTAS

In addition to the full feeds PureClarity accepts changes to individual records. Individual records can be added, deleted and existing ones updated. The delta API endpoint allow you to send these updates. Data is sent in the same structure as the full feed references.

The following records can be sent as deltas:

  • Products
  • Categories against products
  • Account Prices
  • Users

Note that when a delta is pushed to PureClarity they are queued for processing. Each API call will return a token that can then be used to query the status of the delta via the delta status endpoint.

The maximum size of a single delta is 250 Kb. A delta API call can contain multiple updates so long as the total size of the delta is under 250 Kb. The HTTPS POST will reject the delta with an error code if the delta is too large.

NOTE: For product updates the delta will overwrite the product so they must contain the full product information rather than a partial update.

The endpoint for the HTTPS POST deltas is:

https://<region-domain>/api/delta

See the URL Endpoint for the <region-domain> value.

The body of the HTTPS POST should be a JSON object and look like the following:

{
 "AppKey": <string>,
 "SecretKey": <string>,
 "Products": [ {<productdata>} ],
 "DeleteProducts": [<string>,<string>],
 "SetCategoryOnProducts": [ { <categoryOnProductd>} ],
 "RemoveCategoryFromProducts": [ { <removeCategoryFromProduct>} ],
 "AccountPrices": [ {<accountprices>} ],
 "DeleteAccountPrices": [ {<deleteAccountPrice>} ],
 "Users": [ {<userdata>} ]
} 

See the relevant references in this guide for the data structures for products, users and account prices. DeleteProducts should sent as an array of product identifiers (e.g. Id). Examples of category deltas and DeleteAccountPrice deltas are detailed below..

The request will return a status of 200 if successfully added to the queue of deltas to process, and will return the following JSON object:

{
 "Token": "deltatoken123"
}

To query the status of deltas send a HTTPS POST to the following endpoint:

https://<region-domain>/api/deltastatus

The body of the request should contain an array of tokens for which the status is required::

{
 "AppKey": "appkey123",
 "SecretKey": "secretkey123",
 "Tokens": [ "deltatoken123", "delta567" ],
}

This will return a JSON object containing an array, where each entry contains the status of a token requested:

[
  {
    "Token": "deltatoken123",
    "Status": 2,
    "Reason": "Missing price" //Present if Status is 2 (Error)
  }, ...
] 

The following table lists the possible status codes:

Status Description
0: Pending The delta has not been processed yet.
1: Success The delta was applied successfully.
2: Error The delta failed. The property “Reason” will indicate why.

EXAMPLES

Category Deltas:  

{
  "AppKey": "appkey",
  "SecretKey": "secretkey",
  "SetCategoryOnProducts": [
    { 
      "Category": "catid1",
      "Products": [
        { "Id": "prod1" }
      ]
    }
  ],
  "RemoveCategoryFromProducts": [
    { 
      "Category": "catid2",
      "Products": [
        { "Id": "prod1" },
      ]
    }
  ]
}

Delete Account Price Deltas:

{
  "AppKey": "appkey",
  "SecretKey": "secretkey",
  "DeleteAccountPrices": [{"AccountId": "account1", "Id": "prod1"}]
}

TEMPLATING

OVERVIEW

All PureClarity components can be edited using the inbuilt HTML & CSS templates. Templates gives you full control over the look and feel of merchandising and email.  You can edit the default templates for each PureClarity component and create your own themes.

For help on checking the templates on your site, have a look at our Developer Debug Mode.

PureClarity provides default templates for the following content types:

  • Product Recommender
  • Category Recommender
  • Brand Recommender
  • Static Image
  • Image Carousel
  • Personalized email

The PureClarity template language implements a large subset of the HandlebarsJS language and with more advanced helpers from Just Handlebars Helpers. Handlebars allows you to access properties and objects within the templates, for example {{Title}} can be used to display the title of the product.

The full set of objects and properties for each content type can be found in the Objects & Properties section.

Each template has a HTML and CSS file which can be edited in the PureClarity Admin Console.  To edit the templates follow the paths below:

  1. Settings > Templates – Merchandising
  2. Email: Email Automation > Triggered Emails > [select type] > [create new email] > ‘Email Properties’ section > ‘Template’ tab.

Merchandising templates are version controlled and can be edited, set to preview (for use with the Developer Debug bar), and then published for all users to see. It is recommended that as templates are being developed and checked for styling, the preview mode is used.

In the HTML templates object properties and logical expressions are identifiable by using double curly brackets, e.g. {{#if linkLocation}}, as outlined by the HandlebarsJS specification. These expressions populate the component with data at render-time or allow for conditions and looping, for example over an array, and give you control over what PureClarity shows in the style that suits your site. When displaying properties with double brackets the value is escaped. This is obviously problematic if your value contains HTML. To display a value without any encoding use triple brackets, e.g. {{{title}}}.

All templates are built using the data outlined in Objects & Properties section

GENERAL PROPERTIES

There are a couple of general properties that exist within recommender templates:

{{uniqueId}} is a general property that is available within all recommender templates and is a unique reference. In our default template we use this alongside a JavaScript snippet to allow for the scrolling of items within a recommender.

{{clickEvt}} is a property that is available on each item in a recommender template. This should be applied to the mousedown event of the containing DIV element for each item, for example the DIV that contains each product. It is important that this is added to recommender templates as this helps PureClarity to track when a user interacts with an item, and thus attribute click through events to a users activity.

RECOMMENDERS

Recommender templates include:

  • Product Recommender
  • Category Recommender
  • Brand Recommender templates.

Product Recommender

The product recommender template is rendered when a user is shown a recommender based on products in a merchandising zone. We iterate over the {{items}} property array to pull out data for each product. Here we use the {{uniqueId}} property to give each zone a unique reference so that a scroll bar can target each recommender.

Brand Recommender

The brand recommender template is rendered when a user is shown a recommender based on brands in a merchandising zone. Each brand object contains data as provided by the brand feed. If a brand feed has not been submitted, brand recommenders cannot be shown.

Category Recommender

The category recommender template is rendered when a user is shown a recommender based on the categories in a zone. Similar to the brand recommender, category recommenders require a category feed to have been submitted in order to be displayed.

The Image Carousel recommender template is rendered in zones defined to show the Image Carousel. A carousel has a number of properties, including an images array, in order to configure a JavaScript carousel library. Our default template uses the comprehensive jssor carousel, however you could implement your own and take advantage of the properties provided in the carousel object.

STATIC IMAGE

The Static Image recommender template is rendered when a user is shown a recommender configured to show a Static Image in a zone. The image object contains a link, so the image can be wrapped with an anchor tag allowing users to be directed to a specific page when the image is clicked.

OBJECTS & PROPERTIES

OVERVIEW

This article lists all the objects and properties available for use in PureClarity Templates and server-side responses.

IMAGE

For use with Image content type:

Name Type Description
url string The location of the image file
linkLocation string The link location of where a user should be taken if they click the image
altText string The Alt Text attribute for the image
type string Set to “staticimage”
clickEvt string The JavaScript function to be executed on mouse down over the image element.
NOTE: This is required to track when users click through on a product. If this is omitted then reporting will be inaccurate.
html string [Serverside mode only] The html rendered version based on the Template

Carousel has two main objects, the carousel object and the carousel image object:

Name Type Description
height number The height of the carousel
width number The width of the carousel
milliseconds number Milliseconds before auto scrolling, if active
autoscroll boolean Sets if autoscroll is on
isResponsive boolean Expands to width of container
isMaxWidth boolean If responsive, set’s if height and width is the max that the carousel should be
stopOnHover boolean If autoscroll is on, this sets if it should stop when mouse over
images ARRAY<carousel_Image> And array containing Carousel Image objects
type string Set to “carousel”
html string [Serverside mode only] The html rendered version based on the Template

CAROUSEL IMAGE

Name Type Description
url string The location of the image file
linkLocation string The link location of where a user should be taken if they click the image
altText string The Alt Text attribute for the image
showContent boolean Sets if text content should be shown
content string The html content to overlay the image
left number The left pixels for the content
top number The top pixels for the content
index number The index of the image in the array (zero based index)
clickEvt string The JavaScript function to be executed on mouse down over the image element.
NOTE: This is required to track when users click through on a product. If this is omitted then reporting will be inaccurate.

HTML

The properties for html content is as follows:

Name Type Description
html string The raw HTML
type string Set to “html”

PRODUCT RECOMMENDER

Recommenders have two main objects, the main recommender object with a title and an array of items for the recommender:

Name Type Description
title string The title of the recommender
items ARRAY<Product> An array of product objects
type string Set to “recommender-product”

PRODUCT

Name Type Description
Id string The unique product Id
Sku string The product sku
Title string The product title
Link string The url to the product
Image string The url to the main product image
Description string The description of the product
Categories ARRAY<string> An array of category IDs that the product is in
SearchTags ARRAY<string> Search tags if provided in the feed
AssociatedSkus ARRAY<string> Child/Variant skus of the product, if provided in the feed
Brand brand A brand object that is associated with the product. Only available if a brand Id was sent in the product feed that has associated brand data in the brand feed.
Price number The product price
DisplayPrice string A formatted price with currency for the product (e.g. $19.00)
WasPrice number The “Wws” price for a product that is in a promotion
DisplayWasPrice string A formatted was price with currency for the product (e.g. $19.00)
CurrencySymbol string The currency symbol for this products price
clickEvt string The JavaScript function to be executed on mouse down over the product element.
NOTE: This is required to track when users click through on a product. If this is omitted then reporting will be inaccurate.
[custom attribute] ARRAY<string | number> If a custom attribute was sent in the product feed, you can access it as part of the product object using the same name that was provided in the feed

CATEGORY RECOMMENDER

Recommenders have two main objects, the main recommender object with a title and an array of items for the recommender:

Name Type Description
title string The title of the Recommender
items ARRAY<Category> An array of category objects
type string Set to “recommender-category”

CATEGORY

Name Type Description
Id string The category’s unique Id
DisplayName string The category name
Image string The url to the category image
Link string A url link to take an optional brand page
Description string An optional description text
Parents ARRAY<string> An array of parent category IDs
Children ARRAY<string> An array of immediate child category IDs
AllChildIds ARRAY<string> An array of ALL child IDs, not just immediate children.

BRAND RECOMMENDER

Recommenders have two main objects, the main recommender object with a title and an array of items for the recommender:

Name Type Description
title string The title of the recommender
items ARRAY<Brand> An array of brand objects
type string Set to “recommender-brand”

BRAND

Name Type Description
Id string The brands unique Id
DisplayName string The brands name
Image string The url to the brands image
Link string A url link to take an optional brand page
Description string An optional description text
  Bespoke Integration