Analytics 集成

通过连接第三方 Analytics 平台来跟踪用户如何与你的文档交互。Mintlify 会将互动事件发送到你已配置的 Analytics 提供商。

Analytics 集成的工作原理

当你将 Analytics 集成添加到文档站点时，Mintlify 会跟踪页面浏览、搜索查询、API 操作台请求和反馈提交等用户交互，并将这些数据发送到你的分析服务提供方。你可以通过在 docs.json 文件中添加 API key 来连接任意数量的已支持 Analytics 提供方。一旦你在配置中添加了这些服务，Analytics 事件就会开始流向相应的提供方，无需任何额外配置。

支持的平台

Adobe Analytics

Amplitude

Clearbit

Fathom

Google Analytics 4

Google 标签管理器

Heap

Hightouch

Hotjar

LogRocket

Microsoft Clarity

Mixpanel

Pirsch

Plausible

PostHog

Segment

设置

将你的 analytics 提供商凭据添加到 docs.json 的 integrations 对象中。只需包含你想要使用的平台即可。

Analytics 集成只需要公共 API key，这些 key 对任何查看你文档站点的人都是可见的。在 analytics 提供商端与这些公共 key 配对的私有 API key 必须严格保密。不要在 docs.json 中包含私有 API key。

docs.json

"integrations": {
    "adobe": {
        "launchUrl": "required"
    },
    "amplitude": {
        "apiKey": "required"
    },
    "clarity": {
        "projectId": "required"
    },
    "clearbit": {
        "publicApiKey": "required"
    },
    "cookies": {
      "key": "required",
      "value": "required"
    },
    "fathom": {
        "siteId": "required"
    },
    "ga4": {
        "measurementId": "required"
    },
    "gtm": {
        "tagId": "required"
    },
    "heap": {
        "appId": "required"
    },
    "hightouch": {
        "apiKey": "required",
        "apiHost": "optional"
    },
    "hotjar": {
        "hjid": "required",
        "hjsv": "required"
    },
    "logrocket": {
        "appId": "required"
    },
    "mixpanel": {
        "projectToken": "required"
    },
    "pirsch": {
        "id": "required"
    },
    "plausible": {
        "domain": "required"
    },
    "posthog": {
        "apiKey": "required",
        "apiHost": "optional"
    },
    "segment": {
      "key": "required"
    },
    "telemetry": {
      "enabled": "boolean"
    }
}

示例配置

docs.json

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

验证你的配置

在部署更新后的 docs.json 后，请验证事件是否已到达你的 analytics 提供商：

部署你的更改。 只有在 docs.json 的更改部署到线上站点后，analytics 事件才会开始上报。本地 mint dev 会话不会发送事件。
触发一个事件。 访问你的线上站点并与其交互。查看页面、执行搜索或发起一次 API 操作台请求，以生成一个跟踪事件。
检查你的提供商的实时视图。 大多数平台会在一分钟内显示传入的事件：
- Google Analytics 4：Reports → Realtime。
- PostHog：Activity → Live events。
- Mixpanel：Events → Live view。
- Amplitude：Data → Live event stream。
禁用广告拦截器。 uBlock Origin 和 Privacy Badger 等浏览器扩展默认会屏蔽许多 analytics 脚本。如果事件未显示，请在禁用扩展的隐身窗口中进行测试。

如果事件仍未到达，请再次确认你为每个提供商使用的是正确的 key 类型（参见设置中的说明），并且你的 docs.json 更改已成功部署。

跟踪事件

所有事件都使用 docs. 前缀。

Event name	Description
`docs.content.view`	当用户查看页面时。仅适用于默认不跟踪页面浏览次数的 Analytics 提供商。
`docs.content.md.view`	当用户查看页面的 Markdown 版本时。
`docs.navitem.click`	当用户点击页眉导航项时。
`docs.navitem.cta_click`	当用户点击某个行动呼吁 (CTA) 时。
`docs.footer.powered_by_mintlify_click`	当用户点击“Powered by Mintlify”链接时。

搜索

Event name	Description
`docs.search.query`	当用户发起搜索查询时。
`docs.search.close`	当用户关闭搜索栏时。
`docs.search.result_click`	当用户点击某个搜索结果时。

代码和 API 操作台

Event name	Description
`docs.code_block.copy`	当用户从代码块中复制代码时。
`docs.code_block.ask_ai`	当用户请求 AI 助手解释代码块时。
`docs.api_playground.request`	当用户在 API 操作台中调用 API 时。

交互组件

Event name	Description
`docs.accordion.open`	用户打开折叠面板。
`docs.accordion.close`	用户关闭折叠面板。
`docs.expandable.open`	用户打开可展开区域。
`docs.expandable.close`	用户关闭可展开区域。

AI 助手和 Agent

Event name	Description
`docs.assistant.enter`	当用户打开 AI 助手时。
`docs.assistant.completed`	当一次对话结束时。
`docs.assistant.source_click`	当用户在对话中点击引用时。
`docs.assistant.suggestion_click`	当用户在对话中点击建议时。
`docs.assistant.ask_ai_on_text_selection`	当用户选择文本并点击“Ask AI”来询问该选区时。
`docs.assistant.shared`	当用户分享一次对话时。
`docs.assistant.thumbs_up`	当用户在助手回复上点击正向反馈按钮时。
`docs.assistant.thumbs_down`	当用户在助手回复上点击负向反馈按钮时。
`docs.assistant.spam_detected`	当助手在用户消息中检测到垃圾信息时。
`docs.autopilot.suggestion.created`	当 Agent 创建文档建议时。
`docs.autopilot.suggestion.no_suggestion`	当 Agent 判定文档不需要更新时。

Event name	Description
`docs.context_menu.copy_page`	当用户将当前页面复制为 Markdown 时。
`docs.context_menu.copy_mcp_link`	当用户复制托管 MCP 服务器链接时。
`docs.context_menu.copy_add_mcp_command`	当用户复制 `npx add-mcp` 命令以安装 MCP 服务器时。
`docs.context_menu.ai_provider_click`	当用户点击某个 AI 提供商，并以当前页面作为上下文创建对话时。
`docs.context_menu.install_mcp_server`	当用户在代码编辑器上安装托管 MCP 服务器时。

快速入门

组织

自定义

创建内容

编写 API 文档

部署

优化