From f0774b08a8dc540cbb7e0e1a16333bd695f5a423 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Thu, 15 Jun 2023 14:58:56 +0200 Subject: [PATCH 01/10] IBX-5644 - Email triggers --- docs/personalization/how_it_works.md | 2 +- .../integrate_recommendation_service.md | 57 +++++++++++++++++++ 2 files changed, 58 insertions(+), 1 deletion(-) diff --git a/docs/personalization/how_it_works.md b/docs/personalization/how_it_works.md index 25e762acfc..69d6edbae4 100644 --- a/docs/personalization/how_it_works.md +++ b/docs/personalization/how_it_works.md @@ -9,7 +9,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 Personalization client every time these events happen. 3. The Personalization server 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 and then sent in an email. ![Overview of how recommendation works](recommendation_overview.png) diff --git a/docs/personalization/integrate_recommendation_service.md b/docs/personalization/integrate_recommendation_service.md index 34f9b3c71c..2405d07319 100644 --- a/docs/personalization/integrate_recommendation_service.md +++ b/docs/personalization/integrate_recommendation_service.md @@ -151,6 +151,63 @@ if ($recommendations && isset($recommendations->recommendationResponseList)) { curl_close($curl); ``` +## Send e-mails with recommendations + +By using [email triggers]([[= user_doc =]]/personalization/triggers.md), your organization can send emails to individual visitors, for example, to invite them to return to the website or remind them of items abandoned in a cart. + +Email triggers are push messages with recommendations. +Specific conditions, such as the time that must pass before email start being sent, content types and attributes to be included in a response, or a number of repetitions, are first defined based on an interview between you and Ibexa. +Email triggers are then processed on the Personalization server and responses are delivered to a dedicated endpoint. + +To let your visitor and/or customers receive emails with recommendations: + +1\. With the [User API](api_reference/user_api.md#post-requests), add the `e-mail` attribute to the user record. + +2\. Prepare an endpoint that will intercept push messages and pass them on to your mailing system, for example, an Ibexa Connect [webhook](https://doc.ibexa.co/projects/connect/en/latest/tools/webhooks/). The webhook must meet the following requirements: + + - cannot require authentication + - must support POST requests + - must accept JSON objects in a format that resembles the following example: + +``` json +{ + "userId": "12345", + "email": "user.name@domain.co", + "triggerType": "REACTIVATION|ABANDONED_SHOPPING_CART", + "recommendationItems": [ + { + "itemId": 590, + "itemType": 57, + "relevance": 6, + "links": { + "clickRecommended": "//event.test.perso.ibexa.co/api/40639/clickrecommended/1234/57/590?scenario=top_clicked&modelid=10308199&categorypath=&requestuuid=6c8d54b0-e36f-11ed-9a6b-029bc81f23ff", + "rendered": "//event.test.perso.ibexa.co/api/40639/rendered/1234/57/590?scenario=top_clicked&modelid=10308199&categorypath=&requestuuid=6c8d54b0-e36f-11ed-9a6b-029bc81f23ff" + }, + "attributes": [ + { + "key" : "title", + "value": "Product Name" + }, + { + "key": "image", + "value": "/" + }, + { + "key": "price", + "value": "65.50" + }, + { + "key": "currency", + "value": "EUR" + } + ] + } + ] +} +``` + +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, From 6740adc67d95d5aa8e7fcb6bddd1b6ae0bd01ed3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Thu, 15 Jun 2023 15:02:57 +0200 Subject: [PATCH 02/10] Typo fix --- docs/personalization/integrate_recommendation_service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/personalization/integrate_recommendation_service.md b/docs/personalization/integrate_recommendation_service.md index 2405d07319..827822260d 100644 --- a/docs/personalization/integrate_recommendation_service.md +++ b/docs/personalization/integrate_recommendation_service.md @@ -151,7 +151,7 @@ if ($recommendations && isset($recommendations->recommendationResponseList)) { curl_close($curl); ``` -## Send e-mails with recommendations +## Send emails with recommendations By using [email triggers]([[= user_doc =]]/personalization/triggers.md), your organization can send emails to individual visitors, for example, to invite them to return to the website or remind them of items abandoned in a cart. From 86b9009fece026af242509da92fd17eb49a0453f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Thu, 15 Jun 2023 15:10:22 +0200 Subject: [PATCH 03/10] Typo fix --- docs/personalization/integrate_recommendation_service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/personalization/integrate_recommendation_service.md b/docs/personalization/integrate_recommendation_service.md index 827822260d..dcaa474951 100644 --- a/docs/personalization/integrate_recommendation_service.md +++ b/docs/personalization/integrate_recommendation_service.md @@ -159,7 +159,7 @@ Email triggers are push messages with recommendations. Specific conditions, such as the time that must pass before email start being sent, content types and attributes to be included in a response, or a number of repetitions, are first defined based on an interview between you and Ibexa. Email triggers are then processed on the Personalization server and responses are delivered to a dedicated endpoint. -To let your visitor and/or customers receive emails with recommendations: +To let your visitors receive emails with recommendations: 1\. With the [User API](api_reference/user_api.md#post-requests), add the `e-mail` attribute to the user record. From 8a04bdbcee869962dc667f27878f4beb9ef4a575 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Mon, 19 Jun 2023 11:06:32 +0200 Subject: [PATCH 04/10] Review comment implemented --- .../integrate_recommendation_service.md | 60 +++++++++---------- 1 file changed, 29 insertions(+), 31 deletions(-) diff --git a/docs/personalization/integrate_recommendation_service.md b/docs/personalization/integrate_recommendation_service.md index dcaa474951..b1b6e6c5a0 100644 --- a/docs/personalization/integrate_recommendation_service.md +++ b/docs/personalization/integrate_recommendation_service.md @@ -171,38 +171,36 @@ To let your visitors receive emails with recommendations: ``` json { - "userId": "12345", - "email": "user.name@domain.co", - "triggerType": "REACTIVATION|ABANDONED_SHOPPING_CART", - "recommendationItems": [ - { - "itemId": 590, - "itemType": 57, - "relevance": 6, - "links": { - "clickRecommended": "//event.test.perso.ibexa.co/api/40639/clickrecommended/1234/57/590?scenario=top_clicked&modelid=10308199&categorypath=&requestuuid=6c8d54b0-e36f-11ed-9a6b-029bc81f23ff", - "rendered": "//event.test.perso.ibexa.co/api/40639/rendered/1234/57/590?scenario=top_clicked&modelid=10308199&categorypath=&requestuuid=6c8d54b0-e36f-11ed-9a6b-029bc81f23ff" + "customerID":"1234567", + "userExternalId":"user@domain.com", + "triggerType":"REACTIVATION", # Email trigger type: REACTIVATION or ABANDONED_SHOPPING_CART + "triggerName":"TRIGGER_REF_CODE", + "triggerOpenedLink":"NEW_EVENT_FOR_TRIGGER_OPENED", + "recommendations":[ + { + "itemId":959, + "itemType":46, + "links":{ + "clickRecommended":"CLICK_RECOMMENDED_LINK_WITH_TRIGGER_REF_CODE", + "rendered":"RENDERED_LINK" + }, + "attributes":{ + "ses_name":"First product's name", + "ses_image":["img_1", "img_2"] + } }, - "attributes": [ - { - "key" : "title", - "value": "Product Name" - }, - { - "key": "image", - "value": "/" - }, - { - "key": "price", - "value": "65.50" - }, - { - "key": "currency", - "value": "EUR" - } - ] - } - ] + { + "itemId":123, + "itemType":55, + "links":{ + "clickRecommended":"CLICK_RECOMMENDED_LINK_WITH_TRIGGER_REF_CODE", + "rendered":"RENDERED_LINK" + }, + "attributes":{ + "ses_name_for_type_55":"Second product's name" + } + } + ] } ``` From 09aad8caf450baf3a6fd1b6102235357f8ce88f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Mon, 19 Jun 2023 11:08:44 +0200 Subject: [PATCH 05/10] Typo fix --- docs/personalization/integrate_recommendation_service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/personalization/integrate_recommendation_service.md b/docs/personalization/integrate_recommendation_service.md index b1b6e6c5a0..a261546645 100644 --- a/docs/personalization/integrate_recommendation_service.md +++ b/docs/personalization/integrate_recommendation_service.md @@ -173,7 +173,7 @@ To let your visitors receive emails with recommendations: { "customerID":"1234567", "userExternalId":"user@domain.com", - "triggerType":"REACTIVATION", # Email trigger type: REACTIVATION or ABANDONED_SHOPPING_CART + "triggerType":"REACTIVATION|ABANDONED_SHOPPING_CART", "triggerName":"TRIGGER_REF_CODE", "triggerOpenedLink":"NEW_EVENT_FOR_TRIGGER_OPENED", "recommendations":[ From b5f036cd0261341ead9e2c763f0ccfcde0ff3e4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Wed, 21 Jun 2023 15:19:35 +0200 Subject: [PATCH 06/10] Implement review comments --- docs/personalization/integrate_recommendation_service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/personalization/integrate_recommendation_service.md b/docs/personalization/integrate_recommendation_service.md index a261546645..218ec403fd 100644 --- a/docs/personalization/integrate_recommendation_service.md +++ b/docs/personalization/integrate_recommendation_service.md @@ -161,7 +161,7 @@ Email triggers are then processed on the Personalization server and responses ar To let your visitors receive emails with recommendations: -1\. With the [User API](api_reference/user_api.md#post-requests), add the `e-mail` attribute to the user record. +1\. With the [User API](api_reference/user_api.md#post-requests), add the `e-mail` attribute (or another identifier) to the user record. 2\. Prepare an endpoint that will intercept push messages and pass them on to your mailing system, for example, an Ibexa Connect [webhook](https://doc.ibexa.co/projects/connect/en/latest/tools/webhooks/). The webhook must meet the following requirements: From 38a110c267f6f34ddabc9116e45aa1f442c24fb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 4 Jul 2023 13:12:34 +0200 Subject: [PATCH 07/10] Implemented review comments --- docs/personalization/how_it_works.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/personalization/how_it_works.md b/docs/personalization/how_it_works.md index 69d6edbae4..587ede29c0 100644 --- a/docs/personalization/how_it_works.md +++ b/docs/personalization/how_it_works.md @@ -9,7 +9,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 Personalization client every time these events happen. 3. The Personalization server 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 or pushed by the service to a dedicated endpoint and then sent in an email. +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](recommendation_overview.png) From dc3271f9d9c35d2fa8d5ab4db94c759db54a2c02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 4 Jul 2023 13:16:05 +0200 Subject: [PATCH 08/10] Linter results fix --- docs/personalization/integrate_recommendation_service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/personalization/integrate_recommendation_service.md b/docs/personalization/integrate_recommendation_service.md index 218ec403fd..8799c1a9e5 100644 --- a/docs/personalization/integrate_recommendation_service.md +++ b/docs/personalization/integrate_recommendation_service.md @@ -165,7 +165,7 @@ To let your visitors receive emails with recommendations: 2\. Prepare an endpoint that will intercept push messages and pass them on to your mailing system, for example, an Ibexa Connect [webhook](https://doc.ibexa.co/projects/connect/en/latest/tools/webhooks/). The webhook must meet the following requirements: - - cannot require authentication + - can't require authentication - must support POST requests - must accept JSON objects in a format that resembles the following example: From c61a0e8d866fefbbc0269f3c2cb605ca8b8dfe08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 4 Jul 2023 13:30:24 +0200 Subject: [PATCH 09/10] Additional comments implemented --- docs/personalization/integrate_recommendation_service.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/personalization/integrate_recommendation_service.md b/docs/personalization/integrate_recommendation_service.md index 8799c1a9e5..649f765226 100644 --- a/docs/personalization/integrate_recommendation_service.md +++ b/docs/personalization/integrate_recommendation_service.md @@ -163,7 +163,9 @@ To let your visitors receive emails with recommendations: 1\. With the [User API](api_reference/user_api.md#post-requests), add the `e-mail` attribute (or another identifier) to the user record. -2\. Prepare an endpoint that will intercept push messages and pass them on to your mailing system, for example, an Ibexa Connect [webhook](https://doc.ibexa.co/projects/connect/en/latest/tools/webhooks/). The webhook must meet the following requirements: +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 webhook must meet the following requirements: - can't require authentication - must support POST requests From 5112f9b6e39f7cd4d2a22884b8ab60f829665b08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 4 Jul 2023 14:04:35 +0200 Subject: [PATCH 10/10] Post weekly changes --- docs/personalization/integrate_recommendation_service.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/personalization/integrate_recommendation_service.md b/docs/personalization/integrate_recommendation_service.md index 649f765226..f03b0dc928 100644 --- a/docs/personalization/integrate_recommendation_service.md +++ b/docs/personalization/integrate_recommendation_service.md @@ -165,9 +165,8 @@ To let your visitors receive emails with recommendations: 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 webhook must meet the following requirements: +The endpoint must meet the following requirements: - - can't require authentication - must support POST requests - must accept JSON objects in a format that resembles the following example: