개요

기본 생성 테이블¶

• 애널리틱스를 사용 시 아래 표에 있는 테이블들은 기본적으로 제공이 됩니다.
• 기본적으로 제공되는 테이블 이외의 테이블이 필요할 경우 [로그 정의]를 참고 하여 테이블을 생성해야 합니다.
• 테이블명은 " t_[로그명]" 입니다.
• 기본 생성 테이블은 플랫폼에서 직접 수집하는 기본 로그와 게임서버에서 전송이 필요한 게임 로그로 구분됩니다.
• 로그명을 클릭하면 테이블별 필드 정보를 확인할 수 있습니다.

로그 정의¶

• 로그 정의는 Hive 애널리틱스 v2로 게임의 로그를 전송하기 위한 기능입니다.

  • 백오피스에서 게임에서 전송하고 싶은 로그를 정의합니다. 정의 후 생성된 소스코드를 게임에 적용하면 해당 로그가 수집됩니다.
  • 올바르게 정의가 됐는지, 로그가 수집되는지 즉석에서 확인 할 수 있는 기능을 백오피스에서 제공합니다.
  • 백오피스 경로: 애널리틱스 > 로그 정의

• 애널리틱스의 로그 정의 기능은 로그를 전송하기 전, 어떤 필드들을 전송할지 정의 하는 중요한 기능입니다.

• 애널리틱스는 로그 정의 기능은 로그 정의 시 반드시 필요한 필드 와 애널리틱스의 기능을 사용하기 위한 필드 2가지 종류로 구분하여  로그 정의 시 기본적인 필드를 생성합니다.
• 추가적인 필드는 사용자의 필요에 따라 생성하여 사용 할 수 있습니다.

1. 로그 정의 시 반드시 필요한 필드

   • 아래 표는 애널리틱스에 로그정의 시 반드시 포함되어야 하는 필드들 입니다.
   • Hive SDK 클라이언트 로그 전송 기능을 사용하면 해당 필드들은 자동으로 수집 됩니다.

   구분	필드명	설명	데이터 타입	예시
   기준시간	dateTime	로그 발생 시각 형식: “YYYY-MM-DD hh:mm:ss”* 로그가 처리되는 시간 기준 dateTime 이 -4년 ~ +1년 범위를 벗어나는 경우 예외 처리 되어 개별 저장 되며 저장일 기준 +2일 후에 확인 가능합니다	TIMESTAMP	2023-07-07 15:30:00
   	timezone	로그에 입력하는 시간 파라미터 값의 UTC offset 값 * 전송 시 유의 사항 - dateTime 값에 따라 timezone 값을 동적으로 설정하여 전송 미전송 시 KST로 처리되어 GMT+9:00 값 추가	STRING	GMT+9:00
   게임구분	appId	앱센터에 등록된 게임 별 application id - app_id로 발송 시 appId로 수정 저장	STRING	com.com2us.ios.universal
   	appIndex	appId에 부여된 index 번호 * 대체	INTEGER	123456
   	gameId	appId에서 도메인과 게임명을 포함한 값 * 대체	STRING	com.com2us.gamename
   	gameIndex	게임에 부여된 index 값 * 대체	INTEGER	123456
   로그명	category	로그 정의 시 정의한 로그 명	STRING	hive_login_log
   로그 식별자	guid	속성 한 행의 고유 키 값으로 전송된 로그의 중복을 제거하기 위해 사용 (나머지 필드의 값이 같더라도 guid 값이 다른 경우 다른 로그로 인식)* 전송 시 유의 사항-  UUID 와 같은 랜덤 문자열 헝태로 전송을 권장	STRING	61ad27eaad7ae3d1521d
   기타	undefinedRawData	로그 정의에서 정의하지 않은 필드가 있는 경우, json 문자열 형태로 저장하는 필드	STRING	{ "tier" : "10", "fluentd_tag" : "ha2union.game.purchase_log", "country" : "HK" }
   	appIdCompany	appId 에서 2번째 항목을 잘라낸값	STRING	com2us
   	extraLogBody	추가로 저장할 row 를 같이 담은 컬럼	STRING	{ "level" : "10", "petId" : "dog" }

   • 대체) appId 추가 불가 시 한 가지 로그만 있더라도 게임 구분 값으로 대체 사용 가능하며 appId 추가 가능 시 필수 필드에 포함되지 않습니다.
   • appIndex, gameId, gameIndex 에 대한 정보는 앱 센터 AppId 목록 에서 확인 가능합니다.

2. 애널리틱스의 기능을 사용하기 위한 필드

   • 아래 표는 애널리틱스에서 제공하는 게임별 지표, 세그먼트 등 다양한 애널리틱스의 기능을 사용하기 위해 필요한 필드들 입니다.
   • 애널리틱스에서 제공하는 기능을 사용하고자 하는 경우 필수로 생성해야 합니다.
   • Hive SDK 클라이언트 로그 전송 기능을 사용하면 해당 필드들은 자동으로 수집 됩니다.

   필드명	설명	데이터 타입	예시
   vid	게임별로 생성되는 유저 Virtual ID	INTEGER	100967777206
   did	단말기에서 고유하게 생성되는 Device ID	INTEGER	51726905112
   playerId	Hive 통합 인증에서 사용되는 key - player_id로 발송 시 playerId로 수정 저장	INTEGER	100967777106
   serverId	게임이 서비스되는 서버를 식별하기 위한 고유한 ID 정보 - server_id로 발송 시 serverId로 수정 저장	STRING	GLOBAL
   market	게임이 서비스되는 스토어/플랫폼 정보 * 마켓정보 - TS : SKT Tstore - OL : KT OllehMarket - OZ : LGU+ OzStore - AP : Apple Appstore - GO : Google Play - SA : Samsung Apps - LE : Com2us Lebi - MM : ChinaMobile MobileMarket - SN : Sina WeiboPoint - 36 : Qihu 360Point - MO : Momo MomoPoint - DN : eNA obagePoint - NA : NaverAppStore - AM : Amazon - ON : One Store - GA : 갤럭시스토어 - HU : 화웨이 huawei - FU : 펀탭 funtap - OP : OPPO - VI : VIVO - XI : 샤오미 - TC : 텐센트 - GS : google play games service - FA : FacebooK - HS : Hive Store 크로스플레이(PC버전 PG사 결제)	STRING	GO
   bigqueryRegistTimestamp	고객이 전송한 로그가 BigQuery 테이블에 유입된 시간	TIMESTAMP	2023-08-22 03:34:08 UTC
   lang	게임이 서비스되는 언어 정보	STRING	EN
   appIdGroup	앱 센터에 등록된 게임 별 Game ID	STRING	com.com2us.testgame
   checksum	guid 가 잘못된 경우 중복 데이터를 체크하기 위한 기준 컬럼 * 전송 시 유의 사항 - guid를 제외한 모든 컬럼명과 컬럼값을 문자열로 합치고 md5 한 값으로 전송	STRING	20ed52852cb2f72
   country	게임이 서비스 되는 국가 정보	STRING	US
   company	게임을 서비스하는 회사 정보	STRING	com2us

3. 로그정의 사전 정의 필드

   사전 정의 필드는 빅쿼리에 로그 적재시 데이터 활용의 편의를 위해 사전에 정의된 필드이며, 데이터 수집, 정제 과정에서 값을 자동으로 입력 또는 가공될 수 있습니다. 사전 정의 필드 '활성화'할 경우 아래 필드들이 자동으로 생성됩니다.

   주의 - 사전 정의 필드 '비활성화' 상태일경우 '필드 추가하기'에서 동일한 이름으로 필드 정의시 아래 표의 '설명' 과 동일하게 동작 합니다.

   필드명	데이터 타입	설명	자동으로 입력 또는 가공	Hive SDK 로그전송 기능 사용시 자동 수집
   uid	INTEGER	HIVE 플랫폼 공통 유저 구분값	X	O
   vidType	STRING	vid 필드의 구분 값(v1 : vid, v4 : playerid)	X	O
   appIdGroup	STRING	Hive 앱센터에 등록된 gameid값	O	O
   os	STRING	APP이 실행되는 플랫폼	X	O
   osVer	STRING	OS 의 버전 정보	X	O
   model	STRING	APP이 실행되는 디바이스의 모델명	X	O
   channel	STRING	유저가 사용하는 플랫폼 구분 (빈값으로 전송시 'C2S' 입력)	O	O
   deviceCountry	STRING	APP이 실행되는 디바이스의 설정 국가	X	O
   company	STRING	Hive 앱센터에 등록된 Company 값	O	O
   appVer	STRING	App 버전 정보	X	O
   sdkVer	STRING	Hive SDK 의 버전 정보	X	O
   dateTimeOrigin	TIMESTAMP	로그 전송시 전송된 dateTime 원본	O	O
   ymdOri	STRING	dateTime 값을 yyyy-MM-dd 의 형태로 자른 값	O	O
   ymdhOri	STRING	dateTime 값을 yyyy-MM-dd HH 의 형태로 자른 값	O	O
   ymd	STRING	dateTime 값을 UTC로 변환하여 yyyy-MM-dd 로 자른 값	O	O
   ymdh	STRING	dateTime 값을 UTC로 변환하여 yyyy-MM-dd HH 의 형태로 자른 값	O	O
   dateTimeKst	TIMESTAMP	dateTime 값을 KST 기준시간으로 변환	O	O
   ymdKst	STRING	dateTime 값을 KST로 변환하여 yyyy-MM-dd 의 형태로 자른 값	O	O
   ymdhKst	STRING	dateTime 값을 KST로 변환하여 yyyy-MM-dd HH 의 형태로 자른 값	O	O
   gameLanguage	STRING	게임 설정 언어 코드	X	X
   langOrigin	STRING	lang 의 원본	O	X
   deviceLanguage	STRING	유저의 디바이스 언어	X	O
   serverIp	STRING	로그를 전송하는 서버의 IP	X	X
   clientIp	STRING	로그를 발생시킨 사용자 단말의 IP (class 4는 0 으로 변경하고 저장)	O	O
   gameCountry	STRING	게임 국가 설정 정보 (빈값 일경우 country 로 전송된 값이 해당 필드에 저장)	O	X
   geoIpCountry	STRING	clientIp 값에 해당하는 국가 코드	O	O
   source	STRING	로그를 발생 시킨 경로	O	O
   bigqueryRegistTimestamp	TIMESTAMP	데이터가 BigQuery 에 적재된 시간(UTC)	O	O
   timezoneId	STRING	timezone 을 파싱한 결과 값. (원본 로그에 timezone 이 비어있거나 파싱 실패 시, KST 로 취급하여 GMT+09:00)	O	O

로그 정의하기¶

로그 정의 리스트¶

1. 로그 정의 리스트에서는 새로운 로그 정의를 할 수 있고, 기존에 정의한 로그의 상태를 간략히 확인할 수 있습니다.
2. 클라이언트 소스 생성: 정의한 로그 리스트 전체에 해당하는 게임에 적용할 클라이언트 소스코드를 생성합니다.
3. 로그 정의: 새로운 로그를 정의합니다.
4. 불러와서 새 로그 정의: 기존에 정의한 로그 중에 하나를 선택 후 이용 가능하며, 해당 로그 정의 내용을 그대로 복사해서 정의하는 화면으로 이동합니다.
5. 템플릿으로 등록: 기존의 정의한 로그들을 중 자주 사용하는 형식의 로그들을 선택해 템플릿으로 등록할 수 있습니다. 등록한 템플릿은 로그 정의 화면에서 불러와서 사용할 수 있습니다.
6. 빅쿼리에 연결: 정상적으로 로그 데이터 저장소가 생성되었음을 의미합니다.
7. 데이터 플로우에 존재: 새로 정의한 로그의 경우 당일은 X이며, 다음날 오전에 O로 변경된 것을 확인 후 사용해야 합니다. 로그 수집은 당일도 가능합니다. 로그 정의한 당일이 아닌 다른 날 X가 되어 있다면 아래의 설명대로 문의하세요.
8. 빅쿼리에 연결과 데이터 플로우에 존재에 X표시가 되었다면 데이터 연동에 문제가 있음을 의미하며, [기술지원]을 통해 문의해야 합니다.

웹 폼으로 로그 정의하기¶

1. 기본정보
   • 테이블명: 해당 로그의 테이블명을 기입합니다.
   • 설명: 해당 테이블의 설명을 기입합니다. 해당 설명은 세그먼트의 게임 정보 부분에 노출되므로 사용자가 확인하기 쉽도록 기입하는 것을 권장합니다. (EX: level - 유저의 계정 레벨)
   • 템플릿을 통해 필드 작성: 기존에 등록한 템플릿에서 하나를 선택하면, 해당 로그 정의했던 정보들이 그대로 노출되고 필요한 부분을 수정해서 로그 정의를 진행합니다.
2. 공통 필드 설정
   • 공통 필드는 모든 종류의 로그에서 공통적으로 들어갈 수 있는 필드들을 미리 정의해 놓은 부분입니다.
   • 데이터 선택 체크박스를 체크하면 이 로그에서 사용하는 필드가 됩니다. 체크를 하지 않아도 게임에서 전송한다면 로그를 수집할 수 있습니다. 다만, 체크하면 자동으로 서버 소스 코드가 생성되기 때문에 편리하게 생성할 수 있습니다. 클라이언트는 체크하지 않아도 Hive SDK4에서 모두 수집합니다.
3. 정의 필드 설정
   • 정의 필드는 전송할 게임 로그의 필드를 설정하는 부분입니다. 필드명과 필드의 타입, 설명, 샘플 값 입력이 필요합니다.
   • 체크박스를 체크하면 해당 필드는 권장 필드가 되며, 세그먼트에 활용할 수 있는 필드로 정의됩니다.
   • 등록 버튼을 통해 로그 정의가 완료됩니다. 로그 정의를 마치면 리스트에 추가되며 상세 화면에서 필드 추가나 수정, 데이터 수집 확인 등을 할 수 있습니다.

엑셀로 로그 정의하기¶

1. 엑셀파일 만들기

   • 다음과 같은 양식으로 표를 작성합니다.

     테이블명	앱아이디의 앞부분	테이블 설명
     필드명1	필드1의 타입	필드1에 대한 설명	필드1에 들어갈 샘플 값
     필드명2	필드2의 타입	필드2에 대한 설명	필드2에 들어갈 샘플 값

     예를 들어, 다음과 같이 작성할 수 있습니다.

     

   • 엑셀파일의 시트를 추가하여 다수의 로그를 정의할 수도 있습니다. 단, 같은 앱(게임)에 대한 로그만 정의할 수 있습니다. 시트 이름은 어떻게 지어도 상관 없습니다.
2. 엑셀 파일 업로드

   • 로그 정의 리스트에서 '엑셀파일로 정의' 버튼을 클릭하면 아래와 같은 페이지로 이동합니다.

     

   • 이때 나타나는 사각형 박스에 [1 엑셀 파일 만들기] 에서 만든 엑셀 파일을 드래그하고 ‘등록’ 버튼을 누릅니다.

로그 관리하기¶

정의한 로그 상세 화면¶

• 로그 정의 리스트에서 해당 로그에 필드를 추가하거나 로그 전송 상태가 정상인지 확인하려면 로그를 클릭해 상세 화면으로 이동합니다.

1. 기본정보, 빅쿼리 스키마 정보

• 기본정보: 로그 정의한 게임, 카테고리, 등록일, 설명을 확인할 수 있습니다. 설명은 수정도 가능합니다.
• 빅쿼리 스키마 정보: 빅쿼리에 저장된 스키마 정보를 볼 수 있습니다.

2. 로그 필드 정보

• 공통 필드는 검은색, 게임에서 추가한 필드는 파란색으로 라인이 표시됩니다.
• 필드의 설명과 사용 항목은 수정이 가능합니다.

• 사용: 해당 필드의 사용 수준을 선택할 수 있습니다. 이 수준은 로그 정의 하는 사용자의 참고용으로 사용되며, 로그 전송을 개발할 때 사용 수준에 맞게 올바른 적용이 필요합니다. 권장과 필수로 설정되어 있는 필드는 세그먼트에서 활용할 수 있습니다.

  • 필수: 필수로 수집되어야 하는 필드를 의미합니다. 게임에 적용 시 해당 필드의 값이 반드시 들어가도록 적용해야 합니다. 예를 들어, vid 필드가 해당합니다.
  • 권장: 중요도가 높은 필드를 의미하며, 수집이 권장되는 필드입니다. 권장과 필수 필드는 세그먼트의 조건으로 추가할 수 있습니다.
  • 자동: 로그 수집 시스템이 꼭 필요로 하는 필드이며, 자동으로 생성됩니다. 예를들어 geoIpCountry 필드로 클라이언트 IP를 통해 국가값을 받아오는 필드입니다.
  • 선택: 수집은 하나 활용은 선택 사항인 필드입니다. 서버에서 로그를 전송할 경우 보내주지 않아도 되는 필드입니다.

• 빅쿼리 연동: 빅쿼리에 올바르게 연동되어 있는지 표시됩니다. O표시는 정상이며, X표시가 있다면 로그 연동에 문제가 있으므로 기술지원을 통해 문의해야 합니다.

• 필드를 드래그하여 순서를 바꿀 수 있습니다.

3. 필드 추가

• 필드 추가: 기존에 정의했던 로그에 필드를 추가하는 기능입니다. 추가하는 방법은 로그 정의와 동일합니다.
• 추가할 필드를 작성한 후 하단에 있는 필드 추가 실행 버튼을 클릭해야 저장됩니다.

4. ETL 시뮬레이션

• ETL 시뮬레이션은 해당 로그 정의가 올바르게 수집 되는지 확인하는 기능입니다.
• Request - Json Body
  • 해당 로그의 샘플 Json을 확인할 수 있으며, Json 전송 버튼으로 응답이 올바르게 오는지 확인할 수 있습니다.
  • Json 전송 버튼 클릭 시 아래 Response 영역에 결과 값이 노출됩니다. 또한 Json 데이터 저장 서버 경로에 단계별 수집 상태가 표시됩니다.
  • Json 데이터 저장 서버 경로의 버튼들을 클릭하면 하단에 상태값이 표시되고, BigQuery 버튼을 클릭하면 최종적으로 저장이 잘 되었는지 확인됩니다. 그리고 최종 저장된 Json 데이터가 출력됩니다.
  • 이 기능으로 수집된 샘플 데이터는 실제로 DB에 저장되기 때문에 해당 로그로 인한 오차가 발생할 수 있음을 주의해야 합니다.

5. 데이터 샘플

• 데이터 샘플: 해당 정의를 통해 실제 수집된 로그를 확인할 수 있습니다. 최신순으로 최대 10개의 로그까지 노출됩니다.
• 저장 대기중인 최신 데이터 확인: 새로고침하여 로그를 최신 순으로 노출합니다.
• 더보기: 데이터 샘플을 더 많이 확인하기 위한 페이지가 노출됩니다. (아래 이미지)

• 데이터 샘플 더보기 페이지에서는 최신 7일간의 로그를 확인할 수 있으며, 필드를 검색할 수 있는 기능입니다. 좌우 스크롤을 통해 모든 필드를 확인할 수 있습니다.
• 필드 선택: 모든 필드를 선택할 수 있고, 선택한 필드의 값으로 검색할 수 있습니다.
• 비교 방식: 일치 검색인 =와, LIKE 검색 방식을 지원합니다.
• 특정 vid의 로그를 검색하고 싶다면 vid 필드을 선택하고 vid를 기입 후 검색하면 해당 vid의 로그만 노출됩니다.

6. 클라이언트 소스 생성

• 클라이언트 소스 생성: 해당 로그의 언어별 클라이언트 소스를 생성합니다.
• Json 익스포트: 해당 로그를 Json으로 익스포트합니다. 새 창으로 소스가 익스포트되며, 익스포트된 해당 소스를 사용하거나 수정할 수 있습니다.
• 불러와서 새 로그 정의: 해당 로그와 유사한 로그를 정의하고자 한다면 해당 버튼을 통해서 로그가 정의된 상태로 새 로그정의 화면이 노출됩니다.
• 삭제: 해당 로그 정의를 삭제합니다.

정의된 로그를 서버 to 서버로 전송하기¶

[6. 클라이언트 소스 생성] 설명과 같이 Hive애널리틱스 v2는 Hive SDK v4 내의 API 를 통한 전송법을 권장하지만, 서버 to 서버로도 애널리틱스 v2로 로그를 전송하실 수 있습니다. 전송은 fluentd를 사용하는데, 사용법은 아래 링크를 참조해 주세요.

Hive 애널리틱스 동작 구조 : Fluentd 방식

서버 to 서버 로그 정의 전송 방법 : Fluentd 사용

로그 데이터 검증 및 수정 처리¶

• 로그 정의 시 안내되어 있는 내용 외에 추가로 데이터 검증과 수정 처리 되는 부분은 아래와 같습니다.

1. geoipCountry 추가
   • clientIp 값이 있는 경우 IP값을 이용해 MaxMind DB 조회를 통해 국가 값을 매칭 합니다.
   • clientIp 값이 없거나 조회가 되지 않는 경우
     • lang 에 값이 있다면 geoIpCountry에 해당 값을 추가 합니다.

     • lang 의 국가 값 일부는 변경하여 추가 합니다.

       원본	수정 후
       ko	KR
       ja	JP
       vi	VN
       es	ES

   • 최종적으로도 국가 확인이 불가능하다면 geoIpCountry에 "ET" 값을 추가 합니다.
2. clientIp 수정
   • class 4 는 제외하여 기록합니다.
     • 예) 127.0.0.1 → 127.0.0.0
3. appId를 이용한 데이터 최종 보정
   • 앱 센터 데이터에 등록한 데이터를 기준으로 appId로 검색하여 비어 있는 값을 추가 합니다.
     • market
     • os
     • company
     • channel
       • channel에 값이 없는 경우에는 "C2S"로 추가 합니다.
     • sdkVer
     • appidGroup
     • appidCompany