Umami
개요
Umami는 개인정보 보호에 중점을 둔 웹 분석 플랫폼입니다. 쿠키나 개인 데이터 수집 없이 페이지 뷰, 방문자 및 사용자 정의 이벤트를 추적합니다. 기본적으로 GDPR/CCPA를 준수하므로 동의 배너가 필요하지 않습니다. 자체 인프라에 직접 호스팅하거나 Umami Cloud를 사용할 수 있습니다. 깔끔한 대시보드, 실시간 통계 및 프로그래밍 방식 액세스를 위한 API를 제공합니다. 오픈소스 Google Analytics 대안 1위입니다.
사용 시기
- 쿠키 동의 배너 없이 웹사이트 분석이 필요한 경우
- 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에 분석을 추가해주세요."
에이전트는 Umami를 배포하고, 추적 스크립트를 추가하며, 주요 작업(가입, 업그레이드, 기능 사용)에 대한 사용자 정의 이벤트를 설정하고, 내부 대시보드를 위한 API 통합을 생성합니다.
예시 2: 사용자 정의 분석 대시보드 구축하기
사용자 프롬프트: "마케팅 팀을 위해 Umami 데이터를 사용자 정의 대시보드로 가져와주세요."
에이전트는 Umami API를 사용하여 페이지 뷰, 인기 페이지, 리퍼러(referrers) 및 이벤트를 가져온 후 React 대시보드에 표시합니다.
지침
- 쿠키 없음 = 동의 배너 불필요 — 기본적으로 GDPR 준수
data-umami-event속성 — JavaScript 없이 클릭 추적 가능- 사용자 정의 이벤트:
umami.track(name, data)— 유연한 이벤트 추적 - 완전한 제어를 위한 자체 호스팅 — Docker, Vercel, Railway 또는 모든 Node.js 호스트
- 프로그래밍 방식 액세스를 위한 API — 사용자 정의 대시보드 및 리포트 구축
- 다중 사이트 지원 — 하나의 Umami 인스턴스로 여러 웹사이트 추적
- 실시간 대시보드 — 현재 활성 방문자 확인
- UTM 추적 — 캠페인 기여도 분석 자동 작동
- 경량 스크립트 — 2KB 미만, 사이트 속도 저하 없음
- PostgreSQL 또는 MySQL — 백엔드 데이터베이스 선택 가능