# 파라미터 이름과 표기법

매개변수 이름은 두 단계로 정해집니다 — 어떤 형태로 지을지(4가지)와 모든 이름에 공통으로 적용되는 표기 규칙. 그리고 사이트 전체의 일관성.

- 카테고리: 이벤트 택소노미
- 소요 시간: 약 8분
- 난이도: 중간
- 업데이트: 2026.05.14
- 원문: /wiki/playbook/ga4-event-taxonomy-checklist/how-to-name-ga4-parameters

## 목차

- [② 공통 표기 규칙](#notation)
- [③ 사이트 전체 일관성](#consistency)
- [자주 묻는 질문](#faq)

매개변수 이름은 두 단계로 정해집니다 — ① 어떤 **형태**로 지을지(4가지 중 하나), ② 모든 이름에 공통으로 적용되는 **표기 규칙**. 그리고 한 사이트 안에서는 같은 의미가 같은 이름이 되도록 **일관성**을 지킵니다. 이 세 축으로 정리합니다.

## ① 어떤 형태로 이름을 짓는가 — 4가지 중 하나

매개변수 이름은 형태로 다음 4가지로 갈립니다. 한 매개변수는 정확히 하나의 형태에 속합니다.

1GA4 표준 매개변수 — 이름 변경 불가

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`(이벤트 총 금액)는 자리가 달라 혼용 금지.

2[대상]_[기술자] 패턴 — 가장 흔한 자유 명명

우리가 직접 짓는 매개변수의 기본 패턴은 **`[대상]_[기술자]`** — ‘어떤 대상’에 대한 ‘어떤 정보’인가입니다. 한 객체에 대한 여러 정보를 같은 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`).

3단독 이름 — 도메인 표준어

단어 하나로 의미가 자명한 경우엔 prefix를 붙이지 않고 **단독 이름**으로 씁니다. 두 종류 — ① GA4 표준이 이미 단일 단어로 정해 둔 매개변수, ② 한 도메인에서 표준어처럼 정착된 단어.

| 매개변수 | 무엇 | 출처 |
| --- | --- | --- |
| `price` | 상품 단가 | GA4 표준 (`items` 배열 안) |
| `quantity` | 상품 수량 | GA4 표준 (`items` 배열 안) |
| `discount` | 할인 금액 | GA4 표준 |
| `value` | 이벤트 전체 금액 | GA4 표준 |
| `currency` | 통화(`"KRW"`·`"USD"`) | GA4 표준 |
| `coupon` | 사용된 쿠폰 이름 | GA4 표준 |
| `credit` | 학점·수강 점수 | 교육 도메인 — 단독 |
| `point` | 포인트 사용 금액 | 적립금 도메인 — 단독 |

4Boolean 접두사 —`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인가’는 [이벤트 이름과 표기법](/wiki/playbook/ga4-event-taxonomy-checklist/how-to-name-ga4-events) 글에서 자세히 다루었습니다.

### 복합명사 — 붙여 쓰기

매개변수 이름에서 `_`는 **‘대상 ↔ 기술자’ 경계 한 자리만**입니다. 그래서 대상이나 기술자가 복합명사일 때 그 안에 또 `_`를 두지 않습니다.

✓ 권장

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가지 형태의 매개변수가 함께 들어갑니다. 교육 플랫폼의 강좌 결제를 예로 들면:

event: purchase // ── ① GA4 표준 매개변수 ── transaction_id: "ORD-20260514-018" value: 89000 // 이벤트 전체 금액 currency: "KRW" coupon: "신규가입_10%" // ── ③ 단독 이름 (도메인 표준어) ── point: 5000 // 포인트 사용 discount: 9000 // ── ② [대상]_[기술자] 패턴 ── payment_type: "kakao_pay" coupon_value: 9000 // ── items 배열 (각 상품) ── items: [{// ② course_* — 강좌 객체에 묶임 course_id: "C-PSY-101" course_name: "긍정심리학 입문" course_category: "심리" course_type: "online" // ① GA4 표준 + ③ 단독 도메인 표준어 price: 89000 // GA4 표준 quantity: 1 // GA4 표준 credit: 2 // 도메인 표준어}]

네 가지 형태(① 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에서 ‘쪼개서 보기’를 하려면 등록이 필요합니다(→ [데이터 수준 스코프](../../플레이북/데이터 수준 스코프/index.html)).

## Navigation

- [전체 플레이북 Markdown sitemap](/wiki/playbook/sitemap.md)

### 이벤트 택소노미

- [이벤트 택소노미](/wiki/playbook/ga4-event-taxonomy-checklist)
- [로그와 이벤트](/wiki/playbook/ga4-event-taxonomy-checklist/what-is-logs-and-events)
- [이벤트의 구조](/wiki/playbook/ga4-event-taxonomy-checklist/what-is-event-structure)
- [이벤트 택소노미의 정의와 CASE STUDY](/wiki/playbook/ga4-event-taxonomy-checklist/ga4-event-taxonomy-case-study)
- [이벤트 택소노미 문서 — 설계 담당자용](/wiki/playbook/ga4-event-taxonomy-checklist/event-taxonomy-document-for-designers-guide)
- [이벤트 택소노미 문서 — 개발자용](/wiki/playbook/ga4-event-taxonomy-checklist/how-to-implement-event-taxonomy-for-developers)
- [Data Layer와 GTM — 이벤트 태깅의 큰 그림](/wiki/playbook/ga4-event-taxonomy-checklist/data-layer-and-gtm-guide)
- [GA4 이벤트의 종류](/wiki/playbook/ga4-event-taxonomy-checklist/what-is-ga4-event-types)
- [이벤트 이름과 표기법](/wiki/playbook/ga4-event-taxonomy-checklist/how-to-name-ga4-events)
- [주요이벤트와 서브이벤트](/wiki/playbook/ga4-event-taxonomy-checklist/key-events-vs-sub-events)
- [이벤트 이름 설계의 세분성(granularity)](/wiki/playbook/ga4-event-taxonomy-checklist/how-to-decide-event-granularity)
- [파라미터 이름과 표기법](/wiki/playbook/ga4-event-taxonomy-checklist/how-to-name-ga4-parameters) (현재 문서)
- [파라미터의 타입(type)](/wiki/playbook/ga4-event-taxonomy-checklist/how-to-choose-ga4-parameter-types)
- [파라미터의 수준(level)](/wiki/playbook/ga4-event-taxonomy-checklist/what-is-ga4-parameter-levels)
- [GA4 맞춤 측정기준 등록하기](/wiki/playbook/ga4-event-taxonomy-checklist/how-to-register-ga4-custom-dimensions)
- [GA4 전자상거래란?](/wiki/playbook/ga4-event-taxonomy-checklist/what-is-ga4-ecommerce)
- [전자상거래 이벤트를 이해하기 위한 프로그래밍 지식](/wiki/playbook/ga4-event-taxonomy-checklist/ecommerce-event-programming-guide)
- [전자상거래 리포트 100% 이해하기](/wiki/playbook/ga4-event-taxonomy-checklist/ga4-ecommerce-reports-guide)