SDK enterprise-уровня для Unreal Engine / Дополнительные возможности
  На главную

SDK enterprise-уровня для Unreal Engine

Дополнительные возможности

Узнайте о дополнительных настройках из наших инструкций.

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

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

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

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

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

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

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

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

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

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

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

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

  1. Скопируйте в свой проект блупринты BP_BattlepassPanel и BP_StoreDemo со всеми зависимостями.
  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#.
  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#.

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

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

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

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

ПРИМЕР 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

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

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

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

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

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

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

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

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

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

Примечание
Если SDK установлен через Epic Games Launcher, модификация стандартных тем в составе SDK повлечет за собой изменения в других проектах, которые их используют. Для собственного приложения рекомендуется создать отдельную тему.
  • Чтобы создать новую тему, нажмите на значок + рядом с полем 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.

Примечание
Если SDK установлен через Epic Games Launcher, модификация стандартной библиотеки виджетов в составе SDK повлечет за собой изменения в других проектах, которые ее используют. Для собственного приложения рекомендуется создать отдельную библиотеку виджетов.
  • Чтобы создать новую библиотеку виджетов, нажмите на значок + рядом с полем Widgets Library.
  • Чтобы удалить выбранную библиотеку виджетов, нажмите на значок × рядом с полем Widgets Library.

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

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

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

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

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

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

Название методаОписание
SetButtonEnabledЗадает состояние кнопки, которое определяет, реагирует ли кнопка на события мыши, клавиатуры, таймера и т. д.
IsButtonEnabledВозвращает состояние кнопки, которое определяет, реагирует ли кнопка на события мыши, клавиатуры, таймера и т. д.
GetWidgetВозвращает список UI-примитивов, которые содержат виджет. Используется для подписки на события кнопки.
ConstructButtonИнициализирует виджет кнопки. Используется оберткой виджета.
SetExtraDataЗадает кнопке набор дополнительных данных. Каждый виджет самостоятельно обрабатывает полученные данные, отображает или использует их согласно внутренней логике. Например, с помощью набора дополнительных данных можно передать кнопке с выпадающим меню список его элементов.
SetIconDataЗадает кнопке набор значков для отображения. С помощью метода можно задать размер значка, расстояния между значком и другими элементами кнопки.
SetButtonSelectedЗадает положение переключателя. Например, on или off, in cart или not in cart.
GetThemeDataВозвращает набор параметров из темы, которые использует виджет кнопки.
SetButtonTextЗадает текст кнопки.

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

Название методаОписание
SetIsCheckedЗадает состояние флажка — отмечен или снят.
GetIsCheckedВозвращает состояние флажка.
IsTickHoveredПроверяет, находится ли курсор над областью флажка.
ConstructCheckboxИнициализирует виджет флажка. Используется оберткой виджета.
GetWidgetВозвращает список UI-примитивов, которые содержит виджет. Используется для подписки на события флажка.
GetThemeDataВозвращает набор параметров из темы, которые использует виджет флажка.
SetTextЗадает текст флажка.
GetTextПолучает текст флажка.

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

Название методаОписание
GetTextВозвращает значение текста.
SetTextЗадает значение текста.
GetWidgetВозвращает список UI-примитивов, которые содержит виджет. Используется для подписки на события текста.
GetThemeDataВозвращает набор параметров из темы, которые использует виджет текста.
ConstructTextИнициализирует виджет текста. Используется оберткой виджета.

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

Название методаОписание
GetImageВозвращает изображение.
SetImageЗадает изображение.
GetWidgetВозвращает список UI-примитивов, которые содержит виджет. Используется для подписки на события изображения.
GetThemeDataВозвращает набор параметров из темы, которые использует виджет изображения.
ConstructImageИнициализирует виджет изображения. Используется оберткой виджета.

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

Название методаОписание
GetTextВозвращает текст в поле ввода.
SetTextЗадает текст в поле ввода.
GetWidgetВозвращает список UI-примитивов, которые содержит виджет. Используется для подписки на события поля ввода.
ConstructInputИнициализирует виджет поля ввода. Используется оберткой виджета.
GetHintВозвращает текст подсказки для поля ввода.
SetHintЗадает текст подсказки для поля ввода.
SetupFocusУстанавливает фокус на поле ввода.
GetThemeDataВозвращает набор параметров из темы, которые использует виджет поля ввода.
Была ли статья полезна?
Спасибо!
Что может сделать страницу еще лучше? Сообщение
Жаль, что так произошло
Расскажите, почему статья не была полезна. Сообщение
Спасибо за обратную связь!
Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.
Скрыть
Последнее обновление: 3 июля 2024

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

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