-
Notifications
You must be signed in to change notification settings - Fork 223
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
--------- Co-authored-by: Guillaume Mourier <[email protected]>
- Loading branch information
1 parent
1bb6040
commit fef5639
Showing
10 changed files
with
290 additions
and
203 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
--- | ||
title: Bind search analytics events to a user | ||
description: This guide shows you how to manually differentiate users across search analytics using the X-MS-USER-ID HTTP header. | ||
--- | ||
|
||
# Bind search analytics events to a user | ||
|
||
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. | ||
|
||
## Requirements | ||
|
||
- A Meilisearch Cloud project with analytics and monitoring enabled | ||
- A working pipeline for submitting analytics events | ||
|
||
## Add `X-MS-USER-ID` to your search query | ||
|
||
Include the `X-MS-USER-ID` header in your search requests: | ||
|
||
<CodeSamples id="analytics_event_bind_search_1" /> | ||
|
||
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. | ||
|
||
## Add `X-MS-USER-ID` to the analytics event | ||
|
||
Next, submit your analytics event to the analytics endpoint. Send the same header and value in your API call: | ||
|
||
<CodeSamples id="analytics_event_bind_event_1" /> | ||
|
||
## 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,67 @@ | ||
--- | ||
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" /> | ||
|
||
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: | ||
|
||
<CodeSamples id="analytics_event_conversion_1" /> | ||
|
||
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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 user"> | ||
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_search). | ||
</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 |
Oops, something went wrong.