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

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

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

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

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

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

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

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

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

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

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

각 컬럼의 의미:

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

트리거가 여러 개일 때

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

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

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

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

• 이벤트 파라미터(이름) — 그대로 키로 사용. 대소문자·언더스코어까지 정확히 일치시킵니다.
• 데이터 타입 — String은 따옴표로 감싼 문자열, Number는 따옴표 없는 숫자로 전송. 가격·수량처럼 계산이 필요한 값은 Number, 식별자·이름·코드는 String입니다(자세한 건 파라미터의 타입(type) 글).
• 데이터 수준 — Event / User / Item 중 하나. 자리에 따라 코드 작성 방법이 다릅니다(아래 ⑧절). 자세한 개념은 파라미터의 수준(level) 글.
• 예시값 — 가능한 값의 후보. 쉼표로 구분된 값이면 그중 어느 하나가 실제 전송 값으로 들어갑니다.
• 트리거번호 — 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로 흐릅니다.

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

전송 방법 — dataLayer.push가 기본

코드 샘플은 GTM(Google Tag Manager)을 거치는 dataLayer.push 방식으로 작성되어 있습니다. 이 push가 GTM의 ‘맞춤 이벤트’ 트리거를 발화시키고, GTM에서 GA4 이벤트 태그가 자동으로 발송됩니다. ‘왜 GTM을 거치는가’의 원리는 Data Layer와 GTM 글에서 다룹니다.

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

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

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

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

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

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

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

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

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

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

2번 영역의 ‘데이터 수준’ 컬럼은 단순한 분류가 아닙니다 — 각 수준은 코드 작성 방법이 다릅니다. (자세한 개념은 ‘파라미터의 수준(level)’ 참조.)

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)는 한 번씩만 넣고, 상품 정보는 상품 개수만큼 반복합니다.

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

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

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

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

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

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

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번 영역 모두의 ‘세팅 상태’ 셀을 ‘세팅 완료’로 갱신. 이 시점부터 허들러스 측 검수가 시작되고, ‘검수 완료’가 되면 이 이벤트 작업이 종료됩니다.

자주 묻는 질문