Как интегрировать игровую статистику

В этом документе рассказывается, как интегрировать игровую статистику в игру с помощью Google Play Console. Вы узнаете, как создавать, импортировать и настраивать файлы CSV и ZIP.

Как создать или импортировать события

Если вы впервые добавляете события для игры с помощью Google Play Console, это можно сделать двумя способами:

Как создать событие

Чтобы создать событие для игры, выполните следующие действия:

  1. Выберите игру в Google Play Console.
  2. На странице Сервисы Play Games – Игровая статистика (Привлечение пользователей > Сервисы Play Games > Настройка и управление > Игровая статистика) выберите Добавить событие > Создать событие.
  3. Заполните форму на открывшейся странице.
  4. Нажмите Сохранить изменения.

Как импортировать события

Чтобы добавить в игру несколько событий одновременно, сделайте следующее:

  1. Создайте CSV-файл PlayerGameEvent.csv.
  2. Выберите игру в Google Play Console.
  3. На странице сервисы Play Games – Игровая статистика (Привлечение пользователей > сервисы Play Games > Настройка и управление > Игровая статистика) выберите Добавить событие > Импортировать через CSV.
  4. На странице Конфигурация событий перетащите CSV-файл в окно загрузки.
  5. После создания события настройте статистику.

Создание или импорт статистики

Если вы впервые добавляете статистику для игры с помощью Google Play Console, это можно сделать двумя способами:

Создать показатель

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

  1. Выберите игру в Google Play Console.
  2. На странице сервисы Play Games - Игровая статистика (Привлечение пользователей > сервисы Play Games > Настройка и управление > Игровая статистика) выберите Добавить статистику > Создать статистику.
  3. Заполните форму на открывшейся странице.
  4. Нажмите Сохранить изменения.
  5. После создания статистики опубликуйте игру.

Статистика импорта

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

  1. Создайте ZIP-файл со статистикой, переводами и файлами значков в соответствии с рекомендациями.
  2. Выберите игру в Google Play Console.
  3. На странице Игровые сервисы Play – Статистика игры (Привлечение пользователей > Игровые сервисы Play > Настройка и управление > Статистика игры) выберите Добавить статистику > Импортировать ZIP-файл.
  4. Перетащите ZIP-файл на страницу Конфигурация игровой статистики для загрузки.
  5. После загрузки всех статистик опубликуйте игру.

Тестирование игровой статистики

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

  • Откройте приложение Google Play.
  • Войдите в профиль Play Games в приложении Google Play.
  • Посмотреть игровую статистику в игровом профиле.

Как посмотреть журналы на устройстве

Чтобы проверить, правильно ли работает игровая статистика, включите журналы на устройстве:

  1. Включите отладку adb на устройстве и выполните в терминале следующие команды:

    adb shell setprop log.tag.Games INFO
adb logcat -s "PlayGamesServices[GameStatsAgent]:I"

  2. Убедитесь, что в журнале появилось сообщение об успешном выполнении, как показано в примере ниже.

    Successfully uploaded batch of X events.

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

  3. Если какие-либо из отправленных событий не пройдут проверку, вы увидите сообщение об ошибке с подробными сведениями о сбое:

    BatchRecordEvents validation failed for X event(s): ...

Как опубликовать игровую статистику

После тестирования опубликуйте игру. Все события и статистика будут опубликованы вместе с игрой.

Чтобы опубликовать его, выполните следующие действия:

  1. Выберите игру в Google Play Console.
  2. На странице сервисы Play Games – Игровая статистика (Привлечение пользователей > сервисы Play Games > Настройка и управление > Игровая статистика) нажмите Проверить и опубликовать.
  3. На странице Публикация (Привлечение пользователей > Сервисы Play Games > Настройка и управление > Публикация) посмотрите, какие действия нужно выполнить, и устраните проблемы.
  4. Нажмите Опубликовать. Вся игровая статистика опубликована.

Изменить игровую статистику

Если у вас уже есть игровая статистика и вы хотите ее изменить:

  1. Выберите игру в Google Play Console.
  2. Перейдите на страницу Игровые сервисы Play – Статистика игры (Привлечение пользователей > Игровые сервисы Play > Настройка и управление > Статистика игры).
  3. Чтобы изменить событие:
    1. В разделе Конфигурация событий выберите событие.
    2. Вы можете добавлять и удалять свойства событий.
      • Название события изменить нельзя.
    3. Нажмите Сохранить изменения.
  4. Чтобы изменить статистику:
    1. В разделе Настройка игровой статистики выберите показатель.
    2. Вы можете изменить поля Название показателя, Описание показателя и Название файла значка.
      • Нельзя изменить идентификатор показателя и направление прогресса. Статистическая единица и Сведения о связанном событии.
    3. Нажмите Сохранить изменения.
  5. На странице сервисы Play Games > Игровая статистика у измененного показателя будет статус Доступно тестировщикам.
  6. После тестирования нажмите Проверить и опубликовать. Игра будет опубликована, а статистика в ней обновится.

Удалить игровую статистику

Опубликованную игровую статистику нельзя удалить.

Вы можете удалить событие или статистику со статусом Доступно тестировщикам.

  1. Выберите игру в Google Play Console.
  2. Перейдите на страницу Игровые сервисы Play – Статистика игры (Привлечение пользователей > Игровые сервисы Play > Настройка и управление > Статистика игры).
  3. Чтобы удалить событие:
    1. В разделе Конфигурация событий выберите событие.
    2. Нажмите Удалить мероприятие.
  4. Чтобы удалить статистику:
    1. В разделе Конфигурация игровой статистики выберите показатель, который нужно удалить.
    2. Нажмите Удалить игровую статистику.

Рекомендации по созданию CSV-файла для событий

Первая строка файла CSV – это строка заголовка. Импортировать события нужно с помощью CSV-файла, например PlayerGameEvent.csv.

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

CSV-файл содержит объявленное событие и его свойства в виде значений, разделенных запятыми, в следующем порядке:

 Event Name,Property Name,Property Type

Если вы отправляете событие progressUpdate для progressionStat, добавьте строку для этого события. Это событие должно содержать как минимум свойство currentProgress типа INT или STRING, а также любые другие свойства, которые вы хотите отправить.

В таблице ниже представлены описания полей.

Заголовок столбца в файле CSV Наличие в файле Допустимое значение
Название события Обязательно Максимальное количество символов – 50.

Должно состоять только из букв, цифр и символов подчеркивания.

Если используется специальное название события progressUpdate, оно должно включать свойство с названием currentProgress и типом INT64 или STRING.
Название ресурса Обязательно Максимальное количество символов – 50.

Должно состоять только из букв, цифр и символов подчеркивания.

Уникальность в рамках события. Названия свойств должны быть уникальными в рамках одного события.

Не используйте следующие зарезервированные ключевые слова: id, count, key, value, where, from, and, or, true и false.
Тип ресурса Обязательно Строка перечисления с учетом регистра, соответствующая одному из поддерживаемых типов данных: INT64, DOUBLE, STRING, BOOL.

Требования к файлу PlayerGameEvent.csv:

  • Файл поддерживает не более 20 уникальных названий событий, каждое из которых может иметь до 20 свойств.
  • Файл не должен быть пустым и должен содержать хотя бы одну строку.
Пример таблицы
Название события Название ресурса Тип ресурса
matchCompleted продолжительность DOUBLE
matchCompleted убийства INT64
matchCompleted isWinner BOOL
matchCompleted matchType STRING
itemCollected coinsAmount INT64
itemCollected weaponType STRING
progressUpdate currentProgress INT64

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

Вы можете импортировать несколько статистик одновременно, загрузив ZIP-архив. В таблице ниже указаны допустимые названия и типы файлов в ZIP-архиве.

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

ZIP-файл должен соответствовать следующим требованиям:

  • Ограничение на размер ZIP-файла. Максимальный общий размер без сжатия – 10 МБ.
  • Максимальное количество файлов. В ZIP-архиве должно быть не более 53 файлов (3 CSV-файла и 50 значков).
  • Максимальное количество показателей: не более 50 показателей в ProgressionStatConfig.csv и RepetitiveStatsConfig.csv.
  • Поддерживаемые CSV-файлы: ProgressionStatConfig.csv, RepetitiveStatsConfig.csv и StatLocalizations.csv (необязательно). Если вы хотите загрузить только статистику прогресса, не включайте в ZIP-архив CSV-файл с повторяющейся статистикой, иначе в консоли появится ошибка. То же самое относится к загрузке только повторяющихся статистических данных.
  • Формат графических файлов значков: PNG (.png) или JPEG (.jpg, .jpeg).
    • Все значки, на которые ссылаются CSV-файлы, должны находиться в корневом каталоге ZIP-файла.
    • На все графические файлы в ZIP-архиве должна быть ссылка хотя бы в одном показателе.
  • Структура каталога. Все файлы должны находиться в корневом каталоге ZIP-файла. Подкаталоги не допускаются.

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

CSV-файл содержит объявленное событие и его свойства в виде значений, разделенных запятыми, в следующем порядке:

Stat Id,Event Name,Event Property Name,Aggregation Type,Stat Display Name,Stat Description,Filter Property,Filter Operator,Filter Value,Is Competitive,Min limit,Max limit,Icon File Name,Good value direction,Unit

В таблице ниже представлены описания полей.

Заголовок столбца в файле CSV Наличие в файле Допустимое значение
Идентификатор показателя Обязательно Строка длиной до 100 символов.

Должно состоять только из букв, цифр и символов подчеркивания. Должен быть уникальным для всех показателей в игре.
Название события Обязательно Максимальное количество символов – 50.

Должно совпадать с полем Event Name в PlayerGameEvent.csv.
Название свойства события Обязательно Максимум 50 символов.
Отображаемое название показателя Обязательно Максимальная длина – 50 символов.
Отображаемое название по умолчанию для показателя (региональные настройки по умолчанию). Должен быть уникальным для каждого показателя.
Описание показателя Обязательно Строка длиной до 500 символов.
Описание статистики по умолчанию.
Тип агрегирования Обязательно Максимум 50 символов.
SUM, MAX, MIN, COUNT.
Фильтр по ресурсам Необязательно Максимум 50 символов.
Должно быть названием свойства, определенным в файле PlayerGameEvent.csv.
Оператор фильтра Необязательно =, !=, >, <, >=, <=
Операторы сравнения фильтров.
Значение фильтра Необязательно Основа для сравнения: свойство фильтра. Значение фильтра должно быть INT64, DOUBLE, BOOL, STRING.
Конкурентоспособность Обязательно true, false
Минимальное значение Обязательно, если для параметра Is Competitive задано значение True. Минимально допустимое значение для показателей соревновательности
Максимальное значение Обязательно, если для параметра Is Competitive задано значение True. Максимально допустимое значение для показателей соревновательности
Название файла значка Обязательно Название файла изображения значка, включенного в корневой каталог ZIP-файла. Не должно конфликтовать с названиями файлов значков, используемых в повторяющихся показателях.
Направление хорошей ценности Обязательно Указывает, какие значения лучше: более высокие (INCREASING) или более низкие (DECREASING).
Единица измерения Необязательно Единица измерения для необработанных числовых значений или значений длительности. Например, KILOMETER, SECOND, PERCENTAGE, UNITLESS.

Если вы не хотите использовать условие фильтра, оставьте ячейку пустой.

Пример таблицы
Идентификатор показателя Название события Название ресурса Агрегирование Отображаемое название показателя Описание показателя Фильтр по ресурсам (необязательно) Оператор фильтра (необязательно) Значение фильтра (необязательно) Конкурентоспособность minLimit maxLimit Icon filename Направление хорошей ценности единицы
1 matchCompleted продолжительность МАКС Longest Match Survival (Выживание самого длинного совпадения) Время выживания игрока в матче. isWinner = TRUE TRUE 0 50 stat1.png Уменьшается сек.
2 matchCompleted isWinner COUNT Выиграно матчей Количество матчей, выигранных игроком. isWinner = TRUE TRUE 0 50 stat3.png Увеличивается
3 matchCompleted убийства SUM Убийства в матчах 1 на 1 Количество убийств в матчах один на один matchType = "1-on-1" Ложь stat4.png Увеличивается
4 itemCollected coinsAmount SUM Всего собрано золота Игрок собирает монеты во время матча weaponType = "меч" Ложь stat2.png Увеличивается

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

CSV-файл содержит объявленное событие и его свойства в виде значений, разделенных запятыми, в следующем порядке:

Stat Id,Event Property Name,Stat Display Name,Stat Description,Icon File Name,Good value direction,Unit

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

В таблице ниже представлены описания полей.

Заголовок столбца в файле CSV Наличие в файле Допустимое значение
Идентификатор показателя Обязательно Строка длиной до 100 символов.

Должно состоять только из букв, цифр и символов подчеркивания. Должен быть уникальным для всех показателей в игре.
Название свойства события Обязательно Максимальное количество символов – 50.

Должно быть названием свойства, определенным в файле PlayerGameEvent.csv.
Отображаемое название показателя Обязательно Название должно быть уникальным.
Описание показателя Обязательно Максимальная длина – 50 символов.
Описание статистики по умолчанию.
Название файла значка Обязательно Название файла изображения значка, включенного в корневой каталог ZIP-файла. Не должно конфликтовать с названиями файлов значков, используемых в повторяющихся показателях.
Направление хорошей ценности Обязательно Указывает, какие значения лучше: более высокие (INCREASING) или более низкие (DECREASING).
Единица измерения Необязательно Единица измерения для необработанных числовых значений или значений длительности. Например, KILOMETER, SECOND, PERCENTAGE, UNITLESS.
Пример таблицы
Идентификатор показателя Название свойства события Отображаемое название показателя Описание показателя Название файла значка Направление улучшения показателя
5 currentProgress Уровень Игроки накапливают опыт, играя матчи и повышая уровень. Level.png увеличение

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

CSV-файл содержит объявленное событие и его свойства в виде значений, разделенных запятыми, в следующем порядке:

Stat Id,Stat Display Name,Locale,Localized Stat Display Name,Localized Stat Description

В таблице ниже представлены описания полей.

Заголовок столбца в файле CSV Наличие в файле Допустимое значение
Идентификатор показателя Обязательно Строка длиной до 100 символов.

Должно состоять только из букв, цифр и символов подчеркивания. Должен быть уникальным для всех показателей в игре.
Отображаемое название показателя Обязательно Название должно быть уникальным.
Региональные настройки Обязательно Код языка, например en-US.
Добавьте переводы для игры, прежде чем указывать региональные настройки. Задать региональные настройки по умолчанию нельзя.

Поддерживаемые коды перечислены в списке языков.
Локализованное отображаемое название показателя Необязательно Максимум: 50 символов. Переведенное отображаемое название показателя для указанного региона.
Локализованное описание показателя Необязательно Максимальное количество символов – 500. Переведенное описание статистики для указанного региона.
Пример таблицы
Идентификатор показателя Отображаемое название показателя Код языка Локализованное название показателя (UTF-8) Локализованное описание показателя (UTF-8)
1 Longest Match Survival (Выживание самого длинного совпадения) es Supervivencia más larga en partidos Esto denota el tiempo de supervivencia de una jugadora en cualquier partido.
1 Longest Match Survival (Выживание самого длинного совпадения) fr Survie du match le plus long Cela indique la durée de survie d'un joueur dans n'importe quel match.
4 Всего собрано золота es Oro total recolectado La jugadora recoge monedas mientras juega en un partido
4 Всего собрано золота fr Or total collecté Le joueur collecte des pièces en jouant un match

Файлы значков

ZIP-архив должен содержать значки, на которые ссылается CSV-файл.

Правила проверки значков:

Ресурс для проверки Принудительно примененное ограничение или правило
Максимальный размер файла Максимальный размер файла значка – 1 МБ (1 048 576 байт).
Размеры Ровно 512 × 512 пикселей (ширина – 512, высота – 512).
Соотношение сторон Строго 1:1 (квадратное соотношение сторон)
Допустимые форматы PNG (.png) и JPEG (.jpg, .jpeg)
Размещение в ZIP-архиве Он должен находиться в корневом каталоге ZIP-файла.
Проверка ссылок Все названия файлов значков, указанные в столбцах "Название файла значка", должны присутствовать в ZIP-архиве.
Проверка на наличие бесхозных файлов Все графические файлы в ZIP-архиве должны быть упомянуты хотя бы в одной статистике.
Проверка на конфликты Названия файлов значков в правиле ProgressionStatConfig.csv не должны противоречить названиям в правиле RepetitiveStatsConfig.csv.
Визуальные дубликаты Повторяющиеся значки помечаются.

Требования к значкам

Разрешены значки размером 512 x 512 пикселей в формате PNG, JPEG или JPG с прозрачным фоном.

Вид значка не меняется в зависимости от региона, поэтому не используйте текст и другой локализованный контент при оформлении.

Спецификация единицы измерения

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

Свойства числовых показателей (INT64, DOUBLE)

Допустимые значения единиц измерения Пример необработанного значения
(Empty) / UNITLESS / NONE 1234567
% / PERCENTAGE / PERCENT 0,857
Расстояние/длина: CENTIMETER, METER, KILOMETER, FOOT, INCH, MILE, YARD, MILLIMETER, NANOMETER. 15 (KILOMETER)
Скорость: KILOMETER_PER_HOUR, METER_PER_SECOND, MILE_PER_HOUR. 60 (MILE_PER_HOUR)

Свойства статистики продолжительности (DURATION)

Значение категории формата Допустимые значения единиц измерения Пример необработанного значения Пример форматированного вывода
UNIT_BASED / DURATION Обязательный параметр. Возможные значения: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR. 5400 секунд (HOUR) 1,5 часа
COMPONENT_NUMERIC / ЧЧ:ММ:СС / CLOCK Уровень детализации (необязательно, по умолчанию WHOLE_SECONDS): WHOLE_MINUTES, WHOLE_SECONDS, MILLISECONDS_ONE_DIGIT, MILLISECONDS_TWO_DIGITS, MILLISECONDS_THREE_DIGITS. 3661 секунда 01:01:01
COMPONENT_TEXT / TEXT Наименьшая единица (необязательно, по умолчанию – SECONDS): SECONDS, MINUTES, HOURS, DAYS, MONTHS, YEARS. 90 000 секунд 1 д. 1 ч.

Нечисловые свойства показателей (STRING, BOOL)

Столбцы с единицами измерения должны быть пустыми.