Server-Side GTM(SGTM) 메타데이터 자동 주입 필드

개요

sGTM은 모든 요청에 다음 24개 필드를 자동으로 추가한다. 이 문서는 그 필드들의 정의와, 디바이스·GeoIP 정보를 어떤 전략으로 파싱하는지, 필드를 추가할 때 따르는 공통 규칙을 정리한다.

현재 상태 / 정의

기본 메타데이터 (5개)

필드명	타입	설명	예시
miridih_gtm_idx	string	UUID v7 고유 식별자 (시간순 정렬)	"018e6e1d-f4a5-7000-9b3c-d4c5e6f7a8b9"
event_date	string	KST 날짜 (YYYYMMDD)	"20251027"
event_time	string	UTC 시간 (YYYY-MM-DD HH:MM:SS)	"2025-10-27 12:34:56"
event_timestamp	long	마이크로초 Unix 타임스탬프	1760888670929432
p_date	string	KST 파티션 날짜 (YYYY-MM-DD)	"2025-10-27"

사용자 식별 (2개)

필드명	sgtm 필드	설명
up_user_id	user_id	로그인 사용자 ID (GTM 필드 복사)
user_pseudo_id	client_id	익명 사용자 ID (GTM 필드 복사)

디바이스 정보 (11개)

필드명	sgtm 필드	예시
device.category	Client Hints / User Agent	"mobile", "desktop"
device.language	language 필드	"ko-KR"
device.mobile_brand_name	User Agent	"Samsung", "Apple"
device.mobile_model_name	Client Hints	"SM-F721N"
device.mobile_os_hardware_model	Client Hints	"SM-F721N"
device.operating_system	Client Hints / User Agent	"Android", "iOS"
device.operating_system_version	Client Hints / User Agent	"Android 15.0.0", "iOS 26.0.1"
device.web_info.hostname	page_location URL 파싱	"printhub.miricanvas.com"
device.web_info.browser	Client Hints / User Agent	"Chrome", "Whale"
device.web_info.browser_version	Client Hints / User Agent	"141.0.7390.123"

GeoIP 정보 (6개)

필드명	sgtm 필드	예시
geo.country	event_location.country	"South Korea", "United States"
geo.region	event_location.region	"Seoul", "Gyeonggi-do"
geo.continent	event_location.country	"Asia", "Americas"
geo.sub_continent	event_location.country	"Eastern Asia", "Northern America"
geo.city	ip_override (GeoLite2)	"Seoul", "Busan"
geo.metro	ip_override (GeoLite2)	"New York NY", "Nashville TN" (DMA 코드 매핑, 50개 주요 시장, 미국만)

상세 내용

디바이스 파싱 전략

• Client Hints 우선 (49% 커버리지): Chrome, Edge, Whale → JSON 직접 파싱
• User Agent 폴백 (51% 커버리지): Safari, NAVER 인앱 → woothee 라이브러리 파싱

GeoIP 파싱 전략 (하이브리드)

• event_location 우선 (4개 필드): country, region, continent, sub_continent
  • GTM 제공 데이터 사용 (phf::Map 컴파일타임 매핑)
• ip_override 보완 (2개 필드): city, metro
  • GeoLite2-City.mmdb 사용 (Optional)
  • Metro: DMA 코드 → 지역명 매핑 (50개 미국 주요 시장, 예: 501 → "New York NY")
  • 매핑 없는 코드는 필드 추가 안 함
  • DB 없어도 실행 가능 (4개 필드는 파싱됨)

필드 추가 규칙

• 클라이언트가 이 필드를 전송하면 기존 값 유지 (덮어쓰지 않음)
• 값이 없거나 null인 경우 조용히 무시 (필드 추가 안 함, 로그 없음)
• 타입 불일치: ERROR 로그 + 해당 필드 추가 안 함
• 파싱 실패: ERROR 로그 + 해당 필드 추가 안 함
• 원칙: 어떤 에러가 발생해도 이벤트는 Kafka에 전송됨

적용 범위 / 제약

모든 sGTM 수신 요청에 적용된다. geo.metro 는 DMA 코드가 매핑된 미국 50개 주요 시장에만 값이 채워지며, 매핑이 없는 코드는 필드 자체가 추가되지 않는다. GeoLite2-City.mmdb 가 없어도 event_location 기반 4개 GeoIP 필드(country·region·continent·sub_continent)는 파싱된다.