Custom Personalization

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:

  1. Personalization module booked via Makaira Sales and "Personalization -> Custom Personalization" activated via the "Machine Learning" menu entry
  2. 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")
  3. 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)
  4. 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 availability issues. So make sure your service does compute intense / long running calculations beforehand.

      (5) Response of personalized list

      Please respond on our (3) Request of personalization to your AI/BI-API with the following result where the order of the list is representing the final sorting for the customers requested product list.

      {
    "products": [
        {
    	    "id": "3"
        },
        {
    	    "id": "1"
        },
        {
    	    "id": "2"
        }
    ]
}

      Possible Solution for mapping data between Makaira and non-compliant external Personalization Services

      Sometimes providers like trbo cannot comply to our standardized API so you may have to create a small microservice that is called by makaira, which on the other hand just transforms the requests or even merges/reorders product lists based on the non-compliant Personalization service.

      This could look like the following:


      ​

      Back to top