Статистика игры

Game Stats are cumulative statistics about your game that players can view on their Gamer profile . These stats let players track lifetime progress, see highlight moments, and compare with other players, and power Google Play features such as Quests, Social Challenges and more in the future.

Игровая статистика должна:

• Не требует совершения покупок (например, покупки самоцветов), то есть обновления не должны происходить в результате каких-либо внутриигровых покупок.
• Не требуется просмотр рекламы, то есть обновления не должны происходить в результате просмотра рекламы.
• Не следует использовать игру слишком шаблонно (например, открыть игру; зайти в настройки).
• Not include Personal and Sensitive User Data, as defined per Play Policy, including user Ids, passwords, precise location or health data, or any offensive, profane, sexually explicit, violent, or hateful content.
• Должно быть доступно всем пользователям (например, не являться действием, предназначенным для конкретной команды, не быть доступным только пользователям определенного уровня или быть доступным только в течение ограниченного времени в рамках текущих операций и т. д.).

The image shows Game Stats in the Gamer Profile on the You tab. This user interface (UI) in the You tab is available only for testing purposes. The Game Stats UI will be available in September 2026.

Этапы интеграции

Send data using Game Stats API as player events for repetitive stats and a predefined event progressUpdate for the progression stat. You will also need to configure the logic for calculating the stats that would appear on Gamer profile and their display information.

События, происходящие с игроком, представляют собой отдельные внутриигровые моменты, завершение игрового цикла или этапы прогресса.

Событие, связанное с игроком, определяется и моделируется следующим образом:

1. Событием считается конкретное действие, совершенное игроком, например, завершение матча, окончание забега, открытие сундука или сохранение прогресса в определенной области.
2. Each action results in certain outcomes or has certain characteristics defining the action. These are modeled as event properties that provide context about the event and its specific outcomes (for example, match type, coins collected during that run, match result, or headshot count).

Интеграция состоит из следующих этапов:

• Объявите схему исходных данных: определите события проигрывателя, используя загрузку CSV-файла в консоли Play. См. раздел «Создание событий» .
• Интеграция с API игровой статистики: отправка необработанных данных игрока в заявленном формате для событий игрока и события progressUpdate .
  • Отправляйте все определенные события, используя интеграцию на стороне клиента или сервера. Для получения дополнительной информации см. примеры событий игрока и события progressUpdate .
• Upload a ZIP file: Provide 3 CSV files and all icon image files that define 5 repetitive stats and 1 player progression level. For more information, see ZIP file guidelines . Include the following details:
  • CSV-файл для повторяющейся статистики:
    • Уникальный идентификатор для данного показателя.
    • Укажите метку события, которая будет использоваться для расчета статистики. Здесь нельзя использовать метку события progressUpdate .
      • Укажите метку свойства, которая будет использоваться для расчета статистики. Это должно быть свойство указанного события.
      • Укажите тип агрегирования (SUM, MAX, MIN или COUNT), чтобы определить, как вычислять статистические данные по выбранной метке свойства.
      • Укажите необязательное условие фильтрации, чтобы логика вычислялась только при выполнении этого условия. Определите свойство и метку события, оператор (=, <, <=, >= или >) и пороговое значение.
    • Добавьте логический флаг, указывающий, можно ли использовать этот показатель для соревновательных функций.
    • If the feature can be used for competitive features then minimum and maximum hourly limits for a genuine player. This will be used for us to identify players who might be misusing when participating in features like leagues and social challenges.
    • Укажите уникальное отображаемое имя для статистики, которую видят игроки.
    • Предоставьте уникальное описание характеристики. Это описание должно подробно рассказывать о том, как игрок её получает, и будет отображаться игрокам в пользовательском интерфейсе профиля игрока.
    • Укажите уникальный значок, представляющий статистику, введя точное имя файла значка из CSV-файла.
    • Укажите необязательный параметр, который определяет, подходит ли игроку возрастающее или убывающее значение. Этот параметр будет использоваться для празднования действий игрока.
    • Укажите необязательную единицу измерения для данного показателя, например, километры, мили и секунды.
  • CSV-файл со статистикой прогресса игрока:
    • Укажите уникальное отображаемое имя для прогресса игрока, которое видят игроки.
    • Укажите уникальный значок, представляющий данный статистический показатель.
    • Укажите описание показателя прогресса.
    • Provide an optional input whether an increasing value or decreasing value is good for the player. This input will be used for celebrating player movements only when the currentProgress property is of type INT.
    • Укажите необязательную единицу измерения для данного показателя, например, км, мили, секунды.
  • CSV-файл для локализации: Укажите локализованные отображаемые имена для всех статистических данных.
    • Добавьте по одной строке для каждой локализации.
    • Используйте строку с отображаемым именем статистики, добавленную в предыдущем CSV-файле, чтобы однозначно идентифицировать статистику, к которой добавляется локализация.
    • Выберите язык из списка языковых кодов.
    • Добавить локализацию для отображаемого имени на указанном языке.
    • Добавить локализацию для описания статистики на указанном языке.

Спланируйте схему

С помощью API игровой статистики можно отправлять два типа данных: события игрока и предопределенное событие для статистики прогресса игрока.

Следующие примеры иллюстрируют, как выглядят события, происходящие с игроками, в различных типах игр:

События игроков

Игровые события определяются отдельными внутриигровыми моментами, завершением игрового цикла или этапами прогресса.

• Определите события как конкретные игровые моменты, завершение игрового цикла или этапы прогресса:
  • Завершение игрового цикла, например, завершенный матч или забег.
  • Этапы прогресса, такие как сохранение прогресса в исследовании локаций или завершение уровня.
  • Поскольку повторяющиеся статистические данные должны действительно отражать повторяющиеся действия игрока, определенные события должны быть связаны с основным игровым процессом.
• Add properties to provide context about the event and its outcomes, such as the level number, match type, weapon type, number of weapons, headshots, coins collected, match result, lap time, or car type.
• Отправляйте события в рамках игровой сессии сразу же после их возникновения. Например, отправьте событие завершения игрового цикла сразу после его завершения.

событие progressUpdate

Если в вашей игре используется основной механизм прогресса, используйте это событие для отправки текущего прогресса игрока. Событие имеет одно предопределенное свойство под названием "currentProgress" типа INT или STRING . Предполагается, что вы будете отправлять текущее значение прогресса игрока в основном механизме прогресса, используя это свойство. При использовании этого события необходимо наличие предопределенного свойства "currentProgress" и определение статистики прогресса с помощью этого свойства.

В качестве других свойств этого события вы можете передавать текущее значение для других систем прогресса в вашей игре, таких как lifetime highest score или current coin balance .

Поскольку игроки могут сравнивать свои профили с текущим прогрессом в игре, важно, чтобы не было задержек в получении значения текущего прогресса после первой интеграции. Для точного отображения текущего прогресса игрокам следует отправлять событие progressUpdate в начале каждой игровой сессии, а также всякий раз, когда происходит обновление текущего прогресса.

Настройте свою статистику

You will need to configure your repetitive and progression stats by defining the computation logic and display information about each stat. Examples of repetitive stats from different Game Genres are included below. Repetitive stats are usually stats that update repeatedly for any player across a very few (3-4) game sessions and are associated with the core game loop.

Детали интеграции

В этом разделе показано, как создавать события и отправлять их как на стороне клиента, так и на стороне сервера.

Когда следует отправлять данные?

Player Events represent in-game actions related to game loop completions or specific in-game moments. Submit these events as soon as they occur. For example, submit the game loop completion event as soon as the loop completes.

Событие progressUpdate отображает текущий уровень прогресса игрока. Данные о прогрессе следует отправлять с помощью этого события в следующих ситуациях:

1. При каждом обновлении данных о текущем ходе выполнения немедленно отправляйте последнее значение.
2. Чтобы этот показатель всегда присутствовал у игрока при каждом запуске игры, необходимо обеспечить его постоянное наличие.

Пути интеграции

Существует два пути интеграции: клиентская и межсерверная.

Интеграция серверов

Публичная конечная точка API позволяет отправлять события в полезной нагрузке запроса, используя следующие конфигурации:

HTTP-запрос

POST https://games.googleapis.com/games/v1/players/{playerId}/gameStats: batchRecordEvents

Параметры пути

Авторизация и аутентификация

Server-to-server API calls follow standard Server-side access to Play Games Services guidelines using OAuth 2.0. Requests must include a Bearer token authorized with the https://www.googleapis.com/auth/games scope.

События: Текст запроса

API бэкэнда имеет строгие ограничения по проверке структуры:

• Размер пакета: максимум 30 событий на один запрос BatchRecordEventsRequest .
• Количество объектов недвижимости: максимум 25 пользовательских объектов на одно PlayerGameEvent .
• Ограничения по длине: название события (максимум 100 символов), ключи свойств (максимум 100 символов) и строковые значения свойств (максимум 1024 символа).
• Идентификатор события: Должен представлять собой допустимую 36-символьную строку UUID .
• Retry and caching: Avoid caching or accumulating excessive events locally if the API fails, as batch retries exceeding 30 events will be rejected. Always chunk retries to respect the batch size limit.

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").
}

Стоимость недвижимости

// 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")
}

Орган ответа

В случае успеха возвращается HTTP-код 200 OK с пустым JSON-объектом.

Пример текста запроса

Событие: 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
      }
    }
  ]
}

Внедрение клиентских решений

Чтобы узнать о реализации клиента Game Stats для вашей платформы, ознакомьтесь со следующими ресурсами:

• Android
• Единство
• C++

Важные этапы