Umami：网站分析技能

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}
    >
      选择 {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 — 您可以选择后端数据库