Custom Personalization
This Feature is in alpha-state and not yet available.
If you use your own BI tools or other machine learning / AI-based tools and you want to reorder your product lists (search, category, manufacturer and more) based on your data you can use our Custom Personalization.
Requirements:
- Personalization module booked via Makaira Sales and "Personalization -> Custom Personalization" activated via the "Machine Learning" menu entry
- A public API Endpoint of your BI/AI-Tool that we can call to reorder product lists (see Section "Custom Personalization API Endpoint" below – Enter your API Endpoint under "Machine Learning" -> "Personalization -> Custom Personalization")
- optional: If needed, Makaira can provide a full set of products and categories via the additional module Makaira Feed Engine (available formats: XML, JSON, CSV)
- optional: Implementation of a frontend payload (user id, etc.) that we will be passed through to your "Custom Personalization API Endpoint"
Custom Personalization API Endpoint
The communication for the personalization runs server-to-server from the Makaira API to your AI/BI API. If you need additional data from the frontend for your rescoring & resorting you can always pass data from the frontend to the Makaira API.
To get a better understanding for the communication here follows a short flow diagram:

All parts that are highlighted bold in the graphic are parts you have to provide to get the full custom personalization experience. Lets look at every step in more detail:
(1) Request for product list with optional payload
In every enterprise/page
and search
or search/public
request you send to Makaira we need the information that the personalization should be executed in the constraints -> personalization.type
and optional the payload thats provided by e.g. your tracking js library or any other source in constraints -> personalization.data
The following example is for example a enterprise/page
request for the category with personalization of the URL /my/category
POST demo.makaira.io/enterprise/page
{
"url": "\/my\/category\/",
"constraints": {
"query.shop_id": "oxbaseshop",
"query.language": "de",
"personalization.type": "custom",
"personalization.data": {
"your-user-id": "42",
"any-other-key": "data",
"even-more-complex": { "this": "is", "an": "object" }
}
},
"count": 10,
"offset": 0
}
For more information to the endpoints please consult our Makaira API Docs
Please make sure that the additional payload always contains the data you need for a personalization - also in the first page request. E.g. a tracking id thats generated by some sort of browser side javascript library normally is not available at the first request to makaira.
Otherwise please make sure that your AI/BI Server API can handle empty IDs or work with dummy ids so that your customer experience ist not degrading.
(3) Request of personalization to your AI/BI-API
The following request schema will be sent from Makaira to your API Endpoint via a POST-Request, where in metadata
all frontend data will be passed through. Please note that we restrict the personalisation to the first 500 results of you request, while the remaining results will only be availible in Makaira standard sorting.
We will always send product ids to your endpoint, no variant ids or EANs - we take the product id from the field id
in the datatype makaira-productgroup
Additional we provide our score value but you are free to use it or to just ignore it.
POST <Your AI/BI-API-URL>
{
"metadata": {
"your-user-id": "42",
"any-other-key": "data",
"even-more-complex": { "this": "is", "an": "object" }
},
"products": [
{
"id": "1",
"score": "0.8736"
},
{
"id": "2",
"score": "0.5605"
},
{
"id": "3",
// score will be omitted if no score could be calculated
}
]
}
(4) Rescoring & Reordering products
Here you can execute your magic.
Important: We stop requesting your API after 200ms and will return the un-personalized product list as a safety guard if e.g. your server is not responding or if there are other issues.
(5) Response of personalized list
Please respond on our (3) Request of personalization to your AI/BI-API with the following result.
We don't use the score value anymore at this point - we will just take care to reorder the product list based on the list you are responding to us
{
"products": [
{
"id": "3",
"score": "12.8736"
},
{
"id": "1",
"score": "10.5605"
},
{
"id": "2",
// score can be omitted by you
}
]
}