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

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

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

• Не требует совершения покупок (например, покупки самоцветов), то есть обновления не должны происходить в результате каких-либо внутриигровых покупок.
• Не требуется просмотр рекламы, то есть обновления не должны происходить в результате просмотра рекламы.
• Не следует использовать игру слишком шаблонно (например, открыть игру; зайти в настройки).
• Запрещается размещать персональные и конфиденциальные данные пользователей, как это определено в Политике Play, включая идентификаторы пользователей, пароли, точные данные о местоположении или состоянии здоровья, а также любой оскорбительный, нецензурный, содержащий сексуальные намеки, насильственный или разжигающий ненависть контент.
• Должно быть доступно всем пользователям (например, не являться действием, предназначенным для конкретной команды, не быть доступным только пользователям определенного уровня или быть доступным только в течение ограниченного времени в рамках текущих операций и т. д.).

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

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

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

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

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

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

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

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

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

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

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

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

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

событие progressUpdate

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

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

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

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

Вам потребуется настроить повторяющиеся и прогрессивные статистические данные, определив логику вычислений и отображение информации о каждом показателе. Примеры повторяющихся статистических данных из разных игровых жанров приведены ниже. Повторяющиеся статистические данные — это, как правило, показатели, которые многократно обновляются для любого игрока в течение очень небольшого количества (3-4) игровых сессий и связаны с основным игровым циклом.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Размер пакета: максимум 30 событий на один запрос BatchRecordEventsRequest .
• Количество объектов недвижимости: максимум 25 пользовательских объектов на одно PlayerGameEvent .
• Ограничения по длине: название события (максимум 100 символов), ключи свойств (максимум 100 символов) и строковые значения свойств (максимум 1024 символа).
• Идентификатор события: Должен представлять собой допустимую 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").
}

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

// 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++

Важные этапы