Игровая статистика – это совокупные данные об игре, доступные в профиле. С помощью этой статистики пользователи могут отслеживать прогресс за все время, просматривать лучшие моменты и сравнивать свои результаты с достижениями других игроков. Кроме того, она позволяет использовать такие функции Google Play, как квесты и задания.
Игровая статистика должна:
- Не требовать покупки (например, самоцветов), то есть не обновляться в результате покупки в приложении.
- Не требовать просмотра рекламы, то есть не обновляться в результате просмотра рекламы.
- Не описывать стандартные действия в игре, например "открыть игру" или "использовать настройки".
- Не включать личные и конфиденциальные пользовательские данные, как определено в правилах Google Play, в том числе идентификаторы пользователей, пароли, точное местоположение или данные о здоровье, а также любой оскорбительный, непристойный, сексуально откровенный, жестокий или разжигающий ненависть контент.
- Быть доступным всем пользователям (например, не быть командным действием, не быть доступным только пользователям определенного уровня или только в рамках ограниченных по времени событий и т. д.).
На изображении показана игровая статистика в профиле игрока на вкладке Вы. Этот пользовательский интерфейс на вкладке Вы доступен только для тестирования. Интерфейс игровой статистики станет доступен в сентябре 2026 года.
Тип агрегирования
Тип агрегирования указывает Google Play, как рассчитывать статистику на основе значений, которые вы отправляете для каждого события.
- SUM. Используется для суммарной статистики (например, общее количество собранных монет, общий нанесенный урон). Игра должна отправлять точную сумму, заработанную во время каждого события.
- COUNT. Используйте для статистики, представляющей количество вхождений события (например, сыгранных или выигранных игр). Игра должна отправлять отдельные экземпляры событий.
- MAX. Используйте только для разовых достижений, например максимального количества очков за один забег, максимальной серии комбо или максимального урона за один матч. Не используйте MAX в качестве обходного пути для отображения общих итогов за все время на основе предварительно вычисленных текущих значений.
Важное требование к реализации повторяющихся показателей
- Отправлять значения для каждого события. Для каждого события отправляются только данные о том, что произошло в этом событии, например о монетах, собранных за один запуск. Затем задайте тип агрегирования, например SUM или COUNT, в конфигурации статистики. Это позволяет повторно использовать повторяющиеся статистические данные в разных механиках вовлечения и помогает Google Play создавать подходящие условия для игроков.
- Не отправляйте общие значения за все время. Например, не отслеживайте общее количество монет, собранных игроком за все время, и не отправляйте это значение с агрегированием MAX. Она по-прежнему будет показываться в профиле игрока, но Google Play не сможет использовать ее для работы лиг, квестов, спринтов и других функций, которые улучшают игровой процесс и повышают популярность игры.
Инструкции и примеры правильного моделирования событий можно найти в статьях События игрока и Настройка статистики.
Интеграция инструментов
Отправьте данные с помощью Game Stats API в виде событий игрока для повторяющейся статистики и предопределенного события progressUpdate для статистики прогресса. Вам также потребуется настроить логику расчета статистики, которая будет отображаться в профиле игрока, и информацию о ее отображении.
События игрока представляют собой определенные моменты в игре, завершение игрового цикла или этапы прогресса.
Событие игрока определяется и моделируется следующим образом:
- Событие – это определенное действие игрока, например завершение матча, прохождение уровня, открытие сундука или сохранение прогресса в определенной области.
- Каждое действие приводит к определенным результатам или имеет определенные характеристики, определяющие действие. Они моделируются как свойства событий, которые предоставляют контекст о событии и его конкретных результатах (например, тип матча, монеты, собранные во время этого забега, результат матча или количество выстрелов в голову).
Интеграция состоит из следующих этапов:
- Объявите схему первичных данных. Определите события игроков, загрузив CSV-файл в Play Console. Подробнее о том, как создать мероприятие…
- Интегрируйте Game Stats API. Отправляйте необработанные данные игроков в объявленном формате для событий игроков и события
progressUpdate.- Отправьте все заданные события, используя интеграцию на стороне клиента или сервера.
Дополнительную информацию можно найти в примерах для событий проигрывателя и события
progressUpdate.
- Отправьте все заданные события, используя интеграцию на стороне клиента или сервера.
Дополнительную информацию можно найти в примерах для событий проигрывателя и события
- Загрузите ZIP-файл. Предоставьте три CSV-файла и все файлы значков, которые определяют пять повторяющихся показателей и один уровень прогресса игрока.
Дополнительную информацию о требованиях к ZIP-файлам можно найти в этом разделе.
Укажите следующие сведения:
- CSV-файл для повторяющихся статистических данных:
- Уникальный идентификатор показателя.
- Укажите ярлык события, который будет использоваться для расчета статистики. Здесь нельзя использовать ярлык события
progressUpdate.- Укажите ярлык свойства, который будет использоваться для расчета статистики. Это должно быть свойство указанного события.
- Укажите тип агрегирования (SUM, MAX, MIN или COUNT), чтобы определить, как рассчитывать статистику по выбранному ярлыку свойства.
- Укажите необязательное условие фильтра, чтобы логика вычислялась только при его выполнении. Укажите свойство и ярлык события, оператор (=, <, <=, >= или >) и пороговое значение.
- Добавьте логический флаг, чтобы указать, можно ли использовать статистику для соревновательных функций.
- Если функция может использоваться для соревновательных функций, то минимальные и максимальные почасовые лимиты для реального игрока. Это поможет нам выявлять игроков, которые нарушают правила, участвуя в лигах и социальных заданиях.
- Укажите уникальное отображаемое название показателя, которое будет видно игрокам.
- Укажите уникальный текст с описанием статистики. В нем должно быть подробно рассказано, как игрок может заработать этот показатель. Описание будет показываться в интерфейсе игрового профиля.
- Укажите уникальный значок, представляющий показатель, введя точное название файла значка в CSV-файле.
- Укажите, что лучше для игрока: увеличение или уменьшение значения. Эти данные будут использоваться для празднования движений игроков.
- Укажите единицу измерения для показателя, например км, мили или секунды.
- CSV-файл для статистики прогресса игрока:
- Укажите уникальное отображаемое название для прогресса игрока, которое будут видеть пользователи.
- Укажите уникальный значок, представляющий показатель.
- Добавьте описание показателя прогресса.
- Укажите, что лучше для игрока: увеличение или уменьшение значения. Эти данные будут использоваться для
празднования перемещений игроков, только если
свойство
currentProgressимеет тип INT. - Укажите единицу измерения для показателя, например км, мили, секунды.
- CSV-файл для локализации. Укажите локализованные отображаемые названия для всех показателей.
- Добавьте по одной строке для каждой локализации.
- Чтобы однозначно идентифицировать показатель, для которого добавляется локализация, используйте строку отображаемого названия показателя, добавленную в предыдущем CSV-файле.
- Укажите язык из списка кодов языков.
- Добавьте локализованное отображаемое название на указанном языке.
- Добавить локализацию для описания статистики на указанном языке.
- CSV-файл для повторяющихся статистических данных:
Планирование схемы
С помощью Game Stats API можно отправлять два типа данных: события игроков и предопределенные события для статистики прогресса игроков.
Ниже приведены примеры событий игроков в играх разных типов.
События в проигрывателе
События игрока определяются отдельными моментами в игре, завершением игрового цикла или этапами прогресса.
- Определите события как определенные моменты в игре, завершение игрового цикла или этапы прохождения:
- Завершение игрового цикла, например матча или забега.
- Прогресс в игре, например сохраненные данные об исследовании области или пройденный уровень.
- Поскольку повторяющаяся статистика должна отражать повторяющиеся действия игрока, заданные события должны быть связаны с основным геймплеем.
- Добавьте свойства, чтобы предоставить контекст о событии и его результатах, например номер уровня, тип матча, тип оружия, количество оружия, выстрелы в голову, собранные монеты, результат матча, время круга или тип автомобиля.
- Отправляйте события в рамках игрового сеанса сразу после их возникновения. Например, отправляйте событие о завершении игрового цикла сразу после его окончания.
Примеры
| Тип игры | Ярлык события | Момент в игре / завершение события / завершение игрового цикла | Результат | Характеристики |
|---|---|---|---|---|
| Инди-головоломка с линейным развитием сюжета | chapter_completed | Завершение события прогресса | Н/Д | Номер главы, название главы, количество попыток, количество экранов, количество ходов, контент главы |
| screen_completed | Завершение события прогресса | Номер главы, название главы, количество попыток, количество ходов, содержимое главы | ||
| Бесконечный 3D-раннер | run_completed | Завершение игрового цикла | Собранные монеты, счет | Продолжительность забега, монеты, собранные с помощью реактивного ранца, ускоритель, использованный в начале забега, использованные доски для серфинга, магниты, прыгуны и реактивные ранцы. |
| Ролевая экшен-игра с открытым миром | areaExplorationProgress | Завершение события прогресса | Побежденные враги, собранные зелья | Номер области, название области, процент выполнения |
| questCompleted | Завершение игрового цикла | Н/Д | Название квеста | |
| weaponUnlocked | Момент из игры | Н/Д | Название оружия, уровень оружия | |
| chestUnlocked | Момент из игры | Собрано руды для улучшения | ||
| Простая головоломка с декоративной метой | puzzleCompleted | Завершение игрового цикла / события прогресса | Собранные монеты, собранные бустеры | Количество ходов, Использован ли подарок дворецкого?, Тип уровня, номер уровня, использованные цветные бустеры, использованные динамиты |
| cardsCollected | Момент из игры | Карты с одной, двумя и тремя звездами, общее количество карт | Номер альбома, название альбома | |
| Аркадные гонки | raceCompleted | Завершение игрового цикла | Rank, NOS used, race_time | Тип гонки, рейтинг, используемый автомобиль |
| carUpgraded | Момент в игре | Улучшенная характеристика автомобиля, старый уровень / значение, новый уровень / значение. | Тип автомобиля, текущий уровень гаража | |
| Шутер от третьего лица в жанре королевской битвы | matchCompleted | Завершение игрового цикла | Побежденные противники, попадания в голову, очки чести | Тип матча, время выживания |
| Симуляторы киберспортивного менеджмента | matchCompleted | Завершение игрового цикла | Результат, забитые голы, голы | Название команды соперника, название играющей команды |
| trainingCompleted | Момент в игре | Drills done, teamplay_form_attack, teamplay_form_defense, teamplay_form_possession, teamplay_form_condition |
progressUpdate событие
Если в вашей игре есть основная механика прогресса, используйте это событие, чтобы отправлять данные о текущем прогрессе игрока. У события есть одно стандартное свойство currentProgress типа INT или STRING. В этом свойстве нужно передавать текущее значение прогресса игрока в основной механике. Если вы используете это событие, необходимо указать предопределенное свойство currentProgress и определить с его помощью статистику прогресса.
Вы можете отправлять текущее значение для других систем прогресса в игре, например lifetime highest score или current coin balance, в качестве других свойств этого события.
Поскольку игроки могут сравнивать свои профили по текущему прогрессу в игре, важно, чтобы после первой интеграции не было задержки в получении текущего значения прогресса. Чтобы игроки видели точные данные о текущем прогрессе, отправляйте событие progressUpdate в начале каждого игрового сеанса, а также при каждом обновлении текущего прогресса.
Примеры
| Тип игры | Свойство currentProgress события progressUpdate |
|---|---|
| Головоломка с линейным прохождением | Номер текущей главы или уровня |
| 3D-раннер | Рекорд, текущий баланс бустеров |
| Казуальные головоломки | Текущий уровень, количество побед с первой попытки, количество пройденных областей, количество собранных коллекций. |
| Аркадные гонки | Номер текущего уровня, баланс валюты |
| Ролевая экшен-игра с открытым миром | Текущий ранг персонажа, текущий уровень |
| Шутеры от третьего лица | Номер текущего уровня |
| Симуляторы киберспорта | Уровень менеджера, уровень клуба |
Настройте статистику
Вам нужно будет настроить повторяющиеся и прогрессивные показатели, определив логику вычислений и отображаемую информацию для каждого показателя. Примеры повторяющихся показателей из разных жанров игр приведены ниже. Повторяющаяся статистика обычно обновляется для любого игрока в течение нескольких (3–4) игровых сеансов и связана с основным игровым циклом.
Чтобы узнать, когда использовать SUM, COUNT или MAX, прочитайте статью Как выбрать подходящий тип агрегирования.
| Название игры | Отображаемое название игровой статистики | Свойство события | Логика расчета [aggregation] | Фильтр |
|---|---|---|---|---|
| Бесконечный 3D-раннер | Выполненные пробежки | Любое свойство события run_completed | Количество | Все значения [без фильтра] |
| Собрано монет | Свойство coins_collected события run_completed | Сумма | Н/Д | |
| Собрано ключей | Свойство keys_collected события run_completed | Сумма | Н/Д | |
| Наивысшая оценка состояния во время бега | Свойство score события run_completed | Максимум | Н/Д | |
| Забегов с большим количеством монет завершено | Свойство coins_collected события run_completed | Количество | Value > 5000 | |
| Головоломка с линейным прохождением | Главы завершены | Любое свойство события chapter_completed | Количество | Все значения [без фильтра] |
| Завершено экранов | Любое свойство события screen_completed | Количество | Все значения [без фильтра] | |
| Главы, пройденные с первой попытки | Свойство num_try события chapter_completed | Количество | Num_try = 1 | |
| Экраны, пройденные с первой попытки | Свойство num_try события screen_completed | Количество | Num_try = 1 | |
| Ролевая экшен-игра с открытым миром | Квесты выполнены | Любое свойство события quest_completed | Количество | Все значения [без фильтра] |
| Исследованные области | Свойство perc_progress события area_exploration_progress | Количество | Ценность = 100 | |
| Разблокировано мечей | Свойство weapon_type события weapon_unlocked | Количество | Значение – "меч". | |
| Побеждено врагов | Свойство enemies_defeated события area_exploration_progress | Сумма | Н/Д | |
| Собрано зелий здоровья | Свойство enhancement_ores события chest_unlocked | Сумма | Н/Д | |
| Казуальные головоломки | Уровней пройдено | Любое свойство события level_completed | Количество | Все значения [без фильтра] |
| Уровней пройдено с первой попытки | Свойство num_try события level_completed | Количество | Ценность = 1 | |
| Использовано усилителей цвета | Свойство Color_booster_used события level_completed | Сумма | Н/Д | |
| Использовано бомб | Свойство Bomb_booster_used события level_completed | Сумма | Н/Д | |
| Собрано карт | Свойство total_cards события cards_collected | Сумма | Н/Д | |
| Аркадные гонки | Победы | Свойство rank события race_completed | Количество | Ценность = 1 |
| Самый быстрый забег | Свойство race_time события race_completed | Мин. | Н/Д | |
| NOS used | Свойство NOS_used события race_completed | Сумма | Н/Д | |
| Гонки, завершенные на Mustang | Свойство car_type события race_completed | Количество | Value = "Mustang" | |
| Улучшения для автомобилей | Любое свойство события car_upgraded | Количество | Все значения [без фильтра] | |
| Шутер от третьего лица в жанре королевской битвы | Выиграно матчей | Любое свойство события match_completed | Количество | Match_result = TRUE |
| Всего побежденных противников | Свойство Eliminations события match_completed | Сумма | Н/Д | |
| Наибольшее время выживания | Свойство survival_time события match_completed | Максимум | Н/Д | |
| Всего попаданий в голову | Свойство headshots события match_completed | Сумма | Н/Д | |
| Общая ценность навыка | Свойство skill_value события match_completed | Сумма | Н/Д | |
| Симуляторы киберспортивного менеджмента | Выиграно матчей | Свойство result события match_completed | Количество | Результат = "Выиграно" |
| Всего голов | Свойство goals_scored события match_completed | Сумма | Н/Д | |
| Выиграно матчей на харде | Свойство result события hard_match_completed | Количество | Результат = "Выиграно" | |
| Наибольшая разница голов | Свойство goal_difference события match_completed | Максимум | Результат = "Выиграно" | |
| Всего тренировок | Свойство drills_done события training_completed | Сумма | Н/Д | |
| Всего тренингов пройдено | Любое свойство события training_completed | Количество | Н/Д |
Сведения об интеграции
В этом разделе рассказывается, как создавать события и отправлять их при интеграции на стороне клиента и сервера.
Когда отправлять данные
События игрока представляют собой действия в игре, связанные с завершением игровых циклов или определенными моментами в игре. Отправляйте эти события сразу после их возникновения. Например, отправьте событие завершения игрового цикла, как только он завершится.
progressUpdate Event представляет текущий уровень прогресса игрока.
Данные для статистики прогресса должны отправляться с помощью этого события в следующих ситуациях:
- При обновлении текущего прогресса немедленно отправляйте последнее значение.
- Каждый раз, когда игрок запускает игру, чтобы обеспечить постоянное наличие этой статистики для игрока.
Способы интеграции
Существует два способа интеграции: на стороне клиента и межсерверная.
Межсерверная интеграция
Общедоступная конечная точка API позволяет отправлять события в полезной нагрузке запроса, используя следующие конфигурации:
HTTP-запрос
POST https://games.googleapis.com/games/v1/players/{playerId}/gameStats:
batchRecordEvents
Параметры пути
| Параметр | Тип данных | Описание |
|---|---|---|
| playerId | Строка | Идентификатор игрока в игровых сервисах Google Play. |
Авторизация и аутентификация
Вызовы API между серверами выполняются в соответствии со стандартными рекомендациями по доступу к игровым сервисам Play на стороне сервера с использованием OAuth 2.0. Запросы должны содержать токен на предъявителя, авторизованный в области действия https://www.googleapis.com/auth/games.
События: тело запроса
Для API бэкенда действуют строгие ограничения на проверку структуры:
- Размер пакета. Максимум 30 событий на
BatchRecordEventsRequest. - Количество свойств. Для каждого
PlayerGameEventможно задать не более 25 дополнительных параметров. - Ограничения по длине: название события (не более 100 символов), ключи свойств (не более 100 символов) и строковые значения свойств (не более 1024 символов).
- Идентификатор события. Должен быть действительной строкой UUID из 36 символов.
- Повторные попытки и кеширование. Избегайте кеширования или накопления слишком большого количества событий на локальном устройстве в случае сбоя 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") }
Тело ответа
В случае успеха возвращает статус 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 } } ] }
Реализации на стороне клиента
Чтобы узнать, как реализовать клиент игровой статистики для вашей платформы, ознакомьтесь со следующими ресурсами:
Важные события
| Дата | Интеграция API игровой статистики | Конфигурация игровой статистики |
| Сентябрь 2026 г. | Н/Д | Игроки начнут видеть игровую статистику в своих игровых профилях. |