diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 95fe1afbac..33b8f35b72 100644 --- a/.code-samples.meilisearch.yaml +++ b/.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", diff --git a/docs.json b/docs.json index 7e448ae459..1b1ecbef23 100644 --- a/docs.json +++ b/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" } ] } diff --git a/learn/analytics/analytics_metrics_reference.mdx b/learn/analytics/analytics_metrics_reference.mdx new file mode 100644 index 0000000000..f634796644 --- /dev/null +++ b/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. + + +It is not possible to associate multiple `conversion` events with the same query. + + +## 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. diff --git a/learn/analytics/bind_events_user.mdx b/learn/analytics/bind_events_user.mdx index 0030b5bb97..21ae2e3e85 100644 --- a/learn/analytics/bind_events_user.mdx +++ b/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. + +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. + ## 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: -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. + + +Assigning user IDs to search requests is optional. If a Meilisearch Cloud search request does not have an ID, Meilisearch will automatically generate one. + -## 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: +If you prefer to the event in your payload, include a `userId` field with your request: + + + +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. + + +It is mandatory to specify a user ID when sending analytics events. + + ## 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. diff --git a/learn/analytics/configure_analytics.mdx b/learn/analytics/configure_analytics.mdx deleted file mode 100644 index 2a7318b217..0000000000 --- a/learn/analytics/configure_analytics.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Configure search analytics -sidebarTitle: Configure search analytics -description: Meilisearch Cloud offers in-depth search analytics to help you understand how users search in your application. ---- - -import CodeSamplesAnalyticsEventConversion1 from '/snippets/samples/code_samples_analytics_event_conversion_1.mdx'; -import CodeSamplesAnalyticsEventClick1 from '/snippets/samples/code_samples_analytics_event_click_1.mdx'; - -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. - - -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/analytics/configure_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: - - - -By default, Meilisearch associates analytics events with the most recent search of the user who triggered them. - -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. - -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: - - - -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/configure_analytics_events.mdx b/learn/analytics/configure_analytics_events.mdx new file mode 100644 index 0000000000..957aeb0526 --- /dev/null +++ b/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'; + + +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. + + +## 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: + + + +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: + + + +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. + + +It is not possible to associate multiple `conversion` events with the same query. + + +For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint). diff --git a/learn/analytics/configure_monitoring.mdx b/learn/analytics/configure_monitoring.mdx deleted file mode 100644 index d4b16a595d..0000000000 --- a/learn/analytics/configure_monitoring.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Configure application monitoring metrics -sidebarTitle: Configure application monitoring metrics -description: Meilisearch Cloud offers in-depth metrics to help monitor your application performance. ---- - -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. - -## 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: - - - The analytics and monitoring section of the project overview. It shows one button, 'Enable analytics and monitoring', and a short explanation of both features. - - -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/analytics/configure_analytics). - - -## 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. - -Update your application so all API requests point to the new URL: - -```sh -curl \ - -X POST 'http://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 monitoring interface. diff --git a/learn/analytics/deactivate_analytics_monitoring.mdx b/learn/analytics/deactivate_analytics_monitoring.mdx deleted file mode 100644 index 61b606a3eb..0000000000 --- a/learn/analytics/deactivate_analytics_monitoring.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Deactivate search analytics and monitoring -sidebarTitle: Deactivate search analytics and monitoring -description: Meilisearch Cloud offers in-depth search analytics to help you understand how users search in your application. ---- - -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. - - -## 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_endpoint.mdx b/learn/analytics/events_endpoint.mdx index 942938901f..e75b69459a 100644 --- a/learn/analytics/events_endpoint.mdx +++ b/learn/analytics/events_endpoint.mdx @@ -1,38 +1,32 @@ --- title: Analytics events endpoint -sidebarTitle: 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. +description: Use `/events` to submit analytics events such as `click` and `conversion` to Meilisearch Cloud. --- import CodeSamplesAnalyticsEventClick1 from '/snippets/samples/code_samples_analytics_event_click_1.mdx'; -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. + +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. + -## The `/events` endpoint +## Send an event -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. -```http -POST 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. - - -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_user). - - -#### Example - - - -##### Response: `201 Created` - -### The `click` event object +### Body -The `click` event must deliver an object with the following fields: +| Name | Type | Default value | Description | +| :------------ | :-------------- | :------------ | :------------------------------------------------------------------------------ | +| `eventType` | String | N/A | The event type, such as `click` or `conversion`, required | +| `eventName` | String | N/A | A string describing the event, required | +| `indexUid` | String | N/A | The name of the index of the clicked document, required | +| `queryUid` | String | N/A | The [search query's UID](/reference/api/overview#search-metadata) | +| `objectId` | String | N/A | The clicked document's primary key value | +| `objectName` | String | N/A | A string describing the document | +| `position` | Integer | N/A | An integer indicating the clicked document's position in the search result list | +| `userId` | String | N/A | An arbitrary string identifying the user who performed the action | ```json { @@ -44,28 +38,17 @@ The `click` event must deliver an object with the following fields: } ``` -- `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 + +You must provide a string identifying your user if you want Meilisearch Cloud to track conversion and click events. -### The `conversion` event object +You may do that in two ways: -The `conversion` event must deliver an object with the following fields: +- Specify the user ID in the payload, using the `userId` field +- Specify the user ID with the `X-MS-USER-ID` header with your `/events` and search requests + -```json -{ - "eventType": "conversion", - "eventName": "Product Added To Cart", - "indexUid": "products", - "objectID": "0", - "position": 0 -} -``` +#### Example -- `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 + + +##### Response: `201 Created` diff --git a/learn/analytics/migrate_analytics_monitoring.mdx b/learn/analytics/migrate_analytics_monitoring.mdx new file mode 100644 index 0000000000..9da4787bd2 --- /dev/null +++ b/learn/analytics/migrate_analytics_monitoring.mdx @@ -0,0 +1,25 @@ +--- +title: Migrate to the November 2025 Meilisearch Cloud analytics +description: Follow this guide to ensure your Meilisearch Cloud analytics configuration is up to date after the November 2025 release. +--- + + +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. + + +## Analytics and monitoring are always active + +Analytics and monitoring are now active in all Meilisearch Cloud projects. Basic functionality requires no extra configuration. Tracking user conversion, clickthrough, and clicked result position must instead be explicitly configured. + +## Update URLs in your application + +Meilisearch no longer requires `edge.meilisearch.com` to track search analytics. Update your application so all API requests, including click and conversion events, point to your project URL: + +```sh +curl \ + -X POST 'https://PROJECT_URL/indexes/products/search' \ + -H 'Content-Type: application/json' \ + --data-binary '{ "q": "green socks" }' +``` + +`edge.meilisearch.com` remains functional, but no longer provides any benefit and will be discontinued in the future. If you created any custom API keys using the previous URL, you will also need to replace them. diff --git a/reference/api/overview.mdx b/reference/api/overview.mdx index 31aa2b3197..2b66e7a13b 100644 --- a/reference/api/overview.mdx +++ b/reference/api/overview.mdx @@ -129,6 +129,8 @@ curl -X POST 'http://localhost:7700/indexes/INDEX_NAME/search' \ -d '{"q": ""}' ``` +Meilisearch Cloud includes this header by default. + Responses will include a `metadata` object: ```json @@ -151,6 +153,12 @@ Responses will include a `metadata` object: | `primaryKey` | String | Primary key field name, if index has a primary key | | `remote` | String | Remote instance name, if request targets a remote instance | + +A search refers to a single HTTP search request. Every search request is assigned a `requestUid`. A query UID is a combination of `q` and `indexUid`. + +In the context of multi-search, for any given `searchUid` there may be multiple `queryUid` values. + + ## Request body The request body is data sent to the API. It is used with PUT, POST, and PATCH methods to create or update a resource. You must provide request bodies in JSON.