게임 데이터를 이벤트 로그로 전송하기: 이벤트 로그 전송 3편

「테스트 로그로 수집 구조와 지표 검증하기: 이벤트 로그 전송 2편」에서는 테스트 로그를 전송해 이벤트의 수집 구조와 지표 구성을 검증했다. 이번 편에서는 검증한 이벤트 구조를 실제 게임에 적용하고, 이용자의 행동이 발생하는 시점에 실제 데이터를 전송하는 방법을 알아본다.

테스트 로그를 통해 이벤트명과 속성, 자료형과 값의 형식을 확인했더라도 실제 게임에서는 이용자의 행동이 발생하는 시점에 맞춰 로그 전송 코드를 실행해야 한다. 콘텐츠 완료, 재화 획득, 아이템 사용과 같은 행동이 확정되는 위치에 코드를 적용하고 해당 시점의 실제 게임 데이터를 이벤트 속성에 연결한다.

이벤트를 너무 이른 시점에 전송하면 완료되지 않은 행동이 집계될 수 있고, 너무 늦게 전송하면 화면 전환이나 앱 종료로 로그가 누락될 수 있다. 따라서 이벤트의 의미를 기준으로 전송 시점을 정하고 실제 행동이 완료된 직후에 로그를 전송해야 한다.

Hive 애널리틱스의 이벤트 로그는 게임 클라이언트 또는 서버에서 전송할 수 있다. 클라이언트 전송은 Unity, Unreal Engine, C++, Android와 iOS 개발 환경을 지원하며, 서버에서는 Fluentd 또는 HTTP 방식으로 이벤트 로그를 전송할 수 있다.

이벤트 로그는 정상적인 수집과 처리에 필요한 필수 속성과 이벤트의 세부 정보를 나타내는 사용자 정의 속성으로 구성된다.

필수 속성에는 이용자와 기기, 앱과 프로젝트(게임), 이벤트명과 발생 시각을 식별하기 위한 다음 값이 포함된다.

사용자 정의 속성은 캐릭터 레벨, 콘텐츠 종류, 점수와 플레이 시간처럼 이벤트의 세부 정보를 분석하기 위해 자유롭게 구성할 수 있다. 클라이언트와 서버 모두 분석에 필요한 사용자 정의 속성에 실제 게임값을 연결해 직접 전송한다.

contents_success 이벤트를 실제 게임에 적용하는 과정이다. 이용자가 게임 콘텐츠를 완료한 시점에 이벤트를 전송하고, 콘텐츠 종류와 이용자 상태, 플레이 결과를 실제 게임 데이터로 연결한다.

이벤트 전송 시점 확인

contents_success는 게임 콘텐츠가 완료된 시점에 발생하는 이벤트다. 콘텐츠 입장이나 플레이 시작 시점이 아니라 서버 응답이나 게임 로직을 통해 완료 결과가 확정된 직후에 이벤트를 전송한다.

재시도나 화면 전환 과정에서 같은 완료 처리가 여러 번 실행될 수 있다면 하나의 행동에 이벤트가 중복 전송되지 않도록 처리한다.

사용자 정의 속성 연결

contents_success에 사전 정의된 속성을 확인하고 각 속성에 이벤트가 발생한 시점의 실제 게임 데이터를 연결한다.

속성명과 자료형, 값의 단위는 테스트 로그에서 검증한 기준과 동일하게 유지한다. 특히 playTimeSec처럼 시간과 관련된 속성은 초 또는 밀리초 등 사용하는 단위를 통일해야 여러 게임(프로젝트)의 데이터를 같은 기준으로 분석할 수 있다.

필수 속성 구성

이벤트 로그에는 userId, deviceId, identifierProvider, appId, appIdGroup, eventTime, eventName의 필수 속성이 포함되어야 한다.

Hive SDK v4를 이용해 클라이언트에서 전송하면 필수 속성 중 eventName을 제외한 값이 자동으로 수집된다. market, hive_country, language, os, app_version 등 이용자의 앱과 실행 환경을 나타내는 속성도 함께 수집되므로, 필수 속성은 eventName만 직접 구성한다.

Hive Axyl을 이용해 클라이언트에서 전송하면 identifierProvider는 서버에서 hive로 고정되어 수집되며, appId는 SDK를 초기화할 때 지정한 값이 로그 전송 요청 헤더로 자동 전달된다. 이외의 필수 속성은 직접 구성해 전송한다.

서버에서 전송하는 경우에는 Fluentd와 HTTP 방식 모두 필수 속성을 직접 구성한다. 자세한 전송 방법은 개발자 사이트의 이벤트 전송에서 확인할 수 있다.

이벤트 전송 코드 적용

데이터 > 이벤트에서 contents_success를 선택하고 소스 생성 탭으로 이동한다. 클라이언트 또는 서버 개발 방식과 게임의 개발 환경을 선택해 생성된 소스를 확인한다.

개발자는 생성된 소스의 샘플 값을 실제 게임 변수로 교체하고 콘텐츠 완료가 확정되는 위치에 코드를 적용한다. 이벤트명에는 contents_success를 입력하고, 사용자 정의 속성에는 콘텐츠 완료 시점의 characterLv, modeTypeId, modeTypeName, score, playTimeSec 값을 전달한다.

클라이언트로 전송한다면, 사용하는 SDK에 맞춰 직접 전송해야 하는 필수 속성을 구성하고 자동으로 수집되는 필수 속성은 코드에 별도로 입력하지 않는다. 예를 들어 Hive SDK v4 클라이언트 전송 시 Unity 환경에서는 필수 속성 중 eventName과 사용자 정의 속성을 JSONObject로 구성한 뒤 Analytics.sendAnalyticsLog(logData)를 호출해 이벤트를 전송한다.

JSONObject logData = new JSONObject();
// 필수 속성 (eventName만 직접 전송, 나머지는 SDK 자동 수집)
logData.AddField("eventName", "contents_success");
// 사용자 정의 속성
logData.AddField("characterLv", 15);
logData.AddField("modeTypeId", 1);
logData.AddField("modeTypeName", "Tutorial_1");
logData.AddField("score", 12);
logData.AddField("playTimeSec", 120);
Analytics.sendAnalyticsLog(logData);

이벤트 저장

정상적으로 수집된 이벤트는 t_raw_event_log에 저장된다. 필수 속성 누락이나 eventTime 형식 오류 등 수집 기준을 충족하지 못한 이벤트는 t_raw_event_log_rescue에 격리된다.

정상 데이터와 격리 데이터의 저장 구조, 격리 사유를 확인하는 방법은 「이벤트 로그 저장 구조와 적재 실패 데이터 확인하기: 이벤트 로그 전송 4편」에서 자세히 살펴본다.

게임에서 발생한 행동을 일관된 이벤트 로그로 수집하려면 필수 속성과 사용자 정의 속성을 구분하고, 실제 행동이 확정되는 시점에 검증한 값과 자료형을 전송해야 한다.

Hive 애널리틱스는 클라이언트와 서버 환경에 맞는 방식으로 이벤트를 전송하고, 수집된 데이터를 분석에 활용할 수 있는 게임 전문 애널리틱스 솔루션이다. 지금 Hive 애널리틱스에서 분석하려는 게임 행동의 이벤트 구조를 실제 게임 데이터와 연결해보자.