정적 페이지용 힛카운트 "힛터"

정적 웹사이트나 블로그를 운영하다 보면 방문자 수를 측정하고 싶은 욕구가 생긴다.
하지만 대부분의 방문자 카운터는 복잡하거나 서버가 필요하거나 유료인 경우가 많아 불편함이 있었다.
그래서 Cloudflare Workers를 이용한 초간단 방문자 카운터 "힛터"를 개발하게 되었다.

핵심 기능

전체 방문수와 유니크 방문자 수 측정
특정 페이지별 방문 통계
일별 방문 통계
JSON 또는 JSONP 형식으로 응답 지원
쿠키 기반 방문자 식별

사용 방법

1. 기본 사용법 (Fetch API)

가장 권장하는 방법은 Fetch API를 사용하는 것이다. 방문자 수를 가져오면서 동시에 조회수도 증가시킨다.

// 방문자 수 표시할 HTML 요소
const counterElement = document.getElementById('visitor-counter');

// 방문자 수 가져오기
async function getVisitorCount() {
  try {
    const response = await fetch('https://hitter.http-po.st/');
    const data = await response.json();
    
    // 방문자 수 표시
    counterElement.innerHTML = `
      총 방문수: ${data.totalPageHits}<br>
      오늘 방문수: ${data.todayPageHits}
    `;
  } catch (error) {
    console.error('방문자 수 가져오기 실패:', error);
  }
}

// 페이지 로드 시 실행
getVisitorCount();

2. 커스텀 URL 지정

특정 URL에 대한 방문자 수를 기록하고 싶다면 다음과 같이 URL 파라미터를 추가한다.

fetch('https://hitter.http-po.st/?url=https://example.com/page')
  .then(response => response.json())
  .then(data => {
    console.log('총 방문수:', data.totalPageHits);
  });

3. 호스트명과 경로 개별 지정

호스트명과 경로를 개별적으로 지정할 수도 있다.

fetch('https://hitter.http-po.st/?hostname=example.com&pathname=/page')
  .then(response => response.json())
  .then(data => {
    console.log('총 방문수:', data.totalPageHits);
  });

4. JSONP로 데이터 가져오기 (대안)

CORS 제한이 있는 환경에서는 JSONP 방식으로 데이터를 가져올 수 있다.

<div id="hitCounter">방문자 수 로딩 중...</div>
<script>
function updateHitCount(data) {
  document.getElementById('hitCounter').innerHTML = `
    총 방문수: ${data.totalPageHits}<br>
    오늘 방문수: ${data.todayPageHits}
  `;
}
</script>
<script src="https://hitter.http-po.st/jsonp?callback=updateHitCount"></script>

응답 데이터 형식

힛터는 다음과 같은 JSON 형식으로 데이터를 반환한다.

{
  "totalHits": 1000,           // 사이트 전체 방문수
  "totalUniqueHits": 500,      // 사이트 전체 유니크 방문자 수
  "todayHits": 50,             // 오늘 사이트 전체 방문수
  "todayUniqueHits": 30,       // 오늘 사이트 전체 유니크 방문자 수
  "totalPageHits": 200,        // 현재 페이지 총 방문수
  "totalPageUniqueHits": 100,  // 현재 페이지 유니크 방문자 수
  "todayPageHits": 20,         // 오늘 현재 페이지 방문수
  "todayPageUniqueHits": 15    // 오늘 현재 페이지 유니크 방문자 수
}

오픈소스

힛터는 오픈소스 프로젝트로, 누구나 자유롭게 사용하고 기여할 수 있다.

깃허브 저장소: https://github.com/mack-erel/hitter.http-po.st
기술 스택: Cloudflare Workers, Cloudflare D1, TypeScript

프로젝트에 관심이 있다면 저장소를 방문하여 코드를 살펴보고, 이슈를 제기하거나 PR을 보내주면 환영한다. 더 나은 기능이나 개선 사항이 있다면 언제든지 기여해달라.

마무리

누구나 쉽게 사용할 수 있는 간단한 방문자 카운터를 개발했다.
정적 사이트에 방문자 수 표시가 필요하다면 한번 사용해 보라.
코드는 GitHub에서 확인할 수 있으며, 기능 관련 문의는 언제든 환영한다!