Эта страница переведена с помощью Cloud Translation API.

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

Игровая статистика — это накопительные статистические данные о вашей игре, которые игроки могут просматривать в своем профиле . Эта статистика позволяет игрокам отслеживать свой прогресс за все время игры, видеть самые яркие моменты, сравнивать свои результаты с результатами других игроков, а также использовать ее для работы таких функций Google Play, как квесты, социальные испытания и многое другое в будущем.

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

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

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

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

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

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

Объявите схему исходных данных: определите события игрока, используя загрузку CSV-файла в консоли Play. См. рекомендации по работе с CSV-файлами .
Интеграция с API игровой статистики: отправка необработанных данных об игроке в заявленном формате для гибкого управления событиями, связанными с игроком, и событием progressUpdate .
- Отправляйте все определенные события, используя интеграцию на стороне клиента или сервера. Для получения дополнительной информации см. примеры для гибких событий и события progressUpdate .
Загрузите ZIP-файл: предоставьте 3 CSV-файла и все файлы изображений значков, определяющие 5 повторяющихся статистических показателей и 1 уровень прогресса игрока. Для получения дополнительной информации см. рекомендации по загрузке ZIP-файлов . Укажите следующие данные:
- CSV-файл для повторяющейся статистики:
  - Уникальный идентификатор для данного показателя.
  - Укажите метку события, которая будет использоваться для расчета статистики. Здесь нельзя использовать метку события progressUpdate .
    - Укажите метку свойства, которая будет использоваться для расчета статистики. Это должно быть свойство указанного события.
    - Укажите тип агрегирования (SUM, MAX, MIN или COUNT), чтобы определить, как вычислять статистические данные по выбранной метке свойства.
    - Укажите необязательное условие фильтрации, чтобы логика вычислялась только при выполнении этого условия. Определите свойство и метку события, оператор (=, < или >) и пороговое значение.
  - Добавьте логический флаг, указывающий, можно ли использовать этот показатель для соревновательных функций.
  - Если функция предназначена для соревновательных мероприятий, то будут установлены минимальные и максимальные почасовые лимиты для реального игрока. Это позволит нам выявлять игроков, которые могут злоупотреблять функцией, участвуя в таких мероприятиях, как лиги и социальные челленджи.
  - Укажите уникальное отображаемое имя для статистики, которую видят игроки.
  - Предоставьте уникальное описание характеристики. В описании следует подробно рассказать, как игрок её получает.
  - Укажите уникальный значок, представляющий статистику, введя точное имя файла значка из CSV-файла.
  - Укажите порядок отображения статистики в профиле игрока, чтобы определить, в каком порядке игрок будет ее видеть.
  - Укажите необязательный параметр, который определяет, подходит ли игроку возрастающее или убывающее значение. Этот параметр будет использоваться для празднования действий игрока.
  - Укажите необязательную единицу измерения для данного показателя, например, километры, мили и секунды.
- CSV-файл со статистикой прогресса игрока:
  - Укажите уникальное отображаемое имя для прогресса игрока, которое видят игроки.
  - Укажите уникальный значок, представляющий данный статистический показатель.
  - Укажите описание показателя прогресса.
  - Укажите необязательный параметр, который определяет, какое значение — возрастающее или убывающее — подходит игроку. Этот параметр будет использоваться для отображения действий игрока только в том случае, если свойство currentProgress имеет тип INT.
  - Укажите необязательную единицу измерения для данного показателя, например, км, мили, секунды.
- CSV-файл для локализации: Укажите локализованные отображаемые имена для всех статистических данных.
  - Добавьте по одной строке для каждой локализации.
  - Используйте строку с отображаемым именем статистики, добавленную в предыдущем CSV-файле, чтобы однозначно идентифицировать статистику, к которой добавляется локализация.
  - Выберите язык из списка языковых кодов.
  - Добавить локализацию для отображаемого имени на указанном языке.
  - Добавить локализацию для описания статистики на указанном языке.

Название мероприятия	Название объекта недвижимости	Тип недвижимости
матч завершен	продолжительность	ДВОЙНОЙ
матч завершен	убивает	ИНТ
матч завершен	isWinner	БУЛЕВОЕ
матч завершен	matchType	СТРОКА (UTF-8)
itemCollected	количество монет	ИНТ
itemCollected	тип оружия	СТРОКА (UTF-8)
прогрессОбновление	текущий прогресс	ИНТ

Имя файла	Обязательный или необязательный	Принятые значения
`RepetitiveStatsConfig.csv`	Необходимый	Метаданные для множества событий.
`ProgressionStatConfig.csv`	Необходимый	Объявленное событие и его свойства.
`StatLocalizations.csv`	Необязательный	Предоставляет переводы названий и описаний достижений.
Файлы значков	Необходимый	Иконки в формате PNG, JPEG или JPG размером 512 x 512 пикселей.

Идентификатор статистики	Название мероприятия	Название объекта недвижимости	Агрегация	Статистическое отображаемое имя	Описание характеристик	Свойство фильтра (необязательно)	Оператор фильтра (опционально)	Значение фильтра (необязательно)	Конкурентоспособен	минЛимит	maxLimit	имя файла значка	Порядковый номер	Выгодное направление	единица
1	матч завершен	продолжительность	МАКС	Самый долгий матч на выживание	Это показатель времени выживания игрока в любом матче.	isWinner	=	истинный	истинный	0	50	stat1.png	1	Снижение	секунд
2	матч завершен	isWinner	СЧИТАТЬ	Выигранные матчи	Это обозначает количество выигранных игроком матчей.	isWinner	=	истинный	истинный	0	50	stat3.png	2	Увеличение
3	матч завершен	убивает	СУММА	убийства в матче 1 на 1	Количество убийств, совершенных в матчах 1 на 1.	matchType	=	"1 на 1"	ЛОЖЬ			stat4.png	4	Увеличение
4	itemCollected	количество монет	СУММА	Общее количество собранного золота	Игрок собирает монеты во время игры в матче.	тип оружия	=	"меч"	ЛОЖЬ			stat2.png	3	Увеличение

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

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

Гибкие мероприятия для игроков

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

Определите события как конкретные игровые моменты, завершение игрового цикла или этапы прогресса:
- Завершение игрового цикла, например, завершенный матч или забег.
- Этапы прогресса, такие как сохранение прогресса в исследовании локаций или завершение уровня.
Добавьте свойства , чтобы предоставить контекст события и его результатов, такие как номер уровня, тип матча, тип оружия, количество оружия, попадания в голову, собранные монеты, результат матча, время круга или тип автомобиля.
Отправляйте события в рамках игровой сессии сразу же после их возникновения. Например, отправьте событие завершения игрового цикла сразу после его завершения.

Примеры

Тип игры	Метка события	Игровой момент / Завершение события прогресса / Завершение игрового цикла	Исход	Характеристики
Линейная прогрессия — инди-головоломка	глава_завершена	Завершение события прогресса	Н/Д	Номер главы, название главы, количество попыток, количество экранов, количество ходов, содержание главы.
Линейная прогрессия — инди-головоломка	экран_завершен	Завершение события прогресса		Номер главы, название главы, количество попыток, количество ходов, содержание главы.
3D Бесконечный раннер	run_completed	Завершение игрового цикла	Собранные монеты, счет	Продолжительность забега, количество монет, собранных с реактивного ранца, ускоритель, использованный в начале забега, использованные доски для серфинга, использованные магниты, использованный прыгун, использованный реактивный ранец.
Экшен-RPG с открытым миром	areaExploringProgress	Завершение события прогресса	Враги побеждены, зелья собраны.	Номер участка, название участка, процент выполнения работ.
	questCompleted	завершение игрового цикла	Н/Д	Название задания
	оружиеРазблокировано	Момент в игре	Н/Д	Название оружия, уровень оружия
	сундукРазблокирован	Момент в игре	Собранная руда для улучшения качества
Простая головоломка с декоративными мета-элементами	головоломка завершена	Завершение игрового цикла / Завершение события прогресса	Собранные монеты, собранные бустеры	Количество ходов, использованный подарок дворецкого, тип уровня, номер уровня, использованные цветные бустеры, использованная динамитная шашка
Простая головоломка с декоративными мета-элементами	cardsCollected	Момент в игре	1-звездочные карты, 2-звездочные карты, 3-звездочные карты, всего карт	Номер альбома, Название альбома
Аркадные гонки	гонка завершена	завершение игрового цикла	Ранг, использованная закись азота, время гонки	Тип гонки, рейтинг, используемый автомобиль
Аркадные гонки	автомобильОбновлён	Момент в игре	Характеристики автомобиля, которые были модернизированы, старый уровень/значение, новый уровень/значение	Тип автомобиля, текущий уровень гаража
Шутер в жанре «королевская битва» от третьего лица	матч завершен	завершение игрового цикла	Устранения, выстрелы в голову, ценность чести	Тип матча, время выживания
Симуляция управления киберспортом	матч завершен	завершение игрового цикла	Результат, забитые голы, голы	Название команды-соперника, название играющей команды
Симуляция управления киберспортом	обучение завершено	Момент в игре	Выполненные упражнения, teamplay_form_attack, teamplay_form_defense, teamplay_form_possession, teamplay_form_condition

событие `progressUpdate`

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

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

Примеры

Тип игры	свойство currentProgress события `progressUpdate`
Головоломка «Линейная прогрессия»	Текущий номер главы или номер уровня
3D Бесконечный Бегун	Рекордный результат, текущий баланс бустеров
Простая головоломка	Номер текущего уровня, количество побед с первой попытки, количество завершенных областей, количество завершенных сборов.
Аркадные гонки	Текущий уровень, валютный баланс
Экшен-RPG с открытым миром	Текущий ранг персонажа, текущий уровень.
Шутер от третьего лица	Текущий номер уровня
Симулятор киберспорта	Номер уровня менеджера, номер уровня клуба

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

API-интерфейсы и SDK доступны для получения предварительной обратной связи и будут выпущены в общий доступ (GA) начиная с июля 2026 года. См. график.

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

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

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

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

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

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

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

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

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

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

Параметр	Тип данных	Описание
playerId	Нить	Идентификатор PGS игрока.

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

Вызовы API между серверами осуществляются в соответствии со стандартными правилами доступа к сервисам Play Games на стороне сервера с использованием OAuth 2.0. Запросы должны включать токен Bearer, авторизованный в рамках области действия https://www.googleapis.com/auth/games .

Гибкие мероприятия: Запрос на предоставление информации

BatchRecordEventsRequest

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

PlayerGameEvent

{
  "eventId": string,
  "eventName": string,
  "eventProperties": {
    // keys (e.g., "matchId", "score")
    "": {
       object (PropertyValue)
    }
  },
  "eventTime": string
}

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

// 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,
// RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
"timestampValue": "string",
// 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
}

Орган ответа

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

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

Гибкое событие: PlayerGameEvent

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-01-01T18:00:00Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID for deduplication //and idempotency
      "eventName": "matchCompleted",
      "eventTime": "2026-01-01T17:00:00Z",
      "eventProperties": {
        "matchId": {
          "stringValue": "Match_A"
        },
        "gameMode": {
          "stringValue": "Battle_B"
        },
        "locationId": {
          "stringValue": "Location_XYZ"
        },
        "playerElimination": {
          "intValue": 2
        },
        "survivalTimeSeconds": {
          "durationValue": "240s"
        },
        "isWinner": {
          "boolValue": true
        }
      }
    }
  ]
}

событие progressUpdate

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-01-01T18:00:00Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID
      "eventName": "progressUpdate",
      "eventTime": "2026-01-01T17:00:00Z",
      "eventProperties": {
        "currentProgress": {
          "intValue": 52
        },
//Add more properties as per your requirement
      }
    }
  ]
}

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

Интеграция на стороне клиента будет доступна с использованием SDK Unity, Java и C++.

Интеграция PlayerGameEvent на стороне клиента предполагает создание объекта события на Java или C#, в зависимости от SDK, в точках срабатывания и отправку этих данных с помощью функций загрузки, предоставляемых SDK.

Аналогично, для события progressUpdate запишите обновленный прогресс, используя свойство currentProgress с дополнительными определенными свойствами, и отправьте их с помощью функций загрузки, предоставляемых SDK.

События

Интеграция PlayerGameEvent на стороне клиента включает в себя:

Создание гибких игровых событий для игроков

Java


// Build the PlayerGameEvent
PlayerGameEvent event = new PlayerGameEvent.Builder("matchCompleted")
  .addProperty("matchId", "Match_A")
  .addProperty("gameMode", "Battle_B")
  .addProperty("mapId", "Location_XYZ")
  .addProperty("isWinner", true)
  .addProperty("survivalTimeSeconds", "240s")
  .addProperty("playerElimination", 2)
  .build();

List events = new ArrayList<>();
// ... populate list ...

Единство


// Build the PlayerGameEvent
var playerEvent = new PlayerGameEvent.Builder("matchCompleted")
   .AddProperty("matchId", "Match_A")
   .AddProperty("gameMode", "Battle_B")
   .AddProperty("mapId", "Location_XYZ")
   .AddProperty("isWinner", true)
   .AddProperty("survivalTimeSeconds", "240s")
   .AddProperty("playerElimination", 2)
   .Build();
var events = new List();
// ... populate list ...

C++


// Build the PlayerGameEvent
PgsPlayerGameEvent* player_event = PgsPlayerGameEvent_create("matchCompleted");
if (player_event != nullptr) {
   PgsPlayerGameEvent_putString(player_event, "matchId", "Match_A");
   PgsPlayerGameEvent_putString(player_event, "gameMode", "Battle_B");
   PgsPlayerGameEvent_putString(player_event, "mapId", "Location_XYZ");
   PgsPlayerGameEvent_putBoolean(player_event, "isWinner", true);
   PgsPlayerGameEvent_putString(player_event, "survivalTimeSeconds", "240s");
   PgsPlayerGameEvent_putLong(player_event, "playerElimination", 2);
}

Обновление `progressUpdate` сборки. Обновление игрового события игрока.

Java


// Build the PlayerGameEvent
PlayerGameEvent event = new PlayerGameEvent.Builder("progressUpdate")
  .addProperty("currentProgress", 52)
  // Add other properties if needed
  .build();

List events = new ArrayList<>();
// ... populate list ...

Единство


// Build the PlayerGameEvent
var progressEvent = new PlayerGameEvent.Builder("progressUpdate")
   .AddProperty("currentProgress", 52)
   // Add other properties if needed
   .Build();
var events = new List();
// ... populate list ...

C++


PgsPlayerGameEvent* progress_event = PgsPlayerGameEvent_create("progressUpdate");
if (progress_event != nullptr) {
   PgsPlayerGameEvent_putLong(progress_event, "currentProgress", 52);
}

Запись события и загрузка

Java


// Buffers the event locally.
client.recordEvent(event);

// Buffers the events locally, (List version)
client.recordEvents(events);

// This submits the events to PGS
client.requestEventsUpload();

Единство


// Buffers the event locally.
PlayGamesPlatform.Instance.RecordEvent(playerEvent);

// Buffers the events locally, (List version)
PlayGamesPlatform.Instance.RecordEvents(events);

// This submits the events to PGS
PlayGamesPlatform.Instance.RequestEventsUpload();

C++


// Record the event
PgsGameStatsClient_recordEvent(client, player_event);

// This submits the events to PGS
PgsGameStatsClient_requestEventsUpload(client);

// Clean up handle to avoid leaks
PgsPlayerGameEvent_destroy(player_event);

// Clean up client handle when PGS operations are finished
PgsGameStatsClient_destroy(client);

Хронология

Дата	Интеграция API игровой статистики	Настройка игровой статистики
Июнь 2026 г.	Разработчики могут начать планировать модели данных.	Нет в наличии
Июль 2026 г.	API доступен всем разработчикам для начала интеграции (общедоступен в режиме GA). Входящие данные проверяются на соответствие предоставленной схеме и конфигурации.	API конфигурации для предоставления настроек схемы событий и статистики.
Август 2026 г.	Н/Д	Функция Play Console уже доступна и поддерживает загрузку CSV-файлов.
Сентябрь 2026 г.	Н/Д	Игроки начинают видеть игровую статистику в своем профиле.

Имя файла	Обязательный или необязательный
PlayerGameEvent.csv	Необходимый

Идентификатор статистики	Статистическое отображаемое имя	Описание характеристик	Имя файла значка	Выгодное направление
5	Уровень	Игроки накапливают опыт, участвуя в матчах, и повышают свой уровень.	Level.png	увеличение

Статистика игры Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

Рекомендации по использованию CSV-файлов для организации мероприятий

Формат файла PlayerGameEvent.csv

Пример таблицы

Рекомендации по архивированию ZIP-файлов для статистики

Формат RepetitiveStatsConfig.csv

Пример таблицы

Формат ProgressionStatConfig.csv

Пример таблицы

Формат StatLocalizations.csv

Пример таблицы

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

Гибкие мероприятия для игроков

Примеры

событие progressUpdate

Примеры

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

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

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

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

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

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

Гибкие мероприятия: Запрос на предоставление информации

Событие progressUpdate : Тело запроса

Орган ответа

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

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

События

Создание гибких игровых событий для игроков

Java

Единство

C++

Обновление progressUpdate сборки. Обновление игрового события игрока.

Java

Единство

C++

Запись события и загрузка

Java

Единство

C++

Хронология

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

событие `progressUpdate`

Событие `progressUpdate` : Тело запроса

Обновление `progressUpdate` сборки. Обновление игрового события игрока.