Skip to content

Commit 6462ce7

Browse files
guimachiavelliguimachiavelli
authored
Update Cloud analytics documentation (#3389)
1 parent 4ca3dab commit 6462ce7

11 files changed

+226
-207
lines changed

‎.code-samples.meilisearch.yaml‎

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1278,26 +1278,31 @@ negative_search_2: |-
12781278
--data-binary '{ "q": "-\"escape room\"" }'
12791279
analytics_event_click_1: |-
12801280
curl \
1281-
-X POST 'https://edge.meilisearch.com/events' \
1281+
-X POST 'https://PROJECT_URL/events' \
12821282
-H 'Content-Type: application/json' \
12831283
-H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \
12841284
--data-binary '{
12851285
"eventType": "click",
12861286
"eventName": "Search Result Clicked",
12871287
"indexUid": "products",
1288+
"userId": "SEARCH_USER_ID",
1289+
"queryUid": "019a01b7-a1c2-7782-a410-bb1274c81393",
12881290
"objectId": "0",
1291+
"objectName": "DOCUMENT_DESCRIPTION",
12891292
"position": 0
12901293
}'
12911294
analytics_event_conversion_1: |-
12921295
curl \
1293-
-X POST 'https://edge.meilisearch.com/events' \
1296+
-X POST 'https://PROJECT_URL/events' \
12941297
-H 'Content-Type: application/json' \
12951298
-H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY'
12961299
--data-binary '{
12971300
"eventType": "conversion",
12981301
"eventName": "Product Added To Cart",
12991302
"indexUid": "products",
1303+
"userId": "SEARCH_USER_ID",
13001304
"objectId": "0",
1305+
"objectName": "DOCUMENT_DESCRIPTION",
13011306
"position": 0
13021307
}'
13031308
analytics_event_bind_search_1: |-
@@ -1309,12 +1314,25 @@ analytics_event_bind_search_1: |-
13091314
--data-binary '{}'
13101315
analytics_event_bind_event_1: |-
13111316
curl \
1312-
-X POST 'https://edge.meilisearch.com/events' \
1317+
-X POST 'https://PROJECT_URL/events' \
1318+
-H 'Content-Type: application/json' \
1319+
-H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \
1320+
-H 'X-MS-USER-ID: SEARCH_USER_ID' \
1321+
--data-binary '{
1322+
"eventType": "click",
1323+
"eventName": "Search Result Clicked",
1324+
"indexUid": "products",
1325+
"objectId": "0",
1326+
"position": 0
1327+
}'
1328+
analytics_event_bind_event_2: |-
1329+
curl \
1330+
-X POST 'https://PROJECT_URL/events' \
13131331
-H 'Content-Type: application/json' \
13141332
-H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \
1315-
-H 'X-MS-USER-ID: MEILISEARCH_USER_ID' \
13161333
--data-binary '{
13171334
"eventType": "click",
1335+
"userId": "SEARCH_USER_ID",
13181336
"eventName": "Search Result Clicked",
13191337
"indexUid": "products",
13201338
"objectId": "0",

‎docs.json‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -206,11 +206,11 @@
206206
{
207207
"group": "Analytics",
208208
"pages": [
209-
"learn/analytics/configure_analytics",
210-
"learn/analytics/configure_monitoring",
209+
"learn/analytics/configure_analytics_events",
211210
"learn/analytics/bind_events_user",
212-
"learn/analytics/deactivate_analytics_monitoring",
213-
"learn/analytics/events_endpoint"
211+
"learn/analytics/migrate_analytics_monitoring",
212+
"learn/analytics/events_endpoint",
213+
"learn/analytics/analytics_metrics_reference"
214214
]
215215
},
216216
{
@@ -1006,6 +1006,10 @@
10061006
{
10071007
"source": "/guides/back_end/laravel_scout",
10081008
"destination": "/guides/laravel_scout"
1009+
},
1010+
{
1011+
"source": "/learn/analytics/deactivate_analytics_monitoring",
1012+
"destination": "/learn/analytics/migrate_analytics_monitoring"
10091013
}
10101014
]
10111015
}

‎learn/analytics/analytics_metrics_reference.mdx‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: Analytics metrics reference
3+
description: This reference describes the metrics you can find in the Meilisearch Cloud analytics interface.
4+
---
5+
6+
## Total searches
7+
8+
Total number of searches made during the specified period. Multi-search and federated search requests count as a single search.
9+
10+
## Total users
11+
12+
Total number of users who performed a search in the specified period.
13+
14+
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.
15+
16+
## No result rate
17+
18+
Percentage of searches that did not return any results.
19+
20+
## Click-through rate
21+
22+
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.
23+
24+
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.
25+
26+
## Average click position
27+
28+
The average list position of clicked search results. A lower number means users have clicked on the first search results and indicates good relevancy.
29+
30+
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.
31+
32+
## Conversion
33+
34+
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.
35+
36+
You must explicitly [configure your application to send conversion](/learn/analytics/configure_analytics_events) events when conditions are met.
37+
38+
<Note>
39+
It is not possible to associate multiple `conversion` events with the same query.
40+
</Note>
41+
42+
## Search requests
43+
44+
Total number of search requests within the specified time period.
45+
46+
## Search latency
47+
48+
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.
49+
50+
## Most searched queries
51+
52+
Most common query terms users have used while searching.
53+
54+
## Searches without results
55+
56+
Most common query terms that did not return any search results.
57+
58+
## Countries with most searches
59+
60+
List of countries that generate the largest amount of search requests.

‎learn/analytics/bind_events_user.mdx‎

Lines changed: 28 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,29 +7,46 @@ description: This guide shows you how to manually differentiate users across sea
77
import CodeSamplesAnalyticsEventBindSearch1 from '/snippets/samples/code_samples_analytics_event_bind_search_1.mdx';
88
import CodeSamplesAnalyticsEventBindEvent1 from '/snippets/samples/code_samples_analytics_event_bind_event_1.mdx';
99

10-
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.
11-
12-
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.
10+
<Note>
11+
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.
12+
</Note>
1313

1414
## Requirements
1515

16-
- A Meilisearch Cloud project with analytics and monitoring enabled
17-
- A working pipeline for submitting analytics events
16+
- A Meilisearch Cloud project
17+
- A method for identifying users
18+
- A pipeline for submitting analytics events
1819

19-
## Add `X-MS-USER-ID` to your search query
20+
## Assign user IDs to search requests
2021

21-
Include the `X-MS-USER-ID` header in your search requests:
22+
You can assign user IDs to search requests by including an `X-MS-USER-ID` header with your query:
2223

2324
<CodeSamplesAnalyticsEventBindSearch1 />
2425

25-
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.
26+
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.
27+
28+
<Note>
29+
Assigning user IDs to search requests is optional. If a Meilisearch Cloud search request does not have an ID, Meilisearch will automatically generate one.
30+
</Note>
2631

27-
## Add `X-MS-USER-ID` to the analytics event
32+
## Assign user IDs to analytics events
2833

29-
Next, submit your analytics event to the analytics endpoint. Send the same header and value in your API call:
34+
You can assign a user ID to analytics `/events` in two ways: HTTP headers or including it in the event payload.
35+
36+
If using HTTP headers, include an `X-MS-USER-ID` header with your query:
3037

3138
<CodeSamplesAnalyticsEventBindEvent1 />
3239

40+
If you prefer to the event in your payload, include a `userId` field with your request:
41+
42+
<CodeSamplesAnalyticsEventBindEvent2 />
43+
44+
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.
45+
46+
<Warning>
47+
It is mandatory to specify a user ID when sending analytics events.
48+
</Warning>
49+
3350
## Conclusion
3451

35-
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.
52+
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.mdx‎

Lines changed: 0 additions & 71 deletions
This file was deleted.

‎learn/analytics/configure_analytics_events.mdx‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: Configure Meilisearch Cloud analytics events
3+
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.
4+
---
5+
6+
import CodeSamplesAnalyticsEventConversion1 from '/snippets/samples/code_samples_analytics_event_conversion_1.mdx';
7+
import CodeSamplesAnalyticsEventClick1 from '/snippets/samples/code_samples_analytics_event_click_1.mdx';
8+
9+
<Note>
10+
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.
11+
</Note>
12+
13+
## Requirements
14+
15+
You must have a [Meilisearch Cloud](https://meilisearch.com/cloud) account to access search analytics.
16+
17+
## Configure click-through rate and average click position
18+
19+
To track click-through rate and average click position, Meilisearch Cloud needs to know when users click on search results.
20+
21+
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:
22+
23+
<CodeSamplesAnalyticsEventClick1 />
24+
25+
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.
26+
27+
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).
28+
29+
For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint).
30+
31+
## Configure conversion rate
32+
33+
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.
34+
35+
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:
36+
37+
<CodeSamplesAnalyticsEventConversion1 />
38+
39+
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.
40+
41+
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.
42+
43+
<Note>
44+
It is not possible to associate multiple `conversion` events with the same query.
45+
</Note>
46+
47+
For more information, consult the [analytics events endpoint reference](/learn/analytics/events_endpoint).

‎learn/analytics/configure_monitoring.mdx‎

Lines changed: 0 additions & 40 deletions
This file was deleted.

0 commit comments

Comments
 (0)