Интегрируем достижения,Интегрируем достижения

В этом документе объясняется, как интегрировать достижения в вашу игру с помощью консоли Google Play или вызовов API. В нем рассматриваются основные элементы и состояния достижений, а также описывается, как создавать, импортировать и управлять ими.

Прежде чем начать

• Ознакомьтесь с рекомендациями по достижению высоких результатов в проектировании .

• Ознакомьтесь с терминологией в разделе «Основы достижений» .

Создание или импорт новых достижений

Для реализации достижений с нуля выполните следующие шаги:

Добавить достижения

Существует два способа впервые создать достижения с помощью консоли Google Play:

• Создание достижения : добавляйте определения и метаданные для каждого достижения по отдельности.
• Импорт достижений : Импорт определений и других метаданных для нескольких достижений одновременно за один шаг.

Примечание: Используйте API для разблокировки достижений для авторизованного игрока. Это позволит игроку увидеть все скрытые достижения.

Создать достижение

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

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

Импорт достижений

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

1. Создайте ZIP-архив, содержащий ваши достижения.
2. Загрузите файл.

Для получения более подробной информации о ZIP-файле см. раздел «Рекомендации по работе с ZIP-файлами» .

Для импорта достижений:

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

Инструкции по заполнению ZIP-архива

С помощью ZIP-архива можно импортировать несколько достижений одновременно. Точные имена файлов для ZIP-архива указаны в таблице:

Имя файла	Обязательный или необязательный	Принятые значения
			AchievementsMetadata.csv	Необходимый	Метаданные для каждого достижения. См. Атрибуты .
AchievementsLocalizations.csv	Необязательный	Предоставляет переводы названий и описаний достижений.
AchievementsIconsMappings.csv	Необязательный	Сопоставляет достижения с соответствующими файлами значков.
Файлы значков	Необязательный	Иконки в форматах PNG, JPEG или JPG.

Требования к ZIP-файлу:

• Подкаталоги отсутствуют.
• Уникальные имена файлов.
• Только файлы CSV, PNG, JPEG или JPG.
• В CSV-файлах не должно быть строки заголовка.
• Размер каждого файла не должен превышать 1 МБ.
• Архив не должен содержать более 403 файлов.
• Общий размер ZIP-архива не должен превышать 800 МБ.

Формат AchievementsMetadata.csv

Файл AchievementsMetadata.csv содержит метаданные для каждого достижения. Информация должна быть представлена ​​в виде значений, разделенных запятыми, в следующем порядке:

    Name,Description,Incremental value,Steps Needed,Initial State,Points,List Order

Эти поля описаны в следующей таблице:

Заголовки столбцов CSV	Обязательный или необязательный	Принятые значения
			Имя	Необходимый	Максимальное количество символов: 100
Описание	Необязательный	Максимальное количество символов: 500
Прирост стоимости	Необходимый	True или False
Необходимые шаги	Обязательно, если Incremental Value равно True.	Число (без дробей и десятичных знаков). Максимальное значение — 10000.
Начальное состояние	Необходимый	Hidden или Revealed
Баллы	Необходимый	Число, кратное 5, значение которого должно находиться в диапазоне от 5 до 200.
Порядок списка	Необязательный	Число (без дробей и десятичных знаков, больше нуля)

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

• Каждая строка должна содержать семь значений. Если вы хотите пропустить значение, оставьте поле пустым.
• Поля Name и Description используются в качестве языка по умолчанию.
• Поле Name должно быть уникальным для всех достижений.
• В следующих полях запятые не должны встречаться: Name и Description .

Пример файла AchievementsMetadata.csv :

  Achievement1,Achievement One,True,100,Hidden,5,20
  Achievement2,Achievement Two,False,,Revealed,10,30

Формат AchievementsLocalizations.csv

Файл AchievementsLocalizations.csv — это необязательный файл, который содержит все необходимые данные для описания каждого достижения пользователям в разных языковых версиях. Достижения переводятся в соответствии с языковыми версиями, указанными для игры.

Информация должна быть представлена ​​в виде значений, разделенных запятыми, в следующем порядке:

   Name, Localized name, Localized description, locale

Эти поля описаны в следующей таблице:

Заголовки столбцов CSV	Обязательный или необязательный	Описание	Принятые значения
				Имя	Необходимый	Должно совпадать со значением в столбце Name из файла AchievementsMetadata.csv .	Максимальное количество символов: 100
Локализованное имя	Необходимый	Локализованное название достижения.	Максимальное количество символов: 100
Локализованное описание	Необязательный	Локализованное описание достижения в указанном языковом коде.	Максимальное количество символов: 500
Местоположение	Необходимый	Код локали, например, en-US .	Добавьте переводы для вашей игры перед указанием локали. Обратите внимание, что вы не можете указать локаль по умолчанию. Список поддерживаемых языковых кодов можно найти в списке поддерживаемых языков .

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

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

  Например, если игра поддерживает как en-US, так и fr-FR языковые локали, достижение, названное "Achievement1" для en-US, может также называться "Achievement1" для fr-FR.

• Каждая строка должна содержать четыре значения. Если вы хотите опустить значение «Локализованное описание», оставьте его пустым.

Пример файла AchievementsLocalizations.csv :

Achievement1,Achievement One,This is the description of achievement one in English.,en-US
Achievement1,Achievement Un,Voici la description de l'achievement un en français.,fr-FR
Achievement2,Achievement Two,Description of achievement two.,en-US
Achievement2,Logro Dos,Descripción del logro dos.,es-ES
Achievement3,Achievement Three,,en-US
Achievement3,Erfolg Drei,,de-DE

Формат AchievementsIconsMappings.csv

Файл AchievementsIconsMappings.csv является необязательным и используется для сопоставления ваших достижений с заданным значком. Он должен содержать информацию в виде значений, разделенных запятыми, в следующем порядке:

Name, icon filename

Эти поля описаны в следующей таблице.

Заголовки столбцов CSV	Обязательный или необязательный	Описание
			Имя	Необходимый	Должно совпадать со значением в столбце Name из файла AchievementsMetadata.csv .
имя файла значка	Необходимый	Название вашего файла значка.

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

• Каждая строка должна содержать два значения.
• Файлы значков могут быть только в форматах PNG или JPEG.

Пример файла AchievementsIconsMappings.csv :

Valid Achievement,valid-achievement-icon.png
Incremental Achievement,incremental-achievement-icon.jpeg
No Description,no-description-icon.png
Hidden Initial State,hidden-initial-state-icon.png
Large Point Value,large-point-value-icon.jpeg

рекомендации по использованию иконок

Иконки следует создавать в формате PNG, JPEG или JPG размером 512 x 512 пикселей. Вам нужно предоставить нам только иконку для разблокированного достижения. Мы автоматически сгенерируем версию иконки для разблокированного достижения в оттенках серого. Поэтому мы рекомендуем включать в иконки достижений цветные элементы, чтобы пользователи могли различать разблокированные и уже разблокированные достижения.

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

Пример значка достижения.

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

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

Значки, на которые вы ссылаетесь в файле AchievementsIconsMappings.csv должны присутствовать в текущем импортируемом ZIP-архиве.

Обновите игры, добавив в них существующие достижения.

В консоли Google Play можно добавить новые достижения в игру и обновить существующие.

Добавить больше достижений

Если у вас уже есть достижения и вы хотите добавить новые:

1. В консоли Google Play выберите игру.
2. На странице «Достижения» в разделе «Увеличение числа пользователей» ( Увеличение числа пользователей > «Управление сервисами Play Games» > «Настройка и управление» > «Достижения» ) выберите «Добавить достижения» .

Редактировать достижения

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

1. В консоли Google Play выберите игру.
2. На странице «Достижения» в разделе «Увеличение числа пользователей» ( Увеличение числа пользователей > «Достижения» > «Настройка и управление» > «Достижения» ) выберите достижение.
3. Вы можете редактировать любое из полей.
4. Нажмите « Сохранить как черновик» .
5. На странице «Достижения» в разделе «Сервисы игр Play» отредактированное достижение находится в статусе «Доступно для тестировщиков».
6. После проверки достижения нажмите «Проверить и опубликовать» .

   Это повторно опубликует вашу игру, а также все ваши обновленные достижения.

Примечание: После публикации достижения его начальное состояние (скрытое или открытое) и тип (постепенное или стандартное) фиксируются и не могут быть изменены.

Удалить достижение

После публикации достижение удалить его невозможно . Удалить достижение можно только в предварительно опубликованном состоянии.

1. На странице «Достижения» в разделе «Игровые сервисы Play Games» выберите достижение.
2. Чтобы удалить достижение, нажмите «Удалить достижение» .

Сбросить достижение

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

1. На странице «Достижения» в разделе «Игровые сервисы Play Games» выберите достижение.
2. Чтобы сбросить достижения, нажмите «Сбросить прогресс» .
3. Для программного сброса данных о достижениях вызовите методы API управления Achievements .

Добавить переводы для достижений

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

Добавить перевод в игру можно двумя способами:

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

• Вы можете добавить перевод для каждого достижения в своей игре. Чтобы добавить свой собственный перевод для каждого достижения:

  1. В консоли Google Play откройте вкладку «Достижения» для вашей игры, затем выберите существующее достижение.
  2. На странице с подробными сведениями о достижениях выберите вкладку для языка, который вы ранее добавили на вкладке «Подробности игры» .
  3. На странице с подробной информацией о достижении для данного языка отредактируйте форму, добавив свои переводы для этого достижения.
  4. Нажмите «Сохранить» , чтобы сохранить переведенные данные о ваших достижениях.

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

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

• Android
• Единство
• Веб

Результаты тестирования

Примечание: Во время тестирования отображение 0 XP во всплывающем окне «Разблокировка достижения» является нормальным явлением. Это сделано для предотвращения помех в работе системы подсчета очков в реальном времени.

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

• Создайте внутренний тестовый полигон .
• Добавьте тестовые аккаунты в свой игровой проект для тестировщиков.
• Создайте профиль Play Games Services для одной из тестовых учетных записей с помощью приложения Play Games.
• Запустите игру, используя ту же тестовую учетную запись, для которой вы создали профиль в сервисах Play Games.
• Убедитесь, что на экране отображается всплывающее сообщение «Добро пожаловать» от Play Games Services, подтверждающее успешную автоматическую аутентификацию при запуске игры.
• Сыграйте в игру и выполните необходимые шаги, чтобы разблокировать достижения.

• Для проверки достижений:

  • Убедитесь, что после завершения достижения на экране появляется всплывающее окно «Достижение разблокировано».

  • Откройте приложение Play Store и убедитесь, что в разделе достижений на вкладке YouTube отображаются как выполненные, так и находящиеся в процессе достижения (с подробной информацией о ходе выполнения).

Отслеживайте результаты достижений в Play Console.

Вот как быстро найти статистику по индивидуальным достижениям:

• В консоли Google Play .
• Перейдите в Настройки > Игровые проекты .
• Выберите игру.
• В меню слева нажмите «Достижения» .
• На странице «Достижения» вы можете найти статистику, которая позволит понять, разблокируют ли ваши игроки достижения.

Вы также можете отслеживать временные ряды показателей достижений на странице « Увеличение числа пользователей > Сервисы Play Games > Статистика игр» .

Опубликуйте достижения

После завершения тестирования необходимо опубликовать игру. Все достижения вашей игры будут опубликованы вместе с ней. Публикация достижений — обязательный шаг для корректной работы системы достижений.

Для публикации выполните следующие шаги:

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

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

Распространенные ошибки, которых следует избегать

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

• В консоли Play перейдите в раздел «Увеличение числа пользователей» > «Службы Play Games» > «Настройка и управление» > «Достижения» .

  • Перед публикацией убедитесь, что достижения, настроенные в Play Console, не находятся в состоянии «Черновик».
  • Не добавляйте значения ID достижений из Play Console в код игры. Вместо этого используйте реализации клиента .

• Убедитесь, что вы также реализовали логику разблокировки на своем клиенте.

  • Игроки не могут пропустить этап запуска, на котором вызывается API разблокировки. Например, прохождение обучения является достижением, но игроки могут пропустить само обучение.