# 이벤트 택소노미 문서 — 개발자용

택소노미 시트를 펴고 dataLayer push 코드를 사이트에 옮기는 실무 절차. 시트 5개 영역의 읽는 법, 트리거번호별 조건부 전송, 데이터 수준별 코드 작성, 자체 검증과 세팅 완료 처리까지.

- 카테고리: 이벤트 택소노미
- 소요 시간: 약 14분
- 난이도: 중간
- 업데이트: 2026.05.15
- 원문: /wiki/playbook/ga4-event-taxonomy-checklist/how-to-implement-event-taxonomy-for-developers

## 목차

- [② 시트 다섯 영역](#overview)
- [③ 1번 — 트리거 발생 시점](#area1)
- [④ 2번 — 파라미터 명세](#area2)
- [⑤ 3번 — 코드 샘플](#area3)
- [⑥ 4번 — 히스토리](#area4)
- [⑦ 5번 — 트리거 이미지 (두 케이스)](#area5)
- [⑧ 데이터 수준별 코드](#levels)
- [⑨ 공통 파라미터 시트](#common)
- [⑩ 자체 검증](#verify)
- [⑪ 구현 워크플로](#workflow)
- [자주 묻는 질문](#faq)

‘[Data Layer와 GTM — 이벤트 태깅의 큰 그림](/wiki/playbook/ga4-event-taxonomy-checklist/data-layer-and-gtm-guide)’에서 ‘**왜** dataLayer를 통해 데이터를 보내는가’와 ‘개발팀이 맡는 부분은 어디까지인가’를 정리했습니다. 이 글은 그 다음 단계 — **실제 택소노미 시트를 펴고 코드를 사이트에 옮기는 절차**를 정리합니다. 개별 이벤트 시트의 다섯 영역을 어떤 순서로 읽고, 무엇을 추출하고, 어떻게 자체 검증하는지까지.

## ① 작업 시작 전 — 이 한 가지만 기억하면 됩니다

개발팀의 작업 범위는 한 문장으로 정리됩니다.

> **택소노미 문서를 기준으로 — 정확한 위치에, 정확한 구조로, 정확한 값을 데이터레이어에 전달한다.**

이 한 줄을 분해하면 — ‘**정확한 위치**’는 시트의 ‘1번 영역(트리거 발생 시점)’과 ‘5번 영역(참고 이미지)’으로 알아내고, ‘**정확한 구조**’는 ‘3번 영역(코드 샘플)’으로, ‘**정확한 값**’은 ‘2번 영역(파라미터 명세)’으로 알아냅니다. 즉 시트의 5개 영역이 작업 한 건의 모든 정보를 담고 있고, 개발팀은 이 다섯 영역을 차례로 읽어 가면 됩니다.

이 글의 ②~⑦은 시트 영역별 ‘**읽는 법**’, ⑧~⑪은 시트 외부 ‘**실무 절차**’(데이터 수준별 코드·공통 파라미터·자체 검증·완료 처리)를 다룹니다.

## ② 개별 이벤트 시트 — 다섯 영역의 위치

택소노미 문서는 시트 단위로 구성되고, 개별 이벤트 시트는 항상 동일한 5개 영역으로 구성됩니다. 아래는 `purchase` 시트를 예시로 한 화면입니다(다양한 데이터 타입·수준이 한 시트에 등장해 가장 풍부한 예시).

> **다이어그램 설명:** 이벤트 시트의 다섯 영역을 박스와 라벨로 표시한 오버레이 — purchase 시트 기준

이벤트 시트 한 화면의 다섯 영역. ① 트리거 발생 시점 · ② 파라미터 명세 · ③ 코드 샘플 · ④ 추가 논의 히스토리 · ⑤ 트리거 시점 참고 이미지. 각각의 의미는 아래에서 차례로 다룹니다.

개발팀이 작업할 때는 ‘**1번 → 5번 → 2번 → 3번**’ 순으로 봅니다 — 1번에서 ‘어디서 발생하는지’를 파악하고, 5번 이미지가 있으면 그 위치를 시각적으로 확정합니다. 이어 2번에서 ‘어떤 값을 함께 보내야 하는지’를 알아내고, 3번의 코드 샘플을 그대로 가져와 정확한 트리거 시점에 호출하면 끝입니다.

## ③ 1번 영역 — 트리거 발생 시점

이 이벤트가 ‘**어디서·언제·어느 플랫폼에서**’ 발생하는지를 정의하는 표입니다. 코드를 심기 전 가장 먼저 확인합니다.

![이벤트 시트 1번 영역 — ‘이벤트 이름 purchase’ 헤더 아래 트리거 발생 시점 표가 있고, 트리거번호 1 · 페이지명 ‘구매 완료’ · Platform PC/MO · 발생 시점 설명 ‘구매 완료 시점’ · 세팅 상태 ‘대기중’ 행들이 표시된 모습](/wiki-assets/playbook/how-to-implement-event-taxonomy-for-developers/area1-trigger.png)

> 1번 영역 — 트리거 발생 시점. 페이지명·Platform·발생 시점 설명을 보고 ‘어디서 코드를 호출할지’를 결정합니다.

각 컬럼의 의미:

- **트리거번호** — 같은 이벤트가 여러 위치·시점에서 발생할 때의 식별 번호. 한 자리면 보통 `1`.
- **페이지명** — 이벤트가 발생하는 페이지 또는 영역(02 컨텐츠 그룹 시트의 그룹명을 참조). ‘공통’이면 GNB·푸터처럼 전역 UI.
- **Platform** — `PC` / `MO` 별 행이 분리되어 있을 수 있음. PC와 모바일의 트리거 시점이 다르면 두 행을 모두 확인.
- **발생 시점 설명** — ‘GNB 클릭 시점’·‘구매 완료 시점’ 같은 자연어 설명. 5번 영역의 이미지가 있으면 이 설명을 시각화합니다.
- **세팅 상태** — 작업 진행 단계(대기중·세팅 완료·검수 완료). 개발자가 코드를 다 심으면 ‘세팅 완료’로 직접 갱신합니다.

### 트리거가 여러 개일 때

같은 이벤트라도 여러 위치에서 발생할 수 있습니다. 예를 들어 `click_banner`가 메인 페이지 상단 배너에서 한 번, 카테고리 페이지 사이드 배너에서 한 번 발생한다면 1번 영역에 **트리거번호 1, 2 두 행**이 들어 있고 각각의 발생 시점이 따로 적혀 있습니다. 개발자는 두 위치에 각각 코드를 심습니다.

## ④ 2번 영역 — 파라미터 명세

이 이벤트와 함께 보낼 파라미터의 전체 명세입니다. 가장 자세히 읽어야 하는 영역입니다.

![이벤트 시트 2번 영역 — purchase 이벤트의 파라미터 명세 표. value(String·Event·32,500)·transaction_id(String·Event)·payment_method(String·Event·신용카드/네이버페이/무통장입금)·shipping(Number·Event·2,500)·item_id(String·Item·OGLAX25291IVX)·item_name(String·Item·올삭스)·item_category(String·Item·Accessories)·item_variant(String·Item·아이보리)·quantity(Number·Item·1)·price(Number·Item·30,000) 10개 행이 표시되어 있음](/wiki-assets/playbook/how-to-implement-event-taxonomy-for-developers/area2-params.png)

> 2번 영역 — purchase의 파라미터 명세. String/Number 데이터 타입과 Event/Item 데이터 수준이 한 시트에 모두 등장.

개발 시 반드시 확인할 항목:

- **이벤트 파라미터(이름)** — 그대로 키로 사용. 대소문자·언더스코어까지 정확히 일치시킵니다.
- **데이터 타입** — `String`은 따옴표로 감싼 문자열, `Number`는 따옴표 없는 숫자로 전송. 가격·수량처럼 계산이 필요한 값은 Number, 식별자·이름·코드는 String입니다(자세한 건 [파라미터의 타입(type)](/wiki/playbook/ga4-event-taxonomy-checklist/how-to-choose-ga4-parameter-types) 글).
- **데이터 수준** — `Event` / `User` / `Item` 중 하나. 자리에 따라 코드 작성 방법이 다릅니다(아래 ⑧절). 자세한 개념은 [파라미터의 수준(level)](/wiki/playbook/ga4-event-taxonomy-checklist/what-is-ga4-parameter-levels) 글.
- **예시값** — 가능한 값의 후보. 쉼표로 구분된 값이면 그중 어느 하나가 실제 전송 값으로 들어갑니다.
- **트리거번호** — `All`이면 모든 트리거에서 전송. `1`·`2`처럼 특정 번호가 적혀 있으면 그 트리거에서만 전송.

### 트리거번호별 조건부 전송

가장 자주 놓치는 부분입니다. 어떤 파라미터는 ‘1번 트리거에만 의미가 있고 2번 트리거에서는 없는 값’일 수 있습니다.

```
// 트리거 1번에서만 전송 — banner_name 포함
window.dataLayer.push({
  event: 'click_banner',
  trigger_no: 1,
  banner_name: 'main_top_promo'
});

// 트리거 2번에서만 전송 — banner_name 없음, side_section만
window.dataLayer.push({
  event: 'click_banner',
  trigger_no: 2,
  side_section: 'category_left'
});
```

처리 방법은 단순합니다 — **해당 트리거가 아니면 그 파라미터를 보내지 않습니다.** 키를 아예 제외하면 GA4 측에서 자동으로 ‘없음’으로 처리하므로 `null`이나 `undefined`를 명시할 필요 없고, 빈 문자열 `""`도 권장하지 않습니다.

## ⑤ 3번 영역 — 코드 샘플

개별 이벤트 시트에는 ‘설계자가 미리 작성해 둔 코드 샘플’이 들어 있습니다. 이 견본을 그대로 가져다 트리거 시점에 호출하면 1·2번 영역에서 정의한 그대로 데이터가 GA4로 흐릅니다.

![이벤트 시트 3번 영역 — 코드 샘플 박스. window.dataLayer.push({ event: ‘purchase’, value: 32500, transaction_id: ‘26021147321’, payment_method: ‘무통장입금’, shipping: 2, items: \[{ item_id: ‘OGLAX25291IVX’, item_name: ‘올삭스’, item_category: ‘Accessories’, item_variant: ‘아이보리’, quantity: 1, price: 30000 }\] }); 형태의 자바스크립트 코드가 표시되어 있음](/wiki-assets/playbook/how-to-implement-event-taxonomy-for-developers/area3-code.png)

> 3번 영역 — 코드 샘플. purchase 같은 전자상거래 이벤트는 items 배열 안에 상품 객체들이 들어가는 구조.

코드 샘플은 **키와 데이터 타입의 모양**을 보여 주기 위한 견본일 뿐 — 실제 값은 그 시점의 사용자 행동·결제 응답에서 동적으로 추출해 채웁니다.

> **주의**
>
> **샘플의 값을 그대로 사용하지 않습니다.** 예를 들어 코드 샘플에`item_name: '올삭스'`로 적혀 있다고 해서 ‘올삭스’를 그대로 사용하면 모든 구매가 ‘올삭스’로 기록됩니다. 결제 모듈의 응답·장바구니 상태에서 실제 상품 정보를 동적으로 꺼내 채워야 합니다.

### 전송 방법 — dataLayer.push가 기본

코드 샘플은 GTM(Google Tag Manager)을 거치는 `dataLayer.push` 방식으로 작성되어 있습니다. 이 push가 GTM의 ‘맞춤 이벤트’ 트리거를 발화시키고, GTM에서 GA4 이벤트 태그가 자동으로 발송됩니다. ‘**왜 GTM을 거치는가**’의 원리는 [Data Layer와 GTM](/wiki/playbook/ga4-event-taxonomy-checklist/data-layer-and-gtm-guide) 글에서 다룹니다.

## ⑥ 4번 영역 — 추가 논의 히스토리

구현 도중 의문이 생기거나 설계와 다른 상황을 발견하면, 메신저보다 ‘**추가 논의 히스토리**’ 영역에 직접 기록합니다. 질의자·질의 일자·코멘트 및 답변·상태 네 컬럼에 남기면 허들러스 측 담당자가 답변을 달고, 결정 사항은 1·2번 영역에 반영됩니다.

![이벤트 시트 4번 영역 — ‘추가 논의 히스토리’ 표. 질의자 · 질의 일자 · 코멘트 및 답변 · 상태 4개 컬럼](/wiki-assets/playbook/how-to-implement-event-taxonomy-for-developers/area4-history.png)

> 4번 영역 — 시트 안에서 질의·답변을 모두 처리합니다. 메신저로 흩어지는 결정 없이 ‘이 이벤트에 대한 모든 논의’가 한 자리에 남습니다.

‘이 파라미터는 어디서 값을 꺼내나요?’·‘트리거 시점이 PC와 모바일이 다른데 모바일은 정확히 언제인가요?’·‘items 배열 안 변수 매핑이 어렵습니다’ 같은 질문은 이곳에 남기면 결정의 추적성이 보장됩니다.

## ⑦ 5번 영역 — 트리거 시점 참고 이미지 (두 케이스)

5번 영역은 이벤트 종류에 따라 ‘**이미지를 첨부하는 경우**’와 ‘**비워 두는 경우**’로 나뉩니다. 같은 시트 안의 다섯 영역 중 유일하게 ‘이벤트 성격에 따라 달라지는’ 영역입니다.

### CASE 1 — 행동 이벤트: 이미지가 첨부되어 있습니다

`click_gnb`·`click_banner`·`click_floating_kakao` 같은 **행동 이벤트**는 사용자가 ‘**어디를 클릭했는지**’가 곧 트리거 정의의 핵심이라서, PC/모바일 화면 캡처가 5번 영역에 들어 있습니다. 개발자는 1번 영역의 ‘발생 시점 설명’ 문장만으로 위치를 잡기 어려울 때 이 이미지를 보고 클릭 범위·근접 요소를 확정합니다.

![행동 이벤트(click_gnb)의 5번 영역 — ‘트리거 시점 참고 이미지’ 표. 트리거번호 1 · 페이지명 ‘공통’ · PC 화면 설명 컬럼에 PC GNB 영역이 노란색으로 강조된 사이트 캡처, MO 컬럼에 모바일 GNB 메뉴가 펼쳐진 사이트 캡처가 들어가 있는 모습](/wiki-assets/playbook/how-to-implement-event-taxonomy-for-developers/area5-image-with.png)

> CASE 1 — 행동 이벤트. PC/모바일 두 환경 모두 트리거가 발생하는 UI 위치를 캡처로 확인할 수 있습니다.

### CASE 2 — 주요 이벤트: 이미지가 비어 있습니다

`purchase`·`sign_up`·`add_payment_info` 같은 **주요 이벤트**는 5번 영역이 비어 있고 ‘구매 완료 시점(통신)이므로 별도 이미지 제공 없음’ 같은 안내만 적혀 있습니다. 이런 이벤트의 트리거는 화면의 어떤 버튼 클릭이 아니라 ‘**내부 통신이 정상 완료된 콜백**’이기 때문입니다 — 시각적으로 표현할 화면 위치가 없습니다.

![주요 이벤트(purchase)의 5번 영역 — ‘트리거 시점 참고 이미지’ 표. 트리거번호 1 · 페이지명 ‘공통’ · PC와 MO 컬럼에 사이트 화면 캡처 대신 ‘구매 완료 시점(통신)이므로 별도 이미지 제공 없음’이라는 빨간 안내 문구가 표시되어 있는 모습](/wiki-assets/playbook/how-to-implement-event-taxonomy-for-developers/area5-image-none.png)

> CASE 2 — 주요 이벤트. 결제 완료 콜백·가입 완료 콜백처럼 ‘내부 통신 시점’이 트리거라 시각적 위치 표현이 불가능합니다.

> **주의**
>
> **주요 이벤트의 트리거는 ‘버튼 클릭’이 아닙니다.** 결제·가입 같은 주요 이벤트의 코드는 반드시 ‘**API 응답 success 분기 내부**’ 또는 ‘**완료 페이지(thank-you page) 로드 직후**’에 심습니다. 결제 버튼 클릭 시점에 심으면 결제 실패·중복 클릭·결제 취소까지 같이 카운트되어 매출 데이터가 부풀려집니다. 정합성이 가장 중요한 이벤트이므로 절대 시각적 위치(버튼)에 심지 마세요.

## ⑧ 데이터 수준별 코드 — Event / User / Item

2번 영역의 ‘데이터 수준’ 컬럼은 단순한 분류가 아닙니다 — 각 수준은 **코드 작성 방법이 다릅니다**. (자세한 개념은 ‘[파라미터의 수준(level)](/wiki/playbook/ga4-event-taxonomy-checklist/what-is-ga4-parameter-levels)’ 참조.)

### Event 수준

이벤트 호출의 매개변수 객체 안에 그대로 넣습니다.

```
window.dataLayer.push({
  event: 'click_gnb',
  gnb_name: 'Resources'   // ← Event 수준
});
```

### User 수준

로그인 직후·자동 로그인 복원 직후·회원 정보 변경 직후 등 ‘**사용자 식별 가능 시점**’에 한 번 발송합니다. 이후 같은 사용자의 모든 이벤트에 자동 첨부됩니다(페이지 로드와는 무관).

```
window.dataLayer.push({
  event: 'set_user_property',
  user_properties: {
    membership_grade: 'VIP',
    is_subscriber: 'true',
    signup_date: '2024-08-15'
  }
});
```

### Item 수준

전자상거래 이벤트의 `items` 배열 안 각 상품 객체에 들어갑니다. 같은 이벤트라도 상품마다 다른 값을 가질 수 있습니다 — purchase의 items 배열이 가장 대표적입니다.

```
window.dataLayer.push({
  event: 'purchase',
  transaction_id: '26021147321',
  value: 32500,
  payment_method: '무통장입금',
  shipping: 2,
  items: [
    {
      item_id: 'OGLAX25291IVX',
      item_name: '올삭스',
      item_category: 'Accessories',
      item_variant: '아이보리',
      quantity: 1,
      price: 30000
    }
  ]
});
```

한 거래에 상품 두 개 이상이 담길 때는 `items` 배열 안에 객체를 그만큼 늘립니다. 거래 자체의 정보(`transaction_id`·`value`·`shipping`)는 한 번씩만 넣고, 상품 정보는 상품 개수만큼 반복합니다.

## ⑨ 공통 파라미터 시트 — 호출 시점 두 가지

‘공통 파라미터 시트’에는 두 가지 정보가 정의되어 있고, **호출 시점이 다릅니다**.

![공통 파라미터 시트 — 상단에 ‘공통 파라미터’ 설명, 하단에 1번 페이지 공통 파라미터 표(site_language·market_code·platform 등)와 2번 유저 속성 파라미터 표(user_id 등), 그리고 우측에 코드 샘플이 배치되어 있음](/wiki-assets/playbook/how-to-implement-event-taxonomy-for-developers/04-common-param.png)

> 공통 파라미터 시트 — 페이지 공통 파라미터와 유저 속성을 한 시트에서 정의. 두 가지의 호출 시점이 다르므로 분리해 구현합니다.

- **페이지 공통 파라미터**(사이트 언어·플랫폼·시장 코드 등) — 각 페이지가 로드되는 직후 한 번 호출합니다. 페이지 이동 시마다 새로 push 됩니다.
- **유저 속성**(회원 ID·등급·가입일·구독 여부 등) — 사용자가 식별 가능해진 시점에 한 번 호출합니다. 보통 로그인 직후, 자동 로그인 복원 직후, 또는 회원 정보가 변경된 직후입니다. 페이지 로드와는 무관합니다.

개발 흐름은 — ① 페이지 로드 직후 페이지 공통 파라미터 push, ② 로그인 등으로 사용자가 식별되면 유저 속성 push, ③ 이후 각 행동 이벤트는 자신만의 파라미터만 push. 공통 파라미터를 개별 이벤트 시트에 중복으로 적지 않습니다.

## ⑩ 자체 검증 — 콘솔에서 dataLayer 확인

구현이 끝나면 사이트로 이동해 브라우저 콘솔에서 데이터가 정상적으로 들어가는지 확인합니다. ‘이벤트가 GA4까지 갔는가’는 GTM·GA4 디버그뷰에서 확인하지만, ‘**dataLayer까지 정상적으로 도달했는가**’는 사이트 콘솔에서 직접 눈으로 볼 수 있고, 이 단계가 자체 검증의 핵심입니다.

### 3단계 흐름

사이트로 이동해 ‘**① 이벤트 발생 → ② 콘솔에 dataLayer 입력 → ③ 결과 배열 확인**’ 세 단계로 진행합니다.

> **다이어그램 설명:** 자체 검증 3단계 다이어그램. 좌측 위 1번 — 사이트 GNB에서 ‘EXPERIENCE’ 메뉴 클릭을 일으킨다. 우측 위 2번 — Chrome 개발자 도구 콘솔에서 ‘dataLayer’를 입력한다. 그 아래 3번 — 콘솔에 출력된 배열을 펼쳐 ‘event: click_gnb’와 ‘menu_name: EXPERIENCE’ 파라미터가 정상적으로 들어갔는지 확인한다는 흐름이 화살표로 연결되어 있음

자체 검증 3단계 — 사이트에서 이벤트 발생 → 콘솔에 `dataLayer` 입력 → 결과 배열에서 내가 일으킨 이벤트와 파라미터를 확인. 허들러스 측 최종 검증은 별도로 진행되지만, 이 자체 검증이 통과되어야 ‘세팅 완료’ 상태로 넘어갈 수 있습니다.

### 콘솔 사용 팁

- **개발자 도구 열기** — 페이지에서 우클릭 → ‘검사(Inspect)’, 또는 단축키 ⌘ + ⌥ + I(Mac) · F12(Windows). 상단 탭에서 **Console** 선택.
- **새로고침 후 검증** — 페이지에 머물러 있던 동안 쌓인 dataLayer가 길어지면 항목 찾기가 번잡합니다. 새로고침 후 ‘검증하려는 행동’만 한 번 하고 콘솔을 확인하는 편이 깔끔합니다.
- **특정 인덱스만 보기** — `dataLayer[5]`처럼 인덱스로 접근하면 그 항목만 펼쳐집니다. 새로 push 된 항목은 보통 배열 끝쪽에 있습니다.
- **JSON으로 보기** — `JSON.stringify(dataLayer[5], null, 2)`를 입력하면 그 객체가 들여쓰기된 텍스트로 출력되어 시트의 코드 샘플과 한 줄씩 비교하기 쉬워집니다.

허들러스 측 검증은 GTM Preview 모드·GA4 디버그뷰·BigQuery에서 별도로 진행되지만, 개발팀 단계에서 위 자체 검증이 통과되어야 전체 일정이 막힘없이 진행됩니다.

## ⑪ 구현 워크플로 — 한 이벤트를 끝까지

새 이벤트 한 건을 받아 사이트에 심고 ‘세팅 완료’ 처리하기까지의 권장 순서.

1. **1번 영역으로 ‘어디서 호출할지’ 확정**
  
  트리거번호·페이지명·Platform·발생 시점 설명을 읽습니다. 5번 영역에 이미지가 있으면 그 위치를 시각적으로 한 번 더 확정합니다(이미지가 비어 있으면 ‘내부 통신 시점’ 이벤트이므로 API 응답 success 분기에서 호출).
2. **2번 영역으로 파라미터 매핑**
  
  각 파라미터의 이름·데이터 타입·데이터 수준을 정리. 트리거번호 컬럼을 보고 ‘이 트리거에서만 보낼 파라미터’와 ‘공통 파라미터’를 분리.
3. **3번 코드 샘플을 가져와 사이트 코드에 이식**
  
  키 이름·구조는 그대로, 값은 사용자 행동·결제 응답에서 동적으로 추출. `window.dataLayer.push({...})` 호출을 정확한 트리거 시점에 배치합니다.
4. **콘솔에서 자체 검증**
  
  Chrome 개발자 도구 콘솔에서 `dataLayer`를 입력해 정의한 키·값이 들어가는지 확인. 가능하면 GA4 디버그뷰까지 열어 이벤트가 들어오는지 같이 확인.
5. **의문이 생기면 4번 히스토리에 질의 등록**
  
  설계 의도가 모호하거나 추출할 값이 명확하지 않으면 메신저보다 시트 안에 남깁니다. 답변과 결정이 시트에 함께 남아 이후 추적이 쉽습니다.
6. **‘대기중 → 세팅 완료’ 상태 변경**
  
  1번 영역과 2번 영역 모두의 ‘세팅 상태’ 셀을 ‘세팅 완료’로 갱신. 이 시점부터 허들러스 측 검수가 시작되고, ‘검수 완료’가 되면 이 이벤트 작업이 종료됩니다.

> **팁**
>
> **‘세팅 완료’ 처리 전 자체 점검 세 가지**— ① 1번 영역에 명시된 모든 트리거 시점에 코드가 심어져 있는가, ② 2번 영역의 모든 파라미터가 정의된 데이터 타입·수준대로 전송되는가, ③ 트리거번호별 조건부 전송이 정확한가(특정 트리거에서만 보낼 파라미터가 다른 트리거로 새 들어가지 않는가). 셋 다 통과하면 ‘세팅 완료’로 상태를 갱신.

## 자주 묻는 질문

### `dataLayer.push`는 GTM이 없어도 동작하나요?

dataLayer 자체는 단순한 자바스크립트 배열이라 GTM이 없어도 push는 됩니다. 다만 그 push가 GA4로 흐르려면 GTM의 ‘맞춤 이벤트’ 트리거가 잡아 GA4 태그를 발화해 줘야 합니다. GTM이 없는 사이트라면 `gtag('event', '...', {...})`를 직접 호출하는 방식으로 바꿔 사용합니다 — 코드 샘플은 GTM 방식이지만 광고주 환경에 따라 변환해도 됩니다.

### 파라미터 값이 가끔 누락될 때는 어떻게 처리하나요?

값을 못 꺼내는 경우 그 키를 **아예 보내지 않습니다**. 보내지 않으면 GA4는 그 이벤트에서 해당 파라미터가 ‘없음’으로 처리합니다. 굳이 `null`이나 `undefined`를 명시할 필요 없고, 빈 문자열 `""`도 권장하지 않습니다(빈 문자열은 ‘값이 있음 — 빈 문자열’로 잡혀 분석을 혼란스럽게 합니다).

### `purchase` 이벤트를 ‘구매 완료 버튼 클릭’에 호출해도 되나요?

안 됩니다. 결제 버튼 클릭에 호출하면 결제 실패·중복 클릭·결제 취소도 같이 카운트되어 매출 데이터가 부풀려집니다. 결제 모듈의 ‘**결제 완료 콜백 success 분기**’ 또는 ‘결제 완료 페이지(thank-you page) 로드 직후’가 정확한 트리거입니다. 1번 영역의 ‘발생 시점 설명’에 보통 ‘구매 완료 시점’이라고 명시되어 있고, 5번 영역의 이미지가 비어 있는 이유입니다.

### 한 거래에 상품이 여러 개일 때 items 배열은 어떻게 채우나요?

`items` 배열 안에 상품 객체를 상품 개수만큼 넣습니다. 거래 자체의 정보(`transaction_id`·`value`·`shipping`·`payment_method`)는 한 번씩만 적고, 상품 정보(`item_id`·`item_name`·`price`·`quantity`…)는 반복합니다. `value`는 모든 상품의 `price × quantity` 합계와 일치시키는 것이 권장됩니다.

### 유저 속성(User 수준)은 매 페이지마다 다시 보내야 하나요?

아니요 — 로그인 직후 또는 사용자가 식별 가능해진 시점에 ‘**한 번만**’ 보내면 됩니다. 한 번 발송된 유저 속성은 GA4가 그 사용자의 모든 이후 이벤트에 자동 첨부합니다. 매 페이지에 다시 보내면 같은 값이라 무해하긴 하나 트래픽만 늘어납니다. 등급이 바뀌었거나 로그아웃 시점에는 새 값으로 한 번 더 보내 갱신합니다.

### 설계자가 정의한 값과 다른 값을 보내야 할 상황이 있다면?

임의 변경은 금지입니다. 4번 ‘추가 논의 히스토리’ 영역에 사유와 함께 질의를 남기고, 설계자가 1·2번 영역을 갱신한 다음 다시 코드를 수정합니다. 한 사람이라도 임의로 값 표기를 바꾸면 데이터가 두 갈래로 갈라져 분석이 어긋납니다.

### ‘세팅 완료’로 바꾸기 전 최종 점검은?

세 가지를 한 번 더 확인합니다 — ① 1번 영역에 명시된 모든 트리거 시점에 코드가 심어져 있는가, ② 2번 영역의 모든 파라미터가 정의된 데이터 타입대로 전송되는가, ③ 트리거번호별 조건부 전송이 정확한가. 셋 다 통과하면 ‘세팅 완료’로 상태를 갱신하고, 그 이후로는 허들러스 측 검수 결과를 기다립니다.

## 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)