Umami Analytics

Umami 비공식 플러그인(Umami와 무관): EmDash 관리자 화면에서 트래픽, 인기 페이지, 유입 경로, 항목별 조회수를 확인합니다.

플러그인

Umami Analytics

Umami 비공식 플러그인(Umami와 무관): EmDash 관리자 화면에서 트래픽, 인기 페이지, 유입 경로, 항목별 조회수를 확인합니다.

카테고리: analytics
상태: 사용 가능
버전: 0.1.4
가격: 미확인
출처: 공식 플러그인 레지스트리
설치 방식: 레지스트리 샌드박스 플러그인
확인일: 2026-10-21

Claude에서 열기 ChatGPT에서 열기

X에 공유 LinkedIn에 공유 Reddit에 공유

설명

비공식 플러그인입니다. Umami와 제휴 관계가 없으며 Umami의 승인이나 지원을 받지 않습니다.

Umami 수치를 EmDash 관리자 화면 안에서 보여 줍니다. 대시보드에는 사이트 트래픽이, 각 항목 옆에는 해당 항목이 얻은 페이지 조회수가 표시됩니다. Umami Cloud와 3.4.0 이상의 셀프 호스팅 Umami를 지원합니다.

Umami 트래픽 카드. 대시보드에 표시됩니다. 최근 7일간의 방문 수, 페이지 조회수, 참여도를 직전 주와 비교하고, 가장 많이 조회된 5개 페이지와 해당 항목을 보여 줍니다.
Umami Analytics 페이지. 7일, 30일 또는 90일 일별 차트, 이탈률과 방문 시간, 인기 항목, 유입 경로, 국가, 사이트가 붙여 보내는 이벤트 데이터별 페이지 조회수(우선 카테고리별), 그리고 발견한 각 문제의 해결 방법을 알려 주는 설정 점검.
항목별 페이지. 게시된 모든 항목의 7일 및 30일 페이지 조회수를 정렬 가능한 형태로 보여 줍니다. 컬렉션 하나 또는 전체를 대상으로 할 수 있고, 원하면 번역본을 합산할 수 있습니다.
Umami 에디터 패널. 에디터 옆에 각 항목의 7일 및 30일 페이지 조회수를 보여 주며, 사이트가 읽기 이벤트를 보내면 독자가 어디까지 읽었는지도 보여 줍니다.
MCP 도구. 저장된 수치로 답하는 읽기 전용 도구 4개.

플러그인은 읽기만 합니다. Umami나 콘텐츠를 절대 변경하지 않습니다. 데모 데이터로 Umami 웹사이트 없이도 사용해 볼 수 있습니다.

셀프 호스팅 Umami 3.4.0에서 테스트했습니다. Umami Cloud 연결은 Umami가 공개한 API를 따르지만 아직 Cloud 계정에서는 실행해 보지 않았습니다.

Eisbachcode의 EmDash analytics 플러그인을 기반으로 하며 MIT 라이선스입니다.

설치

필요한 것: 플러그인 샌드박스 러너가 있는 EmDash 1.0.1 이상, Umami의 웹사이트(Umami 추적 스크립트가 이미 사이트에 설치되어 있어야 함), 셀프 호스팅 Umami 3.4.0 이상(API 키를 지원하는 첫 셀프 호스팅 릴리스) 또는 Umami Cloud, 그리고 API 키를 암호화하여 저장할 수 있도록 사이트에 설정한 EMDASH_ENCRYPTION_KEY(npx emdash secrets generate로 생성할 수 있음).

레지스트리에서 플러그인을 설치하고 권한을 검토합니다. 콘텐츠 읽기, 스키마 읽기, 모든 공개 호스트에 대한 네트워크 요청입니다. 플러그인은 설정에 입력된 Umami API URL만 요청합니다.
Umami에서 역할이 View only인 사용자를 만듭니다. 이 사용자를 웹사이트가 속한 팀에 팀 역할 View only로 추가합니다. 웹사이트가 팀이 아니라 개인 소유라면 먼저 팀으로 옮기세요.
해당 사용자로 Umami에 로그인하여 Settings > API keys에서 키를 만듭니다.
EmDash에서 Plugins를 열고 이 플러그인의 설정으로 이동합니다. 키를 Umami API key에 붙여 넣습니다.
셀프 호스팅 Umami라면 Umami API URL을 https://your-host/api로 설정합니다. 기본값은 Umami Cloud 주소입니다.
Umami의 웹사이트 설정에 있는 Umami 웹사이트 ID를 입력합니다. 비워 두면 대시보드 카드에 키로 볼 수 있는 웹사이트 목록이 표시되므로 거기서 복사할 수 있습니다. 저장합니다.
Plugins > Umami Analytics를 열고 Check setup을 선택합니다. 수치가 의존하는 모든 항목을 점검하고 문제마다 한 문장으로 알려 줍니다.

첫 동기화는 Keep daily rows for(기본 90일) 범위까지 최신 순으로 거슬러 올라가며 읽습니다. Node에서는 항목이 100개인 사이트의 경우 약 2시간이 걸립니다.

각 컬렉션에는 URL 패턴(콘텐츠 유형 아래)이 필요합니다. 없으면 페이지를 항목과 연결할 수 없습니다. Cloudflare Workers에서는 동기화에 EmDash 배포 가이드의 Cron 트리거가 필요합니다.

셀프 호스팅 Umami는 공개 호스트 이름을 사용해야 합니다. EmDash는 사설 주소를 거부하므로 localhost, LAN 주소, VPN 전용 이름은 사용할 수 없습니다.

MCP 도구를 사용하려면 Plugins에서 이 플러그인의 Agent 접근을 켜세요. 도구가 변경되는 업데이트 후에는 다시 켜야 합니다.

자주 묻는 질문

모든 수치가 0으로 표시되는 이유는 무엇인가요? 대부분의 설정 실수는 오류 없이 0을 표시합니다. Plugins > Umami Analytics를 열고 Check setup을 선택하세요. 발견한 각 문제의 해결 방법을 알려 줍니다.

제 수치가 Umami 대시보드와 다른 이유는 무엇인가요? 날짜는 Time zone 설정을 따릅니다. Umami에서도 웹사이트의 시간대를 사용하지 않으면 자정 무렵의 일별 수치가 달라집니다. /_emdash 아래의 페이지는 제외되며, 합계는 Hostnames to count에 있는 호스트 이름(변경하지 않으면 사이트 URL과 그 www 형태)만 집계합니다.

Umami Cloud에서 작동하나요? Umami가 공개한 API를 따르지만 Cloud 계정에서는 아직 실행해 보지 않았습니다. 확인한 내용을 저장소의 이슈에 알려 주세요.

제 Umami는 로그인 프록시 뒤에 있습니다. 플러그인이 사용하는 8개의 Umami API 엔드포인트는 프록시를 거치지 않고 통과시켜 주세요. README에 목록이 있으며, Umami가 각 엔드포인트에서 API 키를 확인합니다.

요청을 얼마나 보내나요? 동기화 한 번에 Umami로 최대 7개의 요청을 보냅니다. Umami Analytics 페이지를 열면 5개를 보냅니다.

Umami 없이 사용해 볼 수 있나요? 네. Data source를 Demo data로 설정하고 대시보드 카드에서 Refresh를 선택하세요. 실제 항목에 대해 90일치의 가상 트래픽을 생성합니다. 데이터 소스를 전환하면 저장된 모든 수치가 지워지므로 데모 수치가 실제 수치와 섞이지 않습니다.

누가 수치를 볼 수 있나요? 편집자와 관리자는 대시보드 카드, 두 개의 Umami 페이지, MCP 도구를 볼 수 있습니다. 작성자는 자신의 항목에 대한 에디터 패널을 볼 수 있습니다.

카테고리 표는 어디서 오나요? 사이트가 Umami 트래커의 data-before-send 훅으로 페이지 조회에 붙이는 이벤트 데이터에서 옵니다. Views by event data에 최대 3개의 속성 이름을 지정합니다. 이벤트 데이터를 보내지 않는 사이트에서는 표가 표시되지 않습니다.

읽기 완료율은 어떻게 작동하나요? 독자가 항목의 각 깊이에 도달할 때마다 사이트가 사용자 지정 이벤트를 보냅니다. 예를 들어 post와 depth가 있는 post_read입니다. 이에 맞게 4개의 읽기 완료율 설정을 채우세요. 기본값은 비어 있으며 이 경우 기능이 꺼집니다.

어떤 언어를 지원하나요? 영어와 독일어이며, 각 사용자의 관리자 언어를 따릅니다.

보안

보안 문제는 저장소의 보안 권고 양식을 통해 비공개로 신고해 주세요: https://github.com/shanelord01/emdash-umami-analytics/security/advisories/new

Umami API 키로 할 수 있는 일

Umami API 키 자체에는 권한이 없습니다. 키를 만든 사용자가 할 수 있는 일은 무엇이든 할 수 있습니다. 관리자 사용자로 만든 키는 Umami의 모든 웹사이트를 변경하거나 삭제할 수 있으므로, 역할이 View only인 사용자로 만들고 그 사용자를 웹사이트의 팀에 팀 역할 View only로 추가하세요. 이렇게 만든 키는 해당 팀의 웹사이트를 읽을 수만 있고 아무것도 변경할 수 없습니다. 플러그인 자체는 GET 요청만 보냅니다.

네트워크 접근

플러그인은 network:request:unrestricted를 요청합니다. 셀프 호스팅 Umami는 설정에 입력하는 호스트에 있으므로 고정된 호스트 목록으로는 지정할 수 없기 때문입니다. 설정에 입력된 Umami API URL(변경하지 않으면 https://api.umami.is/v1)만 요청하며, 키는 Bearer 토큰으로 보냅니다. 데모 데이터는 요청을 전혀 보내지 않습니다. EmDash는 모든 플러그인에 대해 사설 주소를 거부합니다.

전송되는 것과 저장되는 것

Umami는 API 키, 웹사이트 ID, 집계할 호스트 이름을 받습니다. 콘텐츠는 사이트를 떠나지 않습니다.
키는 암호화된 설정으로 저장됩니다(EMDASH_ENCRYPTION_KEY를 사용하는 AES-GCM). 이 키가 없으면 EmDash는 평문으로 저장하는 대신 저장을 거부합니다. 플러그인은 키를 로그에 기록하지 않습니다.
사이트 데이터베이스에는 일별·경로별 페이지 조회수와 방문 수, 사이트 합계와 일별 참여도, 각 경로와 항목의 대응 및 해당 항목의 조회수와 읽기 완료율, 그리고 동기화 상태와 지난 한 주의 인기 페이지, 유입 경로, 국가가 저장됩니다. Keep daily rows for보다 오래된 일별 행은 삭제됩니다.

누가 무엇을 할 수 있나

대시보드 카드, Analytics 및 항목별 페이지, MCP 도구에는 편집자 역할이 필요합니다. 에디터 패널에는 작성자 역할이 필요하며 해당 사용자가 편집할 수 있는 항목만 표시합니다. 설정을 변경하려면 관리자 역할이 필요합니다.

변경 내역

0.1.4

EmDash 1.2 이상에서는 페이지가 사이드바의 하나의 Umami 폴더(Analytics, Per entry)에 묶입니다. 주소는 바뀌지 않으며, 이전 EmDash에서는 하나씩 나열됩니다.
새 권한은 없으며 MCP 도구도 변경되지 않았습니다.

0.1.3, 2026년 10월 9일

날짜가 이제 사용자의 시간대를 따릅니다. 이전에는 UTC 기준 날짜여서 시드니 오전 10시경 이전의 페이지 조회가 전날로 집계되었습니다. 새 Time zone 설정의 기본값은 Australia/Sydney입니다. Umami의 웹사이트 시간대로 설정하세요.
업데이트 시 저장된 수치가 한 번 지워지고 Umami에서 최신 순으로 다시 읽습니다. 차트와 항목별 조회수는 따라잡는 동안 점차 채워집니다. Node에서는 90일, 항목 100개 기준으로 약 2시간이며, Cloudflare Workers에서는 Cron 트리거의 속도로 진행됩니다. 나중에 이 설정을 변경해도 같은 과정이 수행됩니다.
다른 플러그인으로 오인되지 않도록 Umami 이름을 붙였습니다: Umami Analytics 및 Umami per entry 페이지(주소 동일), Umami 트래픽 카드, Umami 에디터 패널.
레지스트리 페이지에 이 변경 내역을 포함한 탭과 배너가 추가되었습니다.
관리자 화면 수정: “일치하는 페이지 없음” 오류 표시 제거, 대시보드의 인기 페이지가 7일 범위를 포함, 일별 차트에 계열 이름 표시, 에디터 패널에 저장된 기록의 시작일 표시.
새 권한은 없습니다. MCP 도구가 이제 사용자의 시간대 기준으로 일수를 설명하므로 업데이트 후 EmDash가 Agent 접근을 끕니다. Plugins에서 다시 켜세요.

0.1.2, 2026년 10월 1일

합계 옆에 참여도 추가: 이탈률, 평균 방문 시간, 방문당 페이지 수를 직전 기간과 비교하며, site_totals에 새 engagement 필드가 추가되었습니다.
항목별 읽기 완료율(설정 4개, 기본값은 꺼짐)과 이 기능을 켰을 때만 사용되는 새 Umami 엔드포인트 2개. 설치 후 따라잡는 속도도 빨라졌습니다.
업데이트 후 Plugins에서 Agent 접근을 다시 켜세요.

전체 기록: CHANGELOG.md.