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

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

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

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

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

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

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

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

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

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

1. Скопируйте в свой проект блупринты BP_BattlepassPanel и BP_StoreDemo со всеми зависимостями.
2. Измените интерфейс (опционально).
3. Доработайте логику хранения информации.

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

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

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

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

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

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

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

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

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

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

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

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

{
  "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#.

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

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

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

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

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

{
  "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> — название боевого пропуска, указанное в конфигурации.
   • Артикул — идентификатор предмета для покупки уровня. Рекомендуется использовать название предмета.
   • Свойство предмета — расходуемый предмет.
   • Цена — цена перехода на следующий уровень. Задается в виртуальной или реальной валюте.

1. • Группа — #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.

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

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

В состав SDK входит конструктор интерфейса — инструмент, позволяющий настраивать внешний вид пользовательского интерфейса приложения.

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

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

Конструктор интерфейса состоит из двух независимых частей:

• Темы — отвечают за работу с внешним видом.
• Менеджер виджетов — отвечает за работу с виджетами. Позволяет заменять составные части интерфейса целиком.

Работа с темами

Тема представляет собой ассет типа XsollaUtilsTheme. Он содержит список цветов, шрифтов и текстур, которые используются элементами интерфейса. Каждый список состоит из набора пар ключ-значение, где ключ — уникальное название параметра темы, а значение — соответствующий цвет, шрифт или текстура.

Работа с темами доступна в разделе Settings > Project Settings > Plugins > Xsolla Utils:

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

• Чтобы создать новую тему, нажмите на значок + рядом с полем Interface Theme.
• Чтобы удалить выбранную тему, нажмите на значок × рядом с полем Interface Theme.

Добавление связи между элементом интерфейса и темой

Чтобы добавить связь между элементом интерфейса и темой:

1. В блупринте виджета для элемента интерфейса получите доступ к теме при помощи следующих методов:
   • GetCurrentTheme — возвращает текущую тему, указанную в настройках плагина;
   • GetTheme — возвращает тему по названию, указанному в параметре ThemeClass.
2. Из темы получите значения конкретных параметров при помощи следующих методов, передав в них название параметра темы:
   • GetColor — получает значение цвета;
   • GetFont — получает шрифт;
   • GetBrush — получает текстуру.

В демопроекте каждый виджет, поддерживающий работу с темами, имеет набор параметров типа String с названиями параметров тем. Эти параметры используются для придания нужного вида элементу интерфейса.

Примеры виджетов с поддержкой тем расположены в каталоге Content Browser > Xsolla Content > Common > Components > Primitives.

Работа с менеджером виджетов

Менеджер виджетов — это механизм, позволяющий автоматически заменять однотипные элементы интерфейсы на другие, изменяя их внешний вид или логику поведения.

Для построения интерфейса с поддержкой менеджера виджетов должны выполняться следующие условия:

• Для элемента интерфейса должен быть создан виджет с указанным унифицированным интерфейсом.
• В библиотеке должно быть определено название типа для виджета элемента интерфейса.
• Тип виджета для элемента интерфейса должен передаваться обертке — контейнеру для создания элементов интерфейса. Название типа виджета должно совпадать с указанным в библиотеке.
• При построении интерфейса вместо виджета должна использоваться обертка.

Обертки виджетов

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

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

Для различных типов виджетов доступны следующие обертки:

• W_ButtonWrapper — для кнопки;
• W_InputWrapper — для поля ввода;
• W_TextWrapper — для текста;
• W_RichTextWrapper — для rich-текста;
• W_ImageWrapper — для изображения;
• W_CheckBoxWrapper — для флажка.

Параметры отображения создаваемых оберткой виджетов настраиваются в панели Details. В поле Widget Library Name требуется указать название типа виджета из текущей библиотеки виджетов.

Блупринты оберток виджетов расположены в каталоге Content Browser > Xsolla Content > Common > Components > Wrappers.

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

Интерфейсы виджетов

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

Для различных типов виджетов доступны следующие интерфейсы:

• BPI_PrimitivesButton — для кнопки;
• BPI_PrimitivesInput — для поля ввода;
• BPI_PrimitivesText — для текста;
• BPI_PrimitivesRichText — для rich-текста;
• BPI_PrimitivesImage — для изображения;
• BPI_PrimitivesCheckbox — для флажка.

Интерфейсы настраиваются для виджетов элементов интерфейса в разделе Implemented Interfaces панели Details.

Интерфейсы виджетов расположены в каталоге Content Browser > Xsolla Content > Common > Components > Interface.

Библиотека виджетов

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

Таким образом, библиотека виджетов является посредником между обертками и классами виджетов.

В состав SDK входит стандартная библиотека виджетов BP_DefaultWidgetLibrary, содержащая список элементов интерфейсов из демопроекта.

Работа с библиотекой виджетов доступна в разделе Settings > Project Settings > Plugins > Xsolla Utils:

• Чтобы установить текущую библиотеку виджетов, выберите ее в поле Widgets Library.
• Чтобы перейти к редактированию выбранной библиотеки виджетов, нажмите на значок 🔎 рядом с полем Widgets Library.

• Чтобы создать новую библиотеку виджетов, нажмите на значок + рядом с полем Widgets Library.
• Чтобы удалить выбранную библиотеку виджетов, нажмите на значок × рядом с полем Widgets Library.

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

• GetCurrentWidgetsLibrary — возвращает текущую библиотеку виджетов, указанную в настройках плагина.
• GetWidgetsLibrary — возвращает указанную библиотеку виджетов по названию, указанному в параметре WidgetLibraryClass.

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

Методы менеджера виджетов

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

Методы для работы с кнопками

Методы для работы с флажками

Методы для работы с текстом или rich-текстом

Методы для работы с изображениями

Методы для работы с полями ввода