Child pages
  • Ten Minutes Guide
Skip to end of metadata
Go to start of metadata

Documentation has moved

Please use only the new documentation, this one in´s not updated anymore.

For a general introduction and information about the Personalization Solution you can find detailled documentation under

For the EzSystemsRecommendationBundle you can find the documentation under

Thx in advance,

the YOOCHOOSE team

About Recommendations

The idea of the recommendation engine is quite simple and built upon four main steps.

A User visits a web shop and navigates through the shop and leaves some footprints. The most popular footprints are selecting and purchasing of products (1). This information is sent to the event tracker service of the recommendation engine every time these events happen (2). The recommendation engine accumulates the tracked events, categorizes them and calculates recommendations for every product and every user in the web-shop (3). All recommendations are available over the recommender service. They can be fetched and presented to users during their sessions or sent out as e.g. a newsletter (4).

Tracking Events

Step one is called tracking. Every page must call special tracking URL. The simplest way is to place a tiny image on every product page, just it is usually done for analytic tools or visitor counter. It looks like this:

<img href="" width="1" height="1">

Replace "00000" with the ID you have got after the registration. Is is the same for all the tracking calls.
Replace "max.mustermann" with the user ID or session ID of the user currently signed in on you webpage (any URL encoded string is allowed).
Replace "100" with the numeric ID of the product (it must be 1 to 2147483647)

A simple PHP snippet for the tracking.

   $mandator_id = '00000';
   $product_id = 123;
   $server = '';
   $tracking = $server.'/ebl/'.$mandator_id.'/click/'.urlencode(session_id()).'/1/'.$product_id;
   echo "<img href='$tracking' width='1' height='1'>";

Similar tracking image must be placed on the confirmation page after the payment process.

   $server = '';
   foreach ($just_bought_products as $product_id) {
      $tracking = $server.'/ebl/'.$mandator_id.'/buy/'.urlencode(session_id()).'/1/'.$product_id;
      echo "<img href='$tracking' width='1' height='1'>\n";

Fetching Recommendations

After some time the recommendation engine collects enough events and is able to generate recommendations. Recommendations can be easily fetched using the following calls:
Returns the most popular products in the last month.,CLICKED
Returns products the current user (here "max.mustermann") is most probably interesting in. It is so called personalized recommendation.
Returns products most probably interesting to any user who is interested in the product 123.

To make calls, one must use the ID (here "00000") and license key that are generated upon registration.

The result of these calls is JSON formatted and looks like the following:

  "recommendationResponseList": [ 
    { "itemId": 12 }, { "itemId": 13 }, { "itemId": 14 }

Here is a small PHP snippet for making request and parsing results:

  $mandator_id = '00000';
  $license_key = '86109-2778-8757-7597-4319';
  $server = "";
  $scenario = "category_page";
  $url = $server.'/ebl/00000/'.urlencode(session_id()).'/'.urlencode($scenario).'.json';
  $curl = curl_init();
  $request = array(
	CURLOPT_URL => $url, 
	CURLOPT_USERPWD => "$mandator_id:$license_key");
  curl_setopt_array($curl, $request);  
  $body = curl_exec($curl);
  $recommendations = json_decode($body);
  if ($recommendations && isset($recommendations->recommendationResponseList)) {
    foreach ($recommendations->recommendationResponseList as $product) {
      $product_id = $product->itemId;
      # load the product and create the recommendation HTML here
      echo(" \n");
  } else {
      echo("Error: ".$body);

Next steps

For the most simple but still very effective recommendations, the steps described above are actually sufficient. Tracking more events, using additional parameters and custom scenario configuration enables the following additional features:

  • Filtering recommendations based on category
  • Getting usage and revenue statistic
  • Recommendation based on the shopping basket
  • Filtering repeated recommendations

Additional features are available for the advanced edition of the recommendation engine

  • Using "rate" and "like" events
  • Additional models like content based, stereotype based, random, history etc.
  • Multiple product types (for example food/non-food or article/image/video) and cross type recommendations
  • Price based filtering (do not recommend cheap products)
  • Grouping products by custom attributes (size, color, source, theme etc.)
  • A/B testing

User Guide: User Guide
Developer Guide:  Developer Guide
Recommendation Engine Administration GUI: 

  • No labels