Recommendations

Recommendations provides the shop users with recommended products e.g. on a product detail page. You can also create cart based or top seller recommendations. The possibilities are endless! In order to use the capabilities at their full potential we will guide you through them on this page.

Configuration

After the Recommendation module has been enabled for your Makaira Instance, you can access the configuration section via the menu entry "Recommendations".

Create a Recommendation

When you want to create a new Recommendation (Reco), you'll be asked to enter the following information:

Input field	Example	Description
Name	Similar Products	A name that describes your Reco
Identifier	similar-products	A unique identifier - you will need to provide this identifier when you integrate the Reco in your store pages via the Makaira API

🚧
Your are not done yet! After you created the Recommendation, switch to the edit mode in order to adjust its settings.

Edit a Recommendation

After you created a Recommendation (Reco), you can edit it and adjust the available settings to your needs.
The following settings can be configured and adjusted:

Name and Identifier
Please take a look at the "create a recommendation" section for more details about these fields.

Recommendation Base
By choosing an option among the list, you define the data source for your Reco. The following options are available:

Options	Description
Picture Similaritiy°	Products that look similar to the current product. (The image in the picture_url_main field is will be used)
Text Similarity	Products that use a similar product description or have similarities in other text fields.
Bought together°°	Products that are usually bought together with this product.
Behaviour history (Cart based)°°	Other people who had this in their shopping cart also bought these products.
Behaviour history (User based)°°	Other users who bought this also bought these products.
None	No base data will be used, you will have access to the "raw" product data thats imported to Makaira - can be used for Topseller Recos or Best Rated Recos or completely custom Recos where you don't want to rely on any sort of similarity / preweighted result.

Footnotes:
°: After you imported your picture url data in Makaira we will start calculating the picture similarity for you, please contact our Makaira Support for this.
°°: Makaira Tracking is required in order to use this Recommendation Base.

Populate with Text Similarity

🚧
This option is not available for the following Recommendation Bases: Text Similarity, None

This option will add products based on the Recommendation Base "Text Similarity", if not enough results can be retrieved for your selected primary Recommendation Base.

Filter

📘
This option will add products based on the Recommendation Base "Text Similarity", if not enough results can be retrieved for your selected primary Recommendation Base.

With filters, you can filter down the recommended products. You can either use concrete values or values based on the product that the recommendation is based on (input product).

Comparators
The following comparators are available:

Comparator	Required Data Type	Description
like	any	filter where field contains the value
not like	any	filter where field does not contain the value
in list	any	filter where the field value is in the specified list
not in list	any	filter where the field value is not in the specified list
empty	any	filter where the field value is empty
not empty	any	filter where the field value is not empty
greater	int, float	filter where the field value is greater than
greater or equal	int, float	filter where the field value is greater than or equal
less	int, float	filter where the filed value is less than
less or equal	int, float	filter where the field value is less than or equal
between	date	filter where the value is between a range of period

"Compare With" field

You can choose between the following options:

Field value	Description
Static Value	A static value is used for the comparison
Input Product	The value will be taken from the product that you sent during the request to the Makaira API.

Usage of filter function
Please watch the short video to see the filter functionality in action:

Boosting

📘
Use our Preview feature in order to see your changes in real time.

With this option you can boost specific products in your Recommendation.

Comparators
The following comparators are available:

Comparator	Description
use value	Special case for boosting: only for int/float fields - this boosts the product based on the value in the field (e.g. higher rated products to the front)
like	product with field contains the value will be moved to a higher position
not like	product with field not contain the value will be moved to a higher position
in list	product with field's value are in the list of selection will be moved to a higher position
not in list	product with field's value are not in the list of selection will be moved to a higher position
empty	product with field's value is empty will be moved to a higher position
not empty	product with field's value is not empty will be moved to a higher position

Usage of the boosting function
Please watch the short video to see the boosting functionality in action:

Extra features

Use Machine Learning

🚧
This feature only available if you use Makaira Tracking and if you have purchased the Machine Learning module.

This option allows you to automatically apply user-specific data (e.g. device, location) to your Recommendations.

You need to send the constraints IP, User-Agent, Timezone when making a request to the Makaira API (you can find more details in the "API Integration" section)

You can find more information about our Machine Learning module here.

Use Ranking-Mix

This option allows you to reuse your Ranking-Mix on the Recommendations. When using this option, you don't have to reconfigure your general boosting settings.

Randomize

This option adds some entropy to the results. The score of each recommended product may change randomly up to 20%. As a result a user may not always see the same recommendations and you can increase the probability that they may see something that interests them. We recommend to use this option only together with some additional boosting to make sure that the results are not completely random.

Preview

We are providing a preview feature, that can help you during the adjustment of e.g. Filter and Boosting settings. You can open the Preview in the upper right corner. Try out your settings by searching for a product and clicking on it in order to see recommended products.

Please watch the short video to see the Preview functionality in action:

API integration

Makaira allows you to integrate Recommendations in your store front by using our API.
For detailed information about our Recommendation API, please take a look in our Makaira API Documentation. Specifically, look in the "Recommendation" section of the documentation.

_{* Recommendations are only available when you book the Makaira Recommendations module.}

Dynamic Recommendation configuration in the API request

For some use cases it is useful to set the configuration directly in the API request of you storefront/shop. These makes sense when the shop has more information about the customer than the stateless Makaira API. One use case might be that your shop knows for example if the current customer is price sensitive or not. To make profit of this knowledge you can show the price sensitive customer cheap top-seller and the others high priced articles. You have to modify your request for each customer.

Create an empty setting for you new recommendation. This means you just need to give it an ID. Note that all other configurations will be ignored for our use case.

Create an API request with your custom settings. You can use the Makaira UI with its preview to help you to get the raw structure of the request (take a look at the network tab of your browser when you use the preview, the request will go to "recommendation/public").
The example request that sets a main category and boosts a price greater than 33 may look like:

{
  "constraints": {
    "query.language": "de",
    "query.shop_id": "1",
    "query.use_stock": false
  },
  "fields": [
    "id",
    "title",
    "active",
    "picture_url_main"
  ],
  "count": 200,
  "recommendationId": "my_reco_id",
  "productId": "",
  "boosting": [
    {
      "field": "price",
      "operator": "gte",
      "boostingStrength": "med",
      "type": "double",
      "compareWith": "staticValue",
      "value": [
        "33"
      ]
    }
  ],
  "filter": [
    {
      "field": "maincategory",
      "operator": "inList",
      "type": "text",
      "compareWith": "staticValue",
      "value": "my_category"
    }
  ],
  "id": 40,
  "isActive": true,
  "isPopulateTextSimilarity": false,
  "boostWithSimilarAttributes": false,
  "isUseMachineLearning": false,
  "isUseRankingMix": false,
  "name": "em",
  "randomness": false,
  "diversify": false
}

Adapt your request to your needs and test it before you integrate it in your system. Please note that the field "productId" has to be set, but might be an empty string.