Skip to content

Improve analytics overview page clarity #2421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ethanpalm merged 6 commits into from
Dec 19, 2025
Merged

Improve analytics overview page clarity #2421

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
24bda0c
Update integrations/analytics/overview.mdx
mintlify[bot] Dec 18, 2025
c5337a9
Update integrations/analytics/overview.mdx
mintlify[bot] Dec 18, 2025
7b8bc3f
Update integrations/analytics/overview.mdx
mintlify[bot] Dec 18, 2025
464b591
Update integrations/analytics/overview.mdx
mintlify[bot] Dec 18, 2025
fcdc461
Update integrations/analytics/overview.mdx
mintlify[bot] Dec 18, 2025
5236e49
copy edit
ethanpalm Dec 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 87 additions & 34 deletions integrations/analytics/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,13 @@ description: "Connect to analytics platforms to track user engagement and docume
keywords: ["third-party analytics", "engagement tracking", "analytics platforms", "usage tracking"]
---

Automatically send data about your documentation engagement to your third party analytics provider.
Track how users interact with your documentation by connecting to third-party analytics platforms. Mintlify sends engagement events to your configured analytics providers.

## All integrations
## How analytic integrations work

When you add analytics integrations to your documentation site, Mintlify tracks user interactions like page views, search queries, API playground requests, and feedback submissions and sends them to your analytics providers. You can connect any number of supported analytics providers by adding your API keys to the `docs.json` file. Analytics events flow to your providers as soon as you add them to your configuration with no further configuration required.

## Supported platforms

<CardGroup cols={2}>
<Card
Expand Down Expand Up @@ -543,13 +547,11 @@ fill="#7166F6"
/>
</CardGroup>

## Enabling analytics

Set your analytics keys in `docs.json`. You can add an unlimited number of analytics integrations for free.
## Setup

The syntax for `docs.json` is below. You only need to include entries for the platforms you want to connect.
Add your analytics provider credentials to the `integrations` object in `docs.json`. Only include the platforms you want to use.

```json Analytics options in docs.json
```json docs.json
"integrations": {
"amplitude": {
"apiKey": "required"
Expand Down Expand Up @@ -606,34 +608,85 @@ The syntax for `docs.json` is below. You only need to include entries for the pl
}
```

## Analytics events
### Example configuration

```json docs.json
{
"integrations": {
"ga4": {
"measurementId": "G-XXXXXXXXXX"
},
"posthog": {
"apiKey": "phc_xxxxxxxxxxxxx",
"apiHost": "https://app.posthog.com"
},
"mixpanel": {
"projectToken": "xxxxxxxxxxxxx"
}
}
}
```

## Tracked events

All tracked events use the `docs.` prefix.

### Navigation and page views

| Event name | Description |
| :-------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| `docs.content.view` | User views a page. Only sent to providers that don't track page views by default. |
| `docs.navitem.click` | User clicks a header navigation item. |
| `docs.navitem.cta_click` | User clicks a call to action button. |
| `docs.footer.powered_by_mintlify_click` | User clicks the "Powered by Mintlify" link. |

### Search

| Event name | Description |
| :-------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| `docs.search.close` | User closes the search bar. |
| `docs.search.result_click` | User clicks a search result. |

### Code and API playground

| Event name | Description |
| :-------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| `docs.code_block.copy` | User copies code from a code block. |
| `docs.code_block.ask_ai` | User asks the assistant to explain a code block. |
| `docs.api_playground.request` | User makes an API request in the API playground. |

### Interactive components

| Event name | Description |
| :-------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| `docs.accordion.open` | User opens an accordion. |
| `docs.accordion.close` | User closes an accordion. |
| `docs.expandable.open` | User opens an expandable. |
| `docs.expandable.close` | User closes an expandable. |

### Feedback

| Event name | Description |
| :-------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| `docs.feedback.thumbs_up` | User clicks the positive feedback button. |
| `docs.feedback.thumbs_down` | User clicks the negative feedback button. |

### AI assistant

| Event name | Description |
| :-------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| `docs.assistant.enter` | User opens the AI assistant. |
| `docs.assistant.completed` | Chat session completes. |
| `docs.assistant.source_click` | User clicks a citation in a chat response. |
| `docs.assistant.suggestion_click` | User clicks a suggested question. |
| `docs.assistant.ask_ai_on_text_selection` | User selects text and clicks "Ask AI." |
| `docs.assistant.shared` | User shares a chat conversation. |

We send the following events to your analytics provider. All events use the `docs.` prefix.
### Context menu

| Event name | Description |
| :-------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| `docs.accordion.close` | When a user closes an accordion. |
| `docs.accordion.open` | When a user opens an accordion. |
| `docs.api_playground.request` | When a user calls an API in the API playground. |
| `docs.code_block.copy` | When a user copies code from a code block. |
| `docs.code_block.ask_ai` | When a user asks the assistant to explain a code block. |
| `docs.content.view` | When a user views a page. Only available for analytics providers that do not track page views by default. |
| `docs.feedback.thumbs_up` | When a user clicks the positive feedback button. |
| `docs.feedback.thumbs_down` | When a user clicks the negative feedback button. |
| `docs.navitem.cta_click` | When a user clicks a call to action. |
| `docs.expandable.close` | When a user closes an expandable. |
| `docs.expandable.open` | When a user opens an expandable. |
| `docs.navitem.click` | When a user clicks a header navigation item. |
| `docs.footer.powered_by_mintlify_click` | When a user clicks the "Powered by Mintlify" link. |
| `docs.assistant.source_click` | When a user clicks a citation in a chat. |
| `docs.assistant.suggestion_click` | When a user clicks a suggestion in a chat. |
| `docs.assistant.completed` | When a chat session is completed. |
| `docs.assistant.enter` | When a user initiates a chat. |
| `docs.assistant.ask_ai_on_text_selection` | When a user selects text and clicks "Ask AI" to ask about the selection. |
| `docs.assistant.shared` | When a user shares a chat conversation. |
| `docs.search.close` | When a user closes the search bar. |
| `docs.search.result_click` | When a user clicks a search result. |
| `docs.context_menu.copy_page` | When a user copies the current page as markdown. |
| `docs.context_menu.copy_mcp_link` | When a user copies the hosted MCP server link. |
| `docs.context_menu.ai_provider_click` | When a user clicks an AI provider and create a conversation with current page as context. |
| `docs.context_menu.install_mcp_server` | When a user installs the hosted MCP server on code editors. |
| `docs.context_menu.copy_page` | User copies the current page as markdown. |
| `docs.context_menu.copy_mcp_link` | User copies the hosted MCP server link. |
| `docs.context_menu.ai_provider_click` | User clicks an AI provider to create a conversation with the current page as context. |
| `docs.context_menu.install_mcp_server` | User installs the hosted MCP server on code editors. |