战令接入指南

1. 基本概念

游戏中的战令系统，支持战令的配置与管理，可以让玩家在游戏中进行战令解锁、升级、领取战令奖励等。
开发者可以将战令系统和经济系统（使用方法参考「经济系统」）结合使用，使用经济系统中的资源作为战令奖励，领取奖励时，资源将会被自动发放到玩家的背包内。
战令系统在使用上主要分为 战令配置、角色战令 两个部分：

战令配置：包括了战令的名称、有效期、等级、奖励等配置信息，用户可以在UOS网站上进行战令及其奖励槽的配置与管理。
- 奖励槽：用于配置战令各个等级奖励的槽位，一个战令可以有多个奖励槽，如战令的免费版、进阶版、豪华版可以用三个奖励槽来进行表示。玩家可以通过购买或者完成任务的方式解锁奖励槽
角色战令：每个玩家角色在游戏中拥有的战令实体，可以对其进行奖励槽解锁、战令经验提升、领取战令奖励等操作。

2. 功能配置与管理

进入UOS Passport 「战令 -> 战令管理」 页面进行战令的配置与管理。

创建战令

点击左上角 「创建战令」 按钮进行战令创建。
在这一步用户将先配置战令的基本信息，奖励槽的配置将在战令创建完成后进行
配置说明

唯一标识(SlugName)：战令的唯一标识，同一个UOS APP下可以唯一定位一个战令，仅支持字母、数字和-_的组合，且须以字母和数字作为开头，创建成功后不可更改
名称：战令的显示名称
开始时间：战令的开始时间，默认为即刻开始
结束时间：战令的结束时间，默认为永久有效
描述：战令的描述信息

总等级数：角色战令可以升级到的最大等级
每日/每周经验获取上限：用于限制角色战令每日/每周能够获取的经验，可以通过设置游戏世界中每天的开始时间来更改经验的刷新时间
升级经验：配置战令各个等级所需的升级经验，战令默认为0级。可以通过「增加区间」来配置不同等级的不同升级经验

至此，我们创建了一个新的战令，在 「战令管理」 页面中，我们可以查看已有战令的基本情况，对战令进行查看详情、编辑、删除等操作。

创建奖励槽

在这一步用户将先对已创建的战令添加奖励槽，配置相应的战令奖励。
通过 「战令管理」 页面，选择战令进入 「战令详情」 页面，该页面包含了战令的详细信息，同时能够对其奖励槽进行配置。
点击 「添加奖励槽」 按钮开始奖励槽的创建。

用户可以选择新建一个空白的奖励槽，或者导入一个已有的奖励槽，以此为基础进行创建。

配置说明

唯一标识(SlugName)：奖励槽的唯一标识，同一个UOS APP下可以唯一定位一个奖励槽，仅支持字母、数字和-_的组合，且须以字母和数字作为开头，创建成功后不可更改
名称：奖励槽的显示名称
类型：分为免费和付费两种类型，免费类型的奖励槽在角色战令初始化时将会默认解锁
附属奖励槽：付费奖励槽的可选属性。解锁奖励槽时将会同时解锁其附属奖励槽
解锁奖励：付费奖励槽的可选属性。解锁付费奖励槽时获得的奖励，可以包括以下内容
- 战令经验奖励：战令的经验，可用于提升战令等级
- 资源奖励：对应经济系统中的资源，获得后将直接发放至用户背包

等级奖励
- 可以对战令的每一个等级添加经济系统中的资源作为奖励，用户领取后资源奖励将直接发放至用户背包
- 配置奖励时，可以点击图中按钮将目标行复制到当前奖励，提高配置的效率

创建成功后，回到 「战令详情」 页面，我们可以看到已创建的奖励槽，通过奖励槽右上角的菜单按钮，可以对其进行编辑、删除等操作。

using Unity.Passport.Runtime;
using BattlePass;

外部账号系统登录

参考「外部账号系统登录」正确接入外部ID系统。确保在调用战令相关方法之前 已完成外部ID系统的接入

Passport登录

参考「Passport 登录」正确接入 Passport Login，确保在调用战令相关方法之前 用户已经登录完成。
安装并初始化 Feature SDK
- 在 UOS Launcher 服务列表中，找到 Passport Feature，点击 「Install SDK」，将服务 SDK 安装到当前项目中
- 初始化 Feature SDK
```
try
{
await PassportFeatureSDK.Initialize();
}
catch (PassportException e)
{
Debug.Log($"failed to initialize sdk: {e.Message}");
throw;
}
```

1. 初始化角色战令

// 初始化角色战令，战令的免费槽将会自动解锁。初始化成功后，玩家将拥有相应的角色战令。
// 若玩家的角色战令已初始化，则返回相应的角色战令信息
PersonaBattlePassResponse res = await PassportFeatureSDK.BattlePass.InitPersonaBattlePass(slugName);

2. 获取角色战令信息

// 获取指定角色战令的详细信息
PersonaBattlePassResponse res = await PassportFeatureSDK.BattlePass.GetPersonaBattlePass(slugName);

// 将战令的名称打印出来
Debug.Log(res.BattlePass.DisplayName);

// 将奖励槽的名称打印出来
foreach (var slot in res.BattlePass.Slots)
{
    Debug.Log(slot.DisplayName);
}

public class PersonaBattlePassResponse
{
    // 角色战令信息
    public PersonaBattlePass BattlePass;
}

public class PersonaBattlePass
{
    // 角色战令ID
    public string Id;
    // 所属的UOS App ID
    public string UosAppId;
    // 角色ID
    public string PersonaId;
    // 战令的唯一标识Slug
    public string SlugName;
    // 战令的名称
    public string DisplayName;
    // 战令的描述
    public string description;
    // 战令的最大等级
    public uint MaxLevel;
    // 战令各等级升级所需的经验
    public List<uint> UpgradeExps;
    // 当前等级（小于等于该等级的奖励已解锁）
    public uint Level;
    // 当前等级的经验
    public uint Exp;
    // 战令状态，Pending/Active/Expired
    public BattlePassStatus Status;
    // 战令开始时间（UTC）
    public Timestamp StartTime;
    // 战令结束时间（UTC）, 空值表示永久有效
    public Timestamp EndTime;
    // 战令的每日经验获取限制，空值表示无限制
    public uint DailyPointLimit;
    // 战令的每周经验获取限制，空值表示无限制
    public uint WeeklyPointLimit;
    // 本日获得的经验
    public uint DayExp;
    // 本周获得的经验
    public uint WeekExp;
    // 角色战令创建时间（UTC）
    public Timestamp CreatedAt;
    // 奖励槽内容
    public List<PersonaBattlePassSlot> Slots;
}

public class PersonaBattlePassSlot
{
    // 奖励槽ID
    public string Id;
    // 所属的UOS App ID
    public string UosAppId;
    // 奖励槽的唯一标识Slug
    public string SlugName;
    // 奖励槽的名称
    public string DisplayName;
    // 归属的战令ID
    public string BattlePassId;
    // 归属的战令Slug
    public string BattlePassSlug;
    // 奖励槽类型，Free/Paid
    public BattlePassSlotType Type;
    // 奖励槽是否解锁
    public bool Active;
    // 战令奖励列表
    public List<BattlePassReward> Rewards;
    // 奖励槽的初始奖励，解锁奖励槽时会自动领取
    public SlotInitialReward InitialReward;
    // 前置奖励槽的Slug，解锁当前奖励槽会同时解锁前置的奖励槽
    public string PreSlotSlug;
}

public class SlotInitialReward
{
    // 经验
    public uint Exp;
    // 奖励资源列表
    public List<RewardResource> Resources;
}

public class BattlePassReward
{
    // 等级
    public uint Level;
    // 奖励资源列表
    public List<RewardResource> Resources;
}

public class RewardResource
{
    // 奖励资源的唯一标识slug, 即经济系统内资源(resource)的slug
    public string Slug;
    // 奖励资源的数量
    public uint Quantity;
    // 是否被领取
    public bool Claimed;
    // 奖励资源的详细信息
    public ResourceDetail Detail;
}

public class ResourceDetail
{
    // 资源名称
    public string DisplayName;
    // 资源类型(Item/VirtualCurrency/Currency)
    public Economy.ResourceType ResourceType;
    // 资源的自定义属性
    public Dictionary<string, string> CustomData;
}

3. 解锁奖励槽

需在UOS Passport 「战令 -> 战令管理」 页面开启「允许客户端解锁战令奖励槽」后才可访问此客户端SDK接口:

// 解锁角色指定的奖励槽，成功后返回相应的信息
ActivateBattlePassSlotResponse res = await PassportFeatureSDK.BattlePass.ActivateBattlePassSlot(slotSlug);

// 将本次解锁的奖励槽Slug打印出来（包括一起解锁的前置奖励槽）
foreach (var slug in res.SlotSlugs)
{
    Debug.Log(slug);
}

public class ActivateBattlePassSlotResponse
{
    // 本次解锁的奖励槽Slug列表（包括一起解锁的前置奖励槽）
    public List<string> SlotSlugs;
    // 解锁奖励槽后自动领取的初始奖励信息
    public SlotInitialReward InitialReward;
}

4. 增加经验

// 增加角色战令经验，成功后返回当前的等级和经验
AddBattlePassExpResponse res = await PassportFeatureSDK.BattlePass.AddBattlePassExp(slugName, exp);

// 将阅读后邮件的状态打印出来
Debug.Log($"Level: {res.Level}, Exp: {res.Exp}");

public class AddBattlePassExpResponse
{
    // 战令的唯一标识Slug
    public string SlugName;
    // 战令当前等级
    public uint Level;
    // 当前等级的经验
    public uint Exp;
}

5. 领取奖励

// 领取角色的战令奖励，当level和slotSlug都为空时即领取所有可领取的奖励
ClaimBattlePassRewardsResponse res = await PassportFeatureSDK.BattlePass.ClaimBattlePassRewards(slugName, level, slotSlug);

// 将本次领取的奖励资源打印出来
foreach (var resource in res.Resources)
{
    Debug.Log($"Slug: {resource.Slug}, Quantity: {resource.Quantity}");
}

public class ClaimBattlePassRewardsResponse
{
    // 本次领取的奖励资源
    public List<RewardResource> Resources;
}

4. 战令的扩展用法

阶梯礼包

简介：
通过战令实现阶梯礼包功能，阶梯礼包是指一个礼包内，玩家可以通过不同方式、阶梯式的解锁奖励，解锁方式通常有免费、付费、观看广告等。

实现思路：
我们通过配置战令的方式，战令不同等级的奖励作为阶梯礼包不同阶梯的奖励，解锁战令等级就相当于解锁阶梯奖励。

同时，在配置战令槽时，可以通过自定义属性来设置不同等级的配置，如该等级方式、对应的价格、广告地址等。

示例：
通过战令配置一个包含4个阶梯的礼包

战令配置：

创建一个等级为4的战令，战令的每级升级经验都设置为1
添加战令槽，配置角色奖励
添加一个免费的战令槽

战令槽的奖励中，每一级对应阶梯礼包的一个阶梯。
在自定义属性中，可以用cost字段表示该阶梯解锁需要的花费，0表示免费。
用product字段指向经济系统中具体的商品，用户购买该商品后，可以在后端回调中调用添加战令经验的API，使战令经验+1，达到解锁阶梯的效果。
在经济系统中配置解锁所需货币的商品
经济系统中相应的商品配置可以参考如下，阶梯礼包不同价格的解锁对应不同的商品。
玩家完成商品的购买后，可以在后端调用AddBattlePassExp的API，给战令加1经验，即升1级，解锁对应的阶梯奖励。
至此，我们已经通过战令完成了阶梯礼包的基本配置，礼包的SDK使用方法参照战令的API

阶梯礼包的使用流程可以参考下图

5. 附录

核心类和接口

namespace Unity.Passport.Runtime
{
    public partial class PassportFeatureSDK
    {
        public class BattlePass
        {
            // 初始化角色战令
            // slugName: 战令的唯一标识
            public static async Task<PersonaBattlePassResponse> InitPersonaBattlePass(string slugName)

            // 获取角色战令信息
            // slugName: 战令的唯一标识
            public static async Task<PersonaBattlePassResponse> GetPersonaBattlePass(string slugName)

            // 增加角色战令经验
            // slugName: 战令的唯一标识
            // exp: 增加的经验值
            public static async Task<AddBattlePassExpResponse> AddBattlePassExp(string slugName, uint exp)

            // 领取角色战令奖励
            // slugName: 战令的唯一标识
            // level: 指定领取某一等级的奖励，默认为空
            // slotSlug: 指定领取某一奖励槽的奖励，默认为空
            public static async Task<ClaimBattlePassRewardsResponse> ClaimBattlePassRewards(string slugName, uint? level, string slotSlug)

            // 解锁角色奖励槽（需在app下开启「允许客户端解锁战令奖励槽」配置）
            // slotSlug: 奖励槽的唯一标识
            public static async Task<ActivateBattlePassSlotResponse> ActivateBattlePassSlot(string slotSlug)
        }
    }
}

战令接入指南

战令接入指南

1. 基本概念

2. 功能配置与管理

创建战令

创建奖励槽

发布战令

角色战令详情

3. 在 Unity 中接入 SDK

1. 初始化角色战令

2. 获取角色战令信息

3. 解锁奖励槽

4. 增加经验

5. 领取奖励

4. 战令的扩展用法

阶梯礼包

战令配置：

5. 附录

核心类和接口

服务端 API

客户端 API

错误码