Update Cloud analytics documentation

.code-samples.meilisearch.yaml

@@ -1278,26 +1278,31 @@ negative_search_2: |-
     --data-binary '{ "q": "-\"escape room\"" }'
 analytics_event_click_1: |-
   curl \
-    -X POST 'https://edge.meilisearch.com/events' \
+    -X POST 'https://PROJECT_URL/events' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \
     --data-binary '{
       "eventType": "click",
       "eventName": "Search Result Clicked",
       "indexUid": "products",
+      "userId": "SEARCH_USER_ID",
+      "queryUid": "019a01b7-a1c2-7782-a410-bb1274c81393",
       "objectId": "0",
+      "objectName": "DOCUMENT_DESCRIPTION",
       "position": 0
     }'
 analytics_event_conversion_1: |-
   curl \
-    -X POST 'https://edge.meilisearch.com/events' \
+    -X POST 'https://PROJECT_URL/events' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY'
     --data-binary '{
       "eventType": "conversion",
       "eventName": "Product Added To Cart",
       "indexUid": "products",
+      "userId": "SEARCH_USER_ID",
       "objectId": "0",
+      "objectName": "DOCUMENT_DESCRIPTION",
       "position": 0
     }'
 analytics_event_bind_search_1: |-
@@ -1309,12 +1314,25 @@ analytics_event_bind_search_1: |-
     --data-binary '{}'
 analytics_event_bind_event_1: |-
   curl \
-    -X POST 'https://edge.meilisearch.com/events' \
+    -X POST 'https://PROJECT_URL/events' \
+    -H 'Content-Type: application/json' \
+    -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \
+    -H 'X-MS-USER-ID: SEARCH_USER_ID' \
+    --data-binary '{
+      "eventType": "click",
+      "eventName": "Search Result Clicked",
+      "indexUid": "products",
+      "objectId": "0",
+      "position": 0
+    }'
+analytics_event_bind_event_2: |-
+  curl \
+    -X POST 'https://PROJECT_URL/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",
+      "userId": "SEARCH_USER_ID",
       "eventName": "Search Result Clicked",
       "indexUid": "products",
       "objectId": "0",

docs.json

@@ -206,11 +206,11 @@
               {
                 "group": "Analytics",
                 "pages": [
-                  "learn/analytics/configure_analytics",
-                  "learn/analytics/configure_monitoring",
+                  "learn/analytics/configure_analytics_events",
                   "learn/analytics/bind_events_user",
-                  "learn/analytics/deactivate_analytics_monitoring",
-                  "learn/analytics/events_endpoint"
+                  "learn/analytics/migrate_analytics_monitoring",
+                  "learn/analytics/events_endpoint",
+                  "learn/analytics/analytics_metrics_reference"
                 ]
               },
               {
@@ -1006,6 +1006,10 @@
     {
       "source": "/guides/back_end/laravel_scout",
       "destination": "/guides/laravel_scout"
+    },
+    {
+      "source": "/learn/analytics/deactivate_analytics_monitoring",
+      "destination": "/learn/analytics/migrate_analytics_monitoring"
     }
   ]
 }

learn/analytics/analytics_metrics_reference.mdx

@@ -0,0 +1,60 @@
+---
+title: Analytics metrics reference
+description: This reference describes the metrics you can find in the Meilisearch Cloud analytics interface.
+---
+
+## Total searches
+
+Total number of searches made during the specified period. Multi-search and federated search requests count as a single search.
+
+## Total users
+
+Total number of users who performed a search in the specified period.
+
+Include the [user ID](/learn/analytics/bind_events_user) in your search request headers for the most accurate metrics. If search requests do not provide any user ID, the total amount of unique users will increase, as each request is assigned to a unique user ID.
+
+## No result rate
+
+Percentage of searches that did not return any results.
+
+## Click-through rate
+
+The ratio between the number of times users clicked on a result and the number of times Meilisearch showed that result. Since users will click on results that potentially match what they were looking for, a higher number indicates better relevancy.
+
+Meilisearch does not have access to this information by default. You must [configure your application to submit click events](/learn/analytics/configure_analytics_events) to Meilisearch if you want to track it in the Meilisearch Cloud interface.
+
+## Average click position
+
+The average list position of clicked search results. A lower number means users have clicked on the first search results and indicates good relevancy.
+
+Meilisearch does not have access to this information by default. You must [configure your application to submit click events](/learn/analytics/configure_analytics_events) to Meilisearch if you want to track it in the Meilisearch Cloud interface.
+
+## Conversion
+
+The percentage of searches resulting in a conversion event in your application. Conversion events vary depending on your application and indicate a user has performed a specific desired action. For example, a conversion for an e-commerce website might mean a user has bought a product.
+
+You must explicitly [configure your application to send conversion](/learn/analytics/configure_analytics_events) events when conditions are met.
+
+<Note>
+It is not possible to associate multiple `conversion` events with the same query.
+</Note>
+
+## Search requests
+
+Total number of search requests within the specified time period.
+
+## Search latency
+
+The amount of time between a user making a search request and Meilisearch Cloud returning search results. A lower number indicates users receive search results more quickly.
+
+## Most searched queries
+
+Most common query terms users have used while searching.
+
+## Searches without results
+
+Most common query terms that did not return any search results.
+
+## Countries with most searches
+
+List of countries that generate the largest amount of search requests.

learn/analytics/bind_events_user.mdx

@@ -7,29 +7,46 @@ description: This guide shows you how to manually differentiate users across sea
 import CodeSamplesAnalyticsEventBindSearch1 from '/snippets/samples/code_samples_analytics_event_bind_search_1.mdx';
 import CodeSamplesAnalyticsEventBindEvent1 from '/snippets/samples/code_samples_analytics_event_bind_event_1.mdx';
 
-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.
+<Note>
+This article refers to a new version of the Meilisearch Cloud analytics that is being rolled out in November 2025. Some features described here may not yet be available to your account. Contact support for more information.
+</Note>
 
 ## Requirements
 
-- A Meilisearch Cloud project with analytics and monitoring enabled
-- A working pipeline for submitting analytics events
+- A Meilisearch Cloud project
+- A method for identifying users
+- A pipeline for submitting analytics events
 
-## Add `X-MS-USER-ID` to your search query
+## Assign user IDs to search requests
 
-Include the `X-MS-USER-ID` header in your search requests:
+You can assign user IDs to search requests by including an `X-MS-USER-ID` header with your query:
 
 <CodeSamplesAnalyticsEventBindSearch1 />
 
-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.
+Replace `SEARCH_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.
+
+<Note>
+Assigning user IDs to search requests is optional. If a Meilisearch Cloud search request does not have an ID, Meilisearch will automatically generate one.
+</Note>
 
-## Add `X-MS-USER-ID` to the analytics event
+## Assign user IDs to analytics events
 
-Next, submit your analytics event to the analytics endpoint. Send the same header and value in your API call:
+You can assign a user ID to analytics `/events` in two ways: HTTP headers or including it in the event payload.
+
+If using HTTP headers, include an `X-MS-USER-ID` header with your query:
 
 <CodeSamplesAnalyticsEventBindEvent1 />
 
+If you prefer to the event in your payload, include a `userId` field with your request:
+
+<CodeSamplesAnalyticsEventBindEvent2 />
+
+Replace `SEARCH_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.
+
+<Warning>
+It is mandatory to specify a user ID when sending analytics events.
+</Warning>
+
 ## 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.
+In this guide you have seen how to bind analytics events to specific users by specifying an HTTP header for the search request, and either an HTTP header or a `userId` field for the analytics event.

learn/analytics/configure_analytics_events.mdx

@@ -0,0 +1,47 @@
+---
+title: Configure Meilisearch Cloud analytics events
+description: By default, Meilisearch Cloud analytics tracks metrics such as number of users and latency. Follow this guide to track advanced events such as user conversion and click-through rates.
+---
+
+import CodeSamplesAnalyticsEventConversion1 from '/snippets/samples/code_samples_analytics_event_conversion_1.mdx';
+import CodeSamplesAnalyticsEventClick1 from '/snippets/samples/code_samples_analytics_event_click_1.mdx';
+
+<Note>
+This article refers to a new version of the Meilisearch Cloud analytics that is being rolled out in November 2025. Some features described here may not yet be available to your account. Contact support for more information.
+</Note>
+
+## Requirements
+
+You must have a [Meilisearch Cloud](https://meilisearch.com/cloud) account to access search analytics.
+
+## Configure click-through rate and average click position
+
+To track 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's `/events` route:
+
+<CodeSamplesAnalyticsEventClick1 />
+
+You must explicitly submit a `userId` associated with the event. This can be any arbitrary string you use to identify the user, such as their profile ID in your application or their hashed IP address. You may submit user IDs directly on the event payload, or setting a `X-MS-USER-ID` request header.
+
+Specifying a `queryUid` is optional but recommended as it ensures Meilisearch correctly associates the search query with the event. You can find the query UID in the [`metadata` field present in Meilisearch Cloud's search query responses](/reference/api/overview#search-metadata).
+
+For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint).
+
+## 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.
+
+Once you have established what is a conversion in your application, configure it to send a `conversion` event to the `POST` endpoint of Meilisearch Cloud analytics route:
+
+<CodeSamplesAnalyticsEventConversion1 />
+
+You must explicitly submit a `userId` associated with the event. This can be any arbitrary string you can use to identify the user, such as their profile ID in your application or their hashed IP address. You may submit user IDs directly on the event payload, or setting a `X-MS-USER-ID` request header.
+
+Specifying a `queryUid` is optional but recommended as it ensures Meilisearch correctly associates the search query with the event. You can find the query UID in the `metadata` field present in Meilisearch Cloud's search query response.
+
+<Note>
+It is not possible to associate multiple `conversion` events with the same query.
+</Note>
+
+For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint).