Skip to content

Commit b10266b

Browse files
guimachiavelliguimachiavelli
committed
update reference, bind user id to events guide
1 parent 4a2dd28 commit b10266b

File tree

4 files changed

+71
-57
lines changed

4 files changed

+71
-57
lines changed

‎.code-samples.meilisearch.yaml‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1278,14 +1278,16 @@ 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+
"queryUid": "019a01b7-a1c2-7782-a410-bb1274c81393",
12881289
"objectId": "0",
1290+
"objectName": "DOCUMENT_DESCRIPTION",
12891291
"position": 0
12901292
}'
12911293
analytics_event_conversion_1: |-
@@ -1309,12 +1311,25 @@ analytics_event_bind_search_1: |-
13091311
--data-binary '{}'
13101312
analytics_event_bind_event_1: |-
13111313
curl \
1312-
-X POST 'https://edge.meilisearch.com/events' \
1314+
-X POST 'https://PROJECT_URL/events' \
1315+
-H 'Content-Type: application/json' \
1316+
-H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \
1317+
-H 'X-MS-USER-ID: SEARCH_USER_ID' \
1318+
--data-binary '{
1319+
"eventType": "click",
1320+
"eventName": "Search Result Clicked",
1321+
"indexUid": "products",
1322+
"objectId": "0",
1323+
"position": 0
1324+
}'
1325+
analytics_event_bind_event_2: |-
1326+
curl \
1327+
-X POST 'https://PROJECT_URL/events' \
13131328
-H 'Content-Type: application/json' \
13141329
-H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \
1315-
-H 'X-MS-USER-ID: MEILISEARCH_USER_ID' \
13161330
--data-binary '{
13171331
"eventType": "click",
1332+
"userId": "SEARCH_USER_ID",
13181333
"eventName": "Search Result Clicked",
13191334
"indexUid": "products",
13201335
"objectId": "0",

‎learn/analytics/bind_events_user.mdx‎

Lines changed: 26 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,29 +7,44 @@ 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+
This guide shows you how to to manually link analytics events to specific users.
1311

1412
## Requirements
1513

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

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

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

2322
<CodeSamplesAnalyticsEventBindSearch1 />
2423

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

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

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

3136
<CodeSamplesAnalyticsEventBindEvent1 />
3237

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

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.
50+
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/events_endpoint.mdx‎

Lines changed: 25 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -6,33 +6,26 @@ description: This reference describes /events, the endpoint you should use to su
66

77
import CodeSamplesAnalyticsEventClick1 from '/snippets/samples/code_samples_analytics_event_click_1.mdx';
88

9-
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.
9+
Use `/events` to submit analytics events such as `click` and `conversion` to Meilisearch Cloud.
1010

11-
## The `/events` endpoint
11+
## Send an event
1212

13-
The `/events` endpoint is only available for Meilisearch Cloud projects with analytics and monitoring activated.
13+
<RouteHighlighter method="POST" path="/events" />
1414

15-
### Send an event
15+
Send an analytics event to Meilisearch Cloud.
1616

17-
```http
18-
POST https://edge.meilisearch.com/events
19-
```
20-
21-
Send an analytics event to Meilisearch Cloud. Accepts [`click`](#the-click-event-object) and [`conversion`](#the-conversion-event-object) events.
22-
23-
<Tip>
24-
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).
25-
</Tip>
26-
27-
#### Example
28-
29-
<CodeSamplesAnalyticsEventClick />
30-
31-
##### Response: `201 Created`
32-
33-
### The `click` event object
17+
### Body
3418

35-
The `click` event must deliver an object with the following fields:
19+
| Name | Type | Default value | Description |
20+
| :------------ | :-------------- | :------------ | :------------------------------------------------------------------------------ |
21+
| `eventType` | String | N/A | The event type, such as `click` or `conversion`, required |
22+
| `eventName` | String | N/A | A string describing the event, required |
23+
| `indexUid` | String | N/A | The name of the index of the clicked document, required |
24+
| `queryUid` | String | N/A | The [search query's UID](/reference/api/overview#search-metadata) |
25+
| `objectId` | String | N/A | The clicked document's primary key value |
26+
| `objectName` | String | N/A | A string describing the document |
27+
| `position` | Integer | N/A | An integer indicating the clicked document's position in the search result list |
28+
| `userId` | String | N/A | An arbitrary string identifying the user who performed the action |
3629

3730
```json
3831
{
@@ -44,28 +37,17 @@ The `click` event must deliver an object with the following fields:
4437
}
4538
```
4639

47-
- `eventType`: a string indicating this is a `click` event
48-
- `eventName`: a string describing the event
49-
- `indexUid`: a string indicating the clicked document's index
50-
- `objectId`: a string indicating the clicked document's primary key
51-
- `position`: an integer indicating the clicked document's position in the list of search results
40+
<Note>
41+
You must provide a string identifying your user if you want Meilisearch Cloud to track analytics and click events.
5242

53-
### The `conversion` event object
43+
You may do that in two ways:
5444

55-
The `conversion` event must deliver an object with the following fields:
45+
- Specify the user ID in the payload, using the `userId` field
46+
- Specify the user ID with the `X-MS-USER-ID` header when sending search and other analytics events
47+
</Note>
5648

57-
```json
58-
{
59-
"eventType": "conversion",
60-
"eventName": "Product Added To Cart",
61-
"indexUid": "products",
62-
"objectID": "0",
63-
"position": 0
64-
}
65-
```
49+
#### Example
6650

67-
- `eventType`: indicates this is a `conversion` event
68-
- `eventName`: a string describing the event
69-
- `indexUid`: the document's index
70-
- `objectID`: the document's primary key
71-
- `position`: the document's position in the list of search results
51+
<CodeSamplesAnalyticsEventClick />
52+
53+
##### Response: `201 Created`

‎reference/api/overview.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,8 @@ curl -X POST 'http://localhost:7700/indexes/INDEX_NAME/search' \
129129
-d '{"q": ""}'
130130
```
131131

132+
Meilisearch Cloud includes this header by default.
133+
132134
Responses will include a `metadata` object:
133135

134136
```json

0 commit comments

Comments
 (0)