Personalisation

8min
The personalisation is an add-on feature. To enable the option, please submit a support ticket﻿
When a customer enters a physical shop, they may express their preferences to an in-store assistant by highlighting the colours they like, the brands they prefer and what they have purchased before.
The in-store assistant would then use this information to show the customer products they are most likely interested in first, before showing them any others that still may be suitable.
Klevu A.I. is your online assistant.
This personalisation can be provided in two ways:
including some information about the customer's browsing history with each request
defining your own boosting rules based on the information you already know about the customer
You can read more about how this works in our Personalisation Guide.
Browsing History
If you provide the IDs of products which the customer has recently interacted with, the Klevu A.I. will figure out the common aspects of those products and influence the search results.
The easiest way to highlight this is with an example:
In the JSON below, the four record IDs provided within context represent the products that a customer has clicked on before making a search. They all have the brand 'MNH'.
There may be other attributes those products have in common, such as price, color, material, etc., however, we have specified in the query that we are only interested in personalisation based on 'brand'.
When you execute the query, you will see some brand 'MNH' results are coming first.
Note that the impact of personalisation is not always apparent. Klevu is clever. If the customer has recently been looking at 'shoes' but now they are searching for 'washing machines', Klevu will know to disregard any interactions that are not relevant to the current search query.
This is an example how to utilize the recently visited products to personlised the search results. 
POST
Request
Body Parameters
enablePersonalisation
required
Boolean
This must be set to 'true' for enabling personalisation on a particular request. If set to 'false', the recent objects within the context object will be ignored
fields
optional
Array
This is an optional field. By default, Klevu will analyse all attributes of the records the customer has interacted with, in order to determine the common patterns. If you prefer to focus on particular aspects, for example brand or price, specify those attributes within this object.
recentObjects
optional
Object
Use this object to specify the records (e.g. products, categories, etc.) that were recently interacted with by a customer.

Please only specify one recentObject object per record type, one for all KLEVU_PRODUCT entries, another for all KLEVU_CMS pages visited, etc.

Each recentObject object may contain multiple record objects (e.g. 5 recently viewed products). The most recently clicked record should be the first element in the array.
Request Body (JSON)
PHP
JS
Java
Node.js
var data = JSON.stringify({"recordQueries":[{"settings":{"personalisation":{"enablePersonalisation":true,"fields":["brand"]},"context":{"recentObjects":[{"typeOfRecord":"KLEVU_PRODUCT","records":[{"id":"31366487507006"},{"id":"31366466633790"},{"id":"31366456311870"},{"id":"31366467944510"}]}]},"id":"productSearch","typeOfRecords":["KLEVU_PRODUCT"],"limit":5,"query":{"term":"short"},"fields":["id","name","brand"]}}],"context":{"apiKeys":["klevu-156925593843210765"]}});

var xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);
var data = JSON.stringify({"recordQueries":[{"settings":{"personalisation":{"enablePersonalisation":true,"fields":["brand"]},"context":{"recentObjects":[{"typeOfRecord":"KLEVU_PRODUCT","records":[{"id":"31366487507006"},{"id":"31366466633790"},{"id":"31366456311870"},{"id":"31366467944510"}]}]},"id":"productSearch","typeOfRecords":["KLEVU_PRODUCT"],"limit":5,"query":{"term":"short"},"fields":["id","name","brand"]}}],"context":{"apiKeys":["klevu-156925593843210765"]}});

var xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);
Responses
200
{
   meta: {
      qTime: 22,
      responseCode: 200
   },
   queryResults: [
      {
         id: "productSearch",
         meta: {
            qTime: 7,
            noOfResults: 5,
            totalResultsFound: 104,
            typeOfSearch: "WILDCARD_AND",
            offset: 0,
            debuggingInformation: {},
            notificationCode: 1,
            searchedTerm: "short",
            apiKey: "klevu-156925593843210765",
            isPersonalised: false
         },
         records: [
            {
               name: "Erika Running Short",
               id: "31366431014974",
               brand: "KSD"
            },
            {
               name: "Erika Running Short",
               id: "31366431080510",
               brand: "KSD"
            },
            {
               name: "Erika Running Short",
               id: "31366431146046",
               brand: "KSD"
            },
            {
               name: "Meteor Workout Short",
               id: "31366465781822",
               brand: "KKE"
            },
            {
               name: "Hawkeye Yoga Short",
               id: "31366465126462",
               brand: "MNH"
            }
         ],
         filters: []
      }
   ]
}
{
   meta: {
      qTime: 22,
      responseCode: 200
   },
   queryResults: [
      {
         id: "productSearch",
         meta: {
            qTime: 7,
            noOfResults: 5,
            totalResultsFound: 104,
            typeOfSearch: "WILDCARD_AND",
            offset: 0,
            debuggingInformation: {},
            notificationCode: 1,
            searchedTerm: "short",
            apiKey: "klevu-156925593843210765",
            isPersonalised: false
         },
         records: [
            {
               name: "Erika Running Short",
               id: "31366431014974",
               brand: "KSD"
            },
            {
               name: "Erika Running Short",
               id: "31366431080510",
               brand: "KSD"
            },
            {
               name: "Erika Running Short",
               id: "31366431146046",
               brand: "KSD"
            },
            {
               name: "Meteor Workout Short",
               id: "31366465781822",
               brand: "KKE"
            },
            {
               name: "Hawkeye Yoga Short",
               id: "31366465126462",
               brand: "MNH"
            }
         ],
         filters: []
      }
   ]
}
﻿
Try it here!
<iframe src="https://codesandbox.io/embed/klevu-api-sendbox-4ktfrp?fontsize=14&hidenavigation=0&theme=dark&view=preview&initialpath=?payload=browsingHistory"
     style="width:100%; height:550px; border:0; border-radius: 4px; overflow:hidden;"
     title="klevu_api sendbox"
     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
     
   ></iframe>
<iframe src="https://codesandbox.io/embed/klevu-api-sendbox-4ktfrp?fontsize=14&hidenavigation=0&theme=dark&view=preview&initialpath=?payload=browsingHistory"
     style="width:100%; height:550px; border:0; border-radius: 4px; overflow:hidden;"
     title="klevu_api sendbox"
     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
     
   ></iframe>
﻿
Known Preferences
If you have already built up a profile of your customer and would like to use what you know about them to promote certain results, you can use the boost object within each record query.
There are three ways the records can be boosted:
filter conditions
keywords or phrases
IDs of specific records
For example, let's say you have an online store with an area where customers can log in.
From your store's purchase history, you know that one customer is particularly interested in the brand 'KKE'.
From your analytics data, you also know the same customer also looked at the product detail page of the product with ID: '31366487375934' many times.
Finally, you have an area where customers can specify keywords of their interests, and this customer wrote 'comfortable'.
As a merchant with all of this information available, you can build up a profile about this customer. The sample to the right shows how you would convey this information to Klevu during a search.
To find out more about how boosting works with your existing merchandising rules, please read this article on How Personalisation Works.
This is an example how to boost products based on users preference. 
POST
Request
Body Parameters
filters
optional
Array
Specify filter values to apply a boosting score to. They key is the unique identifier of the attribute, eg. Color. Each of the values represents the value of that filter to boost, eg. red or blue.
keywords
optional
Array
Specify keywords or phrases to apply a boosting score to, for example "comfortable".
records
optional
Array
Specify the Klevu ID of any records to apply a boosting score to.
weight
optional
Number
The boosting value to be applied, a decimal between 0 - 999. Please specify values above 1 for boosting the records up the rankings, and a value of 0 to 1 to de-boost records down the rankings.
Request Body (JSON)
PHP
JS
Java
Node.js
var data = JSON.stringify({"recordQueries":[{"boost":{"filters":[{"key":"brand","values":["KKE"],"weight":200},{"key":"brand","values":["MNH","KSD"],"weight":150}],"keywords":[{"phrase":"comfortable","weight":100}],"records":[{"id":"31366487375934","weight":300}]},"id":"productSearch","settings":{"query":{"term":"short"},"limit":5,"typeOfRecords":["KLEVU_PRODUCT"],"fields":["id","name","brand"]}}],"context":{"apiKeys":["klevu-156925593843210765"]}});

var xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);
var data = JSON.stringify({"recordQueries":[{"boost":{"filters":[{"key":"brand","values":["KKE"],"weight":200},{"key":"brand","values":["MNH","KSD"],"weight":150}],"keywords":[{"phrase":"comfortable","weight":100}],"records":[{"id":"31366487375934","weight":300}]},"id":"productSearch","settings":{"query":{"term":"short"},"limit":5,"typeOfRecords":["KLEVU_PRODUCT"],"fields":["id","name","brand"]}}],"context":{"apiKeys":["klevu-156925593843210765"]}});

var xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://eucs15v2.ksearchnet.com/cs/v2/search");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);
Responses
200
{
    "meta": {
        "qTime": 16,
        "responseCode": 200
    },
    "queryResults": [
        {
            "id": "productSearch",
            "meta": {
                "qTime": 13,
                "noOfResults": 5,
                "totalResultsFound": 104,
                "typeOfSearch": "WILDCARD_AND",
                "offset": 0,
                "debuggingInformation": {},
                "notificationCode": 1,
                "searchedTerm": "short",
                "apiKey": "klevu-156925593843210765",
                "isPersonalised": false
            },
            "records": [
                {
                    "name": "Erika Running Short",
                    "id": "31366431146046",
                    "brand": "KSD"
                },
                {
                    "name": "Erika Running Short",
                    "id": "31366431014974",
                    "brand": "KSD"
                },
                {
                    "name": "Erika Running Short",
                    "id": "31366431080510",
                    "brand": "KSD"
                },
                {
                    "name": "Meteor Workout Short",
                    "id": "31366465781822",
                    "brand": "KKE"
                },
                {
                    "name": "Hawkeye Yoga Short",
                    "id": "31366465191998",
                    "brand": "KKE"
                }
            ],
            "filters": []
        }
    ]
}
{
    "meta": {
        "qTime": 16,
        "responseCode": 200
    },
    "queryResults": [
        {
            "id": "productSearch",
            "meta": {
                "qTime": 13,
                "noOfResults": 5,
                "totalResultsFound": 104,
                "typeOfSearch": "WILDCARD_AND",
                "offset": 0,
                "debuggingInformation": {},
                "notificationCode": 1,
                "searchedTerm": "short",
                "apiKey": "klevu-156925593843210765",
                "isPersonalised": false
            },
            "records": [
                {
                    "name": "Erika Running Short",
                    "id": "31366431146046",
                    "brand": "KSD"
                },
                {
                    "name": "Erika Running Short",
                    "id": "31366431014974",
                    "brand": "KSD"
                },
                {
                    "name": "Erika Running Short",
                    "id": "31366431080510",
                    "brand": "KSD"
                },
                {
                    "name": "Meteor Workout Short",
                    "id": "31366465781822",
                    "brand": "KKE"
                },
                {
                    "name": "Hawkeye Yoga Short",
                    "id": "31366465191998",
                    "brand": "KKE"
                }
            ],
            "filters": []
        }
    ]
}
﻿
Try it here!
<iframe src="https://codesandbox.io/embed/klevu-api-sendbox-4ktfrp?fontsize=14&hidenavigation=0&theme=dark&view=preview&initialpath=?payload=knownPreferences"
     style="width:100%; height:550px; border:0; border-radius: 4px; overflow:hidden;"
     title="klevu_api sendbox"
     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
     
   ></iframe>
<iframe src="https://codesandbox.io/embed/klevu-api-sendbox-4ktfrp?fontsize=14&hidenavigation=0&theme=dark&view=preview&initialpath=?payload=knownPreferences"
     style="width:100%; height:550px; border:0; border-radius: 4px; overflow:hidden;"
     title="klevu_api sendbox"
     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
     
   ></iframe>
﻿
﻿
Updated 30 Oct 2023
Did this page help you?
Configurations
Examples