Skip to content

IBX-6270 - Configuration update for triggers #2140

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
Parent: Update importing_assets_from_bundle.md
merged 6 commits into from
Sep 26, 2023
Merged

IBX-6270 - Configuration update for triggers #2140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
26d9fae
IBX-6270 - basic authentication
dabrt Sep 19, 2023
44e19bd
New trigger events
dabrt Sep 21, 2023
658e4f4
Fix typos
dabrt Sep 21, 2023
dfb1280
Implement reviewer comments
dabrt Sep 25, 2023
61b999d
Implement reviewer comments
dabrt Sep 25, 2023
160cee7
Fix capitalization
dabrt Sep 26, 2023
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
183 changes: 132 additions & 51 deletions docs/personalization/api_reference/tracking_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ For consistent tracking it is crucial to choose and use a consistent identifier
A user usually visits a website anonymously.
Therefore, their identifier is either a first-party cookie or a session ID
provided by the website. 
If there is no existing user ID handling that we can re-use, it is recommended that
If there is no existing user ID handling that can be re-used, it is recommended that
you use your own cookie and set the expiry date to at least 90 days from the last usage.
If there is a login mechanism, the user is usually tracked with a temporary
identifier before the login.
Expand Down Expand Up @@ -177,6 +177,19 @@ Multiple category locations of an item (multi-homing) are therefore possible.
Make sure that all embedded and query string parameters are URL encoded and
do not use a backslash [encoded as %5C\].

### Event parameters

For a list of embedded parameters that each of the events may use, see the following table.

|Name|Description|Values|
|---|---|---|
|`customerid`|A customer ID (for example "00000"). Can be used to identify a website in installations that [hosts multiple SiteAccesses]([[= user_doc =]]/personalization/use_cases/#multiple-website-hosting).|alphanumeric|
|userid|A user's ID on the website of the customer. It could be an internal customer code, a session code or a cookie for anonymous users.|URL-encoded alphanumeric|
|`itemtypeid`|Item type ID.|1 to 2147483647|
|`itemid`|A unique ID of the item the user has clicked.</br>String-based identifiers are also supported as item IDs to track content on a website, but it is discouraged due to fraud and security issues. If you are unable to provide numeric identifiers for the tracking process, contact Ibexa for further information and implementation notes.|1 to 2147483647|
|`sourceuserid`|User identifier valid up to now(usually some anonymous session ID)|URL-encoded alphanumeric|
|`targetuserid`|User identifier valid from now on (usually an account ID or login name)|URL-encoded alphanumeric|

### Click event

When the end user opens an item/article detail, a Click events is sent.
Expand All @@ -193,15 +206,8 @@ The URL to track user clicks has the following format:

`GET https://event.perso.ibexa.co/api/[customerid]/click/[userid]/[itemtypeid]/[itemid]`


|Name|Description|Values|
|---|---|---|
|`customerid`|A customer ID (for example "00000"). Can be used to identify a website in installations that [hosts multiple SiteAccesses]([[= user_doc =]]/personalization/use_cases/#multiple-website-hosting).|alphanumeric|
|userid|A user's ID on the website of the customer. It could be an internal customer code, a session code or a cookie for anonymous users.|URL-encoded alphanumeric|
|`itemtypeid`|Item type ID.|1 to 2147483647|
|`itemid`|A unique ID of the item the user has clicked.</br>String-based identifiers are also supported as item IDs to track content on a website, but it is discouraged due to fraud and security issues. If you are unable to provide numeric identifiers for the tracking process, contact Ibexa for further information and implementation notes.|1 to 2147483647|

All embedded parameters are required for the request.
For a detailed description of embedded parameters, see [event parameters](#event-parameters).
Some optional request parameters can be set over query string parameters (GET parameters).

`GET https://event.perso.ibexa.co/api/[customerid]/click/[userid]/[itemtypeid]/[itemid]?parameter1=value1&parameter2=value2`
Expand All @@ -224,7 +230,7 @@ The URL has the following format:

`GET https://event.perso.ibexa.co/api/[customerid]/consume/[userid]/[itemtypeid]/[itemid]`

All embedded parameters are the same as for a Click event.
For a detailed description of embedded parameters, see [event parameters](#event-parameters).
The following table lists the request parameters:

|Name|Description|Values|
Expand Down Expand Up @@ -261,6 +267,7 @@ The URL has the following format: 

`GET https://event.perso.ibexa.co/api/[customerid]/buy/[userid]/[itemtypeid]/[itemid]?fullprice=2.50EUR&quantity=4`

For a detailed description of embedded parameters, see [event parameters](#event-parameters).
In addition to the fact that an item is bought, this event should provide information
about the product price and quantity.

Expand Down Expand Up @@ -315,10 +322,7 @@ The format of the URL is: 

`GET https://event.perso.ibexa.co/api/[customerid]/login/[sourceuserid]/[targetuserid]`

|Name|Description|Values|
|---|---|---|
|sourceuserid|User identifier valid up to now(usually some anonymous session ID)|URL-encoded alphanumeric|
|targetuserid|User identifier valid from now on (usually an account ID or login name)|URL-encoded alphanumeric|
For a detailed description of embedded parameters, see [event parameters](#event-parameters).

### Basket event

Expand All @@ -336,6 +340,18 @@ can be provided in the whole shop.

`GET https://event.perso.ibexa.co/api/[customerid]/basket/[userid]/[itemtypeid]/[itemid]`

For a detailed description of embedded parameters, see [event parameters](#event-parameters).
There are no query string parameters for this event.

### Deletefrombasket event

The Deletefrombasket is issued when the end user removes items from their shopping cart.
It could signify that the user has lost interest in the product.
Based on this information, recommendations presented by the store can be more accurate.

`GET https://event.perso.ibexa.co/api/[customerid]/deletefrombasket/[userid]/[itemtypeid]/[itemid]`

For a detailed description of embedded parameters, see [event parameters](#event-parameters).
There are no query string parameters for this event. 

### Rate event
Expand All @@ -348,7 +364,9 @@ The format of the URL is:

`GET https://event.perso.ibexa.co/api/[customerid]/rate/[userid]/[itemtypeid]/[itemid]?rating=50`

This can also be used for explicit ratings like a five-star rating for hotels.
For a detailed description of embedded parameters, see [event parameters](#event-parameters).

Rate event can also be used for explicit ratings like a five-star rating for hotels.
A predefined rating can be submitted when the user comments on an item.

|Name|Description|Values|
Expand All @@ -365,53 +383,101 @@ The format of the URL is:

`GET https://event.perso.ibexa.co/api/[customerid]/blacklist/[userid]/[itemtypeid]/[itemid]`

For a detailed description of embedded parameters, see [event parameters](#event-parameters).
There are no query string parameters for this event. 

## Tracking events based on recommendations

Tracking events based on integrated recommendations are the only way to measure
success of recommendations.
It is crucial to inform the Personalization server about which recommendations
were shown and what recommendations were clicked.
Otherwise, reliable statistics cannot be calculated and used to check against
the customer's KPIs.

A recommendation response already includes the requests to generate a Clickrecommended
or Rendered event.
They are used and executed when a recommendation is clicked/accepted or a recommendation
is shown.
Tracking events based on integrated recommendations are the only way to measure the accuracy
and effectiveness of recommendations.
Both recommendation response and trigger message include requests to generate these events.
Events of this type inform the Personalization server about the recommendations that
were shown to the user and which of those recommendations were clicked.
Otherwise, it would be impossible to calculate reliable statistics that could be checked
against the customer's KPIs.

A recommendation response includes requests to generate a Rendered and Clickrecommended event.
The first one is executed when a recommendation is shown to the user.
The second is called when a recommendation is clicked or otherwise accepted.
Sending Rendered events causes as many requests as recommendations to be displayed,
a Clickrecommended event is usually sent only once (when a user clicks on
a specific recommendation item).

Example of a recommendation response:

``` jsonp
``` json
"recommendationItems": [
{
"relevance": 23,
"itemType": 1,
"itemId": 100175717,
"origin": {
"itemIds" : [10, 11], // these are the items that the recommendations are based on (context or user history items), multiple values are possible
"itemIds" : [10, 11],
"itemType" : 1,
"source" : "REQUEST" // Possible options: REQUEST (parameter "contextitems") or CLICK, CONSUME, BUY, BASKET, RATE (user history)
"source" : "REQUEST"
},
"category" : "Men/Shirts", // Provided only, if category suggestion is requested
"category" : "Men/Shirts",
"links" : {
"clickRecommended" : "//event.perso.ibexa.co/clickrecommended/johndoe/1/100175717?scenario=also_clicked&modelId=37",
"rendered" : "//event.perso.ibexa.co/rendered/johndoe/1/100175717"
},
```

In the `links` field, the delivered request string is visible, which is executed
when the end user displays or clicks a recommendations.
| Field name | Description |
|---|---|
| `itemIds` |Items that the recommendations are based on (context or user history items), multiple values are possible.|
| `source` |Event that initiated the response: REQUEST (parameter "contextitems") or CLICK, CONSUME, BUY, BASKET, RATE (user history).|
| `category` |A recommended item category. Provided only if category suggestion is requested.|
| `links` | Requests for events that are executed when the end user displays or clicks a recommendation.|

See [Recommendation API](recommendation_api.md) for more details.

You can still implement the traditional way as mentioned below but it is strongly
recommended against this.
If you do so, remember to examine it together with the Ibexa team because it is
crucial for statistical analysis.
A trigger message includes requests for a Triggeropened and Clicktriggered event.
The first is executed once, when the end user opens a trigger message (for example, embedded into a newsletter).
The second is called each time the user follows a link to see the recommended item.
Both requests provide the `triggername` parameter, which passes a unique alphanumerical identifier of the trigger that initiated the message.

Example of a trigger message:

``` json
"customerID":"177751",
"userExternalId":"user@ibexa.co",
"triggerType":"REACTIVATION|ABANDAONED_SHOPPING_CART",
"triggerName":"trigger_ref_code",
"triggerOpenedLink":"//tracker.ibexa.co/api/17751/triggeropened/johndoe?triggername=action_trigger_ref_code",
"recommendations":[
{
"itemId":959,
"itemType":46,
"clickRecommended":"//tracker.ibexa.co/api/17751/clicktriggered/johndoe/46/959?triggername=action_trigger_ref_code",
"attributes":{
"ses_name":"Minimalista Coffee Table",
"ses_image":["img_1", "img_2"]
}
}
]
}
```

For more information, see [Send messages with recommendations](../integrate_recommendation_service.md#send-messages-with-recommendations).

### Rendered event

This event is sent when the website uses the recommendation provided by the recommendation
engine and renders it on the webpage.
In combination with a predefined threshold, it allows the recommender engine to
exclude this item from future results and avoid recommending the same item to the
same user multiple times during a session.

The URL for a Rendered event has the following format:

`GET https://event.perso.ibexa.co/api/[customerid]/rendered/[userid]/[itemtypeid]/[itemid[,itemid]]`

For a detailed description of embedded parameters, see [event parameters](#event-parameters).

It is common that recommendations are rendered as a block with multiple items.
To save traffic and speed up the process, you can bundle multiple recommendations in one request.
Several item IDs must be comma-separated.

### Clickrecommended event

Expand All @@ -422,8 +488,7 @@ The URL has the following format:

`GET https://event.perso.ibexa.co/api/[customerid]/clickrecommended/[userid]/[itemtypeid]/[itemid]?scenario=<scenarioid>`

The embedded parameters are the same as for a Click event.

For a detailed description of embedded parameters, see [event parameters](#event-parameters).
The request parameters are:

|Name|Description|Values|
Expand All @@ -437,23 +502,39 @@ This information comes with the recommendation from the recommendation controlle
The event is used for providing statistics about how often recommendations of
the configured recommendation scenario were accepted or considered as useful by users.

### Rendered event
### Triggeropened event

This event sent when the website uses the recommendation provided by the recommendation
engine and renders it on the webpage.
In combination with a predefined threshold, it allows the recommender engine to
exclude this item from future results and avoid recommending the same item to the
same user multiple times during a session.
The Triggeropened event is sent when the end user opens a trigger message, for example, by opening an email message with recommendations.

The URL for a Rendered event has the following format:
The URL has the following format:

`GET https://event.perso.ibexa.co/api/[customerid]/rendered/[userid]/[itemtypeid]/[itemid[,itemid]]`
`GET https://tracker.ibexa.co/api/[customerid]/triggeropened/[userid]?triggername=<action_trigger_reference_code>`

The Rendered event has the same embedded parameters as the Click event, except
for the item ID.
It is common that recommendations are rendered as a block with multiple items.
To save traffic and reduce latency, you can bundle multiple recommendations in one request.
Several item IDs must be comma-separated.
For a detailed description of embedded parameters, see [event parameters](#event-parameters).
The request parameter is:

|Name|Description|Values|
|---|---|---|
|`triggername`|Identifier of the trigger that the message originates from. This parameter is required.|URL-encoded alphanumeric|

The event is used for providing statistics about how often trigger messages are considered valuable by the users.

### Clicktriggered event

The Clicktriggered event is sent when the end user clicks the link delivered in a trigger message to see the recommended item.

The URL has the following format:

`GET https://tracker.ibexa.co/api/[customerid]/clicktriggered/[userid]/[itemtypeid]/[itemid]?triggername=<action_trigger_reference_code>`

For a detailed description of embedded parameters, see [event parameters](#event-parameters).
The request parameter is:

|Name|Description|Values|
|---|---|---|
|`triggername`|Identifier of the trigger that the recommendation originates from. This parameter is required.|URL-encoded alphanumeric|

The event is used for providing statistics about how often a specific recommendation from the trigger message is considered useful by the user.

## Tracking event examples

Expand Down
19 changes: 13 additions & 6 deletions docs/personalization/integrate_recommendation_service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,17 +151,17 @@ if ($recommendations && isset($recommendations->recommendationResponseList)) {
curl_close($curl);
```

## Send emails with recommendations
## Send messages with recommendations

Email triggers are push messages with recommendations.
With this feature, your organization can invite individual visitors to return to the website or remind them of items abandoned in a cart, for example by sending emails.
Before you can start [using email triggers]([[= user_doc =]]/personalization/triggers), you must contact Ibexa and define specific conditions, for example:
Triggers are push messages with recommendations.
With this feature, your organization can invite individual visitors to return to the website or remind them of items abandoned in a cart by delivering a message, for example, by sending emails.
Before you can start [using triggers]([[= user_doc =]]/personalization/triggers), you must contact Ibexa and define specific conditions, for example:

- the time that must pass before emails start being sent
- the time that must pass before messages start being sent
- Content Types and attributes that are included in a response
- a number of repetitions

Email triggers are then processed on the Personalization server and responses are delivered to a dedicated endpoint.
Triggers are then processed on the Personalization server and responses are delivered to a dedicated endpoint.

To let your visitors receive emails with recommendations:

Expand Down Expand Up @@ -203,6 +203,13 @@ The endpoint must meet the following requirements:
}
```

The object contains links to the recommended items (`triggerOpenedLink`, `clickRecommended`), which are monitored by the Personalization server to gather statistical data.

!!! note "Support for endpoints with authorization"

The trigger service supports additional Basic/Bearer token authentication to secure communication between the Personalization server and the endpoint.
If your endpoint requires authentication, you must provide Ibexa with the token.

3\. Contact `support@ibexa.co` with your organization's requirements to have the email triggers enabled.

## Advanced integration
Expand Down