경기 통계

게임 통계는 플레이어가 게이머 프로필에서 볼 수 있는 게임에 관한 누적 통계입니다. 이러한 통계를 통해 플레이어는 평생 진행 상황을 추적하고, 하이라이트 순간을 확인하고, 다른 플레이어와 비교할 수 있으며, 향후 퀘스트, 소셜 챌린지 등 Google Play 기능을 지원할 수 있습니다.

경기 기록은 다음 요건을 충족해야 합니다.

• 구매가 필요하지 않습니다 (예: 보석 구매). 즉, IAP 구매의 결과로 업데이트되지 않아야 합니다.
• 광고 시청을 요구하지 않아야 합니다. 즉, 광고 시청의 결과로 업데이트되지 않아야 합니다.
• 일반적인 게임 사용이 아니어야 합니다 (예: 게임 열기, 설정 사용).
• 사용자 ID, 비밀번호, 정확한 위치 또는 건강 데이터, 공격적이거나, 불경스럽거나, 성적으로 노골적이거나, 폭력적이거나, 증오 콘텐츠 등 Play 정책에 정의된 개인 정보 및 민감한 사용자 데이터를 포함하지 않습니다.
• 모든 사용자에게 제공되어야 합니다 (예: 팀별 작업이 아니거나 특정 수준의 사용자에게만 제공되거나 기간이 제한된 라이브ops 등으로 제한되지 않음).

통합 단계

반복되는 통계의 경우 게임 통계 API를 플레이어 이벤트로 사용하고 진행 통계의 경우 사전 정의된 이벤트 progressUpdate를 사용하여 데이터를 전송합니다. 또한 게이머 프로필에 표시될 통계와 표시 정보를 계산하는 로직을 구성해야 합니다.

플레이어 이벤트는 고유한 인게임 순간, 게임 루프 완료 또는 진행 상황 마일스톤을 나타냅니다.

플레이어 이벤트는 다음과 같이 정의되고 모델링됩니다.

1. 이벤트는 경기 완료, 달리기 완료, 상자 잠금 해제, 지역에서의 진행 상황 저장과 같은 플레이어가 취한 특정 행동으로 표시됩니다.
2. 각 작업은 특정 결과를 초래하거나 작업을 정의하는 특정 특징이 있습니다. 이러한 속성은 이벤트 및 이벤트의 구체적인 결과 (예: 경기 유형, 해당 경기에서 획득한 코인, 경기 결과, 헤드샷 수)에 관한 컨텍스트를 제공하는 이벤트 속성으로 모델링됩니다.

통합은 다음 단계로 구성됩니다.

• 원시 데이터 스키마 선언: Play Console에서 CSV 업로드를 사용하여 플레이어 이벤트를 정의합니다. 이벤트 만들기를 참고하세요.
• 게임 통계 API와 통합: 플레이어 이벤트 및 progressUpdate 이벤트에 대해 선언된 형식으로 원시 플레이어 데이터를 전송합니다.
  • 클라이언트 측 또는 서버 측 통합을 사용하여 정의된 모든 이벤트를 전송합니다. 자세한 내용은 플레이어 이벤트 및 progressUpdate 이벤트의 예를 참고하세요.
• ZIP 파일 업로드: 반복되는 통계 5개와 플레이어 진행 수준 1개를 정의하는 CSV 파일 3개와 모든 아이콘 이미지 파일을 제공합니다. 자세한 내용은 ZIP 파일 가이드라인을 참고하세요. 다음 세부정보를 포함합니다.
  • 반복 통계용 CSV 파일:
    • 통계의 고유 ID입니다.
    • 통계 계산에 사용할 이벤트 라벨을 지정합니다. 여기에서는 progressUpdate 이벤트 라벨을 사용할 수 없습니다.
      • 통계 계산에 사용할 속성 라벨을 지정합니다. 지정된 이벤트의 속성이어야 합니다.
      • 선택한 속성 라벨의 통계를 계산하는 방법을 결정하려면 집계 유형 (SUM, MAX, MIN 또는 COUNT)을 지정합니다.
      • 조건이 충족될 때만 로직을 계산하도록 선택적 필터 조건을 지정합니다. 속성 및 이벤트 라벨, 연산자 (=, <, <=, >= 또는 >), 기준점 값을 정의합니다.
    • 통계를 경쟁 기능에 사용할 수 있는지 여부를 나타내는 불리언 플래그를 포함합니다.
    • 이 기능을 경쟁 기능에 사용할 수 있는 경우 실제 플레이어의 최소 및 최대 시간당 한도입니다. 이는 리그 및 소셜 챌린지와 같은 기능에 참여할 때 오용할 수 있는 플레이어를 식별하는 데 사용됩니다.
    • 플레이어에게 표시되는 통계에 고유한 표시 이름을 제공합니다.
    • 통계를 설명하는 고유한 텍스트를 제공합니다. 이 설명은 플레이어가 통계를 획득하는 방법을 자세히 설명해야 하며 플레이어의 게임 프로필 UI에 표시됩니다.
    • CSV 파일에 정확한 아이콘 파일 이름을 입력하여 통계를 나타내는 고유한 아이콘을 제공합니다.
    • 값이 증가하는 것이 플레이어에게 좋은지 감소하는 것이 좋은지 선택적 입력을 제공합니다. 이 입력은 플레이어 움직임을 축하하는 데 사용됩니다.
    • 통계의 선택적 측정 단위(예: km, 마일, 초)를 제공합니다.
  • 플레이어 진행 상황 통계용 CSV 파일:
    • 플레이어가 볼 수 있는 플레이어 진행 상황의 고유한 표시 이름을 제공합니다.
    • 통계를 나타내는 고유한 아이콘을 제공합니다.
    • 진행 통계에 대한 설명을 제공합니다.
    • 값이 증가하는 것이 플레이어에게 좋은지 감소하는 것이 좋은지 선택적 입력을 제공합니다. 이 입력은 currentProgress 속성이 INT 유형인 경우에만 플레이어 움직임을 축하하는 데 사용됩니다.
    • 통계의 선택적 측정 단위(예: km, 마일, 초)를 제공합니다.
  • 현지화용 CSV 파일: 모든 통계에 대해 현지화된 표시 이름을 제공합니다.
    • 각 현지화에 대해 하나의 행을 추가합니다.
    • 이전 CSV에 추가된 통계 표시 이름 문자열을 사용하여 현지화가 추가되는 통계를 고유하게 식별합니다.
    • 언어 코드 목록에서 언어를 지정합니다.
    • 지정된 언어로 표시 이름의 현지화를 추가합니다.
    • 지정된 언어로 통계 설명의 현지화를 추가합니다.

스키마 계획

게임 통계 API를 사용하면 플레이어 이벤트와 플레이어 진행 상황 통계에 대해 사전 정의된 이벤트라는 두 가지 유형의 데이터를 전송할 수 있습니다.

다음 예는 다양한 게임 유형에서 플레이어 이벤트가 어떻게 표시되는지 보여줍니다.

플레이어 이벤트

플레이어 이벤트는 고유한 게임 내 순간, 게임 루프 완료 또는 진행 상황 마일스톤으로 정의됩니다.

• 이벤트를 특정 게임 내 순간, 게임 루프 완료 또는 진행 상황 마일스톤으로 정의합니다.
  • 완료된 경기 또는 실행과 같은 게임 루프 완료입니다.
  • 저장된 지역 탐색 진행률 또는 완료된 레벨과 같은 진행 상황 마일스톤
  • 반복적인 통계는 플레이어의 반복 가능한 동작을 실제로 나타내야 하므로 정의된 이벤트는 핵심 게임플레이와 연결되어야 합니다.
• 속성 추가를 통해 레벨 번호, 경기 유형, 무기 유형, 무기 수, 헤드샷, 획득한 코인, 경기 결과, 랩타임, 자동차 유형과 같은 이벤트 및 결과에 관한 컨텍스트를 제공합니다.
• 게임플레이 세션 내에서 이벤트가 발생하는 즉시 이벤트를 전송합니다. 예를 들어 루프가 완료된 직후 게임 루프 완료 이벤트를 전송합니다.

progressUpdate 이벤트

게임에 기본 진행 메커니즘이 있는 경우 이 이벤트를 사용하여 플레이어의 현재 진행 상황을 전송합니다. 이 이벤트에는 INT 또는 STRING 유형의 'currentProgress'라는 사전 정의된 속성이 하나 있습니다. 이 속성을 사용하여 기본 진행 메커니즘에서 플레이어 진행 상황의 현재 값을 전송해야 합니다. 이 이벤트를 사용하는 경우 사전 정의된 'currentProgress' 속성이 있어야 하며 이 속성을 사용하여 진행률 통계를 정의해야 합니다.

게임의 다른 진행 시스템(예: lifetime highest score 또는 current coin balance)의 현재 값을 이 이벤트의 다른 속성으로 전송할 수 있습니다.

플레이어가 게임 내 현재 진행 상황을 기준으로 프로필을 비교할 수 있으므로 첫 통합 후 현재 진행 상황 값을 가져오는 데 지연이 없어야 합니다. 플레이어에게 정확한 현재 진행률을 표시하려면 각 게임 세션이 시작될 때와 현재 진행률이 업데이트될 때마다 progressUpdate 이벤트를 전송해야 합니다.

통계 구성

각 통계에 관한 계산 로직과 표시 정보를 정의하여 반복 및 진행 통계를 구성해야 합니다. 아래에는 다양한 게임 장르의 반복 통계 예가 포함되어 있습니다. 반복적인 통계는 일반적으로 매우 적은 (3~4개) 게임 세션에서 모든 플레이어에 대해 반복적으로 업데이트되고 핵심 게임 루프와 연결된 통계입니다.

통합 세부정보

API 엔드포인트와 SDK는 사전 의견을 위해 제공되며 2026년 8월부터 정식 버전 (GA)으로 제공될 예정입니다. 타임라인을 참고하세요.

이 섹션에서는 클라이언트 측 및 서버 측 통합에서 이벤트를 구성하고 전송하는 방법을 보여줍니다.

데이터를 전송해야 하는 경우

플레이어 이벤트는 게임 루프 완료 또는 특정 게임 내 순간과 관련된 게임 내 활동을 나타냅니다. 이러한 이벤트는 발생하는 즉시 제출하세요. 예를 들어 루프가 완료되는 즉시 게임 루프 완료 이벤트를 제출합니다.

progressUpdate 이벤트는 플레이어의 현재 진행률을 나타냅니다. 진행 상황 통계 데이터는 다음 상황에서 이 이벤트를 사용하여 전송해야 합니다.

1. 현재 진행 상황이 업데이트될 때마다 최신 값을 즉시 전송합니다.
2. 플레이어가 게임을 실행할 때마다 플레이어의 이 통계가 항상 표시되도록 합니다.

통합 방법

통합에는 클라이언트와 서버 간의 두 가지 경로가 있습니다.

서버 간 통합

공개 API 엔드포인트를 사용하면 다음 구성을 사용하여 요청 페이로드에서 이벤트를 전송할 수 있습니다.

경로 매개변수

승인 및 인증

서버 간 API 호출은 OAuth 2.0을 사용하여 표준 Play 게임 서비스에 대한 서버 측 액세스 가이드라인을 따릅니다. 요청에는 https://www.googleapis.com/auth/games 범위로 승인된 Bearer 토큰이 포함되어야 합니다.

이벤트: 요청 본문

백엔드 API에는 엄격한 구조 검증 한도가 있습니다.

• 배치 크기: BatchRecordEventsRequest당 최대 30개의 이벤트
• 속성 수: PlayerGameEvent당 최대 맞춤 속성 25개
• 길이 제한: 이벤트 이름 (최대 100자), 속성 키 (최대 100자), 속성 문자열 값 (최대 1,024자)
• 이벤트 ID: 유효한 36자 UUID 문자열이어야 합니다.
• 재시도 및 캐싱: API가 실패하는 경우 과도한 이벤트를 로컬에 캐시하거나 누적하지 마세요. 30개를 초과하는 일괄 재시도는 거부됩니다. 배치 크기 제한을 준수하기 위해 항상 재시도를 청크로 처리합니다.

BatchRecordEventsRequest

BatchRecordEventsRequest을 참고하세요.

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent

{
  "eventId": string,
  "eventName": string,
  "eventProperties": {
    // keys (e.g., "matchId", "score")
    "": {
       object (PropertyValue)
    }
  },
  "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
}

PropertyValue

// ONE of the following fields will be present:
{
// 64-bit integer formatted as a string to prevent data loss
"intValue": "string",
// Double-precision floating point number.
"doubleValue": number,
// Standard UTF-8 text string.
"stringValue": "string",
// Boolean value (true or false).
"boolValue": boolean,
// Duration in seconds suffixed with 's' (e.g., "240s" or "3.5s").
"durationValue": "string"
}

progressUpdate 이벤트: 요청 본문

BatchRecordEventsRequest

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent - progressUpdate

{
  "eventId": string,
  "eventName": "progressUpdate",
  "eventProperties": {
    "": {
       object (PropertyValue)
// Must have at least one property "currentProgress"  of  type  INT  or  STRING
    }
  },
  "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z")
}

응답 본문

성공하면 빈 JSON 객체와 함께 HTTP 200 OK 상태를 반환합니다.

요청 본문 예시

이벤트: PlayerGameEvent

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID for deduplication and idempotency
      "eventName": "matchCompleted",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-05-09T01:44:44Z").
      "eventProperties": {
        "matchId": {
          "stringValue": "Match_A"
        },
        "gameMode": {
          "stringValue": "Battle_B"
        },
        "locationId": {
          "stringValue": "Location_XYZ"
        },
        "playerElimination": {
          "intValue": 2
        },
        "isWinner": {
          "boolValue": true
        }
      }
    }
  ]
}

progressUpdate 이벤트

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID
      "eventName": "progressUpdate",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
      "eventProperties": {
        "currentProgress": {
          "intValue": 52
        },
//Add more properties as per your requirement
      }
    }
  ]
}

클라이언트 구현

플랫폼의 게임 통계 클라이언트 구현에 관해 알아보려면 다음 리소스를 참고하세요.

• Android
• Unity
• C++

중요 시점