EasyAPI
分析工具設定指南

分析工具設定指南

了解如何在 EasyAPI 中整合 Google Analytics 4 與 Umami Analytics

概述

EasyAPI 支援與熱門的分析平台整合，協助你追蹤使用者行為和網站效能：

  • Google Analytics 4 (GA4)：Google 分析平台的最新版本，適合需要完整使用者行為分析與轉換追蹤的情境。
  • Umami Analytics：注重隱私的開源分析工具，輕量部署、無 Cookie 追蹤，適合自建或合規要求較高的環境。

兩種分析工具可以同時啟用，互不衝突。

功能特色

  • 零程式碼整合 — 僅透過環境變數設定
  • 自動將指令碼注入 Web 介面
  • 支援 Docker Compose 與獨立部署
  • 注重隱私的實作方式
  • 無需修改前端程式碼

Google Analytics 4 設定

1. 取得你的評估 ID

  1. 前往 Google Analytics
  2. 建立新的資源或選擇現有資源
  3. 進入 管理 → 資料串流
  4. 建立或選擇一個網站資料串流
  5. 複製你的 評估 ID（格式：G-XXXXXXXXXX）

2. 設定環境變數

使用 Docker Compose：編輯 docker-compose.yml，在 environment 中新增：

environment:
  - GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX  # 替換為你的實際評估 ID

獨立部署：新增到 .env 檔案或設定為環境變數：

export GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

使用 Docker Run：

docker run -d \
  -e GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX \
  ...其他選項... \
  easyapi/easyapi:latest

3. 重新啟動應用程式

# Docker Compose
docker-compose down && docker-compose up -d

# 獨立部署
# 直接重新啟動你的 EasyAPI 應用程式

Umami Analytics 設定

1. 取得 Umami 憑證

選項 A：使用 Umami Cloud

  1. 在 Umami Cloud 註冊
  2. 新增一個網站
  3. 複製你的 網站 ID（UUID 格式）

選項 B：自架 Umami

  1. 部署你自己的 Umami 實例
  2. 在儀表板中建立網站
  3. 複製你的 網站 ID 和 指令碼 URL

2. 設定環境變數

使用 Docker Compose：

environment:
  - UMAMI_WEBSITE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  # 選填：僅自架實例需要
  - UMAMI_SCRIPT_URL=https://your-umami-domain.com/script.js

獨立部署：

export UMAMI_WEBSITE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export UMAMI_SCRIPT_URL=https://your-umami-domain.com/script.js  # 選填

注意：如果使用 Umami Cloud，不需要設定 UMAMI_SCRIPT_URL，預設使用官方指令碼位址。

3. 重新啟動應用程式

與 Google Analytics 相同 — 重新啟動 EasyAPI 應用程式以套用變更。

同時使用兩種分析工具

你可以同時啟用 Google Analytics 和 Umami：

environment:
  - GOOGLE_ANALYTICS_ID=G-ABC123XYZ
  - UMAMI_WEBSITE_ID=a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6
  - UMAMI_SCRIPT_URL=https://analytics.umami.is/script.js

驗證

重新啟動應用程式後，開啟瀏覽器開發者工具（F12）→ 網路，尋找以下請求：

  • Google Analytics：https://www.googletagmanager.com/gtag/js
  • Umami：你設定的指令碼 URL

你也可以檢視頁面原始碼，在 <head> 區段尋找注入的指令碼。

疑難排解

分析工具無法運作？

  • 確認環境變數設定正確
  • 變更變數後重新啟動應用程式
  • 檢查瀏覽器主控台錯誤
  • 確保評估 ID / 網站 ID 格式正確
  • 檢查廣告攔截器是否造成干擾

Docker 使用者：

docker exec <container-name> env | grep -E "GOOGLE_ANALYTICS|UMAMI"

隱私考量

  • Google Analytics 依據 Google 隱私權政策收集使用者資料
  • Umami 注重隱私，不收集個人資料
  • 如果使用分析工具，請考慮在網站上新增隱私權政策
  • 兩種工具在正確設定時都符合 GDPR 要求

環境變數參考

變數必填預設值說明
GOOGLE_ANALYTICS_ID否-Google Analytics 4 評估 ID（格式：G-XXXXXXXXXX）
UMAMI_WEBSITE_ID否-Umami 網站 ID（UUID 格式）
UMAMI_SCRIPT_URL否https://analytics.umami.is/script.jsUmami 指令碼 URL（自架實例需自訂）