refactor: Main 프로세스 기반 GA4 MP 분석 파이프라인 전환

[choihooo]

요약

• Renderer에서 직접 호출하던 GA를 제거하고, Main 프로세스의 GA4 Measurement Protocol 전송 구조로 리팩토링했습니다.
• Preload에 타입 안전한 analytics 브리지를 추가했습니다 (contextBridge + ipcRenderer.invoke).
• 이벤트 이름/파라미터를 고정된 타입 스키마로 제한했습니다.
• 자동 page_view/URL 기반 추적을 제거하고 이벤트 기반 수집만 유지했습니다.
• Main analytics 모듈에 아래를 구현했습니다.
  • 설치 단위 client_id 영속 저장 (getOrCreateClientId)
  • 공통 파라미터 주입 (app_version, platform, release_channel, screen, session_id)
  • PII 방지(이메일/전화번호 키 drop, 값 mask)
  • 디버그 토글(debug/mp/collect) + DebugView 노출 대응(debug_mode, engagement_time_msec)
• 위젯 dev 로딩 실패(ERR_FAILED) 대응으로 URL 재시도 로직을 추가했습니다.
• 문서와 env를 정리해 secret이 renderer 쪽에 남지 않도록 정리했습니다.

변경 배경

• Renderer는 GA 내부 구현/시크릿을 알면 안 됩니다.
• api_secret은 절대 renderer 번들에 포함되면 안 됩니다.
• 퍼널/핵심 행동 이벤트만 안정적으로 수집해야 합니다.
• 로컬에서 DebugView 검증이 가능해야 합니다.

주요 변경사항

1) 분석 아키텍처 리팩토링

• src/main/src/analytics.ts 추가
  • IPC 핸들러: analytics:logEvent, analytics:setUserId
  • MP 전송 (mp/collect, 옵션으로 debug/mp/collect)
  • client_id 영속 저장: app.getPath('userData')/analytics.json
  • PII 필터링
  • 공통 params 주입
• src/main/src/index.ts에서 analytics 핸들러 등록
• main 시작 시 루트 .env 로드 (dotenv)

2) Preload 브리지 추가

• src/preload/src/index.ts
  • electronAPI.analytics.logEvent(...)
  • electronAPI.analytics.setUserId(...)

3) Renderer 분석 호출 정리

• src/renderer/src/shared/lib/analytics/schema.ts 추가
• src/renderer/src/shared/lib/analytics/client.ts 추가
• src/renderer/src/shared/lib/analytics/events.ts를 logEvent 기반으로 변경
• src/renderer/src/shared/lib/analytics/index.ts export 정리
• src/renderer/src/shared/lib/analytics/ga4.ts 삭제
• src/renderer/src/app/providers/App.tsx에서 GA init/page_view 제거
• src/renderer/src/entities/user/api/use-login-mutation.ts에서 userId 설정 경로 변경
• src/renderer/src/shared/types/vite-env.d.ts 정리

4) 위젯 dev 로딩 안정화

• src/main/src/widgetWindow.ts
  • dev URL 생성: new URL('widget', VITE_DEV_SERVER_URL)
  • 로드 실패 시 재시도 후 fallback

5) 문서/환경변수 정리

• README.md GA 섹션을 새 MP 구조 기준으로 갱신
• ga.md에 런타임 원칙 추가
• src/renderer/.env에서 GA 관련 키 제거

이벤트 스키마

이벤트명	파라미터
download_click	{ platform: 'mac' | 'windows'; source: string }
sign_up_complete	{ user_id?: string }
onboarding_enter	{ step: string }
measure_page_enter	{ session_id: string }
first_measure_start	{ seconds_from_signup: number }
measure_start	{ session_id: string }
measure_end	{ session_id: string; duration_sec: number }
bad_posture_enter	{ session_id: string; posture_level: number }
posture_recovered	{ session_id: string; posture_level: number; recovery_time_sec: number }
widget_toggle	{ enabled: boolean }
widget_visibility_end	{ duration_sec: number; session_id?: string }
notification_toggle	{ enabled: boolean }
meaningful_use	{ type: string }

검증 결과

• pnpm run typecheck 통과 (main/preload/renderer)
• 로컬 수동 검증
  • debug/mp/collect response: { "validationMessages": [] } 확인
  • analytics.json 생성 및 clientId 영속 확인
  • DebugView 노출 확인 (debug_mode + engagement_time_msec 반영 후)

커밋 구성

1. feat(analytics): route renderer events to main via GA4 MP
2. fix(widget): retry dev widget URL before fallback
3. docs(analytics): update MP pipeline and debug setup

릴리즈 메모

• 권장 버전: 0.1.4 (patch)
• 배포는 main 머지 후 해당 커밋에 v0.1.4 태그를 달아 진행하는 것을 권장합니다.

[github-actions]

🔧 Electron Build Results

✅ macOS

• Status: Success
• Job: build-electron (macos-latest, mac)

✅ Windows

• Status: Success
• Job: build-electron (windows-latest, win)

---

This is an automated comment.