개요
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)는 파싱된다.