IBX-8970 Improved personalization details. (#2515)

Author: nkostiv

docs/personalization/enable_personalization.md

@@ -14,7 +14,7 @@ instance must [request access to the service]([[= user_doc =]]/personalization/e
 ## Set up customer credentials
 
 When you receive the credentials, add them to your configuration.
-In the root folder of your project, edit either the `.env` or `.env.local` file 
+In the root folder of your project, edit the `.env.local` file
 by adding the following lines with your customer ID and license key: 
 
 ```
@@ -23,7 +23,7 @@ PERSONALIZATION_LICENSE_KEY=67890-1234-5678-90123-4567
 PERSONALIZATION_HOST_URI=https://server_uri
 ```
 
-!!! note "Configuring user credentials for different customers"
+!!! note "Configuring user credentials for multisite setup and different personalization customers"
 
     If your installation [hosts multiple sites]([[= user_doc =]]/personalization/use_cases/#multiple-website-hosting) with different 
     customer IDs, for example, to provide separate recommendations for different 
@@ -140,6 +140,9 @@ ibexa:
                     content:
                         use_remote_id: true
 ```
+!!! note "Support for alphanumeric content identifier"
+
+     Contact [email protected] with your organization's requirements to have the alphanumeric content identifier enabled.
 
 #### Enable tracking
 
@@ -437,8 +440,8 @@ if the content Fields were previously exported by the export script.
                 "itemType": 38,
                 "relevance": 3,
                 "links": {
-                    "clickRecommended": "//event.test.perso.ibexa.co/api/723/clickrecommended/someuser/38/71?scenario=popular&modelid=4199&categorypath=&requestuuid=d75e7cf0-e4ca-11e7-a94d-0a64dbbea736",
-                    "rendered": "//event.test.perso.ibexa.co/api/723/rendered/someuser/38/71?scenario=popular&modelid=4199&categorypath=&requestuuid=d75e7cf0-e4ca-11e7-a94d-0a64dbbea736"
+                    "clickRecommended": "//event.perso.ibexa.co/api/723/clickrecommended/someuser/38/71?scenario=popular&modelid=4199&categorypath=&requestuuid=d75e7cf0-e4ca-11e7-a94d-0a64dbbea736",
+                    "rendered": "//event.perso.ibexa.co/api/723/rendered/someuser/38/71?scenario=popular&modelid=4199&categorypath=&requestuuid=d75e7cf0-e4ca-11e7-a94d-0a64dbbea736"
                 },
                 "attributes": [
                     {
@@ -472,8 +475,8 @@ if the content Fields were previously exported by the export script.
                 "itemType": 38,
                 "relevance": 1,
                 "links": {
-                    "clickRecommended": "//event.test.perso.ibexa.co/api/723/clickrecommended/someuser/38/75?scenario=popular&modelid=4199&categorypath=&requestuuid=d75e7cf0-e4ca-11e7-a94d-0a64dbbea736",
-                    "rendered": "//event.test.perso.ibexa.co/api/723/rendered/someuser/38/75?scenario=popular&modelid=4199&categorypath=&requestuuid=d75e7cf0-e4ca-11e7-a94d-0a64dbbea736"
+                    "clickRecommended": "//event.perso.ibexa.co/api/723/clickrecommended/someuser/38/75?scenario=popular&modelid=4199&categorypath=&requestuuid=d75e7cf0-e4ca-11e7-a94d-0a64dbbea736",
+                    "rendered": "//event.perso.ibexa.co/api/723/rendered/someuser/38/75?scenario=popular&modelid=4199&categorypath=&requestuuid=d75e7cf0-e4ca-11e7-a94d-0a64dbbea736"
                 },
                 "attributes": [
                     {

docs/personalization/integrate_recommendation_service.md

@@ -22,7 +22,7 @@ The easiest way of embedding the tracking URL is placing a one pixel image on ev
 like in the case of analytical tools or visitor counters.
 A code that includes an image looks like this:
 
-`<img href="https://event.perso.ibexa.co/ebl/00000/click/<user_ID>/<content_type_ID>/<content_ID>" width="1" height="1">`
+`<img href="https://event.perso.ibexa.co/api/00000/click/<user_ID>/<content_type_ID>/<content_ID>" width="1" height="1">`
 
 where:
 
@@ -39,19 +39,21 @@ PHP:
 
 ``` php
 $mandator_id = '00000';
+$content_type_id = '1';
 $product_id = '123';
 $server = '//event.perso.ibexa.co';
-$tracking = $server.'/ebl/'.$mandator_id.'/click/'.urlencode(session_id()).'/1/'.$product_id;
+$tracking = $server.'/api/'.$mandator_id.'/click/'.urlencode(user_id()).$content_type_id.$product_id;
 echo "<img href='$tracking' width='1' height='1'>";
 ```
 
 JavaScript:
 
 ``` js
 var mandator_id = '00000';
+var content_type_id = '1';
 var product_id = '123';
 var server = '//event.perso.ibexa.co';
-var url = server + '/api/' + mandator_id + '/click/' + getSessionId() + '/1/' + product_id;
+var url = server + '/api/' + mandator_id + '/click/' + getUserId() + content_type_id + product_id;
 var ycimg=new Image(1,1);
 ycimg.src=url;
 ```
@@ -61,7 +63,7 @@ A similar tracking image can be placed on a confirmation page that ends the paym
 ``` php
 $server = '//event.perso.ibexa.co';
 foreach ($just_bought_products as $product_id) {
-   $tracking = $server.'/ebl/'.$mandator_id.'/buy/'.urlencode(session_id()).'/1/'.$product_id;
+   $tracking = $server.'/api/'.$mandator_id.'/buy/'.urlencode(user_id()).$content_type_id.$product_id;
    echo "<img href='$tracking' width='1' height='1'>\n";
 }
 ```
@@ -128,7 +130,7 @@ $mandator_id = '00000';
 $license_key = '67890-1234-5678-90123-4567';
 $server = "https://reco.perso.ibexa.co";
 $scenario = "category_page";
-$url = $server.'/ebl/00000/'.urlencode(session_id()).'/'.urlencode($scenario).'.json';
+$url = $server.'/api/v2/00000/'.urlencode(user_id()).'/'.urlencode($scenario).'.json';
 
 $curl = curl_init();
 $request = array(

docs/personalization/tracking_integration.md

@@ -11,15 +11,15 @@ where the event must be sent [pixel tracking](integrate_recommendation_service.m
 For example, with HTML: 
 
 ``` html
-<img href="https://event.perso.ibexa.co/ebl/00000/click/johndoe/1/100?categorypath=/a/ab/abc" width="1" height="1">
+<img href="https://event.perso.ibexa.co/api/00000/click/johndoe/1/100?categorypath=/a/ab/abc" width="1" height="1">
 ```
 
 or with JavaScript:
 
 ``` js
 <script type="text/javascript">
 var img = new Image(1,1);
-img.src = "https://event.perso.ibexa.co/ebl/00000/click/johndoe/1/100?categorypath=/a/ab/abc";
+img.src = "https://event.perso.ibexa.co/api/00000/click/johndoe/1/100?categorypath=/a/ab/abc";
 </script>
 ```
 

docs/personalization/tracking_with_ibexa-tracker.md

@@ -9,8 +9,8 @@ JavaScript in your site.
 The approach is very generic and evaluate it if it meets your
 **requirements and security policy**.
 
-If you want the `userid` to be generated automatically, leave out the user 
-params in the `_ycq.push` calls.
+If you want the `userid` to be generated automatically, set user
+parameter as empty `''` in the `_ycq.push` calls.
 If a predefined cookie already exists, it is used. 
 Otherwise a new one is created.
 
@@ -32,7 +32,7 @@ the closing `</head>` tag.
 <script type="text/javascript">
   var _ycq = _ycq || [];
   _ycq.push(['_setMandator', '<YOUR_MANDATOR_ID>']);
-  _ycq.push(['_trackEvent', '1', 'click', '<PAGE_ID>', '<USER_ID>']);
+  _ycq.push(['_trackEvent', '<CONTENT_TYPE_ID>', 'click', '<CONTENT_ID>', '<USER_ID>']);
 
   (function() {
     var yc = document.createElement('script'); 
@@ -85,17 +85,17 @@ Here is an example of typical usage of the method:
 ``` js
 var _ycq = _ycq || [];
 _ycq.push(['_setMandator', '<YOUR_MANDATOR_ID>']);
-_ycq.push(['_trackEvent', '1', 'click', 'https://mydoc.pdf', 'user1234']);
+_ycq.push(['_trackEvent', '1', 'click', '10', '']);
 ```
 
 ## Tracker object names
 
-| Object          | Description   | Example  |
-| --------------- | ------------- | ----- |
+| Object          | Description   | Example |
+| --------------- | ------------- | ------ |
 | `_setMandator ` | - Executed with one additional parameter: `MandatorId` | `_ycq.push (['_setMandator' , '<YOUR_MANDATOR_ID>']);` |
-| `_trackEvent` | - Executed with four additional parameters: `ItemType`, `EventType`, `ItemId`, `UserId`.<br /> - `EventType` can be any of the [described types]([[= user_doc =]]/personalization/event_types/) |  capturing an event: `_ycq.push(['_trackEvent', '1', 'buy', 'https://mydoc.pdf', 'user1234x']);` |
-| `_trackTimedEvent` | - Executed with five additional parameters: `ItemType`, `EventType`, `ItemId`, `Timeout`, `UserId`.<br /> - `EventType` can be any of the [described types]([[= user_doc =]]/personalization/event_types/).<br /> - `Timeout` can be any integer greater than than 0 representing time in ms | consume event sent after 20s: `_ycq.push(['_trackTimedEvent', '1', 'consume', 'https://mydoc.pdf', '20000', 'user1234x']);` |
-| `_login` | - Executed with two additional parameters: anonymous userId, pseudonymous userId.<br /> - It is to be triggered when a user logs in and the tracking identity is changed.<br /> |-|
+| `_trackEvent` | - Executed with four additional parameters: `ItemType`, `EventType`, `ItemId`, `UserId`.<br /> - `EventType` can be any of the [described types]([[= user_doc =]]/personalization/event_types/) | capturing an event: `_ycq.push(['_trackEvent', '1', 'buy', '10', '']);` |
+| `_trackTimedEvent` | - Executed with five additional parameters: `ItemType`, `EventType`, `ItemId`, `Timeout`, `UserId`.<br /> - `EventType` can be any of the [described types]([[= user_doc =]]/personalization/event_types/).<br /> - `Timeout` can be any integer greater than 0 representing time in ms | consume event sent after 20s: `_ycq.push(['_trackTimedEvent', '1', 'consume', '10', '20000', '']);` |
+| `_login` | - Executed with two additional parameters: anonymous userId, pseudonymous userId.<br /> - It is to be triggered when a user logs in and the tracking identity is changed.<br /> | - |
 | `ycreco=true` | - If you want to send a click recommended event you can append the following parameter to the recommended item URLs: | [https://mydomain.com/mypage.html?ycreco=true](https://mydomain.com/mypage.html?ycreco=true) or <br />[https://mydomain.com/mypage.html?myparameter=x&ycreco=true](https://mydomain.com/mypage.html?myparameter=x&ycreco=true) |
 
 ## Tracking with HTML event handlers
@@ -104,7 +104,7 @@ The asynchronous tracking syntax should also be used from within DOM event handl
 For example, the following button generates an event when it is clicked:
 
 ``` js
-<button onclick = "_ycq.push(['_trackEvent', '2', 'click', 'itemId1', 'user1234x'])"/><button>
+<button onclick = "_ycq.push(['_trackEvent', '2', 'click', 'itemId1', ''])"/><button>
 ```
 
 Even if this button is clicked before the browser has finished loading `ibexa-tracker.js`,