В этом документе рассказывается, как интегрировать достижения в игру с помощью Google Play Console или вызовов API. В ней описаны основные элементы и состояния достижений, а также рассказано, как их создавать, импортировать и настраивать.
Подготовка
Ознакомьтесь с рекомендациями по созданию качественных достижений.
Ознакомьтесь с терминологией в статье Основы работы с достижениями.
Создайте или импортируйте новые достижения.
Чтобы реализовать достижения с нуля, выполните следующие действия:
Добавить достижения
Если вы впервые добавляете достижения для игры с помощью Google Play Console, это можно сделать двумя способами:
- Создать, указав определения и прочие метаданные для каждого достижения по отдельности.
- Импортировать определения и прочие метаданные для нескольких достижений одновременно.
Как создать достижение
Чтобы добавить достижение в ещё не опубликованную игру, сделайте следующее:
- Выберите игру в Google Play Console.
- В разделе игровых сервисов Play перейдите к достижениям (Привлечение пользователей > Игровые сервисы Play > Настройка и управление > Достижения) и нажмите Создать достижение.
- Заполните форму на открывшейся странице.
- Нажмите Сохранить как проект.
- После этого вам потребуется опубликовать достижения.
Импорт достижений
Чтобы добавить в игру несколько достижений одновременно, сделайте следующее:
- Создайте ZIP-архив с достижениями.
- Читайте подробную статью
Дополнительную информацию о требованиях к ZIP-файлам можно найти в этом разделе.
Чтобы импортировать достижения, следуйте инструкциям ниже.
- Выберите игру в Google Play Console.
- В разделе игровых сервисов Play перейдите к достижениям (Привлечение пользователей > Игровые сервисы Play > Настройка и управление > Достижения) и выберите Импортировать достижения.
- На открывшейся странице нажмите Загрузить.
- Выберите ZIP-файл.
- Нажмите Сохранить как проект.
- После этого вам потребуется опубликовать игру.
Рекомендации по созданию ZIP-архива
Вы можете импортировать несколько достижений одновременно, загрузив ZIP-архив. В таблице ниже указано, какие названия и типы файлов следует использовать в ZIP-архиве.
| Название файла | Наличие в архиве | Допустимое значение |
|---|---|---|
AchievementsMetadata.csv
|
Обязательно | Метаданные для каждого достижения. Подробнее об атрибутах… |
AchievementsLocalizations.csv
|
Необязательно | Переводы названий и описаний. |
AchievementsIconsMappings.csv
|
Необязательно | Сведения для сопоставления достижений с файлами значков. |
| Файлы значков | Необязательно | Значки в формате PNG, JPEG или JPG. |
Требования к ZIP-архиву:
- Архив не должен содержать подкаталоги.
- Названия файлов не могут повторяться.
- Допустимы форматы файлов CSV, PNG, JPEG или JPG.
- В файлах CSV не должно быть строк заголовков.
- Размер каждого файла – до 1 МБ.
- В ZIP-архиве должно быть не более 403 файлов.
- Размер ZIP-архива – до 800 МБ.
Формат файла AchievementsMetadata.csv
Файл AchievementsMetadata.csv содержит метаданные для каждого достижения. Значения указываются через запятую в следующем порядке:
Name,Description,Incremental value,Steps Needed,Initial State,Points,List Order
В таблице ниже представлены описания полей.
| Заголовок столбца в файле CSV | Наличие в файле | Допустимое значение |
|---|---|---|
| Name | Обязательно | Строка длиной до 100 символов. |
| Description | Необязательно | Строка длиной до 500 символов. |
| Incremental Value | Обязательно | True или False
|
| Steps Needed | Обязательно, если Incremental Value – True..
|
Целое число. Максимальное значение – 10 000. |
| Initial State | Обязательно | Hidden или Revealed
|
| Баллы | Обязательно | Число, кратное пяти, максимальное значение – 200. |
| List Order | Необязательно | Целое положительное число. |
Требования к файлу 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 | Обязательно | Должно совпадать со столбцом Name в файле AchievementsMetadata.csv.
|
Строка длиной до 100 символов. |
| Localized name | Обязательно | Локализованное название достижения. | Строка длиной до 100 символов. |
| Localized description | Необязательно | Локализованное описание достижения в указанном регионе. | Строка длиной до 500 символов. |
| Locale | Обязательно | Код языка, например en-US.
|
Добавьте переводы для игры, прежде чем указывать региональные настройки. Задать региональные настройки по умолчанию нельзя.
Поддерживаемые коды перечислены в списке языков. |
Требования к файлу AchievementsLocalizations.csv:
- Названия достижений могут повторяться только в разных языках.
Например, если игра доступна на английском и французском языках, то английское название достижения может совпадать с французским.
- В каждой строке должно быть четыре значения. Если локализованного описания нет, оставьте поле Localized Description пустым.
Пример файла 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 | Обязательно | Должно совпадать со столбцом Name в файле AchievementsMetadata.csv.
|
| Icon filename | Обязательно | Название файла значка. |
Требования к файлу 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
Требования к значкам
Разрешены значки размером 512 x 512 пикселей в формате PNG, JPEG или JPG. Необходимо предоставить значки только для разблокированных достижений. Версии в серых оттенках для открытых достижений будут генерироваться автоматически. Чтобы игрокам было проще понять, разблокировано достижение или нет, используйте значки с яркими элементами.
На устройствах Android значок показывается на [тостах][a] под круглой маской. Убедитесь, что при этом не обрезаются важные детали.
Вид значка не меняется в зависимости от региона, поэтому не используйте текст и другой локализованный контент при оформлении.
Файлы значков
ZIP-архив должен содержать значки, на которые ссылается файл AchievementsIconsMappings.csv.
Как обновить игры с существующими достижениями
Вы можете добавлять новые достижения и обновлять существующие в Google Play Console.
Как добавить больше достижений
Если в игре уже есть достижения, но вы хотите добавить другие, сделайте следующее:
- Выберите игру в Google Play Console.
- В разделе сервисов Play Games перейдите к достижениям (Привлечение пользователей > Сервисы Play Games > Настройка и управление > Достижения) и нажмите Добавить достижения.
Изменить достижения
Если в игре уже есть достижения, но вы хотите их изменить, сделайте следующее:
- Выберите игру в Google Play Console.
- На странице Игровые сервисы Play - Достижения (Привлечение пользователей > Игровые сервисы Play > Настройка и управление > Достижения) выберите достижение.
- Вы можете изменить любое из полей.
- Нажмите Сохранить как проект.
- На странице сервисы Play Games - Достижения измененное достижение будет иметь статус "Доступно тестировщикам".
- После тестирования нажмите Проверить и опубликовать.
Игра будет опубликована, а достижения в ней обновятся.
Как удалить достижение
Опубликованные достижения нельзя удалить. Удалить достижение можно только до публикации.
- На странице сервисы Play Games – Достижения выберите достижение.
- Чтобы удалить достижение, нажмите Удалить достижение.
Как сбросить достижения
Вы можете сбросить данные о прогрессе игроков только на этапе тестирования достижений.
- На странице сервисы Play Games – Достижения выберите достижение.
- Чтобы сбросить достижения, нажмите Сбросить прогресс.
- Чтобы сбросить данные программно, используйте набор методов
Achievementsиз Management API.
Как локализовать достижения
Вы можете добавить переводы достижений в вашу игру. Перед этим убедитесь, что сама игра уже переведена.
Добавить перевод можно двумя способами:
Вы можете использовать импорт достижений, чтобы загрузить переводы для многих новых достижений одновременно. Этот вариант нельзя использовать для загрузки переводов уже существующих достижений.
Указать перевод для каждого достижения по отдельности. Для этого сделайте следующее:
- Выберите игру в Google Play Console, перейдите на вкладку Достижения и нажмите на нужное.
- На странице достижения откройте вкладку языка, который ранее указали в сведениях об игре.
- На странице приложения сведений об этом достижении на нужном языке измените форму, добавив переводы.
- Нажмите Сохранить.
Реализации на стороне клиента
Чтобы узнать, как реализовать достижения на вашей платформе, ознакомьтесь со следующими ресурсами:
Тестирование достижений
Чтобы убедиться, что достижения работают правильно, выполните следующие действия:
- Настройте канал внутреннего тестирования.
- Добавьте тестовые аккаунты в проект игры для тестировщиков.
- Создайте профиль игровых сервисов Play для одного из тестовых аккаунтов в приложении "Play Игры".
- Откройте игру, используя тот же тестовый аккаунт, для которого вы создали профиль игровых сервисов Play.
- Убедитесь, что при запуске игры на экране появляется всплывающее приветствие от сервисов Play Games. Это подтверждает, что автоматическая аутентификация прошла успешно.
- Играйте и выполняйте необходимые действия, чтобы разблокировать достижения.
Чтобы проверить достижения, выполните следующие действия:
Убедитесь, что при получении достижения на экране появляется всплывающее окно "Достижение разблокировано".
Откройте приложение Google Play и убедитесь, что в разделе достижений на вкладке Вы показаны как полученные, так и неполученные достижения (с подробными сведениями о прогрессе).
Как отслеживать эффективность достижений в Play Console
Чтобы посмотреть краткую статистику по отдельным достижениям, сделайте следующее:
- В Google Play Console.
- Перейдите в раздел Настройки> Проекты игр.
- Выберите игру.
- В меню слева выберите Достижения.
- На странице Достижения можно найти статистику, которая поможет понять, разблокируют ли игроки достижения.
Вы также можете отслеживать эффективность достижений на временной диаграмме на странице Привлечение пользователей > сервисы Play Games > Статистика игры.
Опубликуйте достижения
После тестирования вам нужно опубликовать игру. Достижения будут опубликованы вместе с ней. Публикация достижений – обязательный шаг для их правильной работы.
Чтобы опубликовать его, выполните следующие действия:
- Выберите игру в Google Play Console.
- На странице Сервисы Play Games > Достижения (Привлечение пользователей > Сервисы Play Games > Настройка и управление > Достижения) нажмите Проверить и опубликовать.
- На странице Сервисы Play Games – Публикация (Привлечение пользователей > Сервисы Play Games > Настройка и управление > Публикация) посмотрите, что нужно сделать, и устраните проблемы.
- Нажмите Опубликовать.
Все достижения в игре опубликованы.
Чего не стоит делать?
Ниже перечислены распространенные ошибки, которых следует избегать при реализации достижений в игре. Они подчеркивают важность:
В Play Console выберите Привлечение пользователей > сервисы Play Games > Настройка и управление > Достижения.
- Перед публикацией убедитесь, что достижения, настроенные в Play Console, не находятся в статусе "Проект".
- Не добавляйте значения идентификаторов достижений из Play Console в код игры. Используйте клиентские реализации.
Убедитесь, что вы также реализовали логику разблокировки в своем клиенте.
- Игроки не могут пропустить шаг, на котором вызывается API разблокировки. Например, завершение обучения – это достижение, но игроки могут пропустить обучение.