其他功能

通过方法详解文档了解高级设置。

如何在应用程序中实现战斗通行证

注意
使用Game Commerce插件时请参考本方法详解。

战斗通行证让玩家在战斗通行证有效期内通过完成任务或增加活跃度方式的获得奖励,从而提高玩家参与度。

提供有限奖励的免费战斗通行证可以面向所有玩家。免费通行证中不包含最终奖励。

此外,玩家也可以购买提供所有奖励(包括最终奖励)的付费通行证。

通行证全部进度分成几个等级。要解锁新等级并在通行证到期前打开最终奖励,玩家需获得相应的经验或购买等级。

演示项目提供了使用艾克索拉产品实现战斗通行证的示例。要试用战斗通行证:

  1. 启动Xsollus演示Map。
  2. 以演示用户身份登录或创建新用户。
  3. 单击侧边栏菜单中的Battle pass

要调整战斗通行证用于自己的项目:

  1. 在项目中添加战斗通行证逻辑
  2. 创建奖励优惠券组
  3. 创建战斗通行证配置
  4. 创建战斗通行证商品项
  5. 创建升级商品项

在项目中添加战斗通行证逻辑

要添加战斗通行证逻辑:

  1. BP_BattlepassPanelBP_StoreDemo蓝图以及所有依赖项复制到您的项目中。
  2. 更改界面(可选)。
  3. 修改信息存储逻辑

创建奖励优惠券组

奖励可以是虚拟物品和虚拟货币套餐。

当前解决方案中,奖励以优惠券兑换的形式发放给玩家。要创建优惠券组:

  1. 发布商帐户中前往您的项目。
  2. 创建用于奖励玩家的虚拟物品虚拟货币套餐
  3. 对于每个奖励,按照以下建议设置优惠券活动

    • 根据战斗通行证预计的优惠券兑换数指定每个用户的兑换次数。战斗通行证中的一张优惠券可以兑换多次(例如针对不同的战斗通行证等级、付费版和免费版进行设置)。
    • 活动有效期必须与战斗通行证的有效期一致。

要创建战斗通行证配置,建议提前创建一个奖励列表,并为每个奖励指定:

  • 优惠券码
  • 虚拟物品或虚拟货币套餐SKU
  • 奖励是否属于战斗通行证的某个指定等级
  • 奖励是否属于免费版或付费版

注:
可在上一个战斗通行证到期之前为新的战斗通行证配置奖励。为避免破坏应用程序的逻辑,请不要在新战斗通行证开始之前激活优惠券活动。

创建战斗通行证配置

战斗通行证配置是一个包含以下信息的JSON文件:

  • 战斗通行证名称
  • 战斗通行证到期日
  • 等级结构,指示免费版和付费版的奖励

注:
战斗通行证付费版最高等级享受的奖励自动为最终战斗通行证奖励。其显示与完成等级的奖励不同。

JSON文件结构:

参数类型描述
Name
string战斗通行证的名称。必须与战斗通行证商品项的名称一致。
ExpiryDate
string战斗通行证到期日。
Levels
array战斗通行证等级结构。
Levels.Tier
integer等级数。
Levels.Experience
integer到达下一个等级需要的经验。
Levels.FreeItem
object战斗通行证免费版的奖励信息。可以是null
Levels.FreeItem.Sku
string虚拟物品或虚拟货币套餐的SKU。用于向用户显示奖励图片和奖励信息。 对于虚拟货币套餐,套餐SKU和虚拟货币SKU均可使用。
Levels.FreeItem.Quantity
integer奖励数量。
Levels.FreeItem.Promocode
string奖励的优惠券码。
Levels.PremiumItem
object战斗通行证付费版的奖励信息。可以是null
Levels.PremiumItem.Sku
string虚拟物品或虚拟货币套餐的SKU。用于向用户显示奖励图片和奖励信息。 对于虚拟货币套餐,套餐SKU和虚拟货币SKU均可使用
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. 创建一个虚拟物品,包含以下参数:
    • 商品名称 — 配置中指定的商品通行证名称。
    • SKU — 战斗通行证ID。建议使用配置中指定的战斗通行证名称。
    • 商品属性 — 消耗品还是非消耗品。
注:
在应用程序调试过程中,建议创建消耗品。这样可以测试在有或没有战斗通行证时系统的反应。
    • 价格 — 战斗通行证付费版的价格。可以用真实货币或虚拟货币进行设置。
注:
如果虚拟物品同时具有真实货币和虚拟货币下的价格,则应用程序显示虚拟货币下的价格。
    • 组 — #BATTLEPASS#
  1. 向创建的虚拟物品中添加战斗通行证配置:
    1. 使用Get virtual item API调用获取JSON格式的当前商品描述。
    2. 使用在线服务或JavaScript中的JSON.stringify()方法将战斗通行证配置转换为一个字符串。
    3. 在商品描述中,在long_description参数的en对象中指定结果字符串。
    4. 使用Update virtual item API调用修改商品,在请求正文中指定更新后的商品描述。

战斗通行证商品项描述示例:

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>是配置中指定的战斗通行证名称。
    • SKU — 建议使用配置中指定的战斗通行证名称。
    • 商品属性 — 消耗品还是非消耗品。
    • 价格 — 等级的价格。可用虚拟或真实货币进行设置。

注:
如果升级商品项同时具有真实货币和虚拟货币下的价格,则应用程序显示虚拟货币下的价格。
    • 组 — #BATTLEPASS#

当前战斗通行证解决方案的细节

战斗通行证的显示逻辑

应用程序根据以下逻辑只显示一个战斗通行证:

  • 如果存在一个或多个未到期的战斗通行证,应用程序显示离到期日最近的战斗通行证。
  • 如果所有通行证都已到期,应用程序显示最后一个到期的战斗通行证。

示例1

当前日期:2021年3月4日。

各战斗通行证的到期日:2021年3月1日、2021年4月1日、2021年5月1日。

应用程序显示到期日为2021年4月1日的战斗通行证。

示例2

当前日期:2021年3月4日。

各战斗通行证的到期日:2021年2月1日、2021年3月1日。

应用程序显示到期日为2021年3月1日的战斗通行证。

信息存储逻辑

当前解决方案中,玩家战斗通行证的所有进度信息(等级、经验、收到的奖励等)存储在用户可编辑属性中。演示中包含读取和编辑这些属性的演示,见Character页面。

如果系统未找到所需的属性,将自动创建新属性。如果系统找到的属性不属于当前战斗通行证,将自动删掉这些属性。

注意
用户可编辑属性可在游戏客户端侧更改。为保护玩家战斗通行证的进度数据,建议实现自己的逻辑时使用只读属性。

为判断玩家的付费状态,将检查玩家物品库中存在的战斗通行证商品项。

本文对您的有帮助吗?
谢谢!
我们还有其他可改进之处吗? 留言
非常抱歉
请说明为何本文没有帮助到您。 留言
感谢您的反馈!
我们会查看您的留言并运用它改进用户体验。
隐藏

如何使用SDK配置应用程序UI

SDK包含一个UI生成器,可使用它配置应用程序UI的视觉效果。

您可以编辑影响UI元素视觉效果(颜色、纹理及字体)的全局设置来更改UI。这些属性的组合叫做主题。

要替换同一类型的UI元素,可使用小组件包装,即创建的UI元素的容器。

UI生成器包含2个独立部分:

使用主题

主题是一个XsollaUtilsTheme类型的资源。它包含用于UI元素的颜色、字体和纹理列表。每个列表是一组键值对,其中键是主题参数的唯一名称,值是相应的颜色、字体或纹理。

您可以在Settings > Project Settings > Plugins > Xsolla Utils中对主题进行操作:

  • 要设置UI的主题,请在Interface Theme字段中选择主题。
  • 要编辑所选主题,请单击Interface Theme字段旁边的🔎按钮。

注:
如果SDK是通过Epic Games启动器安装,从SDK修改标准主题将影响使用这些主题的其他项目。建议单独为您的应用程序创建一个主题。
  • 要创建新主题,请单击Interface Theme字段旁边的+图标。
  • 要删除选择的主题,请单击Interface Theme字段旁边的×图标。
注:
如果更改了主题参数名称,则需要编辑它的所有小组件。

将UI元素与主题关联

要将UI元素与主题关联:

  1. 在UI元素小组件蓝图中,通过以下方法访问主题:
    • GetCurrentTheme — 返回在插件设置中指定的当前主题。
    • GetTheme — 按照在ThemeClass参数中指定的名称返回主题。
  2. 使用以下方法通过传入主题参数名称获取相应参数的值:
    • GetColor — 获取颜色值。
    • GetFont — 获取字体。
    • GetBrush — 获取纹理。

在演示项目中,每个支持主题的小组件有一组包含主题参数名称,类型为String的参数。这些参数用于为UI元素设置视觉效果。

要查找支持主题的小组件示例,请前往Content Browser > Xsolla Content > Common > Components > Primitives

使用小组件管理器

小组件管理器是一个机制,可以让您通过更改UI元素的视觉效果和行为将其替换为同一类型的UI元素。

要创建支持小组件管理器的UI,需满足以下条件:

  • 使用指定统一接口为UI元素创建小组件。
  • 小组件库中定义UI元素小组件的类型名称。
  • 将UI元素的小组件类型传入包装。包装是用于创建UI元素的容器。小组件类型的名称应与库中的名称相同。
  • 创建UI时,请使用包装而不要使用小组件。

小组件包装

包装是一个在包装所在页的区域中创建所需小组件的容器。

创建UI时使用小组件包装可让您自动在整个UI中更改UI元素,只需更改包装中的小组件即可。而使用UI基元的标准流程在此情况中只能手动替换所有小组件。

以下是用于不同小组件类型的包装:

  • W_ButtonWrapper — 用于按钮
  • W_InputWrapper — 用于输入字段
  • W_TextWrapper — 用于文本
  • W_RichTextWrapper — 用于富文本
  • W_ImageWrapper — 用于图片
  • W_CheckBoxWrapper — 用于复选框

Details面板中,可配置包装创建的小组件的显示参数。在Widget Library Name字段中,应指定小组件类型在当前小组件库中的名称。

可在Content Browser > Xsolla Content > Common > Components > Wrappers中找到小组件包装蓝图。

包装使用小组件管理器方法与小组件交互。

小组件接口

为使UI基元以同普通小组件交互的方式与小组件包装交互,包装使用统一接口。

以下是用于不同小组件类型的包装:

  • BPI_PrimitivesButton — 用于按钮
  • BPI_PrimitivesInput — 用于输入字段
  • BPI_PrimitivesText — 用于文本
  • BPI_PrimitivesRichText — 用于富文本
  • BPI_PrimitivesImage — 用于图片
  • BPI_PrimitivesCheckbox — 用于复选框

可在Details面板的Implemented Interfaces部分配置UI元素小组件的接口。

可在Content Browser > Xsolla Content > Common > Components > Interface中找到小组件接口。

小组件库

小组件库是XsollaUtilsWidgetsLibrary类型的资源,包含一组键值对形式的小组件类。键包含小组件类型的名称,值包含由该键的相应包装创建的小组件类。

小组件库相当于包装和小组件类之间的接口。

BP_DefaultWidgetLibrary默认小组件库包含在SDK中。该库包含演示项目中的一组UI元素。

您可以在Settings > Project Settings > Plugins > Xsolla Utils中对小组件库进行操作:

  • 要安装当前小组件库,请在Widgets Library字段中选择该库。
  • 要编辑所选小组件库,请单击Widgets Library字段旁边的🔎按钮。

注:
如果SDK是通过Epic Games启动器安装,从SDK修改标准小组件库将影响使用该库的其他项目。建议单独为您的应用程序创建一个小组件库。
  • 要创建新小组件库,请单击Widgets Library字段旁边的+图标。
  • 要删除选择的小组件库,请单击Widgets Library字段旁边的×图标。

请使用包装蓝图中的以下方法访问小组件库:

  • GetCurrentWidgetsLibrary — 返回插件设置中指定的当前小组件库。
  • GetWidgetsLibrary — 按照 WidgetLibraryClass参数中指定的名称返回指定的小组件库。

请使用包装蓝图中的GetWidget方法获取库中的小组件类型。

小组件管理器的方法

包装使用以下方法与小组件交互。创建自己的包装和支持主题的小组件时可使用这些方法。

操作按钮的方法

方法名称描述
SetButtonEnabled设置定义按钮是否响应了键盘、鼠标、定时器等事件的按钮状态。
IsButtonEnabled返回定义按钮是否响应了键盘、鼠标、定时器等事件的按钮状态。
GetWidget返回包含该小组件的UI基元列表。用于订阅按钮点击事件。
ConstructButton初始化按钮小组件。由小组件包装使用。
SetExtraData设置按钮的其他数据。每个小组件根据内在逻辑处理收到的数据、展示数据或使用数据。例如,可用一组其他数据将下拉菜单元素列表传入有下拉菜单的按钮。
SetIconData设置一组按钮显示图标。使用此方法指定图标大小以及图标和其他按钮元素之间的距离。
SetButtonSelected设置开关位置。例如:在购物车中不在购物车中等。
GetThemeData返回按钮小组件使用的主题参数组。
SetButtonText设置按钮的文本。

操作复选框的方法

方法名称描述
SetIsChecked设置复选框被勾选或未勾选的状态。
GetIsChecked返回复选框的状态。
IsTickHovered检查鼠标是否悬浮在复选框区域。
ConstructCheckbox初始化复选框小组件。由小组件包装使用。
GetWidget返回小组件包含的UI基元列表。用于订阅复选框事件。
GetThemeData返回复选框小组件使用的主题参数组。
SetText设置复选框的文本。
GetText接收复选框的文本。

操作文本或富文本的方法

方法名称描述
GetText返回文本值。
SetText设置文本值。
GetWidget返回小组件包含的UI基元列表。用于订阅文本事件。
GetThemeData返回文本小组件使用的主题参数组。
ConstructText初始化文本小组件。由小组件包装使用。

操作图片的方法

方法名称描述
GetImage返回图片。
SetImage设置图片。
GetWidget返回小组件包含的UI基元列表。用于订阅图片事件。
GetThemeData返回图片小组件使用的主题参数组。
ConstructImage初始化图片小组件。由小组件包装使用。

操作输入字段的方法

方法名称描述
GetText将文本返回输入字段。
SetText设置输入字段的文本。
GetWidget返回小组件包含的UI基元列表。用于输入字段事件。
ConstructInput初始化输入字段小组件。由小组件包装使用。
GetHint返回输入字段的提示文本。
SetHint设置输入字段的提示文本。
SetupFocus设置输入字段的焦点。
GetThemeData返回输入字段小组件使用的主题参数组。
本文对您的有帮助吗?
谢谢!
我们还有其他可改进之处吗? 留言
非常抱歉
请说明为何本文没有帮助到您。 留言
感谢您的反馈!
我们会查看您的留言并运用它改进用户体验。
隐藏
上次更新时间: 2024年7月3日

发现了错别字或其他内容错误? 请选择文本,然后按Ctrl+Enter。

报告问题
我们非常重视内容质量。您的反馈将帮助我们做得更好。
请留下邮箱以便我们后续跟进
感谢您的反馈!