파라미터 이름과 표기법
매개변수 이름은 두 단계로 정해집니다 — ① 어떤 형태로 지을지(4가지 중 하나), ② 모든 이름에 공통으로 적용되는 표기 규칙. 그리고 한 사이트 안에서는 같은 의미가 같은 이름이 되도록 일관성을 지킵니다. 이 세 축으로 정리합니다.
① 어떤 형태로 이름을 짓는가 — 4가지 중 하나
매개변수 이름은 형태로 다음 4가지로 갈립니다. 한 매개변수는 정확히 하나의 형태에 속합니다.
GA4 추천 이벤트가 정해 둔 매개변수들은 이름을 그대로 따라야 합니다. 우리가 자유롭게 짓는 영역이 아닙니다. 우리 마음대로 바꾸면 GA4의 자동 보고서·기능이 작동하지 않습니다.
| 추천 이벤트 | 표준 매개변수 (이름 그대로) |
|---|---|
purchase | transaction_id · value · currency · items (선택: coupon · shipping · tax) |
add_to_cart · view_item · view_cart | currency · value · items |
begin_checkout | currency · value · items (선택: coupon) |
view_item_list · select_item | item_list_id · item_list_name · items |
sign_up · login | method |
search | search_term |
items 배열 안 | item_id · item_name · item_brand · item_category · item_variant · price · quantity · discount · coupon |
흔한 함정 — GA4 표준은 value이지 revenue가 아닙니다. Universal Analytics(UA) 시절의 revenue를 그대로 쓰면 GA4 ‘수익 창출’ 보고서가 채워지지 않습니다. 또 price(상품 단가)와 value(이벤트 총 금액)는 자리가 달라 혼용 금지.
우리가 직접 짓는 매개변수의 기본 패턴은 [대상]_[기술자] — ‘어떤 대상’에 대한 ‘어떤 정보’인가입니다. 한 객체에 대한 여러 정보를 같은 prefix로 묶으면, 매개변수만 봐도 ‘무엇에 관한 정보군’인지가 한눈에 잡힙니다.
같은 객체의 여러 매개변수 — 배너 예시
| 매개변수 | 무엇 |
|---|---|
banner_name | 배너의 이름·텍스트 |
banner_position | 배너의 위치("hero_top"·"side_right") |
banner_type | 배너의 종류("image"·"video"·"text") |
banner_index | 같은 영역에 여러 배너가 있을 때의 순서(0부터) |
이벤트 이름과의 자연스러운 짝짓기
이벤트 이름의 ‘대상’ 부분이 그대로 매개변수 prefix가 되는 경우도 흔합니다.
| 이벤트 이름 | 기본 매개변수 | 값 예시 |
|---|---|---|
click_btn | btn_name | "회원가입" · "자세히 보기" |
click_gnb | gnb_name | "핫딜" · "신상품" |
click_tab | tab_name | "리뷰" · "문의" |
click_popup | popup_name | "newsletter" |
play_video | video_name | "intro" · "product_demo" |
도메인 특화 객체 — 강좌·학교 예시
업종에 따라 자주 등장하는 ‘대상’이 달라집니다. 교육·연수 서비스라면 강좌(course)·학교(school)에 관한 매개변수가 그룹을 이룹니다.
| 매개변수 | 무엇 |
|---|---|
course_id | 강좌(연수)의 고유 코드 |
course_name | 강좌(연수)명 |
course_category | 강좌 카테고리(주제) |
course_type | 강좌 유형("online"·"offline" 등) |
school_name | 학교 이름 |
school_level | 학교 급("elementary"·"middle"·"high"·"university") |
자주 쓰는 기술자(suffix) — 텍스트 식별 _name, 고유 ID _id, 분류 _type·_category·_level, 위치·순서 _position·_index·_location. 한 사이트 안에서는 같은 의미에 같은 기술자를 통일해서 씁니다(위치는 항상 _position).
단어 하나로 의미가 자명한 경우엔 prefix를 붙이지 않고 단독 이름으로 씁니다. 두 종류 — ① GA4 표준이 이미 단일 단어로 정해 둔 매개변수, ② 한 도메인에서 표준어처럼 정착된 단어.
| 매개변수 | 무엇 | 출처 |
|---|---|---|
price | 상품 단가 | GA4 표준 (items 배열 안) |
quantity | 상품 수량 | GA4 표준 (items 배열 안) |
discount | 할인 금액 | GA4 표준 |
value | 이벤트 전체 금액 | GA4 표준 |
currency | 통화("KRW"·"USD") | GA4 표준 |
coupon | 사용된 쿠폰 이름 | GA4 표준 |
credit | 학점·수강 점수 | 교육 도메인 — 단독 |
point | 포인트 사용 금액 | 적립금 도메인 — 단독 |
is_/has_참/거짓 정보는 GA4가 Boolean 타입을 지원하지 않아 ‘문자열·숫자’로 보냅니다. 이름에 의미가 보이도록 접두사 두 가지를 약속합니다.
| 접두사 | 의미 | 예시 |
|---|---|---|
is_ | 상태·구성·속성 | is_login · is_premium · is_marketing_consent · is_first_purchase |
has_ | 소유·포함 | has_coupon · has_pending_order · has_subscription |
값 표기는 한 가지로 통일 — 본 위키는 문자열 "true"/"false"를 권장하지만, 현장에선 "Y"/"N"이나 숫자 1/0도 쓰입니다. 어떤 표기든 한 사이트 안에서 한 가지로 통일되어야 BigQuery·보고서에서 분기 처리가 줄어듭니다. 주로 ‘그 사용자가 어떤 상태인가/무엇을 가지고 있는가’를 표현할 때 — 즉 사용자 속성(user property)에서 자주 쓰입니다.
② 모든 매개변수에 공통으로 적용되는 표기 규칙
위 4가지 형태와 무관하게 모든 매개변수 이름은 다음 규칙을 따릅니다.
글자 — snake_case
영문 소문자·숫자·언더바(_)만 쓰고, 모두 소문자입니다. snake_case 외 표기법(camel·kebab·Pascal)과의 비교와 ‘왜 snake_case인가’는 이벤트 이름과 표기법 글에서 자세히 다루었습니다.
복합명사 — 붙여 쓰기
매개변수 이름에서 _는 ‘대상 ↔ 기술자’ 경계 한 자리만입니다. 그래서 대상이나 기술자가 복합명사일 때 그 안에 또 _를 두지 않습니다.
icecream_name
‘icecream’을 한 단어로 두고, 그 뒤에 _name이라는 기술자. _가 명확히 ‘대상 ↔ 기술자’ 경계를 표시합니다.
ice_cream_name
_가 두 자리에 있어 ‘대상’이 어디까지인지 사람·기계 모두 헷갈립니다. ice + cream + name인지 ice_cream + name인지.
같은 원리로 giftcard_id(✓) / gift_card_id(✗), creditcard_type(✓) / credit_card_type(✗).
GA4 기술 한도
| 규칙 | 내용 |
|---|---|
| 시작 문자 | 문자로 시작(숫자·언더바·기호 금지). 영문 소문자로 시작. |
| 허용 문자 | 영문 소문자·숫자·언더바(_)만. |
| 길이 | 이벤트 매개변수 이름 40자 이내, 사용자 속성 이름 24자 이내. |
| 한 이벤트당 매개변수 수 | 약 25개. 평균 5~10개가 자연스러움. |
| 예약 접두사 | ga_ · google_ · firebase_로 시작 금지. |
③ 사이트 전체의 일관성
형태와 표기 규칙을 따랐어도, 같은 의미가 두 이름으로 흩어지면 데이터가 무너집니다. 한 사이트 안에서는 한 의미를 한 이름으로 고정하는 게 가장 중요한 약속입니다.
- 같은 의미는 같은 이름. ‘버튼 이름’은 늘
btn_name으로 —button_label이나btnText로 섞어 쓰지 않습니다. - 기술자(suffix)는 사이트 표준어로. 위치는 항상
_position, 분류는 항상_category, 고유 ID는 항상_id. - GA4 표준 이름은 그대로.
price를item_price로,value를revenue로 바꾸지 않습니다. - Boolean 값 표기도 한 가지로.
"true"/"false"·"Y"/"N"·1/0중 한 가지를 사이트 전반에서 통일합니다.
사례 — 한 결제 이벤트의 매개변수 모음
실제로 한 결제 이벤트에는 4가지 형태의 매개변수가 함께 들어갑니다. 교육 플랫폼의 강좌 결제를 예로 들면:
네 가지 형태(① GA4 표준 / ② 짝짓기 / ③ 단독 / ④ Boolean)가 자연스럽게 공존하면서, 매개변수 이름만 봐도 ‘무엇에 관한 정보’인지가 한눈에 잡힙니다.
자주 묻는 질문
click_btn에 btn_name 말고 button_text처럼 다르게 지어도 되나요?
기술적으로는 됩니다 — GA4가 매개변수 이름을 자유롭게 정하게 허용합니다. 다만 한 사이트 안에서 같은 정보(버튼의 텍스트)를 btn_name과 button_text로 섞어 쓰면 분석이 흩어집니다. ‘대상은 이벤트의 대상 부분을 그대로 따른다’는 우리 규약을 따라 btn_name으로 통일합니다.
왜 복합명사는 붙여 쓰나요? ice_cream_name이 더 읽기 좋아 보이는데요.
매개변수 이름에서 _의 역할이 ‘대상 ↔ 기술자’ 경계라서입니다. 단어 안에도 _가 들어가면 사람도 기계도 “이 이름의 ‘대상’ 부분이 어디까지인가?”를 매번 추측해야 합니다. icecream_name은 명확히 ‘대상=icecream, 기술자=name’. 같은 이유로 giftcard_id · creditcard_type도 한 단어로.
Boolean 값은 꼭 "true"/"false"로 보내야 하나요?
아닙니다 — 현장에선 세 가지 표기가 다 쓰입니다.
- 문자열
"true"/"false"— 의미가 가장 직관적. 본 위키 권장. - 문자열
"Y"/"N"— 짧아서 운영자가 자주 씀. 가독성은 한국어 환경에서 익숙. - 숫자
1/0— DB·로그 시스템과의 호환이 좋음.
중요한 건 ‘한 사이트 안에서 한 가지로 통일’입니다. true와 1이 섞이면 같은 정보가 두 가지 형태로 쌓여 BigQuery 쿼리·보고서에서 매번 분기 처리해야 합니다.
GA4 추천 이벤트의 value를 price로 보내면 안 되나요?
안 됩니다. 둘은 자리가 다릅니다. value는 ‘이벤트 전체의 금액’(purchase면 총 결제 금액, add_to_cart면 담은 상품 총액)이고, price는 items 배열 안 ‘한 상품의 단가’입니다. value를 빼고 price만 보내면 GA4의 수익 창출 보고서가 채워지지 않고, price 자리에 총액을 넣으면 ‘상품별 단가’ 분석이 깨집니다.
is_ / has_ 어느 쪽인지 헷갈릴 때는?
“그 사용자가 무엇인가”(상태)이면 is_, “그 사용자가 무엇을 가지고 있는가”(소유)면 has_. VIP 회원인가? → is_vip. 쿠폰 보유 중인가? → has_coupon. 마케팅 동의했나? → is_marketing_consent. 진행 중인 주문이 있나? → has_pending_order.
매개변수도 ‘맞춤 측정기준’으로 등록해야 보고서에서 보이나요?
네 — 우리가 보낸 매개변수를 GA4 보고서·탐색에서 ‘이름으로’ 골라 쓰려면 맞춤 측정기준/측정항목으로 등록해야 합니다(이벤트 범위 ~50개 한도). 등록하지 않아도 데이터는 쌓이고 BigQuery에서는 다 보이지만, GA4 UI에서 ‘쪼개서 보기’를 하려면 등록이 필요합니다(→ 데이터 수준 스코프).