跳轉至

設定 Google Analytics

要在 Zensical 中加入 Google Analytics 4 很簡單，可以使用底下兩種方式的其中一種即可。

從 zensical.toml 設定檔插入

只要在 zensical.toml 中加入底下設定即可。

[project.extra.analytics]
provider = "google"
property = "G-XXXXXXXXXX"

這是官方建議的做法，也跟本專案實際使用的方式相同。

手動加入追蹤程式碼

除了 的方式之外，也可以手動將底下程式碼加到 overrides/main.html 中！

{% extends "base.html" %}

{% block extrahead %}
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'G-XXXXXXXXXX');
</script>
{% endblock %}

記得把 G-XXXXXXXXXX 換成你的 GA4 評估 ID。

搜尋追蹤

若要追蹤站內搜尋，到 Google Analytics 後台的資料串流 → 增強型評估，確認 網站搜尋 已開啟。

「這一頁對您有幫助嗎？」評分元件

可以在每頁底部加上簡單的意見回饋元件，讓讀者立即評價這頁是否有幫助：

[project.extra.analytics]
provider = "google"
property = "G-XXXXXXXXXX"

[project.extra.analytics.feedback]
title = "這一頁對您有幫助嗎？"

[[project.extra.analytics.feedback.ratings]]
icon = "material/emoticon-happy-outline"
name = "這一頁很有幫助"
data = 1
note = "感謝您的回饋！"

[[project.extra.analytics.feedback.ratings]]
icon = "material/emoticon-sad-outline"
name = "這一頁還可以更好"
data = 0
note = """
  感謝您的回饋！請透過
  <a href="https://github.com/your-repo/issues/new/?title=[Feedback]+{title}+-+{url}" target="_blank" rel="noopener">意見表單</a>
  告訴我們如何改進這一頁。
"""
屬性 說明
title、ratings 兩者都必填。評分的數量不限，例如可以做 1～5 顆星
icon 評分圖示，必須是內建圖示，否則建置會失敗。常見組合：material/emoticon-happy-outline + emoticon-sad-outline、material/thumb-up-outline + thumb-down-outline、material/heart + heart-broken
name 滑鼠移上去或鍵盤聚焦時顯示的說明
data 隨自訂事件傳送到 Google Analytics 的值（必須是整數）
note 讀者送出評分後顯示的訊息，可含 HTML。可用 {url}（頁面網址）與 {title}（頁面標題）預先填好表單，例如上面連到 GitHub 的「新增 issue」表單

與 Cookie 同意整合

這個元件會把資料送到第三方服務，所以已經和 Cookie 同意整合：讀者如果沒有接受 analytics Cookie，就不會顯示評分元件。

某一頁不想顯示，用 front matter 隱藏：

---
hide:
  - feedback
---

在 Google Analytics 查看評分

  1. 進入 Google Analytics → 管理 → 自訂定義，切換到「自訂指標」，建立指標：名稱 Page helpful、說明 Was this page helpful?、事件參數 data、測量單位 Standard。
  2. 到「探索」建立新的空白探索：維度加入「事件名稱」與「網頁位置」；指標加入「事件計數」與「Page helpful」；列放「網頁位置」；值放兩個指標；篩選條件為「事件名稱 完全符合 feedback」。

報表大約需要 24 小時以上才會開始顯示資料。

使用其他分析服務

想串接其他以 JavaScript 追蹤的分析服務，在 overrides/ 建立 partials/integrations/analytics/custom.html（檔名就是 provider 的名稱），並在設定使用：

[project.extra.analytics]
provider = "custom"
property = "foobar"
overrides/partials/integrations/analytics/custom.html
<script>
  /* 在這裡加入自訂的分析整合 */
  var property = "{{ config.extra.analytics.property }}"

  document.addEventListener("DOMContentLoaded", function() {
    /* 使用 instant navigation 時，location$ 會在每次換頁時送出目前網址 */
    location$.subscribe(function(url) {
      /* 在這裡加入自訂的頁面事件追蹤 */
    })
  })
</script>

analytics 底下可以放任意的鍵值，方便在多個專案共用同一個整合。

自訂評分元件的處理，只要用 JavaScript 處理使用者互動產生的事件：

docs/js/feedback.js
document$.subscribe(function() {
  var feedback = document.forms.feedback
  if (typeof feedback === "undefined") return

  feedback.hidden = false                       // 預設是隱藏的，要先顯示
  feedback.addEventListener("submit", function(ev) {
    ev.preventDefault()

    var page = document.location.pathname       // 取得頁面
    var data = ev.submitter.getAttribute("data-md-value")
    console.log(page, data)                     // 換成送到分析服務的程式碼

    feedback.firstElementChild.disabled = true  // 送出後停用表單
    var note = feedback.querySelector(
      ".md-feedback__note [data-md-value='" + data + "']"
    )
    if (note) note.hidden = false               // 顯示對應的訊息
  })
})

官方正在改版分析整合

Zensical 的分析整合承襲自 Material for MkDocs，官方正在重新設計，讓它更貼近 Zensical 並提供更多客製化選項。

參考資料