Google Analytics 운영

Central 운영자를 위한 설정이며 App SDK 연동 작업은 아닙니다. 아래 예시로 브라우저 수집과 서버 보고서를 각각 구성하고 동의 거부 및 일반 고객 테넌트 제외를 확인하세요. App 코드에서 GA를 직접 초기화하지 않습니다. 값의 소유권은 설정의 소유권을 참고하세요.

설정하고 결과 확인

Indexable marketing page, developer portal, public demo를 수집하는 운영 배포는 다음과 같이 설정합니다.

GOOGLE_ANALYTICS_ENABLED=true
GOOGLE_ANALYTICS_MEASUREMENT_ID=G-XXXXXXXXXX
GOOGLE_ANALYTICS_COLLECT_SUBDOMAINS=developers
GOOGLE_ANALYTICS_COLLECT_TENANT_FIXTURES=demo

ANALYTICS_PROPERTY_ID=123456789
ANALYTICS_CREDENTIALS_BASE64=<base64-service-account-json>
ANALYTICS_CACHE_STORE=file
ANALYTICS_CACHE_MINUTES=60
ANALYTICS_STALE_CACHE_MINUTES=10080
ANALYTICS_CLICK_DIMENSIONS_ENABLED=false
ANALYTICS_REQUEST_TIMEOUT_MILLISECONDS=12000123456789101112

환경 값을 바꾼 뒤 config cache를 지웁니다. 동의하지 않은 상태로 indexable Central page에 들어가 GA request와 _ga cookie가 없는지 확인합니다. 동의를 허용하면 page view가 전송되어야 합니다. 다시 거절하면 cookie가 제거되어야 합니다. 일반 customer tenant를 열어 shell config에 demo measurement ID가 없는지 확인하고, demo fixture tenant에서는 demo 초기화 경로를 지난 뒤에만 수집이 시작되는지 확인합니다.

Central admin에 로그인해 analytics page 넷을 엽니다. Overview, acquisition, content, surfaces 보고서가 선택한 기간에 맞게 렌더링되어야 합니다. Data API 갱신이 실패하면 stale-cache 기간까지 마지막 성공 보고서를 보여줄 수 있습니다. Browser 수집은 되는데 보고서만 없다면 공개 measurement ID보다 숫자 property, credential, Data API 접근 권한, cache 설정을 먼저 확인하세요.

무엇인가

Nexia에는 애플리케이션이 소유하는 Google Analytics 4 통합이 하나 있고 서로 분리된 두 부분으로 구성됩니다. Browser 수집은 동의한 Central 화면과 서버가 allowlist한 demo fixture에서 page·interaction event를 보냅니다. Server 보고는 GA4 Data API를 읽어 Central Filament admin에 운영자용 보고서 넷을 그립니다. 공개 measurement ID와 비공개 보고 credential은 의도적으로 별도 설정입니다.

어떻게 맞물리는가

Central browser injection은 다음 조건을 모두 만족할 때만 일어납니다.

1. GOOGLE_ANALYTICS_ENABLED가 true이고 measurement ID가 있습니다.
2. 요청이 indexable marketing document이거나 host가 GOOGLE_ANALYTICS_COLLECT_SUBDOMAINS 항목 중 하나로 시작합니다.
3. 방문자가 analytics 동의를 허용합니다.

추가 Central host의 기본값은 developers입니다. Developer portal은 marketing document가 아니지만 이 목록으로 수집할 수 있습니다. Authentication page와 그 밖의 등록되지 않은 Central page는 수집하지 않습니다.

Tenant shell 규칙은 더 좁습니다. 현재 tenant의 fixture_key가 GOOGLE_ANALYTICS_COLLECT_TENANT_FIXTURES에 있을 때만 demo analytics를 주입하며 기본값은 demo입니다. Customer tenant에는 fixture key가 없으므로 domain 이름이 바뀌어도 일치할 수 없습니다. 이 조건을 넓은 tenant-domain 규칙으로 바꾸지 마세요.

Central browser runtime은 analytics storage를 denied로 시작하고 광고 기능과 개인화를 끄며, 초기화 전에는 typed event를 보내지 않습니다. 사용자가 거절하면 consent를 denied로 갱신하고 GA disable flag를 세우며 _ga* cookie를 제거합니다. Destination 추적은 query string과 fragment를 버립니다. 지원 event는 navigation_click, cta_click, generate_lead, demo_session_start, demo_app_opened입니다. 이름, email, tenant identifier, 사용자 자유 입력값, 그 밖의 PII를 event parameter에 넣으면 안 됩니다.

Server 보고는 다음 독립 설정을 사용합니다.

Central admin에는 google-analytics-dashboard, google-analytics-acquisition, google-analytics-content, google-analytics-surfaces만 등록됩니다. Tenant admin에는 짝이 되는 page가 없습니다.

경계

전용 비운영 data stream이 없다면 local과 staging에서는 수집을 끄세요. Production stream을 재사용하면 개발 traffic이 acquisition, retention, content 보고서를 오염시킵니다. Measurement ID는 공개 설정이지만 숫자 property ID는 서버 보고서를 선택하고 service-account credential은 비밀로 보관합니다. JSON은 repository 밖에 mount하거나 Base64 secret으로 전달하고 절대 commit하지 마세요.

Consent는 banner state만을 뜻하지 않습니다. 새 Central tracking code는 typed·consent-aware analytics entrypoint를 호출해야 초기화 전 no-op이 보장됩니다. Demo tracker는 server가 allowlist fixture 설정을 주입한 뒤에만 초기화됩니다. App에서 GA library를 직접 호출하면 안 됩니다. 새 event parameter에는 privacy 검토가 필요하며 안정적이고 cardinality가 낮은 값을 써야 합니다.

Interaction 보고서의 element_id, placement, destination_path column은 GA4의 event-scoped custom dimension에 의존합니다. Property에 세 dimension을 모두 등록하기 전에는 ANALYTICS_CLICK_DIMENSIONS_ENABLED=false를 유지하세요. 먼저 켜면 Data API가 custom-dimension 보고서를 거부합니다. Flag가 꺼져 있어도 event 수집은 계속할 수 있습니다.

관련 문서

• 환경변수 — browser·server-side Analytics 값과 secret owner 전체 조회
• 설정의 소유권 — analytics 값 중 deployment config와 product behavior 구분
• Site Configuration — GA4 배포 secret과 섞지 않고 테넌트 사이트 설정 운영
• 테넌트와 컨텍스트 — server-side identity로 customer tenant 수집을 제외하는 이유
• 테넌트 컨텍스트 문제 해결 — 요청이 잘못된 tenant 또는 Central 화면에 도달할 때 진단