Как реализовать боевой пропуск в приложении

Внимание
Используйте эту инструкцию для работы только с ассетом Game Commerce.

Боевой пропуск позволяет увеличить вовлеченность игроков через выдачу вознаграждений за выполнение заданий или активную игру в период действия пропуска.

Бесплатный боевой пропуск с ограниченным количеством вознаграждений доступен всем игрокам. Финальное вознаграждение также не входит в бесплатный пропуск.

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

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

В демопроекте приведен пример реализации боевого пропуска с помощью продуктов Иксоллы. Чтобы проверить боевой пропуск:

  1. Запустите демосцену Xsollus.
  2. Авторизуйтесь под учетной записью демопользователя или создайте нового пользователя.
  3. В боковом меню выберите пункт Battle pass.

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

  1. Добавьте логику боевого пропуска в свой проект.
  2. Создайте набор купонов с вознаграждениями.
  3. Создайте конфигурацию боевого пропуска.
  4. Создайте предмет боевого пропуска.
  5. Создайте предмет повышения уровня.

Добавление логики боевого пропуска в проект

Вся логика боевого пропуска содержится в префабе BattlepassPage и поделена на следующие блоки:

  • ScriptHolders — скрипты по работе с конфигурацией боевого пропуска, предметами и информацией об игроке;
  • UIScriptHolders — скрипты для взаимодействия с игроком.

Чтобы добавить логику боевого пропуска:

  1. В своем проекте создайте экземпляр префаба BattlepassPage.
  2. Измените интерфейс (опционально).
  3. Доработайте логику хранения информации.

Создание набора купонов с вознаграждениями

Вознаграждениями могут быть виртуальные предметы и пакеты виртуальной валюты.

В текущей реализации начисление вознаграждения игроку происходит через погашение купона. Для создания набора купонов:

  1. Откройте проект в Личном кабинете.
  2. Создайте виртуальные предметы и пакеты виртуальной валюты, которые будут начисляться игрокам.
  3. Для каждого вознаграждения настройте кампанию с купонами с учетом следующих рекомендаций:

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

Для построения конфигурации боевого пропуска рекомендуется заранее создать список вознаграждений и для каждого из них указать:

  • код купона;
  • артикул виртуального предмета или пакета виртуальной валюты;
  • принадлежность к конкретному уровню боевого пропуска;
  • принадлежность к платной и/или бесплатной версии.

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

Создание конфигурации боевого пропуска

Конфигурация боевого пропуска представляет собой JSON-файл, который содержит:

  • название боевого пропуска;
  • дату окончания срока действия боевого пропуска;
  • структуру уровней с указанием вознаграждений для платной и бесплатной версии.

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

Структура JSON-файла:

ПараметрТипОписание
Name
stringНазвание боевого пропуска. Должно совпадать с названием предмета боевого пропуска.
ExpiryDate
stringДата окончания срока действия боевого пропуска.
Levels
arrayСтруктура уровней боевого пропуска.
Levels.Tier
integerНомер уровня.
Levels.Experience
integerКоличество опыта для достижения следующего уровня.
Levels.FreeItem
objectИнформация о вознаграждении для бесплатной версии боевого пропуска. Может принимать значение null.
Levels.FreeItem.Sku
stringАртикул виртуального предмета или пакета виртуальной валюты. Используется для показа игроку изображения вознаграждения и информации о нем.

Примечание
Для пакета виртуальной валюты может использоваться как артикул пакета, так и артикул виртуальной валюты.
| |
Levels.FreeItem.Quantity
| integer | Количество вознаграждений. | |
Levels.FreeItem.Promocode
| string | Код купона вознаграждения. | |
Levels.PremiumItem
| object | Информация о вознаграждении для платной версии боевого пропуска. Может принимать значение null. | |
Levels.PremiumItem.Sku
| string | Артикул виртуального предмета или пакета виртуальной валюты. Используется для показа игроку изображения вознаграждения и информации о нем.

Примечание
Для пакета виртуальной валюты может использоваться как артикул пакета, так и артикул виртуальной валюты.
| |
Levels.PremiumItem.Quantity
| integer | Количество вознаграждений. | |
Levels.PremiumItem.Promocode
| string | Код купона вознаграждения. |

Пример конфигурации боевого пропуска:

Copy
Full screen
Small screen
{
  "Name": "BP2021JAN",
  "ExpiryDate": "29-03-2021",
  "Levels": [
    {
      "Tier": 1,
      "Experience": 1000,
      "FreeItem": {
        "Sku": "Sku",
        "Quantity": 10,
        "Promocode": "HELLO_WORLD"
      },
      "PremiumItem": {
        "Sku": "Sku2",
        "Promocode": "HELLO_WORLD2"
      }
    },
    {
      "Tier": 2,
      "Experience": 1000
    },
    {
      "Tier": 3,
      "Experience": 1000
    }
  ]
}

Создание предмета боевого пропуска

Предмет боевого пропуска является контейнером для конфигурации боевого пропуска и используется для определения премиум-статуса игрока (приобрел ли игрок платную версию).

Для создания предмета боевого пропуска:

  1. Откройте проект в Личном кабинете.
  2. Создайте группу виртуальных предметов с названием #BATTLEPASS#.

Примечание
Группа #BATTLEPASS# является вспомогательной и не отображается во внутриигровом магазине и инвентаре.

  1. Создайте виртуальный предмет, указав следующие параметры:
    • Название предмета — название боевого пропуска, указанное в конфигурации.
    • Артикул — идентификатор боевого пропуска. Рекомендуется использовать название боевого пропуска, указанного в конфигурации.
    • Свойство предмета — расходуемый или нерасходуемый предмет.

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

    • Цена — цена платной версии боевого пропуска. Задается в виртуальной или в реальной валюте.

Примечание
Если для виртуального предмета заданы цены в реальной и виртуальной валюте, в приложении будет отображаться цена в реальной валюте.

    • Группа — #BATTLEPASS#.

Примечание
На этапах отладки приложения рекомендуется дополнительно поместить предмет в группу, отличную от #BATTLEPASS#. В этом случае он будет виден в инвентаре.

  1. Добавьте к созданному виртуальному предмету конфигурацию боевого пропуска:
    1. Получите текущее описание предмета в формате JSON с помощью метода API Get virtual item.
    2. Преобразуйте конфигурацию боевого пропуска в строку с помощью онлайн-сервиса или метода JSON.stringify() в JavaScript.
    3. В описании предмета укажите полученную строку в объекте en параметра long_description.
    4. Измените предмет с помощью метода API Update virtual item, указав в теле запроса скорректированное описание предмета.

Пример описания предмета боевого пропуска:

Copy
Full screen
Small screen
{
  "sku": "BP2021JAN",
  "name":{
    "en": "BP2021JAN"
  },
  "type": "virtual_good",
  "description":{
    "en": "BP2021JAN"
  },
  "image_url": "https://cdn3.xsolla.com/img/misc/images/7cb1c2b719af329a9bc1df994d58b749.png",
  "long_description": {
    "en": "{
                \"Name\":\"BP2021JAN\",
                \"ExpiryDate\":\"01-07-2021\",
                \"Levels\":
                    [
                        {
                            \"Tier\":1,
                            \"Experience\":100,
                            \"FreeItem\":
                                {
                                    \"Sku\":\"Bullets\",
                                    \"Promocode\":\"B2021S1FL1E100\",
                                    \"Quantity\":50
                                }
                        }
                    ]
            }"
  },
  "attributes":[
  ],
  "is_free": false,
  "order": 1,
  "groups":[
    "Battlepass"
  ],
  "regional_prices":[
  ],
  "prices":[
    {
      "amount": 1,
      "currency": "USD",
      "is_default": true,
      "is_enabled": true
    }
  ],
  "media_list":[
  ],
  "vc_prices":[
  ],
  "is_enabled": true,
  "is_show_in_store": true,
  "regions":[
  ],
  "inventory_options":{
    "consumable": false,
    "expiration_period": null
  }
}

Создание предмета для покупки уровня

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

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

  1. Откройте проект в Личном кабинете.
  2. Создайте виртуальный предмет, указав следующие параметры:
    • Название предмета — название предмета покупки уровня в формате <battlepassname>_levelup_util, где <battlepassname> — название боевого пропуска, указанное в конфигурации.
    • Артикул — идентификатор предмета для покупки уровня. Рекомендуется использовать название предмета.
    • Свойство предмета — расходуемый предмет.
    • Цена — цена перехода на следующий уровень. Задается в виртуальной или реальной валюте.

Примечание
Если для предмета покупки уровня заданы цены в реальной и виртуальной валюте, в приложении будет отображаться цена в реальной валюте.

    • Группа — #BATTLEPASS#.

Примечание
На этапах отладки приложения дополнительно поместите предмет покупки уровня в группу, отличную от #BATTLEPASS#. В этом случае он будет виден в инвентаре.

Особенности текущей реализации боевого пропуска

Логика отображения боевого пропуска

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

  • Если существует один или несколько боевых пропусков с неистекшим сроком действия, отображается боевой пропуск с ближайшей датой окончания срока действия.
  • Если срок действия всех боевых пропусков истек, отображается последний истекший боевой пропуск.

ПРИМЕР 1

Текущая дата: 04.03.2021.

Даты окончания срока действия боевых пропусков: 01.03.2021, 01.04.2021, 01.05.2021.

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

ПРИМЕР 2

Текущая дата: 04.03.2021.

Даты окончания срока действия боевых пропусков: 01.02.2021, 01.03.2021.

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

Логика хранения информации

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

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

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

Для определения премиум-статуса игрока проверяется наличие предмета боевого пропуска в инвентаре игрока.

Была ли статья полезна?
Спасибо!
Что может сделать страницу еще лучше? Сообщение
Жаль, что так произошло
Расскажите, почему статья не была полезна. Сообщение
Спасибо за обратную связь!
Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
Оценить страницу
Оценить страницу
Что может сделать страницу еще лучше?

В другой раз

Спасибо за обратную связь!
Последнее обновление: 8 августа 2022

Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.

Сообщите о проблеме
Мы постоянно улучшаем качество нашей документации. Ваш отзыв поможет нам в этом.
Укажите email-адрес, чтобы мы могли связаться с вами
Спасибо за обратную связь!