From 91046c83168e1383384fcfc803679d40f80ff7f8 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 16 May 2024 19:14:56 +0200 Subject: [PATCH 1/8] Add new analytics section --- .code-samples.meilisearch.yaml | 12 ++ config/redirects.json | 8 + config/sidebar-learn.json | 28 ++- learn/analytics/analytics.mdx | 85 +++++++++ .../deactivate_analytics_monitoring.mdx | 31 ++++ learn/analytics/events.mdx | 68 ++++++++ learn/{cloud => analytics}/monitoring.mdx | 6 +- learn/cloud/analytics.mdx | 161 ------------------ 8 files changed, 229 insertions(+), 170 deletions(-) create mode 100644 learn/analytics/analytics.mdx create mode 100644 learn/analytics/deactivate_analytics_monitoring.mdx create mode 100644 learn/analytics/events.mdx rename learn/{cloud => analytics}/monitoring.mdx (96%) delete mode 100644 learn/cloud/analytics.mdx diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index b40b64bc6c..f5cf67aebd 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -1209,3 +1209,15 @@ negative_search_2: |- -X POST 'http://localhost:7700/indexes/movies/search' \ -H 'Content-Type: application/json' \ --data-binary '{ "q": "-\"escape room\"" }' +analytics_event_send_1: |- + curl \ + -X POST 'https://edge.meilisearch.com/events' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \ + --data-binary '{ + "eventType": "click", + "eventName": "Search Result Clicked", + "indexUid": "products", + "objectId": "0", + "position": 0 + }' diff --git a/config/redirects.json b/config/redirects.json index 08f4dccb81..42387fc1a8 100644 --- a/config/redirects.json +++ b/config/redirects.json @@ -153,5 +153,13 @@ { "source": "/docs/learn/async/managing_tasks", "destination": "/docs/learn/async/working_with_tasks" + }, + { + "source": "/docs/learn/cloud/analytics", + "destination": "/docs/learn/analytics/analytics" + }, + { + "source": "/docs/learn/cloud/analytics", + "destination": "/docs/learn/analytics/monitoring" } ] diff --git a/config/sidebar-learn.json b/config/sidebar-learn.json index d1666c4b9a..55f845e33d 100644 --- a/config/sidebar-learn.json +++ b/config/sidebar-learn.json @@ -62,19 +62,35 @@ ] }, { - "title": "Cloud features", - "slug": "cloud", + "title": "Analytics", + "slug": "analytics", "routes": [ { - "source": "learn/cloud/analytics.mdx", - "label": "Analytics", + "source": "learn/analytics/analytics.mdx", + "label": "Configure search analytics", "slug": "analytics" }, { - "source": "learn/cloud/monitoring.mdx", - "label": "Monitoring", + "source": "learn/analytics/monitoring.mdx", + "label": "Configure application monitoring metrics", "slug": "monitoring" }, + { + "source": "learn/analytics/deactivate_analytics_monitoring.mdx", + "label": "Deactivate search analytics and monitoring", + "slug": "deactivate_analytics_monitoring" + }, + { + "source": "learn/analytics/events.mdx", + "label": "Analytics events reference", + "slug": "events" + } + ] + }, + { + "title": "Cloud features", + "slug": "cloud", + "routes": [ { "source": "learn/cloud/teams.mdx", "label": "Teams", diff --git a/learn/analytics/analytics.mdx b/learn/analytics/analytics.mdx new file mode 100644 index 0000000000..d4b4397a99 --- /dev/null +++ b/learn/analytics/analytics.mdx @@ -0,0 +1,85 @@ +--- +title: Configure search analytics +description: Meilisearch Cloud offers in-depth search analytics to help you understand how users search in your application. +--- + +# Analytics + +Enable Meilisearch Cloud analytics to help you understand how users search in your application. + +This guide walks you through activating analytics, updating your project URL, and configuring all data points. + +## Requirements + +You must have a [Meilisearch Cloud](https://meilisearch.com/cloud?utm_campaign=oss&utm_source=docs&utm_medium=analytics) account to access search analytics. + +## Enable analytics in the project overview + +Log into your Meilisearch Cloud account and navigate to your project's overview. Find the "Analytics and monitoring" section and click on the "Enable analytics and monitoring" button: + +![The analytics section of the project overview. It shows one button, "Enable analytics", and a short explanation of the feature.](/assets/images/cloud-analytics/01-analytics-enable.png) + +Meilisearch Cloud will begin processing your request. The "Analytics and monitoring" section will update when the feature is enabled. + + +Activating analytics will automatically activate [monitoring](/learn/cloud/monitoring). + + +## Update URLs in your application + +When you enable analytics, Meilisearch Cloud changes your project's API URL. Meilisearch Cloud is only able to track metrics for queries sent to this URL. + +Update your application so all API requests point to the new URL: + +```sh +curl \ + -X POST 'https://edge.meilisearch.com/indexes/products/search' \ + -H 'Content-Type: application/json' \ + --data-binary '{ "q": "green socks" }' +``` + +**The previous API URL will remain functional**, but requests targeting it will not send any data to the analytics interface. If you created any custom API keys using the previous URL, you will need to replace them. + +## Configure click-through rate and average click position + +To track metrics like click-through rate and average click position, Meilisearch Cloud needs to know when users click on search results. + +Every time a user clicks on a search result, your application must send a `click` event to the `POST` endpoint of Meilisearch Cloud analytics route: + +```sh +curl \ + -X POST 'https://edge.meilisearch.com/events' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' + --data-binary '{ + "eventType": "click", + "eventName": "Search Result Clicked", + "indexUid": "products", + "objectId": "0", + "position": 0 + }' +``` + + For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint). + +## Configuring conversion rate + +To track conversion rate, first identify what should count as a conversion for your application. For example, in a web shop, a conversion might be a user finalizing the checkout process. + +Once you have established what counts as a conversion in your application, configure it to send a `conversion` event to the `POST` endpoint of Meilisearch Cloud analytics route: + +```sh +curl \ + -X POST 'https://edge.meilisearch.com/events' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' + --data-binary '{ + "eventType": "conversion", + "eventName": "Product Added To Cart", + "indexUid": "products", + "objectId": "0", + "position": 0 + }' +``` + +It is not possible to associate multiple `conversion` events with the same search. For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint). diff --git a/learn/analytics/deactivate_analytics_monitoring.mdx b/learn/analytics/deactivate_analytics_monitoring.mdx new file mode 100644 index 0000000000..8b59c9bece --- /dev/null +++ b/learn/analytics/deactivate_analytics_monitoring.mdx @@ -0,0 +1,31 @@ +--- +title: Deactivate search analytics and monitoring +description: Meilisearch Cloud offers in-depth search analytics to help you understand how users search in your application. +--- + +# Deactivate search analytics and monitoring + +This guide shows you how to deactivate Meilisearch Cloud's search analytics and monitoring. + +## Disable analytics and monitoring in the project overview + +Log into your Meilisearch Cloud account and navigate to your project's overview. Find the "Analytics and monitoring" section and press the "Disable analytics and monitoring" button: + +![The analytics section of the project overview. It shows one button, "Disable analytics and monitoring", and a short explanation of both features.](/assets/images/cloud-analytics/02-analytics-disable.png) + +## Update URLs in your application + +Disabling analytics and monitoring changes your API URL. Update your application so all API requests point to the correct URL: + +```sh +curl \ + -X POST 'https://PROJECT_URL/indexes/products/search' \ + -H 'Content-Type: application/json' \ + --data-binary '{ "q": "green socks" }' +``` + +**The previous API URL will remain functional**, but Meilisearch recommends not using it after disabling analytics in your project. If you created any custom API keys using the previous URL, you will need to replace them. + +## Update `conversion` and `click` events + +If you were tracking `conversion` and `click` events, update your application to stop sending them to Meilisearch Cloud. diff --git a/learn/analytics/events.mdx b/learn/analytics/events.mdx new file mode 100644 index 0000000000..450694dc7c --- /dev/null +++ b/learn/analytics/events.mdx @@ -0,0 +1,68 @@ +--- +title: Analytics events reference +description: When using Meilisearch Cloud analytics, certain data points require you to send data to the `/events` route. +--- + +# Analytics events reference + +When using Meilisearch Cloud analytics, certain data points require you to send data to the `/events` route. + +## The `/events` endpoint + +The `/events` endpoint is only available for Meilisearch Cloud projects with analytics and monitoring activated. + +### Send an event + + + +Send an analytics event to Meilisearch Cloud. Accepts `click` and `conversion` events. + + +Meilisearch automatically associates analytics events with the most recent search of the user who triggered them. To manually bind an analytics event to a specific search, include the same `X-MS-USER-ID` header in your search and event requests. + + +#### Example + + + +##### Response: `201 Created` + +### The `click` event object + +The `click` event must deliver an object with the following fields: + +```json +{ + "eventType": "click", + "eventName": "Search Result Clicked", + "indexUid": "products", + "objectId": "0", + "position": 0 +} +``` + +- `eventType`: a string indicating this is a `click` event +- `eventName`: a string describing the event +- `indexUid`: a string indicating the clicked document's index +- `objectId`: a string indicating the clicked document's primary key +- `position`: an integer indicating the clicked document's position in the list of search results + +### The `conversion` event object + +The `conversion` event must deliver an object with the following fields: + +```json +{ + "eventType": "conversion", + "eventName": "Product Added To Cart", + "indexUid": "products", + "objectID": "0", + "position": 0 +} +``` + +- `eventType`: indicates this is a `conversion` event +- `eventName`: a string describing the event +- `indexUid`: the document's index +- `objectID`: the document's primary key +- `position`: the document's position in the list of search results diff --git a/learn/cloud/monitoring.mdx b/learn/analytics/monitoring.mdx similarity index 96% rename from learn/cloud/monitoring.mdx rename to learn/analytics/monitoring.mdx index 2f88ad8e9d..88e1d8fd36 100644 --- a/learn/cloud/monitoring.mdx +++ b/learn/analytics/monitoring.mdx @@ -1,12 +1,12 @@ --- -title: Monitoring metrics +title: Configure application monitoring metrics description: Meilisearch Cloud offers in-depth metrics to help monitor your application performance. sidebarDepth: 3 --- # Monitoring -Enable Meilisearch Cloud monitoring to keep track of application performance and service status. +Enable Meilisearch Cloud monitoring to keep track of application performance and service status. ## Requirements @@ -23,7 +23,7 @@ Log into your Meilisearch Cloud account and navigate to your project's overview. Meilisearch Cloud will begin processing your request. The "Analytics and monitoring" section will update with new instruction text and buttons when the feature is enabled. -Activating monitoring will automatically activate [analytics](/learn/cloud/analytics). +Activating monitoring will automatically activate [analytics](/learn/cloud/analytics). ### Update URLs in your application diff --git a/learn/cloud/analytics.mdx b/learn/cloud/analytics.mdx deleted file mode 100644 index d936c80eae..0000000000 --- a/learn/cloud/analytics.mdx +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Analytics -description: Meilisearch Cloud offers in-depth search analytics to help you understand how users search in your application. -sidebarDepth: 3 ---- - -# Analytics - -Enable Meilisearch Cloud analytics to help you understand how users search in your application. - -## Requirements - -You must have a [Meilisearch Cloud](https://meilisearch.com/cloud?utm_campaign=oss&utm_source=docs&utm_medium=analytics) account to access search analytics. - -## Activating analytics - -### Enable analytics in the project overview - -Log into your Meilisearch Cloud account and navigate to your project's overview. Find the "Analytics and monitoring" section and click on the "Enable analytics and monitoring" button: - -![The analytics section of the project overview. It shows one button, "Enable analytics", and a short explanation of the feature.](/assets/images/cloud-analytics/01-analytics-enable.png) - -Meilisearch Cloud will begin processing your request. The "Analytics and monitoring" section will update when the feature is enabled. - - -Activating analytics will automatically activate [monitoring](/learn/cloud/monitoring). - - -### Update URLs in your application - -When you enable analytics, Meilisearch Cloud changes your project's API URL. Meilisearch Cloud is only able to track metrics for queries sent to this URL. - -Update your application so all API requests point to the new URL: - -```sh -curl \ - -X POST 'https://edge.meilisearch.com/indexes/products/search' \ - -H 'Content-Type: application/json' \ - --data-binary '{ "q": "green socks" }' -``` - -**The previous API URL will remain functional**, but requests targeting it will not send any data to the analytics interface. If you created any custom API keys using the previous URL, you will need to replace them. - - -Meilisearch Cloud analytics silently ignores requests to [the `/multi-search` route](/reference/api/multi_search). This is a known bug and will be fixed in a future Cloud update. - - -### Configuring click-through rate and average click position - -To track metrics like click-through rate and average click position, Meilisearch Cloud needs to know when users click on search results. - -Every time a user clicks on a search result, your application must send a `click` event to the `POST` endpoint of Meilisearch Cloud analytics route: - -```sh -curl \ - -X POST 'https://edge.meilisearch.com/events' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' - --data-binary '{ - "eventType": "click", - "eventName": "Search Result Clicked", - "indexUid": "products", - "objectId": "0", - "position": 0 - }' -``` - - -Meilisearch automatically associates analytics events with the most recent search of the user who triggered them. To manually bind an analytics event to a specific search, include the same `X-MS-USER-ID` header in your search and event requests. - - -#### The `click` event object - -The `click` event must deliver an object with the following fields: - -```json -{ - "eventType": "click", - "eventName": "Search Result Clicked", - "indexUid": "products", - "objectId": "0", - "position": 0 -} -``` - -- `eventType`: a string indicating this is a `click` event -- `eventName`: a string describing the event -- `indexUid`: a string indicating the clicked document's index -- `objectId`: a string indicating the clicked document's primary key -- `position`: an integer indicating the clicked document's position in the list of search results - -### Configuring conversion rate - -To track conversion rate, first identify what should count as a conversion for your application. For example, in a web shop, a conversion might be a user finalizing the checkout process. - -Once you have established what counts as a conversion in your application, configure it to send a `conversion` event to the `POST` endpoint of Meilisearch Cloud analytics route: - -```sh -curl \ - -X POST 'https://edge.meilisearch.com/events' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer Meilisearch_API_Key' - --data-binary '{ - "eventType": "conversion", - "eventName": "Product Added To Cart", - "indexUid": "products", - "objectId": "0", - "position": 0 - }' -``` - -It is not possible to associate multiple `conversion` events with the same search. - -#### The `conversion` event object - -The `conversion` event must deliver an object with the following fields: - -```json -{ - "eventType": "conversion", - "eventName": "Product Added To Cart", - "indexUid": "products", - "objectID": "0", - "position": 0 -} -``` - -- `eventType`: indicates this is a `conversion` event -- `eventName`: a string describing the event -- `indexUid`: the document's index -- `objectID`: the document's primary key -- `position`: the document's position in the list of search results - -## Deactivating analytics - -### Disable analytics in the project overview - -Log into your Meilisearch Cloud account and navigate to your project's overview. Find the "Analytics and monitoring" section and press the "Disable analytics and monitoring" button: - -![The analytics section of the project overview. It shows one button, "Disable analytics and monitoring", and a short explanation of both features.](/assets/images/cloud-analytics/02-analytics-disable.png) - - -Deactivating analytics will automatically deactivate [monitoring](/learn/cloud/monitoring). - - -### Update URLs in your application - -Disabling analytics changes your API URL. Update your application so all API requests point to the correct URL: - -```sh -curl \ - -X POST 'https://PROJECT_URL/indexes/products/search' \ - -H 'Content-Type: application/json' \ - --data-binary '{ "q": "green socks" }' -``` - -**The previous API URL will remain functional**, but Meilisearch recommends not using it after disabling analytics in your project. If you created any custom API keys using the previous URL, you will need to replace them. - -### Update `conversion` and `click` events - -Update your application so it is no longer sending `conversion` and `click` events to Meilisearch Cloud. From 27fb24637ae6a834cd18daefb5c04dd71e3ba6a3 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 16 May 2024 19:17:24 +0200 Subject: [PATCH 2/8] fix titles --- learn/analytics/analytics.mdx | 2 +- learn/analytics/monitoring.mdx | 34 +++------------------------------- 2 files changed, 4 insertions(+), 32 deletions(-) diff --git a/learn/analytics/analytics.mdx b/learn/analytics/analytics.mdx index d4b4397a99..b299c6986f 100644 --- a/learn/analytics/analytics.mdx +++ b/learn/analytics/analytics.mdx @@ -3,7 +3,7 @@ title: Configure search analytics description: Meilisearch Cloud offers in-depth search analytics to help you understand how users search in your application. --- -# Analytics +# Configure search analytics Enable Meilisearch Cloud analytics to help you understand how users search in your application. diff --git a/learn/analytics/monitoring.mdx b/learn/analytics/monitoring.mdx index 88e1d8fd36..91a29e94c1 100644 --- a/learn/analytics/monitoring.mdx +++ b/learn/analytics/monitoring.mdx @@ -1,10 +1,9 @@ --- title: Configure application monitoring metrics description: Meilisearch Cloud offers in-depth metrics to help monitor your application performance. -sidebarDepth: 3 --- -# Monitoring +# Configure application monitoring metrics Enable Meilisearch Cloud monitoring to keep track of application performance and service status. @@ -12,9 +11,7 @@ Enable Meilisearch Cloud monitoring to keep track of application performance and You must have a [Meilisearch Cloud](https://meilisearch.com/cloud?utm_campaign=oss&utm_source=docs&utm_medium=monitoring) account to access monitoring metrics. -## Activating monitoring - -### Enable monitoring in the project overview +## Enable monitoring in the project overview Log into your Meilisearch Cloud account and navigate to your project's overview. Find the "Analytics and monitoring" section and click on the "Enable analytics and monitoring" button: @@ -26,7 +23,7 @@ Meilisearch Cloud will begin processing your request. The "Analytics and monitor Activating monitoring will automatically activate [analytics](/learn/cloud/analytics). -### Update URLs in your application +## Update URLs in your application When you enable monitoring, Meilisearch Cloud changes your project's API URL. Meilisearch Cloud is only able to track metrics for queries sent to this URL. @@ -40,28 +37,3 @@ curl \ ``` **The previous API URL will remain functional**, but requests targeting it will not send any data to the monitoring interface. - -## Deactivating monitoring - -### Disable monitoring in the project overview - -Log into your Meilisearch Cloud account and navigate to your project's overview. Find the "Analytics and monitoring" section and press the "Disable analytics and monitoring" button: - -![The analytics section of the project overview. It shows one button, "Disable analytics and monitoring", and a short explanation of both features.](/assets/images/cloud-analytics/02-analytics-disable.png) - - -Deactivating monitoring will automatically deactivate [analytics](/learn/cloud/analytics). - - -### Update URLs in your application - -Disabling monitoring changes your API URL. Update your application so all API requests point to the correct URL: - -```sh -curl \ - -X POST 'http://PROJECT_URL/indexes/products/search' \ - -H 'Content-Type: application/json' \ - --data-binary '{ "q": "green socks" }' -``` - -**The previous API URL will remain functional**, but Meilisearch recommends not using it after disabling monitoring in your project. From b937665c6a018a0ba80db63cc3332aa1adbb2f0c Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 20 May 2024 18:38:11 +0200 Subject: [PATCH 3/8] first draft ready --- .code-samples.meilisearch.yaml | 14 +++++++- config/sidebar-learn.json | 10 +++--- ...{analytics.mdx => configure_analytics.mdx} | 36 ++++--------------- ...onitoring.mdx => configure_monitoring.mdx} | 0 .../{events.mdx => events_endpoint.mdx} | 12 +++---- 5 files changed, 31 insertions(+), 41 deletions(-) rename learn/analytics/{analytics.mdx => configure_analytics.mdx} (76%) rename learn/analytics/{monitoring.mdx => configure_monitoring.mdx} (100%) rename learn/analytics/{events.mdx => events_endpoint.mdx} (72%) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index f5cf67aebd..e6b2463787 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -1209,7 +1209,7 @@ negative_search_2: |- -X POST 'http://localhost:7700/indexes/movies/search' \ -H 'Content-Type: application/json' \ --data-binary '{ "q": "-\"escape room\"" }' -analytics_event_send_1: |- +analytics_event_click_1: |- curl \ -X POST 'https://edge.meilisearch.com/events' \ -H 'Content-Type: application/json' \ @@ -1221,3 +1221,15 @@ analytics_event_send_1: |- "objectId": "0", "position": 0 }' +analytics_event_conversion_1: |- + curl \ + -X POST 'https://edge.meilisearch.com/events' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' + --data-binary '{ + "eventType": "conversion", + "eventName": "Product Added To Cart", + "indexUid": "products", + "objectId": "0", + "position": 0 + }' diff --git a/config/sidebar-learn.json b/config/sidebar-learn.json index 55f845e33d..1584fbbae9 100644 --- a/config/sidebar-learn.json +++ b/config/sidebar-learn.json @@ -66,12 +66,12 @@ "slug": "analytics", "routes": [ { - "source": "learn/analytics/analytics.mdx", + "source": "learn/analytics/configure_analytics.mdx", "label": "Configure search analytics", "slug": "analytics" }, { - "source": "learn/analytics/monitoring.mdx", + "source": "learn/analytics/configure_monitoring.mdx", "label": "Configure application monitoring metrics", "slug": "monitoring" }, @@ -81,9 +81,9 @@ "slug": "deactivate_analytics_monitoring" }, { - "source": "learn/analytics/events.mdx", - "label": "Analytics events reference", - "slug": "events" + "source": "learn/analytics/events_endpoint.mdx", + "label": "Analytics events endpoint", + "slug": "events_endpoint" } ] }, diff --git a/learn/analytics/analytics.mdx b/learn/analytics/configure_analytics.mdx similarity index 76% rename from learn/analytics/analytics.mdx rename to learn/analytics/configure_analytics.mdx index b299c6986f..db2dff0305 100644 --- a/learn/analytics/analytics.mdx +++ b/learn/analytics/configure_analytics.mdx @@ -22,7 +22,7 @@ Log into your Meilisearch Cloud account and navigate to your project's overview. Meilisearch Cloud will begin processing your request. The "Analytics and monitoring" section will update when the feature is enabled. -Activating analytics will automatically activate [monitoring](/learn/cloud/monitoring). +Activating analytics will automatically activate [monitoring](/learn/cloud/monitoring). ## Update URLs in your application @@ -46,21 +46,9 @@ To track metrics like click-through rate and average click position, Meilisearch Every time a user clicks on a search result, your application must send a `click` event to the `POST` endpoint of Meilisearch Cloud analytics route: -```sh -curl \ - -X POST 'https://edge.meilisearch.com/events' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' - --data-binary '{ - "eventType": "click", - "eventName": "Search Result Clicked", - "indexUid": "products", - "objectId": "0", - "position": 0 - }' -``` + - For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint). + For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint#the-conversion-event-object). ## Configuring conversion rate @@ -68,18 +56,8 @@ To track conversion rate, first identify what should count as a conversion for y Once you have established what counts as a conversion in your application, configure it to send a `conversion` event to the `POST` endpoint of Meilisearch Cloud analytics route: -```sh -curl \ - -X POST 'https://edge.meilisearch.com/events' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' - --data-binary '{ - "eventType": "conversion", - "eventName": "Product Added To Cart", - "indexUid": "products", - "objectId": "0", - "position": 0 - }' -``` + + +It is not possible to associate multiple `conversion` events with the same search. -It is not possible to associate multiple `conversion` events with the same search. For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint). +For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint#the-conversion-event-object). diff --git a/learn/analytics/monitoring.mdx b/learn/analytics/configure_monitoring.mdx similarity index 100% rename from learn/analytics/monitoring.mdx rename to learn/analytics/configure_monitoring.mdx diff --git a/learn/analytics/events.mdx b/learn/analytics/events_endpoint.mdx similarity index 72% rename from learn/analytics/events.mdx rename to learn/analytics/events_endpoint.mdx index 450694dc7c..9074819321 100644 --- a/learn/analytics/events.mdx +++ b/learn/analytics/events_endpoint.mdx @@ -1,11 +1,11 @@ --- -title: Analytics events reference -description: When using Meilisearch Cloud analytics, certain data points require you to send data to the `/events` route. +title: Analytics events endpoint +description: This reference describes /events, the endpoint you should use to submit analytics events to Meilisearch Cloud. It also describes the accepted event objects and the data you must include in them. --- -# Analytics events reference +# Analytics events endpoint -When using Meilisearch Cloud analytics, certain data points require you to send data to the `/events` route. +This reference describes `/events`, the endpoint you should use to submit analytics events to Meilisearch Cloud. It also describes the accepted event objects and the data you must include in them. ## The `/events` endpoint @@ -15,7 +15,7 @@ The `/events` endpoint is only available for Meilisearch Cloud projects with ana -Send an analytics event to Meilisearch Cloud. Accepts `click` and `conversion` events. +Send an analytics event to Meilisearch Cloud. Accepts [`click`](#the-click-event-object) and [`conversion`](#the-conversion-event-object) events. Meilisearch automatically associates analytics events with the most recent search of the user who triggered them. To manually bind an analytics event to a specific search, include the same `X-MS-USER-ID` header in your search and event requests. @@ -23,7 +23,7 @@ Meilisearch automatically associates analytics events with the most recent searc #### Example - + ##### Response: `201 Created` From d8e837014973c20ed2acabeca39eef9a2e1ab63b Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 22 May 2024 17:58:59 +0200 Subject: [PATCH 4/8] add binding analytics events guide --- .code-samples.meilisearch.yaml | 20 ++++++++++++++++ config/sidebar-learn.json | 5 ++++ learn/analytics/bind_events_user.mdx | 31 +++++++++++++++++++++++++ learn/analytics/configure_analytics.mdx | 8 +++++-- learn/analytics/events_endpoint.mdx | 4 ++-- 5 files changed, 64 insertions(+), 4 deletions(-) create mode 100644 learn/analytics/bind_events_user.mdx diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index e6b2463787..5823423c21 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -1233,3 +1233,23 @@ analytics_event_conversion_1: |- "objectId": "0", "position": 0 }' +analytics_event_bind_search_1: |- + curl \ + -X POST 'http://localhost:7700/indexes/INDEX_NAME/search' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \ + -H 'X-MS-USER-ID: MEILISEARCH_USER_ID' \ + --data-binary '{}' +analytics_event_bind_event_1: |- + curl \ + -X POST 'https://edge.meilisearch.com/events' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \ + -H 'X-MS-USER-ID: MEILISEARCH_USER_ID' \ + --data-binary '{ + "eventType": "click", + "eventName": "Search Result Clicked", + "indexUid": "products", + "objectId": "0", + "position": 0 + }' \ No newline at end of file diff --git a/config/sidebar-learn.json b/config/sidebar-learn.json index 1584fbbae9..ee76b5c2f6 100644 --- a/config/sidebar-learn.json +++ b/config/sidebar-learn.json @@ -75,6 +75,11 @@ "label": "Configure application monitoring metrics", "slug": "monitoring" }, + { + "source": "learn/analytics/bind_events_user", + "label": "Bind analytics events to a user", + "slug": "bind_events_user" + }, { "source": "learn/analytics/deactivate_analytics_monitoring.mdx", "label": "Deactivate search analytics and monitoring", diff --git a/learn/analytics/bind_events_user.mdx b/learn/analytics/bind_events_user.mdx new file mode 100644 index 0000000000..569af3dd9a --- /dev/null +++ b/learn/analytics/bind_events_user.mdx @@ -0,0 +1,31 @@ +--- +title: Bind analytics events to a user +description: This guide shows you how to manually bind analytics events to search queries using the X-MS-USER-ID HTTP header. +--- + +# Bind analytics events to a user + +By default, Meilisearch associates analytics events with the most recent search of the user who triggered them. This guide shows you how to manually bind analytics events to search queries using the `X-MS-USER-ID` HTTP header. + +## Requirements + +- A Meilisearch Cloud project with analytics and monitoring enabled +- A working pipeline for submitting analytics events + +## Add `X-MS-USER-ID` to your search query + +Include the `X-MS-USER-ID` header in your search requests: + + + +Replace `MEILISEARCH_USER_ID` with any value that uniquely identifies that user. This may be an authenticated user's ID when running searches from your own back end, or a user's IP address. + +## Add `X-MS-USER-ID` to the analytics event + +Next, submit your analytics event to the analytics endpoint. Send the same header and value in your API call: + + + +## Conclusion + +In this guide you have seen how to bind analytics events to specific users by specifying the same HTTP header for both the search request and the analytics event. diff --git a/learn/analytics/configure_analytics.mdx b/learn/analytics/configure_analytics.mdx index db2dff0305..90a61d8529 100644 --- a/learn/analytics/configure_analytics.mdx +++ b/learn/analytics/configure_analytics.mdx @@ -48,9 +48,11 @@ Every time a user clicks on a search result, your application must send a `click - For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint#the-conversion-event-object). +By default, Meilisearch associates analytics events with the most recent search of the user who triggered them. -## Configuring conversion rate +For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint#the-conversion-event-object). + +## Configure conversion rate To track conversion rate, first identify what should count as a conversion for your application. For example, in a web shop, a conversion might be a user finalizing the checkout process. @@ -58,6 +60,8 @@ Once you have established what counts as a conversion in your application, confi +By default, Meilisearch associates analytics events with the most recent search of the user who triggered them. + It is not possible to associate multiple `conversion` events with the same search. For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint#the-conversion-event-object). diff --git a/learn/analytics/events_endpoint.mdx b/learn/analytics/events_endpoint.mdx index 9074819321..342b8486fc 100644 --- a/learn/analytics/events_endpoint.mdx +++ b/learn/analytics/events_endpoint.mdx @@ -17,8 +17,8 @@ The `/events` endpoint is only available for Meilisearch Cloud projects with ana Send an analytics event to Meilisearch Cloud. Accepts [`click`](#the-click-event-object) and [`conversion`](#the-conversion-event-object) events. - -Meilisearch automatically associates analytics events with the most recent search of the user who triggered them. To manually bind an analytics event to a specific search, include the same `X-MS-USER-ID` header in your search and event requests. + +By default, Meilisearch associates analytics events with the most recent search of the user who triggered them. Include the same `X-MS-USER-ID` header in your search and event requests to manually [bind analytics events to a user](/learn/analytics/bind_events_search). #### Example From adc191bdd4e112c06530eddd9bd90d0ef99be618 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 22 May 2024 18:03:01 +0200 Subject: [PATCH 5/8] fix broken link --- config/sidebar-learn.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/sidebar-learn.json b/config/sidebar-learn.json index ee76b5c2f6..ecb8b2f69e 100644 --- a/config/sidebar-learn.json +++ b/config/sidebar-learn.json @@ -76,7 +76,7 @@ "slug": "monitoring" }, { - "source": "learn/analytics/bind_events_user", + "source": "learn/analytics/bind_events_user.mdx", "label": "Bind analytics events to a user", "slug": "bind_events_user" }, From e2f4d0e3808a528ac1b0fd9acab0576e05d72b93 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 23 May 2024 13:46:59 +0200 Subject: [PATCH 6/8] Apply suggestions from code review --- .code-samples.meilisearch.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 5823423c21..2b2336c86a 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -1252,4 +1252,4 @@ analytics_event_bind_event_1: |- "indexUid": "products", "objectId": "0", "position": 0 - }' \ No newline at end of file + }' From 4b282bfe3e6040812439d26fd058513fa2c7c351 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 23 May 2024 14:11:54 +0200 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: Guillaume Mourier --- learn/analytics/bind_events_user.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/learn/analytics/bind_events_user.mdx b/learn/analytics/bind_events_user.mdx index 569af3dd9a..da52850f17 100644 --- a/learn/analytics/bind_events_user.mdx +++ b/learn/analytics/bind_events_user.mdx @@ -1,11 +1,13 @@ --- -title: Bind analytics events to a user -description: This guide shows you how to manually bind analytics events to search queries using the X-MS-USER-ID HTTP header. +title: Bind search analytics events to a user +description: This guide shows you how to manually differentiate users across search analytics using the X-MS-USER-ID HTTP header. --- -# Bind analytics events to a user +# Bind search analytics events to a user -By default, Meilisearch associates analytics events with the most recent search of the user who triggered them. This guide shows you how to manually bind analytics events to search queries using the `X-MS-USER-ID` HTTP header. +By default, Meilisearch uses IP addresses to identify users and calculate the total user metrics. This guide shows you how to use the `X-MS-USER-ID` HTTP header to manually link analytics events to specific users. + +This is useful if you're searching from your back end, as all searches would otherwise appear to come from your server's IP address, making it difficult to accurately track the number of individual users. ## Requirements @@ -18,7 +20,7 @@ Include the `X-MS-USER-ID` header in your search requests: -Replace `MEILISEARCH_USER_ID` with any value that uniquely identifies that user. This may be an authenticated user's ID when running searches from your own back end, or a user's IP address. +Replace `MEILISEARCH_USER_ID` with any value that uniquely identifies that user. This may be an authenticated user's ID when running searches from your own back end, or a hash of the user's IP address. ## Add `X-MS-USER-ID` to the analytics event From 5e669f11ecc85e7c9ac103438d0b0bc96a8a83f5 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 23 May 2024 19:26:38 +0200 Subject: [PATCH 8/8] create new "Teams" section (#2833) --- config/redirects.json | 4 ++++ config/sidebar-learn.json | 8 ++++---- learn/{cloud => teams}/teams.mdx | 0 3 files changed, 8 insertions(+), 4 deletions(-) rename learn/{cloud => teams}/teams.mdx (100%) diff --git a/config/redirects.json b/config/redirects.json index 42387fc1a8..e92064a07b 100644 --- a/config/redirects.json +++ b/config/redirects.json @@ -161,5 +161,9 @@ { "source": "/docs/learn/cloud/analytics", "destination": "/docs/learn/analytics/monitoring" + }, + { + "source": "/docs/learn/cloud/teams", + "destination": "/docs/learn/teams/teams" } ] diff --git a/config/sidebar-learn.json b/config/sidebar-learn.json index ecb8b2f69e..349588148d 100644 --- a/config/sidebar-learn.json +++ b/config/sidebar-learn.json @@ -93,12 +93,12 @@ ] }, { - "title": "Cloud features", - "slug": "cloud", + "title": "Teams", + "slug": "teams", "routes": [ { - "source": "learn/cloud/teams.mdx", - "label": "Teams", + "source": "learn/teams/teams.mdx", + "label": "Meilisearch Cloud teams", "slug": "teams" } ] diff --git a/learn/cloud/teams.mdx b/learn/teams/teams.mdx similarity index 100% rename from learn/cloud/teams.mdx rename to learn/teams/teams.mdx