Skip to content

配置站点分析

与网络上提供的任何其他服务一样，了解项目文档的实际使用情况可能是一个重要的成功因素。Material for MkDocs 与Google Analytics进行了本地集成，并提供了可定制的[cookie 同意]和反馈小部件。

配置

Google Analytics

默认值：无

Material for MkDocs 与 Google Analytics 4 和即将停用的 Universal Analytics 集成。根据给定的属性前缀，将以下行添加到mkdocs.yml中：

Google Analytics 4

extra:
analytics:
    provider: google
    property: G-XXXXXXXXXX

Universal Analytics

extra:
analytics:
    provider: google
    property: UA-XXXXXXXX-X
如何测量站点搜索使用情况？

除了页面浏览量和事件之外，可以跟踪站点搜索以更好地了解用户如何使用您的文档以及他们希望找到什么。为了启用站点搜索跟踪，需要执行以下步骤：

Google Analytics 4

  1. 转到Google Analytics的管理设置
  2. 选择相应跟踪代码的属性
  3. 选择数据流选项卡，然后单击相应的URL
  4. 在增强测量部分中，单击齿轮图标
  5. 确保站点搜索已启用

Universal Analytics

  1. 转到Google Analytics的管理设置
  2. 选择相应跟踪代码的属性
  3. 转到视图设置选项卡
  4. 向下滚动并启用站点搜索设置
  5. 将查询参数设置为 q

这个页面有帮助吗？

默认值：无

可以在每个页面底部包含一个简单的反馈小部件，鼓励用户即时提供页面是否有帮助的反馈。将以下行添加到mkdocs.yml中：

extra:
  analytics: # (1)!
    feedback:
      title: 这个页面有帮助吗？
      ratings:
        - icon: material/emoticon-happy-outline
          name: 这个页面有帮助
          data: 1
          note: >-
            感谢您的反馈！
        - icon: material/emoticon-sad-outline
          name: 这个页面可以改进
          data: 0
          note: >- # (2)!
            感谢您的反馈！通过使用我们的<a href="..." target="_blank" rel="noopener">反馈表单</a>来帮助我们改进这个页面。

  1. 这个功能与Google Analytics本地集成，因此也需要提供provider和property。但是，也可以提供[自定义反馈集成]。

  2. 您可以在用户提交反馈后显示任意的 HTML 标签，例如链接到反馈表单。

title和ratings是必需的属性。请注意，允许定义超过两个评级，例如实现 1-5 星级评级。由于反馈小部件向第三方服务发送数据，因此它当然与[cookie 同意]功能1本地集成。

如何可视化收集的反馈评级？

要可视化反馈评级，您需要使用Google Analytics创建一个自定义报告，该报告将快速显示项目文档中评级最差和评级最好的页面。

Google Analytics 4

  1. 转到Google Analytics的仪表板

  2. 在左侧菜单中，转到配置页面，然后选择自定义定义

  3. 单击自定义指标选项卡，然后单击创建自定义指标，输入以下值：

    • 指标名称：页面有帮助
    • 描述：这个页面有帮助吗？
    • 事件参数：data
    • 测量单位：标准

  4. 在左侧菜单中，转到探索页面，创建一个空白探索

  5. 配置报告如下：

    • 维度：添加事件名称和页面位置
    • 指标：添加事件计数和页面有帮助 （在步骤3中创建的自定义指标）
    • 行：页面位置
    • 值：拖放事件计数和页面有帮助
    • 过滤器：为事件名称添加新的过滤器， 精确匹配 / feedback

数据可用性延迟

该报告可能需要24小时或更长时间才能开始显示数据。

Universal Analytics

  1. 转到Google Analytics的仪表板
  2. 打开左侧的自定义面板，转到自定义报告
  3. 创建一个新的自定义报告，设置自定义标题和名称
  4. 将平均值和总事件数添加到度量组
  5. 将事件标签添加到维度钻取
  6. 将事件类别添加到筛选器，并过滤值为feedback

现在，保存报告并收集一些反馈评级后，您将获得一个包含总评级数和每个页面的平均评级的页面列表。这应该有助于您确定需要改进的页面：

反馈报告

每个评级可用以下属性：

icon

默认值：无 · 必需 – 此属性必须指向有效的图标路径，引用主题中的任何图标，否则构建将失败。一些常见的组合：

* :material-emoticon-happy-outline: + :material-emoticon-sad-outline: – `material/emoticon-happy-outline` + `material/emoticon-sad-outline`
* :material-thumb-up-outline: + :material-thumb-down-outline: – `material/thumb-up-outline` + `material/thumb-down-outline`
* :material-heart: + :material-heart-broken: – `material/heart` + `material/heart-broken`

name

默认值：无 · 必需 – 此属性的值在用户交互（即键盘焦点或鼠标悬停）时显示，解释图标背后评级的含义。

data

默认值：无 · 必需 – 此属性的值作为数据值发送到传输给 Google Analytics 的自定义事件2（或任何自定义集成）。

note

默认值：无 · 必需 – 用户选择评级后显示此属性的值。它可以包含任意的 HTML 标签，特别是通过表单要求用户为当前页面提供更详细的反馈非常有用。还可以使用以下占位符来预填充当前页面的 URL 和标题：

  • {url} – 页面 URL
  • {title} – 页面标题
https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url}

在此示例中，当点击链接时，用户将被重定向到存储库的“新问题”表单，其中包含当前文档的路径作为标题的预填充内容，例如：

[Feedback] 设置站点分析 – /setup/setting-up-site-analytics/

替代 GitHub 问题的方法是[Google 表单]。

用法

隐藏反馈小部件

可以使用前置属性hide将文档中的反馈小部件隐藏。在 Markdown 文件的顶部添加以下行：

---
hide:
  - feedback
---
# 文档标题

自定义

自定义站点分析

要集成另一个提供基于 JavaScript 的跟踪解决方案的分析服务提供商，只需按照主题扩展中的指南创建一个新的部分，并在overrides文件夹中创建一个新的部分。部分的名称用于通过mkdocs.yml配置自定义集成：

overrides/partials/integrations/analytics/custom.html

<script>
  /* 在此处添加自定义分析集成，例如 */
  var property = "{{ config.extra.analytics.property }}" // (1)!

  /* 等待页面加载和应用程序挂载 */
  document.addEventListener("DOMContentLoaded", function() {
    location$.subscribe(function(url) {
      /* 在此处添加自定义页面事件跟踪 */ // (2)!
    })
  })
</script>
  1. 作为示例，此变量接收在mkdocs.yml中设置的值，即property的值为"foobar"。
  2. 如果使用即时加载，可以使用location可观察对象来监听导航事件，它始终会发出当前的URL。

mkdocs.yml

extra:
  analytics:
    provider: custom
    property: foobar # (1)!
  1. 您可以添加任意的键值组合来配置自定义集成。如果要在多个存储库之间共享自定义集成，这将特别有用。

自定义站点反馈

自定义反馈小部件集成只需使用一些[额外的 JavaScript]处理用户与反馈小部件交互时生成的事件：

docs/javascripts/feedback.js

var feedback = document.forms.feedback
feedback.addEventListener("submit", function(ev) {
  ev.preventDefault()

  /* 检索页面和反馈值 */
  var page = document.location.pathname
  var data = ev.submitter.getAttribute("data-md-value")

  /* 发送反馈值 */
  console.log(page, data)
})

mkdocs.yml

extra_javascript:
  - javascripts/feedback.js

  1. 如果用户不接受analytics cookie，则不会显示反馈小部件。 ↩

  2. 请注意，对于 Google Analytics，数据值必须是整数。 ↩