GA 트래킹 개발 명세 (FRD)¶

요지¶

GA4 이벤트 트래킹 파이프라인을 어떻게 구현하는지 정리한다. 핵심 결정은 트래킹을 클라이언트에서 GA로 직접 보내는 것이다 — 백엔드를 거치지 않으므로 Spring은 트래킹에 전혀 관여하지 않는다. 그 위에 공통 유틸, 명명 규칙, 화면별 이벤트 목록을 정의한다.

상위 PRD (링크 · 변경 시 알림)¶

기획(명명·환경 분리·성공지표)은 prd를 본다.

기술 접근 · 아키텍처¶

이벤트는 Next.js 클라이언트 → Google Analytics 서버로 직접 전송. Spring 백엔드는 비즈니스 로직 API만 담당하며 트래킹 파이프라인에 관여하지 않는다.

사용자 → 브라우저(Next.js) → lib/gtag.ts(sendEvent) → Google Analytics
         (비즈니스 로직은 별도로 Spring Boot API 호출)

처리 흐름(시퀀스) — 트래킹은 GA로 직접, 비즈니스는 Spring으로(두 경로 비교차): 1. 페이지 접속 → Next.js 로드·렌더 → GA 스크립트 초기화. 2. 라우트 변경(/login) → Analytics 컴포넌트가 sendPageView → GA로 page_view 전송. 3. 버튼 클릭(예: 로그인) → sendEvent('login_click', { text:'로그인' }) → GA 전송. 4. 동시에 비즈니스 요청 POST /api/login → Spring 인증 → 응답. 5. 성공 후 /home 이동 → 다시 page_view 자동 전송.

범위 — In: GA4 스크립트 연동·환경별 초기 설정, 공통 유틸(래퍼 sendEvent), 자동 page_view, 명명 규칙·스키마 가이드, DebugView 검증. Out: 개별 비즈니스 기능 상세 이벤트 스키마(각 기능 FDD), 상세 리포트, 서버사이드 태깅.

API · 데이터 모델¶

명명 규칙·기본 유형¶

[domain]_[action] 또는 [domain]_[object]_[action]. 좋은 예: login_click, signup_submit, studyroom_enter_click. 나쁜 예: ClickLogin, event_1.

유형	예시 이벤트명	핵심 파라미터
페이지 뷰	`page_view`(자동)	`page_location`(자동)
클릭	`[domain]_click`	`target`, `text`
폼 제출	`[domain]_submit`	`form_id`
노출/조회	`[domain]_view`	`item_name`

화면별 이벤트¶

모든 이벤트에 user_type(teacher/student/guardian/null)을 공통으로 싣고, 페이지 조회는 {도메인}_page_view로 통일한다. 화면별 이벤트는 수십 건이라 전체 목록은 GA4 데이터 수집 기획서에 있고, 여기서는 대표적인 것만 추린다.

GNB: gnb_logo_click, gnb_alarm_click, gnb_profile_click, gnb_logout_click.
스터디룸: studyroom_create_click, studyroom_student_invite_open, studyroom_studynote_tab_click, studyroom_studynote_create_enter, studyroom_question_tab_click, studyroom_homework_tab_click 등(파라미터 room_id, user_type).
수업노트: studynote_create_click/_success/_fail(파라미터 has_title, image_count, visibility 등), 그룹 CRUD.
학생: student_invite_click/_success/_fail, student_remove_confirmed, studyroom_student_end_confirmed.
질문/과제: question_create_click, reply_create_click, homework_create_click, homework_submit_click.
LNB/Footer/마이페이지는 TBD.

의존성 · 영향 범위¶

트래킹이 클라이언트에서 GA로 바로 가므로 백엔드 작업이 따로 없다(개별 비즈니스 API는 각 기능 FDD가 맡는다). 가장 중요한 원칙은 안정성이다 — 트래킹 코드가 깨지거나 네트워크가 실패해도 사용자 화면에는 영향이 없어야 하고(콘솔 경고 수준으로 처리), 환경별로 올바른 측정 ID를 써서 dev와 prod 데이터를 갈라 저장해야 한다.

테스트 계획¶

DebugView로 환경별 ID 수집 검증, 핵심 화면 이벤트 발화·파라미터 정확성, dev/prod 데이터 분리, 트래킹 실패의 UX 무영향, 라우트 변경 시 page_view 자동 전송.

작업 분해 (FE Tasks)¶

단계	작업
1	`.env.development`/`.env.production`에 `NEXT_PUBLIC_GA_MEASUREMENT_ID` 추가(값은 환경변수만)
2	`app/layout.tsx`에 GA 스크립트·초기화
3	`lib/gtag.ts`(또는 `lib/ga/gtag.ts`)에 `sendEvent`/`sendPageView` 구현 — 모든 이벤트 단일 경로
4	`Analytics` 컴포넌트(`usePathname`/`useSearchParams`)로 `page_view` 자동 전송
5	테스트 버튼에 `test_click` 연동
6	GA 실시간 > DebugView로 환경별 ID 수집 검증

BE 태스크: 본 아키텍처가 백엔드와 무관함을 인지(직접 작업 없음).