TerminalSkills/skills

Umami

概述

Umami 是一個注重隱私的網頁分析平台 — 它在不使用 Cookie 或收集個人資料的情況下追蹤頁面瀏覽量、訪客和自訂事件。預設符合 GDPR/CCPA 規範（無需同意橫幅）。可在您自己的基礎架構上自架部署，或使用 Umami Cloud。提供簡潔的儀表板、即時統計資料以及用於程式化存取的 API。這是最受歡迎的開源 Google Analytics 替代方案。

使用時機

• 需要網站分析但無需 Cookie 同意橫幅
• 必須符合 GDPR/CCPA 規範
• 不想將分析資料交給 Google
• 想在自己的基礎架構上自架分析服務
• 喜歡簡單、乾淨的分析功能，不想用 GA4 的複雜性
• 需要透過 API 存取分析資料以建立儀表板或報表

說明

自架設定

# Docker Compose
git clone https://github.com/umami-software/umami.git
cd umami
docker compose up -d

# 或者一鍵部署到 Vercel/Netlify/Railway
# 請參閱：https://umami.is/docs/install

加入追蹤腳本

<!-- 加入到您網站的 <head> 中 -->
<script
  defer
  src="https://analytics.mysite.com/script.js"
  data-website-id="your-website-id"
></script>

// Next.js — app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          defer
          src="https://analytics.mysite.com/script.js"
          data-website-id="your-website-id"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

自訂事件追蹤

// 追蹤自訂事件
// Umami 會暴露一個全域的 `umami` 物件

// 追蹤按鈕點擊
document.getElementById("signup-btn")?.addEventListener("click", () => {
  umami.track("signup-click", { plan: "pro", source: "header" });
});

// 追蹤表單提交
function handleSubmit(formData: FormData) {
  umami.track("form-submit", {
    form: "contact",
    subject: formData.get("subject"),
  });
}

// 在 React 中追蹤
function PricingCard({ plan }: { plan: string }) {
  return (
    <button
      onClick={() => umami.track("pricing-click", { plan })}
      data-umami-event="pricing-click"
      data-umami-event-plan={plan}
    >
      Choose {plan}
    </button>
  );
}

API 存取

// api/analytics.ts — 程式化擷取分析資料
const UMAMI_URL = "https://analytics.mysite.com";
const UMAMI_TOKEN = process.env.UMAMI_API_TOKEN;

async function getPageViews(websiteId: string, days = 30) {
  const endDate = Date.now();
  const startDate = endDate - days * 24 * 60 * 60 * 1000;

  const res = await fetch(
    `${UMAMI_URL}/api/websites/${websiteId}/pageviews?startAt=${startDate}&endAt=${endDate}&unit=day`,
    { headers: { Authorization: `Bearer ${UMAMI_TOKEN}` } }
  );
  return res.json();
}

async function getTopPages(websiteId: string) {
  const endDate = Date.now();
  const startDate = endDate - 7 * 24 * 60 * 60 * 1000;

  const res = await fetch(
    `${UMAMI_URL}/api/websites/${websiteId}/metrics?startAt=${startDate}&endAt=${endDate}&type=url`,
    { headers: { Authorization: `Bearer ${UMAMI_TOKEN}` } }
  );
  return res.json();  // [{ x: "/pricing", y: 1234 }, ...]
}

範例

範例 1：為 SaaS 加入隱私友善分析

使用者提示：「在我們的 SaaS 中加入分析功能，不使用 Cookie 或同意橫幅。」

代理將部署 Umami、加入追蹤腳本、設定關鍵動作（註冊、升級、功能使用）的自訂事件，並為內部儀表板建立 API 整合。

範例 2：建立自訂分析儀表板

使用者提示：「將我們的 Umami 資料匯入行銷團隊的自訂儀表板。」

代理將使用 Umami API 取得頁面瀏覽量、熱門頁面、來源和事件，然後在 React 儀表板中顯示。

指南

• 無 Cookie = 無同意橫幅 — 預設符合 GDPR 規範
• data-umami-event 屬性 — 無需 JavaScript 即可追蹤點擊
• 使用 umami.track(name, data) 追蹤自訂事件 — 靈活的事件追蹤
• 自架以獲得完整控制權 — Docker、Vercel、Railway 或任何 Node.js 主機
• 用於程式化存取的 API — 建立自訂儀表板和報表
• 多站台支援 — 一個 Umami 實例可追蹤多個網站
• 即時儀表板 — 立即查看目前活躍訪客
• UTM 追蹤 — 活動歸因自動生效
• 輕量級腳本 — 小於 2KB，不會減慢您的網站速度
• PostgreSQL 或 MySQL — 您可自由選擇後端資料庫