이벤트 택소노미 문서 — 설계 담당자용
허들러스 이벤트 택소노미 문서는 한 광고주의 GA4 이벤트·파라미터·트리거 시점 전체를 ‘한 시트 안에서’ 정의하고 추적하기 위한 작업 공간입니다. 시트 구성과 각 시트의 역할, 그리고 ‘이벤트 시트’의 다섯 영역이 어떤 의미를 갖는지를 알면 설계 → 개발 → 검수의 흐름을 막힘없이 운영할 수 있습니다.
① 문서 전체 구조
이벤트 택소노미 문서는 시트 단위로 나뉩니다. ‘01. 개요’ 시트는 사용 안내라 작업과는 직접 관련이 없고, 실제 설계는 02번 시트부터 시작됩니다.
- 02. 컨텐츠 그룹 — 이벤트가 발생하는 ‘페이지’의 인덱스
- 03. 이벤트 리스트(Event List) — 설계 전체안의 이벤트 한눈 보기
- 04. 파라미터 리스트(Parameter List) — 사용할 파라미터 전체 목록
- 공통 파라미터 — 모든 페이지·이벤트에 자동으로 따라붙는 변수와 유저 프로퍼티
- 각 이벤트 시트(
purchase·click_gnb· …) — 개별 이벤트의 트리거·파라미터·코드 샘플·히스토리·트리거 이미지
설계 작업의 흐름은 ‘페이지 인덱스(02) → 전체 이벤트 명세(03) → 파라미터 명세(04) → 공통 항목 정의 → 개별 이벤트 시트 작성’ 순으로 자연스럽게 이어집니다.
② 02 시트 — 컨텐츠 그룹 인덱스
이전 단계에서 컨텐츠 그룹핑 작업(사이트의 페이지를 묶어 ‘공통·구매 완료·상품 상세·이벤트 상세·브랜드 소개’ 등의 그룹으로 분류한 결과)을 거쳤다면, 그 결과를 이 시트에 인덱싱해 둡니다.
이 시트의 인덱스가 중요한 이유는 — 이후 ‘각 이벤트 시트’에서 ‘이 이벤트가 어느 페이지(컨텐츠 그룹)에서 발생하는가’를 정의할 때 여기서 정의한 그룹명을 그대로 참조하기 때문입니다. 페이지 이름을 자유롭게 쓰면 사람마다 다른 표기가 섞여 데이터가 흩어지므로, 컨텐츠 그룹 인덱스로 ‘표기 단일화’를 보장합니다.
기본 항목 두 개
- 공통 — 모든 페이지에 적용되는 공통 영역(예: GNB·푸터·팝업 등 페이지에 종속되지 않는 UI). 임의 수정 금지.
- 구매 완료 — 결제 직후 도달하는 페이지.
purchase이벤트가 발생하는 자리.
이외의 항목은 광고주의 사이트 구조에 따라 컨텐츠 그룹핑 결과를 그대로 채워 넣습니다.
③ 03 시트 — 이벤트 리스트(Event List)
설계 전체안의 이벤트들이 한 시트에 펼쳐져 있어 ‘무엇이 있고 무엇이 없는지’를 한눈에 검토할 수 있는 시트입니다. 설치 예정 + 설치된 이벤트 전체가 들어가며, 각 이벤트별로 어떤 파라미터가 함께 발송되는지도 같이 보입니다.
설계 검토 회의나 외부 공유 단계에서 가장 많이 펼치는 시트입니다 — ‘이벤트가 너무 많지 않은가’·‘분류가 일관된가’·‘비슷한 이벤트가 중복 정의돼 있지 않은가’를 한 자리에서 점검할 수 있습니다.
④ 04 시트 — 파라미터 리스트(Parameter List)
사용할 파라미터 전체의 사전입니다. 공통 파라미터를 포함해 모든 이벤트에서 등장하는 파라미터가 한 자리에 정리되어 있어, 새 파라미터를 추가할 때 ‘이미 있는 이름인지’ 검색해 보고 들어가는 안전망 역할을 합니다.
‘같은 의미, 같은 이름’ 원칙을 지키려면 새 파라미터를 정의할 때마다 이 시트를 먼저 열어 보고 — 비슷한 의미의 기존 이름이 있는지 확인하는 습관이 필요합니다.
⑤ ‘공통 파라미터’ 시트
두 가지가 정의되어 있고 발송 시점이 다릅니다. ① 페이지 공통 파라미터 — 모든 페이지 로드 시 자동으로 따라붙어야 하는 변수(사이트 언어·플랫폼·시장 코드 등). 페이지가 새로 로드될 때마다 다시 push 됩니다. ② 유저 속성(user property) — 사용자가 식별 가능해진 시점(로그인 직후 등)에 한 번 부여되어 이후 모든 이벤트에 자동 첨부되는 정보(회원 ID·등급·가입일 등). 페이지 로드와는 무관하게 ‘사용자 식별 가능 시점’에 한 번 호출합니다.
여기에 정의된 파라미터는 ‘개별 이벤트 시트’에서 다시 적지 않습니다. 한 번 정의하면 자동으로 모든 이벤트에 따라붙기 때문입니다. 파라미터를 어느 자리에 두느냐의 자세한 개념은 ‘파라미터의 수준(level)’에서 다룹니다.
⑥ 각 이벤트 시트 — 5개 영역
공통 파라미터 시트 다음부터는 purchase·click_gnb·view_item 같은 개별 이벤트 시트가 이어집니다. 모든 이벤트 시트는 동일한 5개 영역으로 구성됩니다 — 아래는 purchase 시트를 예시로 한 화면입니다(다양한 데이터 타입과 수준이 한 시트에 등장해 가장 풍부한 예시).
1번 영역 — 트리거 발생 시점
이 이벤트가 PC/Mo 환경에서 ‘언제·어디서’ 발생하는지를 정의하는 영역입니다. 컬럼은 트리거번호·페이지명·Platform·발생 시점 설명·세팅 상태로 구성됩니다.
트리거번호가 핵심 개념입니다. 같은 이벤트라도 발생 시점이나 영역이 여러 개일 수 있습니다 — 예를 들어 click_banner가 메인 페이지의 상단 배너에서 한 번, 카테고리 페이지의 사이드 배너에서 한 번 발생한다면 각각 1번·2번 트리거로 구분합니다. 트리거번호는 같은 이벤트 안에서 발생 위치를 식별하는 키입니다.
2번 영역 — 파라미터 명세
이 이벤트와 함께 발송할 파라미터의 사전입니다. 이벤트 이름·이벤트 파라미터·설명·데이터 타입·데이터 수준·예시값·트리거번호·세팅 상태·비고 컬럼으로 구성됩니다.
설계 시 자주 보게 되는 두 핵심 컬럼:
- 데이터 타입 —
String또는Number(파라미터의 타입(type)에서 자세히) - 데이터 수준 —
Event·User·Item중 하나(파라미터의 수준(level)에서 자세히)
트리거번호 컬럼의 활용 — 어떤 파라미터는 1번 트리거에만, 어떤 파라미터는 2번 트리거에만 의미가 있을 수 있습니다. 그럴 경우 트리거번호 컬럼에 해당 트리거 번호만 적어 두면 됩니다(모든 트리거에 공통이면 ‘All’). 개발 단계에서는 해당 트리거가 아닐 때 그 파라미터를 보내지 않으면 됩니다 — 보내지 않으면 GA4가 자동으로 undefined로 처리합니다.
3번 영역 — 코드 샘플
이 이벤트를 실제 사이트에 심을 때 사용할 코드의 견본입니다. window.dataLayer.push({...}) 형태로 작성되어 있고, 위 1·2번 영역에서 정의한 이벤트 이름과 파라미터가 그대로 들어가 있습니다.
4번 영역 — 추가 논의 히스토리
설계·개발·검수 과정에서 발생한 질의·답변·문제를 날짜별로 저장하는 영역입니다. 누가 언제 어떤 질문을 했고 어떻게 정리되었는지를 한 자리에 두어, 이후 새 이슈가 떠올랐을 때 ‘이전에 같은 얘기를 했는지’ 빠르게 확인할 수 있습니다.
5번 영역 — 트리거 시점 참고 이미지
문장만으로 설명하기 어려운 ‘이 버튼이 정확히 어디 있는지’·‘이 영역의 클릭 범위는 어디까지인지’를 이미지로 표현하는 영역입니다. PC/Mo 화면 각각에 트리거 시점을 표시한 캡처가 들어갑니다.
이 영역은 이벤트 종류에 따라 ‘이미지를 첨부하는 경우’와 ‘비워 두는 경우’로 나뉩니다. 같은 이벤트 시트라도 이 두 패턴이 공존합니다.
CASE 1 — 행동 이벤트: 이미지를 첨부합니다
click_gnb·click_banner·click_floating_kakao 같은 ‘행동 이벤트’는 사용자가 ‘어디를 클릭했는지’가 곧 트리거 정의의 핵심이라서, PC/모바일 화면 캡처를 5번 영역에 반드시 첨부합니다. 문장만으로는 ‘이 버튼이 정확히 어디 있는지’를 전달하기 어렵기 때문입니다.
CASE 2 — 주요 이벤트: 이미지를 비워 둡니다
purchase·sign_up·add_payment_info 같은 ‘주요 이벤트’는 5번 이미지 영역을 비워 둡니다. 이런 이벤트의 트리거는 화면의 어떤 버튼 클릭이 아니라 ‘내부 통신이 정상 완료된 콜백’이기 때문에 시각적으로 표현할 화면 위치가 없습니다. 그래서 5번 영역에는 ‘구매 완료 시점(통신)이므로 별도 이미지 제공 없음’ 같은 설명만 적혀 있고, PC/MO 캡처 자리는 비어 있습니다.
⑦ 세팅 상태 흐름
1번 영역(트리거 발생 시점)과 2번 영역(파라미터 명세)에는 ‘세팅 상태’ 컬럼이 있습니다. 이 상태값이 설계 → 개발 → 검수의 진행을 추적하는 단일 지표입니다.
STEP 1
대기중
담당 — 설계 담당자
설계자가 이벤트·파라미터·코드 샘플을 작성해 둔 상태. 개발자가 작업을 가져가기 전까지 이 상태를 유지합니다.
STEP 2
세팅 완료
담당 — 광고주 개발 담당자
개발자가 사이트에 코드를 심고 ‘대기중 → 세팅 완료’로 상태를 변경. 이 시점부터 데이터가 실제로 GA4로 흐르기 시작합니다.
STEP 3
검수 완료
담당 — 허들러스
허들러스가 GA4·태그 매니저·디버그뷰로 ‘이 이벤트가 설계대로 정확히 들어오는지’를 검증한 뒤 ‘검수 완료’로 마무리. 이 시점에 이 이벤트의 구현 작업이 종료됩니다.
설계 담당자는 ‘대기중’ 상태로 작업물을 넘기는 것까지가 첫 책임이고, 이후엔 4번 히스토리 영역에 올라오는 질의에 답하면서 검수가 끝날 때까지 모니터링합니다.
자주 묻는 질문
새 이벤트를 추가할 때 어디서부터 시작하나요?
① 04 파라미터 리스트에서 ‘이미 같은 의미의 파라미터가 있는지’ 검색 → ② 새 시트를 만들고 ③ 1번 영역(트리거 발생 시점)부터 채웁니다. 이벤트 이름을 정한 뒤 트리거번호·페이지명·발생 시점 설명을 적고, 이어 2번 영역(파라미터)·3번 영역(코드 샘플)·5번 영역(이미지)을 채웁니다. 마지막으로 03 이벤트 리스트에도 행을 추가해 전체 목록과 동기화합니다.
같은 이벤트의 트리거가 둘 이상이면 시트도 두 개로 나누나요?
아니요 — 시트는 이벤트 이름당 1개입니다. 트리거가 여러 개면 1번 영역의 행을 늘려 트리거번호 1·2·3 식으로 구분합니다. 2번 파라미터 영역에서도 ‘이 파라미터는 1번 트리거에만 필요’ 같은 식으로 트리거번호 컬럼에 표시해 두면, 개발 단계에서 해당 트리거에서만 그 값을 전송합니다.
‘공통’ 페이지명은 언제 쓰나요?
특정 페이지에 종속되지 않는 이벤트일 때 사용합니다. GNB·푸터·전역 팝업·플로팅 버튼 등 모든 페이지에서 같은 동작을 하는 UI 영역이 ‘공통’입니다. 02 컨텐츠 그룹 시트에서 ‘공통’ 항목이 기본 항목으로 들어가 있는 이유이기도 합니다.
왜 주요 이벤트는 트리거 시점 이미지를 안 찍나요?
주요 이벤트(purchase·sign_up 등)는 ‘버튼을 클릭한 순간’이 아니라 ‘내부 처리가 정상 완료된 순간’을 트리거로 잡습니다 — 구매 콜백이 정상 응답한 직후·가입이 서버에서 완료된 직후. 클릭 위치가 아니라 ‘처리 완료 콜백’이 트리거이므로 이미지로 표현할 화면 위치가 없습니다. 이런 이벤트들은 정합성이 가장 중요하므로 시각 묘사 대신 ‘어떤 통신 콜백에 붙이는지’를 1번 영역의 발생 시점 설명에 명확히 적어 두는 것이 핵심입니다.
설계자가 ‘세팅 상태’를 직접 변경할 일이 있나요?
없습니다. ‘대기중’은 설계 시 기본값이고, ‘세팅 완료’는 광고주 개발 담당자가, ‘검수 완료’는 허들러스 담당자가 변경합니다. 설계자가 임의로 ‘세팅 완료’로 바꾸면 검수 대상이 사라져 누락이 생길 수 있어 권한이 분리되어 있습니다.
파라미터를 추가하거나 변경했을 때 03·04 시트와 어떻게 맞추나요?
03 이벤트 리스트와 04 파라미터 리스트는 각 이벤트 시트의 ‘목차’ 역할이므로, 개별 시트의 파라미터를 추가/변경했다면 두 시트에도 같은 변경을 반영해야 일관성이 유지됩니다. 가장 안전한 흐름은 ‘개별 이벤트 시트 → 04 파라미터 리스트 → 03 이벤트 리스트’ 순으로 동기화하는 것.
컨텐츠 그룹에 없는 페이지에서 이벤트가 발생하면?
02 컨텐츠 그룹 시트에 그 페이지 그룹을 먼저 추가하고, 그 이름을 개별 이벤트 시트의 페이지명 컬럼에서 참조합니다. 컨텐츠 그룹 인덱스에 없는 이름을 그냥 적어 버리면 ‘공통’과 ‘공 통’처럼 표기가 흩어져 분석 시 데이터가 분리됩니다.