diff --git a/docs/guide/personalization/basic_integration.md b/docs/guide/personalization/basic_integration.md index dd64482b54..73d03af746 100644 --- a/docs/guide/personalization/basic_integration.md +++ b/docs/guide/personalization/basic_integration.md @@ -82,7 +82,7 @@ To return products that are most probably interesting for users interested in pr `https://reco.yoochoose.net/api/v2/00000//cross_sell.json?contextitems=123` -A response with two recommendations will resemble the following object: +A response with two recommendations resembles the following object: ``` json { @@ -149,12 +149,73 @@ if ($recommendations && isset($recommendations->recommendationResponseList)) { curl_close($curl); ``` +## Sending messages with recommendations + +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 messages start being sent +- Content Types and attributes that are included in a response +- a number of repetitions + +Triggers are then processed on the Personalization server and responses are delivered to a dedicated endpoint. + +To let your visitors receive emails with recommendations: + +1\. With the [User API](user_api.md#post-requests), add the `e-mail` attribute (or another identifier) to the user record. + +2\. Prepare an endpoint to intercept push messages and pass them on, for example, to your mailing system. +Out of many options, it could be an Ibexa Connect [webhook](https://doc.ibexa.co/projects/connect/en/latest/tools/webhooks/). +The endpoint must meet the following requirements: + + - must support POST requests + - must accept JSON objects in a format that resembles the following example: + +``` json +{ + "customerID":"1234567", + "userExternalId":"user@domain.com", + "triggerType":"REACTIVATION|ABANDONED_SHOPPING_CART", + "triggerName":"TRIGGER_REF_CODE", + "triggerOpenedLink":"NEW_EVENT_FOR_TRIGGER_OPENED", + "recommendations":[ + { + "itemId":959, + "itemType":46, + "clickRecommended":"CLICK_RECOMMENDED_LINK_WITH_TRIGGER_REF_CODE", + "attributes":{ + "ses_name":"Minimalista Coffee Table", + "ses_image":["img_1", "img_2"] + } + }, + { + "itemId":123, + "itemType":55, + "clickRecommended":"CLICK_RECOMMENDED_LINK_WITH_TRIGGER_REF_CODE", + "attributes":{ + "ses_name_for_type_55":"Minimalista Coffee Table" + } + } + ] +} +``` + +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 You can configure integration at a more advanced level to track more events, use additional parameters, apply custom scenario configurations, apply filters, and enable additional features. -For more information about available functionalities, see the [User Documentation]([[= user_doc =]]/personalization/personalization). +For more information about available functionalities, see the [User Documentation]([[= user_doc =]]/personalization/personalization). For more information about integrating the Personalization service, see [Developer guide](developer_guide/tracking_api.md) and [Best practices](best_practices/tracking_integration.md). diff --git a/docs/guide/personalization/developer_guide/tracking_api.md b/docs/guide/personalization/developer_guide/tracking_api.md index 2b15b9ddae..2d37c3964a 100644 --- a/docs/guide/personalization/developer_guide/tracking_api.md +++ b/docs/guide/personalization/developer_guide/tracking_api.md @@ -13,7 +13,7 @@ The most popular user events are: - Login - When a user logs in on a website - Clickrecommended - When a user clicks a recommendation -For a complete list of events, see [Event types]([[= user_doc =]]/personalization/event_types) in the user documentation.  +For a complete list of events, see [Event types]([[= user_doc =]]/personalization/event_types) in the user documentation. Depending on the event type, some additional parameters, such as item price or user rating, must be provided. @@ -69,16 +69,16 @@ For example: ### User identifier -High quality recommendations can only be delivered if the underlying data is correct and consistent.  +High quality recommendations can only be delivered if the underlying data is correct and consistent. For consistent tracking it is crucial to choose and use a consistent identifier for a user. 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 +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 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. -Immediately after a successful login process a Login event must be sent. +Immediately after a successful login process a Login event must be sent. At this point a [pseudonymous](https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32016R0679&from=EN#d1e1489-1-1) user ID, -for example, a system's internal registration id, must be used.  +for example, a system's internal registration id, must be used. After logout, the anonymous user ID can be used again. !!! note @@ -160,11 +160,24 @@ Multiple category locations of an item (multi-homing) are therefore possible. !!! note Events are forwarded to the recommendation engine with HTTP or HTTPS requests - (or [RESTful-Requests](https://en.wikipedia.org/wiki/Representational_state_transfer). + (or [RESTful-Requests](https://en.wikipedia.org/wiki/Representational_state_transfer). Both GET and POST methods are allowed for the event tracking. 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.
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. @@ -179,15 +192,8 @@ The URL to track user clicks has the following format: `GET https://event.yoochoose.net/api/[customerid]/click/[userid]/[itemtypeid]/[itemid]` - -|Name|Description|Values| -|---|---|---| -|`customerid`|Your customer ID (for example "00000").|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.
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.yoochoose.net/api/[customerid]/click/[userid]/[itemtypeid]/[itemid]?parameter1=value1¶meter2=value2` @@ -210,7 +216,7 @@ The URL has the following format: `GET https://event.yoochoose.net/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| @@ -218,7 +224,7 @@ The following table lists the request parameters: |`percentage`|Informs how much of an item was consumed, for example, that an article was read only in 20%, a movie was watched in 90% or someone finished 3/4 of all levels of a game.|0-100| The logic for calculating the percentage is defined by the implementation. -For articles, this could be by scrolling down, for a movie/video based on the consumption part.  +For articles, this could be by scrolling down, for a movie/video based on the consumption part. You must decide what 100% consumption means. For example, a movie contains end titles that are almost never consumed. Therefore, they should not be part of the percentage calculation. @@ -238,10 +244,11 @@ As the name suggests, this event is used when an end user buys an item. It must be sent to the event tracker at the end of a successful check-out process to ensure that no further action of the user can result in an abort. -The URL has the following format:  +The URL has the following format: `GET https://event.yoochoose.net/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. @@ -261,7 +268,7 @@ this event type is not applicable. Every Buy event can contain a price. If the price is set, it is stored with the event and used for calculating the revenue for statistics. -The price must be a price the user paid for the item, including all taxes and discounts.  +The price must be a price the user paid for the item, including all taxes and discounts. If product price filtering is activated, the information provided over the product import is used. For more information, see [Content API](content_api.md). @@ -285,14 +292,11 @@ You should correlate both IDs to correlate the Buy events (account ID) with the preceding Click events (visit-scoped ID). The Login event serves exactly this purpose. -The format of the URL is:  +The format of the URL is: `GET https://event.yoochoose.net/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 @@ -301,7 +305,7 @@ This event is especially useful if anonymized checkout is allowed or no recurrin identification is possible. By using the shopping cart products as input for getting recommendations, problems with an empty profile or no buy history for the user can be solved. -The more valuable Basket events instead of recent user clicks can be used to provide +The more valuable Basket events instead of recent user clicks can be used to provide personalized recommendations. It also happens quite often that users "store" products on their shopping wishlist and plan to buy them later. @@ -310,7 +314,19 @@ in the whole shop. `GET https://event.yoochoose.net/api/[customerid]/basket/[userid]/[itemtypeid]/[itemid]` -There are no query string parameters for this event.  +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 @@ -322,7 +338,9 @@ The format of the URL is: `GET https://event.yoochoose.net/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| @@ -338,47 +356,101 @@ The format of the URL is: `GET https://event.yoochoose.net/api/[customerid]/blacklist/[userid]/[itemtypeid]/[itemid]` -There are no query string parameters for this event.  +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 recommendation engine about which recommendations were shown and -what recommendations were clicked. -Otherwise, reliable statistics cannot be calculated and used to check against a 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.yoochoose.net/clickrecommended/johndoe/1/100175717?scenario=also_clicked&modelId=37", - "rendered" : "//event.yoochoose.net/rendered/johndoe/1/100175717" + "clickRecommended" : "//event.perso.ibexa.co/clickrecommended/johndoe/1/100175717?scenario=also_clicked&modelId=37", + "rendered" : "//event.perso.ibexa.co/rendered/johndoe/1/100175717" }, + } +] +``` + +| 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. + +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"] + } + } + ] ``` -In the `links` field, the delivered request string is visible, which is executed when the end user -displays or clicks a recommendations. -See [Recommendation API](recommendation_api.md) for more details. +For more information, see [Sending messages with recommendations](../basic_integration.md#sending-messages-with-recommendations). -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. +### 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 @@ -389,8 +461,7 @@ The URL has the following format: `GET https://event.yoochoose.net/api/[customerid]/clickrecommended/[userid]/[itemtypeid]/[itemid]?scenario=` -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| @@ -399,26 +470,44 @@ The request parameters are: The scenario parameter identifies the originating scenario to gain detailed statistics about the scenario that motivated the user to click on a recommendation. -This information comes with the recommendation from the recommendation controller.  +This information comes with the recommendation from the recommendation controller. 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.yoochoose.net/api/[customerid]/rendered/[userid]/[itemtypeid]/[itemid[,itemid]]` +`GET https://tracker.ibexa.co/api/[customerid]/triggeropened/[userid]?triggername=` -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=` + +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 @@ -468,7 +557,7 @@ User "johndoe" likes the product 133 and wants to rate it with 5 stars. ### Response handling -The following HTTP response codes are used by the event tracker.   +The following HTTP response codes are used by the event tracker. |HTTP Status Code|Description| |---|---| diff --git a/docs/guide/personalization/img/Diagram source/recommendation_overview.xml b/docs/guide/personalization/img/Diagram source/recommendation_overview.xml new file mode 100644 index 0000000000..48b0658749 --- /dev/null +++ b/docs/guide/personalization/img/Diagram source/recommendation_overview.xml @@ -0,0 +1,179 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/guide/personalization/img/recommendation_overview.png b/docs/guide/personalization/img/recommendation_overview.png index 08268bf8bd..6b0e60a05a 100644 Binary files a/docs/guide/personalization/img/recommendation_overview.png and b/docs/guide/personalization/img/recommendation_overview.png differ diff --git a/docs/guide/personalization/personalization.md b/docs/guide/personalization/personalization.md index 49e34ecbfe..8982b9e956 100644 --- a/docs/guide/personalization/personalization.md +++ b/docs/guide/personalization/personalization.md @@ -25,7 +25,7 @@ The idea behind the Personalization service is built upon four main steps. 1. A User visits a news service or an online store, navigates through it and leaves some footprints. The most popular footprints are selecting (CLICK) and purchasing  products (BUY). 2. This information is sent to the Recommendation client every time these events happen. 3. The Recommendation engine accumulates the tracked events, categorizes them and calculates recommendations for every product and every user in the shop. -4. Recommendations can be fetched from the Personalization service and presented to users during their sessions. +4. Recommendations can be fetched from the Personalization service and presented to users during their sessions or pushed by the service to a dedicated endpoint, for example, to be forwarded to customers. ![Overview of how recommendation works](img/recommendation_overview.png)