게임 통계 통합

이 문서에서는 Google Play Console을 사용하여 게임에 게임 통계를 통합하는 방법을 설명합니다. 여기에서는 필수 CSV 및 ZIP 파일 형식을 다루고 이러한 파일을 만들고 가져오고 관리하는 방법을 설명합니다.

일정 만들기 또는 가져오기

Google Play Console을 사용하여 처음으로 이벤트를 추가하는 방법에는 두 가지가 있습니다.

이벤트 만들기

게임의 이벤트를 만들려면 다음 단계를 완료하세요.

  1. Google Play Console에서 게임을 선택합니다.
  2. Play 게임즈 서비스 - 게임 통계 페이지(사용자 늘리기 > Play 게임즈 서비스 > 설정 및 관리 > 게임 통계)에서 이벤트 추가 > 이벤트 만들기를 선택합니다.
  3. 이벤트 만들기 페이지에서 양식을 작성합니다.
  4. 변경사항 저장을 클릭합니다.

이벤트 가져오기

게임에 여러 이벤트를 한 번에 추가하려면 다음 단계를 따르세요.

  1. 이벤트 CSV 파일 PlayerGameEvent.csv를 만듭니다.
  2. Google Play Console에서 게임을 선택합니다.
  3. Play 게임즈 서비스 - 게임 통계 페이지(사용자 늘리기 > Play 게임즈 서비스 > 설정 및 관리 > 게임 통계)에서 이벤트 추가 > CSV를 통해 가져오기를 선택합니다.
  4. 이벤트 구성 페이지에서 업로드할 CSV 파일을 드롭합니다.
  5. 이벤트를 만든 후 통계를 설정합니다.

통계 만들기 또는 가져오기

Google Play Console을 사용하여 처음으로 통계를 추가하는 방법에는 두 가지가 있습니다.

통계 만들기

게임의 통계를 만들려면 다음 단계를 완료하세요.

  1. Google Play Console에서 게임을 선택합니다.
  2. Play 게임즈 서비스 - 게임 통계 페이지(사용자 늘리기 > Play 게임즈 서비스 > 설정 및 관리 > 게임 통계)에서 통계 추가 > 통계 만들기를 선택합니다.
  3. 통계 만들기 페이지에서 양식을 작성합니다.
  4. 변경사항 저장을 클릭합니다.
  5. 통계를 만든 후 게임을 게시합니다.

통계 가져오기

통계를 가져오려면 다음 단계를 따르세요.

  1. 통계용 ZIP 파일 가이드라인에 따라 통계, 현지화, 아이콘 파일이 포함된 ZIP 파일을 만듭니다.
  2. Google Play Console에서 게임을 선택합니다.
  3. Play 게임즈 서비스 - 게임 통계 페이지(사용자 늘리기 > Play 게임즈 서비스 > 설정 및 관리 > 게임 통계)에서 통계 추가 > ZIP을 통해 가져오기를 선택합니다.
  4. 게임 통계 구성 페이지에서 업로드할 ZIP 파일을 드롭합니다.
  5. 모든 통계를 업로드한 후 게임을 게시합니다.

테스트 게임 통계

게임 통계가 의도한 대로 작동하는지 확인하려면 다음 단계에 따라 테스트하세요.

  • Play Console에서 내부 테스트 트랙을 설정합니다.
  • 테스터를 위해 게임 프로젝트에 테스트 계정을 추가합니다.
  • Play 게임즈 앱을 사용하여 테스트 계정 중 하나의 Play Games 서비스 프로필을 만듭니다.
  • Play 게임즈 서비스 프로필을 만든 것과 동일한 테스트 계정을 사용하여 게임을 엽니다.
  • 게임 실행 시 자동 인증이 성공했음을 확인하는 Play 게임즈 서비스 '환영 토스트'가 화면에 표시되는지 확인합니다.
  • 테스트 계정 사용자는 게임을 플레이하여 이벤트를 트리거할 수 있습니다. API 응답을 확인하여 이벤트가 기록되었는지 확인합니다.

테스트를 위해 기기에서 게임 통계 공개 상태 관리하기

Play Console에서 테스터가 게임을 사용할 수 있게 되면 다음 단계에 따라 기기에서 게임 통계를 확인합니다.

  1. Google Play 스토어 캐시를 지웁니다.

    1. 기기의 설정 앱을 엽니다.
    2. 앱 > Google Play 스토어를 탭합니다.
    3. 저장용량 및 캐시를 탭한 다음 캐시 지우기를 탭합니다.

  2. Google Play 스토어 앱을 엽니다.

  3. 플레이 시간 추적 섹션 또는 게이머 프로필을 사용하여 게임 통계를 확인합니다.

방법 1: 플레이 시간 추적 섹션 사용

플레이 시간 추적 섹션으로 이동한 다음 탭하여 게임 통계를 확인합니다.

게임 통계 테스트 방법 1을 사용하여 플레이 시간 추적 섹션을 사용합니다.
'나' 탭의 '플레이 시간 추적' 섹션

방법 2: 게이머 프로필 사용

  1. 내 페이지 탭을 탭한 다음 게이머 프로필을 탭합니다.
  2. 게임 통계 섹션으로 이동합니다.
  3. 기간에 전체를 선택합니다.
  4. 게임이 표시되지 않으면 모든 게임 보기를 탭합니다.
  5. 게임을 선택하여 통계를 확인합니다.
게이머 프로필을 사용하는 게임 통계 테스트 방법 2
게이머 프로필의 게임 통계 섹션

기기에서 로그 보기

게임 통계가 설계된 대로 작동하는지 확인하려면 기기에서 로그를 사용 설정하세요.

  1. 기기에서 adb 디버깅을 사용 설정하고 터미널에서 다음 명령어를 실행합니다.

    adb shell setprop log.tag.Games INFO
adb logcat -s "PlayGamesServices[GameStatsAgent]:I"

  2. 다음 예와 같이 성공 로그 메시지가 표시되는지 확인합니다.

    Successfully uploaded batch of X events.

    참고: API는 부분 업로드를 지원하므로 이 정보 로그는 일괄 처리가 완료되었음을 나타냅니다. 배치 내 개별 이벤트 중 하나라도 스키마 검증에 실패하면 이 메시지 앞에 오류 로그가 표시됩니다.

  3. 제출된 이벤트 중 유효성 검사에 실패한 이벤트가 있으면 실패를 자세히 설명하는 오류 메시지가 표시됩니다.

    BatchRecordEvents validation failed for X event(s): ...

게임 통계 게시

테스트를 완료한 후에는 게임을 게시해야 합니다. 게임의 모든 이벤트와 통계가 함께 게시됩니다.

게시하려면 다음 단계를 따르세요.

  1. Google Play Console에서 게임을 선택합니다.
  2. Play 게임즈 서비스 - 게임 통계 페이지(사용자 늘리기 > Play 게임즈 서비스 > 설정 및 관리 > 게임 통계)에서 검토 및 게시를 클릭합니다.
  3. Play 게임즈 서비스 - 게시 페이지(사용자 늘리기 > Play 게임즈 서비스 > 설정 및 관리 > 게시)에서 작업을 검토하고 문제를 해결합니다.
  4. 게시를 클릭합니다. 모든 게임 통계가 게시됩니다.

게임 통계 수정

기존 게임 통계가 있고 수정하려면 다음 단계를 따르세요.

  1. Google Play Console에서 게임을 선택합니다.
  2. Play 게임즈 서비스 - 게임 통계 페이지(사용자 늘리기 > Play 게임즈 서비스 > 설정 및 관리 > 게임 통계)로 이동합니다.
  3. 이벤트를 수정하려면 다음 단계를 따르세요.
    1. 이벤트 구성 섹션에서 이벤트를 선택합니다.
    2. 이벤트 속성을 추가하거나 삭제할 수 있습니다.
      • 이벤트 이름은 수정할 수 없습니다.
    3. 변경사항 저장을 클릭합니다.
  4. 통계를 수정하려면 다음 단계를 따르세요.
    1. 게임 통계 구성 섹션에서 통계를 선택합니다.
    2. 통계 이름, 통계 설명, 아이콘 파일 이름 필드를 수정할 수 있습니다.
      • 통계 ID, 진행 방향은 수정할 수 없습니다. 통계 단위 및 연결된 이벤트 세부정보
    3. 변경사항 저장을 클릭합니다.
  5. Play Games 서비스 - 게임 통계 페이지에서 수정된 통계는 테스터에게 제공됨 상태입니다.
  6. 통계를 테스트한 후 검토 및 게시를 클릭합니다. 이렇게 하면 업데이트된 모든 통계와 함께 게임이 다시 게시됩니다.

게임 통계 삭제

게임 통계가 게시된 후에는 삭제할 수 없습니다.

테스터에게 제공됨 상태의 이벤트 또는 통계를 삭제할 수 있습니다.

  1. Google Play Console에서 게임을 선택합니다.
  2. Play 게임즈 서비스 - 게임 통계 페이지(사용자 늘리기 > Play 게임즈 서비스 > 설정 및 관리 > 게임 통계)로 이동합니다.
  3. 이벤트를 삭제하려면 다음 단계를 따르세요.
    1. 이벤트 구성 섹션에서 이벤트를 선택합니다.
    2. 일정 삭제를 클릭합니다.
  4. 통계를 삭제하려면 다음 단계를 따르세요.
    1. 게임 통계 구성에서 삭제할 통계를 선택합니다.
    2. 게임 통계 삭제를 클릭합니다.

이벤트용 CSV 파일 가이드라인

CSV 파일의 첫 번째 행은 헤더 행입니다. PlayerGameEvent.csv와 같은 이벤트 CSV 파일을 사용하여 이벤트를 가져와야 합니다.

PlayerGameEvent.csv 형식

CSV에는 선언된 이벤트와 속성이 다음 순서로 쉼표로 구분된 값으로 포함됩니다.

 Event Name,Property Name,Property Type

progressionStat에 대한 progressUpdate 이벤트를 전송하는 경우 이 이벤트의 행을 추가합니다. 이 이벤트에는 INT 또는 STRING 유형의 currentProgress 속성과 전송하려는 기타 속성이 하나 이상 포함되어야 합니다.

이러한 필드는 다음 표에 설명되어 있습니다.

CSV 열 헤더 필수 또는 선택사항 허용되는 값
이벤트 이름 필수 최대 50자(영문 기준)

문자, 숫자, 밑줄로만 구성되어야 합니다.

특수 이벤트 이름 progressUpdate를 사용하는 경우 유형이 INT64 또는 STRING인 currentProgress이라는 속성을 포함해야 합니다.
속성 이름 필수 최대 50자(영문 기준)

문자, 숫자, 밑줄로만 구성되어야 합니다.

이벤트별로 고유: 속성 이름은 동일한 이벤트 내에서 고유해야 합니다.

다음 예약된 키워드를 사용하지 마세요. id, count, key, value, where, from, and, or, true, false
부동산 유형 필수 지원되는 데이터 유형 중 하나와 일치하는 대소문자를 구분하는 열거형 문자열: INT64, DOUBLE, STRING, BOOL

PlayerGameEvent.csv 파일 요구사항:

  • 파일은 최대 20개의 고유한 이벤트 이름을 지원하며 이벤트당 최대 20개의 속성을 지원합니다.
  • 파일 콘텐츠는 비워 둘 수 없으며 행이 하나 이상 있어야 합니다.
테이블 예시
이벤트 이름 속성 이름 부동산 유형
matchCompleted 기간 DOUBLE
matchCompleted 킬 INT64
matchCompleted isWinner BOOL
matchCompleted matchType 문자열
itemCollected coinsAmount INT64
itemCollected weaponType 문자열
progressUpdate currentProgress INT64

통계용 ZIP 파일 가이드라인

ZIP 파일을 사용하여 통계를 한 번에 가져올 수 있습니다. ZIP 파일에 사용할 정확한 파일 이름은 표를 참고하세요.

파일 이름 필수 또는 선택사항 허용되는 값
RepetitiveStatsConfig.csv 필수 반복 통계는 플레이어가 정기적으로 수행하는 인게임 액션을 나타냅니다.
ProgressionStatConfig.csv 필수 진행 상황 통계는 게임에서 플레이어의 진행 상황을 나타냅니다.
StatLocalizations.csv 선택사항 게임 통계 이름 및 설명의 번역을 제공합니다.
아이콘 파일 필수 512x512 PNG, JPEG 또는 JPG 형식의 아이콘입니다.

ZIP 파일은 다음 요구사항을 충족해야 합니다.

  • ZIP 파일 크기 제한: 압축 해제된 총 크기는 최대 10MB입니다.
  • 최대 파일 수: ZIP 파일에 총 53개 (CSV 3개, 아이콘 50개)까지 포함할 수 있습니다.
  • 최대 결합 통계 한도: ProgressionStatConfig.csv 및 RepetitiveStatsConfig.csv의 총 통계가 최대 50개입니다.
  • 지원되는 CSV 파일: ProgressionStatConfig.csv, RepetitiveStatsConfig.csv, StatLocalizations.csv (선택사항) 진행 통계만 업로드하려면 반복 통계 CSV 파일을 ZIP에 포함하지 마세요. 그렇지 않으면 콘솔에서 오류가 발생합니다. 반복적인 통계만 업로드하려는 경우에도 마찬가지입니다.
  • 아이콘 이미지 파일: PNG (.png) 또는 JPEG (.jpg, .jpeg)
    • CSV에서 참조되는 모든 아이콘은 ZIP 파일의 루트에 있어야 합니다.
    • ZIP에 있는 모든 이미지 파일은 하나 이상의 통계에서 참조해야 합니다.
  • 디렉터리 구조: 모든 파일은 ZIP 파일의 루트에 있어야 합니다. 하위 디렉터리는 허용되지 않습니다.

RepetitiveStatsConfig.csv 형식

CSV에는 선언된 이벤트와 속성이 다음 순서로 쉼표로 구분된 값으로 포함됩니다.

Stat Id,Event Name,Event Property Name,Aggregation Type,Stat Display Name,Stat Description,Filter Property,Filter Operator,Filter Value,Is Competitive,Min limit,Max limit,Icon File Name,Good value direction,Unit

이러한 필드는 다음 표에 설명되어 있습니다.

CSV 열 헤더 필수 또는 선택사항 허용되는 값
통계 ID 필수 최대 100자(영문 기준)

문자, 숫자, 밑줄로만 구성되어야 합니다. 게임의 모든 통계에서 고유해야 합니다.
이벤트 이름 필수 최대 50자(영문 기준)

PlayerGameEvent.csv 형식에 정의된 이벤트 이름을 참조해야 합니다.
이벤트 속성 이름 필수 최대 50자(영문 기준)
통계 표시 이름 필수 최대 50자
통계의 기본 표시 이름 (기본 언어)입니다. 통계 간에 고유해야 합니다.
통계 설명 필수 최대 500자(영문 기준)
통계의 기본 설명입니다.
집계 유형 필수 최대 50자(영문 기준)
SUM, MAX, MIN, COUNT
필터 속성 선택사항 최대 50자(영문 기준)
PlayerGameEvent.csv에 정의된 속성 이름이어야 합니다.
필터 연산자 선택사항 =, !=, >, <, >=, <=
필터 비교 연산자입니다.
필터 값 선택사항 필터 속성과 비교됩니다. 필터 값은 INT64, DOUBLE, BOOL, STRING여야 합니다.
경쟁력 있음 필수 true, false
최소 한도 Is Competitive가 true인 경우 필수 경쟁 통계에 허용되는 최소 점수입니다.
최대 한도 Is Competitive가 true인 경우 필수 경쟁 통계에 허용되는 최대 점수입니다.
아이콘 파일 이름 필수 ZIP 파일의 루트에 포함된 아이콘 이미지의 파일 이름입니다. 반복 통계에 사용되는 아이콘 파일 이름과 충돌할 수 없습니다.
가치 방향 필수 높은 값 INCREASING이 더 나은지 낮은 값 DECREASING이 더 나은지 지정합니다.
단위 선택사항 원시 숫자 또는 기간 값의 측정 단위입니다. 예를 들어 KILOMETER, SECOND, PERCENTAGE, UNITLESS입니다.

필터 조건을 사용하지 않으려면 셀을 비워 두세요.

테이블 예시
통계 ID 이벤트 이름 속성 이름 집계 통계 표시 이름 통계 설명 필터 속성 (선택사항) 필터 연산자 (선택사항) 필터 값 (선택사항) 경쟁력 있음 minLimit maxLimit 아이콘 파일 이름 가치 방향 단위
1 matchCompleted 기간 MAX 최장 매치 생존 모든 경기에서 플레이어의 생존 시간을 나타냅니다. isWinner = TRUE TRUE 0 50 stat1.png 감소세 초
2 matchCompleted isWinner COUNT 승리한 경기 플레이어가 승리한 경기 수를 나타냅니다. isWinner = TRUE TRUE 0 50 stat3.png 증가세
3 matchCompleted 킬 SUM 1대1 경기 킬 1대1 경기에서 기록한 킬 수 matchType = '1:1' FALSE stat4.png 증가세
4 itemCollected coinsAmount SUM 총 골드 수집량 플레이어가 경기에서 플레이하는 동안 코인을 수집합니다. weaponType = "sword" FALSE stat2.png 증가세

ProgressionStatConfig.csv 형식

CSV에는 선언된 이벤트와 속성이 다음 순서로 쉼표로 구분된 값으로 포함됩니다.

Stat Id,Event Property Name,Stat Display Name,Stat Description,Icon File Name,Good value direction,Unit

진행률 통계는 게이머 프로필에서 플레이어에게 첫 번째 통계로 표시됩니다.

이러한 필드는 다음 표에 설명되어 있습니다.

CSV 열 헤더 필수 또는 선택사항 허용되는 값
통계 ID 필수 최대 100자(영문 기준)

문자, 숫자, 밑줄로만 구성되어야 합니다. 게임의 모든 통계에서 고유해야 합니다.
이벤트 속성 이름 필수 최대 50자(영문 기준)

PlayerGameEvent.csv에 정의된 속성 이름이어야 합니다.
통계 표시 이름 필수 고유한 이름이어야 합니다.
통계 설명 필수 최대 50자
통계의 기본 설명입니다.
아이콘 파일 이름 필수 ZIP 파일의 루트에 포함된 아이콘 이미지의 파일 이름입니다. 반복 통계에 사용되는 아이콘 파일 이름과 충돌할 수 없습니다.
가치 방향 필수 높은 값 INCREASING이 더 나은지 낮은 값 DECREASING이 더 나은지 지정합니다.
단위 선택사항 원시 숫자 또는 기간 값의 측정 단위입니다. 예를 들어 KILOMETER, SECOND, PERCENTAGE, UNITLESS입니다.
테이블 예시
통계 ID 이벤트 속성 이름 통계 표시 이름 통계 설명 아이콘 파일 이름 좋은 값 방향
5 currentProgress 수준 플레이어는 경기를 플레이하고 레벨을 올려 XP를 누적합니다. Level.png 증가

StatLocalizations.csv 형식

CSV에는 선언된 이벤트와 속성이 다음 순서로 쉼표로 구분된 값으로 포함됩니다.

Stat Id,Stat Display Name,Locale,Localized Stat Display Name,Localized Stat Description

이러한 필드는 다음 표에 설명되어 있습니다.

CSV 열 헤더 필수 또는 선택사항 허용되는 값
통계 ID 필수 최대 100자(영문 기준)

문자, 숫자, 밑줄로만 구성되어야 합니다. 게임의 모든 통계에서 고유해야 합니다.
통계 표시 이름 필수 고유한 이름이어야 합니다.
언어 필수 언어 코드(예: en-US)
언어를 지정하기 전에 게임에 번역을 추가합니다. 기본 언어는 지정할 수 없습니다.

지원되는 언어 코드는 지원되는 언어 목록에서 확인할 수 있습니다.
현지화된 통계 표시 이름 선택사항 최대 50자(영문 기준) 지정된 언어의 번역된 통계 표시 이름입니다.
현지화된 통계 설명 선택사항 최대 500자(영문 기준) 지정된 언어로 번역된 통계 설명입니다.
테이블 예시
통계 ID 통계 표시 이름 언어 코드 현지화된 통계 이름 (UTF-8) 현지화된 통계 설명 (UTF-8)
1 최장 매치 생존 es 경기에서 더 오래 생존 이는 모든 경기에서 플레이어의 생존 시간을 나타냅니다.
1 최장 매치 생존 fr 가장 긴 경기 생존 이는 모든 경기에서 플레이어가 생존한 시간을 나타냅니다.
4 총 골드 수집량 es Oro total recolectado La jugadora recoge monedas mientras juega en un partido
4 총 골드 수집량 fr 또는 total collecté 플레이어가 경기를 플레이하여 코인을 모읍니다.

아이콘 파일

CSV 파일에서 참조하는 아이콘은 현재 가져온 ZIP 파일에 있어야 합니다.

아이콘 검사 규칙은 다음과 같습니다.

유효성 검사 속성 적용된 제약 조건 / 규칙
최대 파일 크기 아이콘 파일당 최대 1MB (1,048,576바이트)
크기 정확히 512x512픽셀 (너비 = 512, 높이 = 512)
가로세로 비율 엄격하게 1:1 (정사각형 가로세로 비율)
허용되는 형식 PNG (.png) 및 JPEG (.jpg, .jpeg)
ZIP의 게재위치 ZIP 파일의 루트 디렉터리에 있어야 합니다.
참조 검사 '아이콘 파일 이름' 열에 지정된 모든 아이콘 파일 이름이 ZIP에 있어야 합니다.
분리 확인 ZIP 내의 모든 이미지 파일은 하나 이상의 통계에서 참조해야 합니다.
충돌 확인 ProgressionStatConfig.csv의 아이콘 파일 이름은 RepetitiveStatsConfig.csv와 충돌할 수 없습니다.
시각적 중복 중복 아이콘이 신고됩니다.

아이콘 가이드라인

아이콘은 투명한 배경이 있는 512x512 PNG, JPEG 또는 JPG 파일로 만들어야 합니다.

모든 언어에서 동일한 아이콘이 사용되므로 아이콘에 텍스트나 현지화된 콘텐츠를 포함하지 않는 것이 좋습니다.

단위 사양

단위 열은 플레이어를 위해 원시 통계 값이 형식화되고 현지화되는 방식을 제어합니다.

숫자 통계 속성 (INT64, DOUBLE)

허용되는 단위 값 원시 값 예시
(비어 있음) / UNITLESS / NONE 1234567
% / PERCENTAGE / PERCENT 0.857
거리/길이: 센티미터, 미터, 킬로미터, 피트, 인치, 마일, 야드, 밀리미터, 나노미터 15 (킬로미터)
속도: KILOMETER_PER_HOUR, METER_PER_SECOND, MILE_PER_HOUR 60 (MILE_PER_HOUR)

기간 통계 속성 (DURATION)

카테고리 값 형식 지정 허용되는 단위 값 원시 값 예시 형식 지정된 출력 예시
단위 기반 / 기간 필수: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR 5400초 (HOUR) 1시간 30분
COMPONENT_NUMERIC / HH:MM:SS / CLOCK 세부사항 (선택사항, 기본값 WHOLE_SECONDS): WHOLE_MINUTES, WHOLE_SECONDS, MILLISECONDS_ONE_DIGIT, MILLISECONDS_TWO_DIGITS, MILLISECONDS_THREE_DIGITS 3661초 01:01:01
COMPONENT_TEXT / TEXT 가장 작은 단위 (선택사항, 기본값 SECONDS): SECONDS, MINUTES, HOURS, DAYS, MONTHS, YEARS 90000초 1일 1시간

숫자가 아닌 통계 속성 (STRING, BOOL)

단위 열은 비워 두어야 합니다.