PostHog Next.js 설치부터 첫 이벤트 추적까지: 인디 메이커용 30분 셋업 가이드

1. 먼저 무엇을 추적할지 정한다

분석 도구를 붙일 때 가장 흔한 실수는 “일단 다 보자”로 시작하는 것입니다. 1인 메이커에게 필요한 첫 분석은 보통 복잡한 리포트가 아니라, 사용자가 핵심 행동까지 도착하는지 확인하는 흐름입니다.

처음에는 아래 3가지만 정해도 충분합니다.

이름은 나중에 봐도 이해되게 cta_clicked, signup_started, project_created처럼 동사 중심으로 둡니다. 이벤트 이름을 자주 바꾸면 비교가 어려워지므로, 처음부터 짧은 규칙을 정해두는 편이 좋습니다.

2. Next.js에 PostHog 붙이기

공식 Next.js 가이드는 posthog-js를 설치하고 instrumentation-client.ts에서 초기화하는 흐름을 안내합니다. 먼저 패키지를 추가합니다.

npm install --save posthog-js

.env.local에는 클라이언트에서 읽을 수 있도록 NEXT_PUBLIC_ 접두사를 붙입니다.

NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN=ph_project_token
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

그리고 프로젝트 루트에 instrumentation-client.ts를 만듭니다.

import posthog from 'posthog-js'

if (typeof window !== 'undefined' && process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN) {
  posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN, {
    api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
    defaults: '2026-05-30',
  })
}

이 단계까지 끝나면 기본 페이지뷰가 들어오는지 PostHog의 이벤트 화면에서 확인합니다. 로컬 개발 중 데이터가 섞이는 것이 싫다면 localhost에서는 초기화를 건너뛰는 조건을 추가해도 됩니다.

3. 첫 이벤트는 버튼 하나로 시작한다

커스텀 이벤트는 사용자가 “의미 있는 행동”을 했을 때만 보냅니다. 예를 들어 랜딩페이지의 주요 버튼이라면 다음처럼 시작할 수 있습니다.

'use client'

import posthog from 'posthog-js'

export function StartButton() {
  return (
    <button
      onClick={() =>
        posthog.capture('cta_clicked', {
          location: 'landing_hero',
          intent: 'start_project',
        })
      }
    >
      시작하기
    </button>
  )
}

프로퍼티에는 개인정보보다 맥락을 넣습니다. location, plan, source, step처럼 나중에 필터링할 수 있는 값이 좋습니다. 이메일, 전화번호, 자유 입력 내용처럼 민감해질 수 있는 값은 대체로 보내지 않는 편이 안전합니다.

로그인 이후 사용자를 연결해야 한다면, 앱의 인증 흐름이 안정된 뒤 posthog.identify(user.id)를 호출합니다. 단, 익명 방문과 로그인 사용자를 어떻게 이어볼지 정책을 먼저 정해두는 것이 좋습니다.

4. 개인정보 안전벨트: 동의, DNT, 개발 데이터

분석은 제품 판단을 돕는 도구이지, 사용자를 몰래 추적하는 장치가 되어서는 안 됩니다. 특히 한국 사용자를 대상으로 한다면 쿠키, 개인정보 처리방침, 동의 UX를 제품 상황에 맞게 점검해야 합니다.

동의 전 수집을 피하고 싶다면 기본 opt-out으로 시작하고, 사용자가 동의했을 때만 opt-in하는 방식이 단순합니다.

posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN!, {
  api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
  defaults: '2026-05-30',
  opt_out_capturing_by_default: true,
})

// 동의 버튼 클릭 후
posthog.opt_in_capturing()

브라우저의 Do Not Track 신호를 존중하고 싶다면 초기화 전에 navigator.doNotTrack 값을 확인해 PostHog를 아예 시작하지 않는 방식도 고려할 수 있습니다. 또한 개발자 본인 트래픽은 데이터 해석을 흐리기 쉬우니, 로컬 환경 제외와 내부 계정 필터링을 함께 두는 편이 좋습니다.

5. 30분 체크리스트

마지막으로 아래 순서대로 확인합니다.

• posthog-js 설치
• NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN, NEXT_PUBLIC_POSTHOG_HOST 설정
• instrumentation-client.ts에서 초기화
• 페이지뷰가 들어오는지 확인
• 핵심 CTA에 posthog.capture() 추가
• 이벤트 이름과 프로퍼티 규칙 메모
• 쿠키 동의, opt-in/out, 개발 데이터 제외 점검

처음부터 모든 화면을 추적할 필요는 없습니다. 1인 빌더에게 더 중요한 것은 “방문자가 어디서 멈추는지”와 “핵심 가치를 실제로 경험하는지”를 매주 같은 기준으로 보는 것입니다. PostHog는 그 기준선을 만드는 도구로 작게 붙이고, 제품 질문이 생길 때마다 이벤트를 조금씩 늘려가면 됩니다.

참고: PostHog 공식 Next.js 문서 https://posthog.com/docs/libraries/next-js, JavaScript Web 문서 https://posthog.com/docs/libraries/js