이벤트 설계 및 전송 가이드¶

이벤트 텍소노미란?¶

이벤트 텍소노미(Event Taxonomy)는 수집하는 이벤트와 속성을 일관된 구조와 명명 규칙으로 체계화한 분류 체계입니다.

게임에서 발생하는 수많은 행동 데이터(로그인, 구매, 레벨업 등)를 아무 규칙 없이 수집하면, 팀마다 다른 이름으로 같은 데이터를 보내거나 분석 시 어떤 데이터가 무엇을 의미하는지 파악하기 어려워집니다. 이벤트 텍소노미는 이러한 혼란을 방지하고, 수집된 데이터를 분석에 바로 활용할 수 있도록 돕습니다.

왜 필요한가요?¶

구조¶

애널리틱스의 이벤트 텍소노미는 이벤트와 속성 두 계층으로 구성됩니다.

이벤트 (Event)
├── 플랫폼 속성 (Platform Attribute)   ← SDK 연동만으로 자동 수집
└── 이벤트 속성 (Event Attribute)      ← 이벤트와 함께 직접 전송

이벤트란?¶

이벤트는 유저가 게임 내에서 수행한 특정 행동을 데이터로 기록한 단위입니다. "언제, 누가, 무엇을 했는가"를 담고 있으며, 분석의 가장 기본 단위가 됩니다.

• 예: 유저가 아이템을 구매했다 → item_purchase 이벤트 발생
• 예: 유저가 특정 스테이지를 클리어했다 → stage_clear 이벤트 발생
• 예: 유저가 앱에 로그인했다 → login 이벤트 발생

속성이란?¶

속성은 이벤트가 발생했을 때 함께 기록되는 세부 정보입니다. 이벤트만으로는 "무슨 일이 일어났는지"만 알 수 있지만, 속성을 통해 "어떤 조건에서, 어떤 값으로" 발생했는지까지 파악할 수 있습니다.

• 예: item_purchase 이벤트의 속성 → 아이템 ID, 결제 금액, 통화 단위
• 예: stage_clear 이벤트의 속성 → 스테이지 번호, 클리어 시간, 사용 캐릭터

속성은 수집 주체에 따라 두 가지로 나뉩니다.

• 플랫폼 속성: 별도 설정 없이 SDK 연동만으로 Hive에서 기본 수집하는 속성입니다. 국가, OS, 앱 버전, 서버 ID 등이 포함됩니다.
• 이벤트 속성: 이벤트와 함께 직접 전송하는 속성입니다. 분석에 필요한 항목을 직접 정의하고 전송합니다.

사용자 정의 이벤트 전송¶

게임에서 직접 정의한 이벤트(사용자 정의 이벤트)는 아래 수집 스키마에 맞춰 전송하면 애널리틱스에서 분석에 활용할 수 있습니다.

실제 데이터 전송은 Hive SDK 클라이언트 로그 전송 방법을 사용합니다. 전송에 필요한 소스 코드는 이벤트의 [소스 생성] 탭에서 언어별로 자동 생성할 수 있습니다.

이벤트 전송 전에 이벤트에서 이벤트명과 속성을 미리 정의해두면 팀 내 공유와 관리가 편리합니다. 단, 사전 정의 없이 데이터를 전송하더라도 애널리틱스가 수신된 데이터를 자동으로 인식하며, 최대 1시간 이내에 이벤트 목록에 반영됩니다.

애널리틱스 수집 스키마¶

사용자 정의 이벤트를 전송할 때 사용하는 기본 스키마입니다. 모든 이벤트는 아래 형식으로 전송해야합니다.

이벤트명 명명 규칙¶

eventName에 사용할 이벤트명은 아래 규칙을 따라 작성할 것을 권고합니다.

• 권장 문자: 영문(a–z, A–Z, 대/소문자 구분), 숫자(0–9), 언더바(_), 하이픈(-)
• 구분자: 단어 사이는 공백이 아닌 언더바(_)로 구분
• 형태: 이벤트를 명확하게 설명하는 명사_동사 형태 권장
• 예시: item_purchase, level_up, tutorial_complete, stage_start

hiveAttribute / eventAttribute 구조 예시¶

hiveAttribute와 eventAttribute는 각각 JSON 객체 형태로 전송합니다.

hiveAttribute — Hive 프로비저닝 서버에서 제공하는 플랫폼 속성입니다. 마켓, 서버 ID 등이 해당되며, 현재는 개발자가 직접 값을 설정하여 전송해야 합니다. 추후 자동 수집 방식으로 변경될 예정입니다.

{
  "market": "GO",
  "serverId": "Asia"
}

eventAttribute — 이벤트와 함께 직접 전송하는 속성입니다. 해당 이벤트를 분석하는 데 필요한 세부 정보를 담습니다.

{
  "level": "100",
  "contentsType": "dungeon"
}

속성 명명 규칙¶

eventAttribute 및 hiveAttribute의 키 이름은 아래 규칙을 따라 작성할 것을 권고합니다.

• 권장 문자: 영문(a–z, A–Z, 대/소문자 구분), 숫자(0–9), 언더바(_), 하이픈(-)
• 구분자: 단어 사이는 공백이 아닌 언더바(_)로 구분
• 예시: item_id, contents-type, stage_level

속성 키 변환 규칙¶

속성을 전송하면 시스템이 아래 규칙에 따라 일부 키 이름을 자동으로 변환합니다. 분석 시 실제로 조회되는 키 이름이 달라질 수 있으므로 주의하세요.

-Hive 접미사 (hiveAttribute)¶

hiveAttribute의 모든 키 끝에 -Hive가 자동으로 붙습니다.

-Event 접미사 (eventAttribute)¶

eventAttribute의 키 중 아래 8개 공통 필드와 이름이 겹치는 경우에만 -Event가 자동으로 붙습니다.

• timezone, dateTime, identifierProvider, userId, deviceId, appId, category, eventName

추천 이벤트¶

아래는 애널리틱스에서 분석 활용도가 높은 이벤트 예시입니다. 각 이벤트를 eventName과 eventAttribute에 맞춰 전송하면 차트·퍼널·리텐션 등 애널리틱스의 모든 기능으로 바로 분석할 수 있습니다.

레벨업¶

eventAttribute (공통):

재화¶

eventAttribute (공통):

콘텐츠¶

eventAttribute (공통):

인앱 상점¶

eventAttribute (공통):

메이트¶

eventAttribute (공통):

사회활동¶

연관 메뉴¶

• 이벤트 — 이벤트 및 속성 등록·관리
• 메트릭 — 자주 사용하는 이벤트 집계 설정을 메트릭으로 저장