hsb.horse
Partytown 및 Google Analytics(GA4) 도입 방침
결정
- 트래픽 분석 도구로 Google Analytics 4(GA4)를 채택하고, 측정 ID는
G-WZ3RT34EZZ를 사용한다. @astrojs/partytown을 도입해type="text/partytown"방식으로 GA 스크립트를 Web Worker로 오프로딩한다.- 측정 태그 출력 책임은 공통 레이어(
Layout하위 전용 컴포넌트)로 일원화한다. - 측정은 프로덕션 URL에서만 활성화하고, 로컬 개발/프리뷰 환경에서는 비활성화한다.
- 초기 범위는 페이지뷰 측정으로 한정하고, 커스텀 이벤트 분류는 별도 ADR에서 정의한다.
- 초기 도입에서는
gtag('config', ...)에 추가 프라이버시 파라미터를 오버라이드하지 않고 GA4 기본 설정으로 프로덕션 운영을 시작한다.
구현 규약
| 항목 | 규약 |
|---|---|
| 스크립트 실행 방식 | gtag.js를 type="text/partytown"으로 로드한다. |
| ID 관리 | 측정 ID를 페이지에 하드코딩하지 않고 PUBLIC_GA_MEASUREMENT_ID로 주입한다(초기값 G-WZ3RT34EZZ). |
| 출력 조건 | PROD가 true이고 측정 ID가 존재할 때만 태그를 출력한다. |
| 배치 | 페이지별 구현이 아니라 공통 Layout에서 중앙 관리한다. |
| 이벤트 범위 | 초기 범위는 page_view만 포함한다. 임의 커스텀 이벤트는 이번 단계에서 제외한다. |
배경
현재는 분석 도구가 없어 유입/조회 추세나 주요 페이지 성과를 파악할 수 없다. 동시에 서드파티 스크립트를 메인 스레드에서 실행하면 TTI/FID/INP에 악영향을 줄 수 있다.
프로젝트는 이미 Astro 공통 Layout에서 head 책임을 관리하고 있으므로, 분석 태그도 같은 패턴으로 통합하는 것이 자연스럽다. 다국어 구조 특성상 페이지 단위 구현은 불일치 위험이 커서 피해야 한다.
옵션
- 옵션 A: 일반
gtag.js를 메인 스레드에서 직접 로드한다 - 옵션 B:
@astrojs/partytown으로gtag.js를 Worker에서 실행한다(채택) - 옵션 C: GA4를 도입하지 않고 다른 경량 분석 도구로 전환한다
근거
- 성능: Partytown으로 서드파티 실행을 Worker로 이동해 메인 스레드 부담을 줄일 수 있다.
- 운영 안정성: 공통 레이어 출력으로 신규 페이지 추가 시 태그 누락을 방지할 수 있다.
- 단계적 도입: 우선 페이지뷰부터 시작하고 이벤트 설계는 후속 ADR로 분리할 수 있다.
- 감사 가능성: 프로덕션 전용 게이팅과 “GA 기본 설정으로 시작” 전제를 명시할 수 있다.
영향
@astrojs/partytown의존성을 추가하고astro.config.mjs에 integration 설정이 필요하다.Layout에서 참조하는 공통 Analytics 컴포넌트(또는 동등 책임)를 추가해야 한다.PUBLIC_GA_MEASUREMENT_ID환경변수 운영 규칙을 정의/유지해야 한다.- 개인정보 처리방침에 GA4 사용 및 측정 목적을 반영해야 한다.
- 수용 기준은 아래와 같다.
- GA 태그는 프로덕션에서만 출력된다
- 모든 공개 페이지에서 페이지뷰가 측정된다
- Lighthouse(또는 동등 지표) 기준 메인 스레드 성능 저하가 허용 범위 이내다