New analytics section

.code-samples.meilisearch.yaml

@@ -1209,3 +1209,27 @@ negative_search_2: |-
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "-\"escape room\"" }'
+analytics_event_click_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
+ }'
+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
+ }'

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"
  }
 ]

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/configure_analytics.mdx",
+ "label": "Configure search analytics",
  "slug": "analytics"
  },
  {
- "source": "learn/cloud/monitoring.mdx",
- "label": "Monitoring",
+ "source": "learn/analytics/configure_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_endpoint.mdx",
+ "label": "Analytics events endpoint",
+ "slug": "events_endpoint"
+ }
+ ]
+ },
+ {
+ "title": "Cloud features",
+ "slug": "cloud",
+ "routes": [
  {
  "source": "learn/cloud/teams.mdx",
  "label": "Teams",

learn/analytics/configure_analytics.mdx

@@ -0,0 +1,63 @@
+---
+title: Configure search analytics
+description: Meilisearch Cloud offers in-depth search analytics to help you understand how users search in your application.
+---
+
+# Configure search 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.
+
+<Capsule intent="note" title="Monitoring and analytics">
+Activating analytics will automatically activate [monitoring](/learn/cloud/monitoring).
+</Capsule>
+
+## 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:
+
+<CodeSamples id="analytics_event_click_1" />
+
+ For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint#the-conversion-event-object).
+
+## 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:
+
+<CodeSamples id="analytics_event_conversion_1" />
+
+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).

learn/cloud/monitoring.mdx → learn/analytics/configure_monitoring.mdx

@@ -1,20 +1,17 @@
 ---
-title: Monitoring metrics
+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. 
+Enable Meilisearch Cloud monitoring to keep track of application performance and service status.
 
 ## Requirements
 
 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:
 
@@ -23,10 +20,10 @@ 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.
 
 <Capsule intent="note" title="Monitoring and analytics">
-Activating monitoring will automatically activate [analytics](/learn/cloud/analytics). 
+Activating monitoring will automatically activate [analytics](/learn/cloud/analytics).
 </Capsule>
 
-### 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)
-
-<Capsule intent="note" title="Monitoring and analytics">
-Deactivating monitoring will automatically deactivate [analytics](/learn/cloud/analytics). 
-</Capsule>
-
-### 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.

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.

learn/analytics/events_endpoint.mdx

@@ -0,0 +1,68 @@
+---
+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 endpoint
+
+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
+
+The `/events` endpoint is only available for Meilisearch Cloud projects with analytics and monitoring activated.
+
+### Send an event
+
+<RouteHighlighter method="POST" route="https://edge.meilisearch.com/events"/>
+
+Send an analytics event to Meilisearch Cloud. Accepts [`click`](#the-click-event-object) and [`conversion`](#the-conversion-event-object) events.
+
+<Capsule intent="tip" title="Binding analytics events to a search">
+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.
+</Capsule>
+
+#### Example
+
+<CodeSamples id="analytics_event_click_1" />
+
+##### 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