Skip to content

IBX-8970 Improved personalization details. #2515

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Oct 10, 2024
Merged

IBX-8970 Improved personalization details. #2515

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6980f70
IBX-89740 Improved personalization details.
nkostiv Oct 9, 2024
2f319f8
IBX-89740 Improved personalization details.
nkostiv Oct 9, 2024
f3ddcff
Merge remote-tracking branch 'origin/IBX-8970_perso_dev_doc_update' i…
nkostiv Oct 9, 2024
f2af25f
IBX-89740 Fixed empty spaces.
nkostiv Oct 9, 2024
a7814be
IBX-89740 Small fixes.
nkostiv Oct 9, 2024
d3a01cd
IBX-89740 Small fixes.
nkostiv Oct 9, 2024
17738fb
IBX-89740 Doc review comments.
nkostiv Oct 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions docs/personalization/enable_personalization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `.env.local` file
by adding the following lines with your customer ID and license key:
Copy link
Contributor

@dabrt dabrt Oct 9, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In the root folder of your project, edit `.env.local` file
by adding the following lines with your customer ID and license key:
In the root folder of your project, edit the `.env.local` file by adding the following lines with your customer ID and license key:


```
Expand All @@ -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
Expand Down Expand Up @@ -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.
Copy link
Contributor

@dabrt dabrt Oct 9, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Contact `[email protected]` with your organization's requirements to have the alphanumeric content identifier enabled.
Contact [email protected] with your organization's requirements to have the alphanumeric content identifier enabled.


#### Enable tracking

Expand Down Expand Up @@ -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": [
{
Expand Down Expand Up @@ -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": [
{
Expand Down
12 changes: 7 additions & 5 deletions docs/personalization/integrate_recommendation_service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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;
```
Expand All @@ -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";
}
```
Expand Down Expand Up @@ -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(
Expand Down
4 changes: 2 additions & 2 deletions docs/personalization/tracking_integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
```

Expand Down
20 changes: 10 additions & 10 deletions docs/personalization/tracking_with_ibexa-tracker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@
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.

Expand All @@ -32,7 +32,7 @@
<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');
Expand Down Expand Up @@ -85,17 +85,17 @@
``` 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', '']);` |

Check warning on line 96 in docs/personalization/tracking_with_ibexa-tracker.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/personalization/tracking_with_ibexa-tracker.md#L96 

[Ibexa.Semicolon] Only use the semicolon if you're absolutely sure what you're doing.
Raw output 
{"message": "[Ibexa.Semicolon] Only use the semicolon if you're absolutely sure what you're doing.", "location": {"path": "docs/personalization/tracking_with_ibexa-tracker.md", "range": {"start": {"line": 96, "column": 282}}}, "severity": "WARNING"}
| `_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', '']);` |

Check warning on line 97 in docs/personalization/tracking_with_ibexa-tracker.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/personalization/tracking_with_ibexa-tracker.md#L97 

[Ibexa.Semicolon] Only use the semicolon if you're absolutely sure what you're doing.
Raw output 
{"message": "[Ibexa.Semicolon] Only use the semicolon if you're absolutely sure what you're doing.", "location": {"path": "docs/personalization/tracking_with_ibexa-tracker.md", "range": {"start": {"line": 97, "column": 403}}}, "severity": "WARNING"}
| `_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
Expand All @@ -104,7 +104,7 @@
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`,
Expand Down
Loading