周期任务接入指南

1. 基本概念

周期任务系统通常用于管理和追踪玩家的周期性系列任务，旨在鼓励玩家每天参与游戏并完成一系列特定任务以获取积分或奖励。
通过累积任务集周期内获得的积分，玩家可以解锁各种奖励，如金币、经验值、道具或特殊装备，激励玩家保持游戏活跃度和参与度。
开发者可以将周期任务系统和经济系统（使用方法参考「经济系统」）结合使用，使用经济系统中的资源作为任务或积分奖励，领取奖励时，资源将会被自动发放到玩家的背包内。
周期任务系统在使用上主要分为 任务配置、角色任务 两个部分：

任务配置：包括了任务集的名称、类型、重置周期、任务、奖励等配置信息，用户可以在UOS网站上进行任务集及其下任务列表的配置与管理。
- 任务集：多个任务的集合，用于整体的显示与定时重置。
- 任务/积分奖励：任务集下的小任务，每条任务都有自己的目标值。
角色任务：每个玩家角色在游戏中拥有的任务集实体，可以对其下的任务进行更新任务分数、领取任务奖励等操作。

2. 功能配置与管理

创建任务集

在 UOS Passport 服务 「任务」 处点击 「立即创建」 ，创建一个名为 "每日任务" 的任务集：
在这一步用户将先配置任务集的基本信息，任务集下的任务列表将在任务集创建完成后进行配置。
任务集有两种类型：

积分任务：任务集下分成积分奖励和任务列表两个部分。完成任务列表中的任务可以获得相应的积分，积分累积到一定值后可以领取对应的积分奖励（即经济系统中的资源）。
独立任务：完成任务列表中的任务可以直接获得任务对应的奖励（即经济系统中的资源）。

选择好所需要的任务集类型后，可以配置任务集的基本信息及自定义属性。
配置说明：

唯一标识(SlugName)：任务集唯一标识，同一个UOS APP下可以唯一定位一个任务集，仅支持字母、数字、-、_的组合
任务集名称：可用作任务集的展示名称。
重置周期：可选择每日、每周一、每月1日，为任务集的重置时间。到重置时间后，玩家同步任务集后，任务进度会全部归0。
游戏每日重置时间：游戏世界新的一天开始的时间，假设此配置为2:00，且此任务集的重置周期为每日，则此任务集会于每日的凌晨2点重置。假设此任务集的重置周期为每周，则会于每周一的凌晨2点重置。
注意：此配置为app下全局配置，修改后此app下所有周期性重置相关的战令、月卡、任务均会于重置当日的此时刻重置。
自定义属性：自定义任务集属性。

点击 「保存」 存储已填写的信息，进入任务集内配置任务集下的任务列表。

配置积分任务

如果任务集选择的类型是「积分任务」，在「积分奖励」右侧点击「添加」，创建一个积分奖励。
配置说明：

唯一标识(SlugName)：积分奖励的唯一标识，同一个UOS APP下可以唯一定位一个积分奖励（app下所有任务集中都不可重复），仅支持字母、数字、-、_的组合
名称：可用作积分奖励的展示名称。
描述：积分奖励的基本描述。
目标积分：领取此积分奖励玩家需要获得的积分数量。
达成奖励：当玩家此任务集下的积分达到目标积分后，玩家可领取的奖励。奖励内容为passport经济系统下配置的资源，玩家领取奖励后奖励会被发放至玩家的背包中。
自定义属性：自定义的积分奖励属性。

点击 「创建」 存储已填写的信息。至此，成功创建了此任务集下的一个积分奖励。
在「任务列表」右侧点击 「添加」，创建一个任务。
配置说明：

唯一标识(SlugName)：任务的唯一标识，同一个UOS APP下可以唯一定位一个任务（app下所有任务集中都不可重复），仅支持字母、数字、-、_的组合
名称：可用作任务的展示名称。
描述：任务的基本描述。
目标值：达成此任务玩家需要达到的目标值。
达成奖励：当玩家此任务的达成值达到目标值后，玩家可以获得的积分数。领取此任务奖励会增加玩家此任务集下的相应积分。
自定义属性：自定义的任务属性。

至此，我们已经完成了一个积分任务类型的任务集的基本配置。一个完整的任务集配置可能如下：

在上图的例子中，如果玩家达成了「组队2次」的目标，则领取「组队2次」的任务奖励后，玩家会获得10积分。此时此任务集下积分为10，已达到「10分奖励」的目标积分，可以领取「10分奖励」对应的奖励内容（即1个钻石资源）。
如果玩家又达成了「获胜5局」的目标，则领取「获胜5局」的任务奖励后，玩家会获得30积分。此时此任务集下累计积分达到了40，已达到「20分奖励」的目标积分，可以领取「20分奖励」对应的奖励内容（即2个钻石资源）。
至此，我们已经完成了此任务集的所有配置。如果想要发布此任务集，可以单独对于期望发布的任务或积分奖励进行发布，或点击右上角进行全部发布。任务集需要发布后才可被玩家同步获取。

至此，我们成功配置并发布了一个积分任务类型的任务集。

配置独立任务

如果任务集选择的类型是 「独立任务」，在 「任务列表」 右侧点击 「添加」，创建一个任务。
配置说明：

唯一标识(SlugName)：任务的唯一标识，同一个UOS APP下可以唯一定位一个任务（app下所有任务集中都不可重复），仅支持字母、数字、-、_的组合
名称：可用作任务的展示名称。
描述：任务的基本描述。
目标值：达成此任务玩家需要达到的目标值。
达成奖励：当玩家此任务集下的积分达到目标积分后，玩家可领取的奖励。奖励内容为passport经济系统下配置的资源，玩家领取奖励后奖励会被发放至玩家的背包中。
自定义属性：自定义的任务属性。

至此，我们已经完成了一个独立任务类型的任务集的基本配置。一个完整的任务集配置可能如下：

在完成任务集的所有配置后，如果想要发布此任务集，可以单独对于期望发布的任务进行发布，或点击右上角进行全部发布。任务集需要发布后才可被玩家同步获取。
在上图的例子中，如果玩家达成了「20次组队」的目标，则可领取「20次组队」的任务奖励（即20个钻石资源）。此任务集将于每月1日重置

3. 在 Unity 中接入 SDK

在接入 SDK 前请确保完成 「功能配置」
在接入 SDK 前，请确保在代码中引入了 Passport 的命名空间：

using Unity.Passport.Runtime;

外部账号系统登录

参考「外部账号系统登录」正确接入外部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. 初始化角色任务

// 推荐在玩家每次登录或刷新任务时调用，用于将任务集配置同步至玩家的数据中，同时负责任务集的定期重置
List<Quest.PersonaQuest> personaQuests = await PassportFeatureSDK.Quest.FetchPersonaQuests();
foreach (Quest.PersonaQuest quest in personaQuests)
{
    // 获得任务集的展示名称
    Debug.Log(quest.DisplayName);
    // 获得任务集下的玩家积分奖励列表（如果任务集类型为积分任务）
    Debug.Log(quest.ProgressBar);
    // 获得任务集下的玩家任务列表
    Debug.Log(quest.Items);
}

public class PersonaQuest
{
  // 任务集所属的uos appID
  public string IdDomainID;
  // 任务集的唯一标识
  public string SlugName;
  // 显示名称
  public string DisplayName;
  // 任务类型(DailyQuest/WeeklyQuest/MonthlyQuest)
  public Quest.QuestType QuestType;
  // 重置时间点
  public uint DailyResetTime;
  // 自定义属性
  public Dictionary<string, string> Properties;
  // 任务布局类型(Basic独立任务/WithProgressBar积分任务)
  public Quest.Layout Layout;
  // 任务列表(进度条积分奖励部分，按阈值从小到大排列)
  public List<Quest.PersonaQuestItem> ProgressBar;
  // 任务列表(主体任务列表部分)
  public List<Quest.PersonaQuestItem> Items;
  // 创建时间（UTC）
  public Timestamp CreatedAt;
  // 创建用户
  public string CreatedBy;
  // 最后修改时间（UTC）
  public Timestamp ModifiedAt;
  // 最后修改用户
  public string ModifiedBy;
}

public class PersonaQuestItem
{
  // 任务的唯一标识
  public string SlugName;
  // 名称
  public string DisplayName;
  // 任务描述
  public string Description;
  // 任务组别
  public string Series;
  // 起始值
  public uint StartingValue;
  // 阈值，到达则表示任务已完成
  public uint ThresholdValue;
  // 玩家任务当前达成的值，已完成的任务不再更新此项
  public uint AchievedValue;
  // 任务是否已完成
  public bool Completed;
  // 任务完成的时间
  public Timestamp CompletionTime;
  // 完成任务可获得的奖励
  public List<Quest.Rewards> Rewards;
  // 玩家是否已经领取奖励
  public bool Redeemed;
  // 玩家任务记录自定义属性
  public Dictionary<string, string> CustomData;
  // 任务自定义属性
  public Dictionary<string, string> Properties;
}

public class Rewards
{
  // 资源的唯一标识
  public string SlugName;
  // 资源的种类(Resource经济系统资源/Point进度条积分)
  public Quest.RewardType RewardType;
  // 资源数量
  public uint Quantity;
  // 经济系统资源的详细信息
  public Quest.ResourceInfo Resource;
}

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

2. 获取角色任务

// 用于展示玩家任务集列表，也可指定slugName以获得某个特定的任务集
Quest.SearchPersonaQuestsResponse response = await PassportFeatureSDK.Quest.SearchPersonaQuests();
foreach (Quest.PersonaQuest quest in response.Quests)
{
    // 获得任务集的展示名称
    Debug.Log(quest.DisplayName);
    // 获得任务集下的玩家积分奖励列表（如果任务集类型为积分任务）
    Debug.Log(quest.ProgressBar);
    // 获得任务集下的玩家任务列表
    Debug.Log(quest.Items);
}

public class SearchPersonaQuestsResponse
{
    // 符合搜索条件的总数
    public uint Total;
    // 结果起始位置
    public uint Start;
    // 结果获取的数量
    public uint Count;
    // 玩家的任务集列表
    public List<Quest.PersonaQuest> Quests;
}

3. 更新玩家任务

// 用于更新玩家任务集下任务列表中某条任务的达成值
// 注意此处slugName为某条任务的slugName，而不是任务集的slugName。
var questItemSlug = "team_2";
Quest.UpdatePersonaQuestItemResponse updatedPersonaQuestItem = await PassportFeatureSDK.Quest.UpdatePersonaQuestItem(slugName: questItemSlug, Quest.QuestItemUpdateAction.Increase, 10);

public class UpdatePersonaQuestItemResponse
{
  // 玩家任务信息
  public Quest.PersonaQuestItem QuestItem;
}

4. 领取任务奖励

// 玩家领取任务/积分奖励
// 注意此处slugName为某条任务的slugName或者某个积分奖励的slugName
// 如果任务集是积分任务，则领取任务的奖励会增加相应的积分，积分达标后领取积分奖励会获得相应的资源
var questItemSlug = "team_2";
Quest.RedeemQuestItemRewardsResponse redeemed = await PassportFeatureSDK.Quest.RedeemQuestItemRewards(slugName: questItemSlug);

public class RedeemQuestItemRewardsResponse
{
  // 玩家任务信息
  public Quest.PersonaQuestItem QuestItem;
}

4. 集成示例

积分任务集成示例

// 首先确保玩家需要获取的任务内容均已发布
try
{
    // 在玩家登录时，调用FetchPersonaQuests初始化角色任务
    // 推荐在玩家每次登录或刷新任务时调用，用于将任务集配置同步至玩家的数据中，同时负责任务集的定期重置
    List<Quest.PersonaQuest> personaQuests = await PassportFeatureSDK.Quest.FetchPersonaQuests();

    // 获取slugName为dailyQuest的任务集
    var questSlug = "dailyQuest";
    Quest.SearchPersonaQuestsResponse response = await PassportFeatureSDK.Quest.SearchPersonaQuests(slugName: questSlug);
    if (response.Quests.Count != 1)
    {
        // 处理未找到任务集逻辑
    }
    Quest.PersonaQuest dailyQuest = response.Quests[0];
    // 获取任务集名称
    Debug.Log(dailyQuest.DisplayName);
    // 获取任务集自定义属性
    Debug.Log(dailyQuest.Properties);
    // 获取任务集重置周期
    Debug.Log(dailyQuest.QuestType);
    // 获取任务集重置时间点
    Debug.Log(dailyQuest.DailyResetTime);
    // 获取dailyQuest任务集的积分奖励条，ProgressBar根据获得奖励的节点进行了切割，可将所有ProgressBar下的所有progressBarItem拼接展示成一个完整的进度条
    foreach (Quest.PersonaQuestItem progressBarItem in dailyQuest.ProgressBar)
    {
        // 获取积分阈值，可展示于进度条的达成节点
        Debug.Log(progressBarItem.ThresholdValue);
        // 获取玩家已经达成的积分值，可展示于进度条玩家在此区间内当前达成的进度
        Debug.Log(progressBarItem.AchievedValue);
        // 获取玩家是否已达成积分要求
        Debug.Log(progressBarItem.Completed);
        // 获取达成此积分可以获得的奖励，可展示于进度条达成节点对应的宝箱
        foreach (Quest.Rewards reward in progressBarItem.Rewards)
        {
            // 获取奖励资源对应的slugName
            Debug.Log(reward.SlugName);
            // 获取可以获得的此奖励资源数量
            Debug.Log(reward.Quantity);
            if (reward.Resource != null)
            {
                // 获取奖励资源的展示名称
                Debug.Log(reward.Resource.DisplayName);
            }
        }
        // 获取玩家是否已领取此积分奖励
        Debug.Log(progressBarItem.Redeemed);
    }
    // 获取dailyQuest任务集的任务列表
    foreach (Quest.PersonaQuestItem item in dailyQuest.Items)
    {
        // 获取任务名称
        Debug.Log(item.DisplayName);
        // 获取任务描述
        Debug.Log(item.Description);
        // 获取任务阈值，表示玩家需要达成此值才能领取奖励
        Debug.Log(item.ThresholdValue);
        // 获取玩家已经达成的值
        Debug.Log(item.AchievedValue);
        // 获取玩家是否已达成此任务
        Debug.Log(item.Completed);
        // 获取玩家达成任务后可以获取的奖励积分数
        if (item.Rewards.Count == 1 && item.Rewards[0].RewardType == Quest.RewardType.Point)
        {
            Debug.Log(item.Rewards[0].Quantity);
        }
        // 获取玩家是否已领取此任务奖励
        Debug.Log(item.Redeemed);
    }

    // 更新玩家任务，在需要修改玩家任务达成值时调用
    // 假设dailyQuest的任务集下有个任务是“获胜5局”，那么在玩家每次获得一局游戏的胜利时，可以使用UpdatePersonaQuestItem使得玩家此任务的达成值加一
    // 当达成值达到此任务的目标值5的时候，此任务会被标记为已完成
    // 这里的slugName是需要更新的任务的slugName，不是任务集的slugName。任务的slugName也是app下全局唯一的。
    var questItemSlug = "win_count";
    Quest.UpdatePersonaQuestItemResponse updatedPersonaQuestItem = await PassportFeatureSDK.Quest.UpdatePersonaQuestItem(slugName: questItemSlug, Quest.QuestItemUpdateAction.Increase, 1);

    // 领取任务奖励
    // 假设玩家已经达成了上述的“获胜5局”任务，即可领取此任务的奖励
    // 假设此任务的奖励为30积分，那么RedeemQuestItemRewards之后，玩家此任务集下的积分条会自动增加30积分
    Quest.RedeemQuestItemRewardsResponse redeemedItem = await PassportFeatureSDK.Quest.RedeemQuestItemRewards(slugName: questItemSlug);

    // 领取积分奖励
    // 假设玩家已经领取了上面的30积分奖励后，达到了积分奖励point_1的目标积分（10分），就可以领取这个积分奖励的奖励
    // RedeemQuestItemRewards之后，玩家的背包内就会增加相应的奖励资源
    var progressBarItemSlug = "point_1";
    Quest.RedeemQuestItemRewardsResponse redeemedPoint = await PassportFeatureSDK.Quest.RedeemQuestItemRewards(slugName: progressBarItemSlug);
}
catch (PassportException e)
{
    Debug.Log(e.Code);
    Debug.Log(e.ErrorMessage);
    Debug.Log(e);
}

独立任务集成示例

// 首先确保玩家需要获取的任务内容均已发布
try
{
    // 在玩家登录时，调用FetchPersonaQuests初始化角色任务
    // 推荐在玩家每次登录或刷新任务时调用，用于将任务集配置同步至玩家的数据中，同时负责任务集的定期重置
    List<Quest.PersonaQuest> personaQuests = await PassportFeatureSDK.Quest.FetchPersonaQuests();

    // 获取slugName为monthlyRewards的任务集
    var questSlug = "monthlyRewards";
    Quest.SearchPersonaQuestsResponse response = await PassportFeatureSDK.Quest.SearchPersonaQuests(slugName: questSlug);
    if (response.Quests.Capacity != 1)
    {
        // 处理未找到任务集逻辑
    }
    Quest.PersonaQuest dailyQuest = response.Quests[0];
    // 获取任务集名称
    Debug.Log(dailyQuest.DisplayName);
    // 获取任务集自定义属性
    Debug.Log(dailyQuest.Properties);
    // 获取任务集重置周期
    Debug.Log(dailyQuest.QuestType);
    // 获取任务集重置时间点
    Debug.Log(dailyQuest.DailyResetTime);
    // 获取monthlyRewards任务集的任务列表
    foreach (Quest.PersonaQuestItem item in dailyQuest.Items)
    {
        // 获取任务名称
        Debug.Log(item.DisplayName);
        // 获取任务描述
        Debug.Log(item.Description);
        // 获取任务阈值，表示玩家需要达成此值才能领取奖励
        Debug.Log(item.ThresholdValue);
        // 获取玩家已经达成的值
        Debug.Log(item.AchievedValue);
        // 获取玩家是否已达成此任务
        Debug.Log(item.Completed);
        // 获取达成此任务可以获得的奖励
        foreach (Quest.Rewards reward in item.Rewards)
        {
            // 获取奖励资源对应的slugName
            Debug.Log(reward.SlugName);
            // 获取可以获得的此奖励资源数量
            Debug.Log(reward.Quantity);
            if (reward.Resource != null)
            {
                // 获取奖励资源的展示名称
                Debug.Log(reward.Resource.DisplayName);
            }
        }
        // 获取玩家是否已领取此任务奖励
        Debug.Log(item.Redeemed);
    }

    // 更新玩家任务，在需要修改玩家任务达成值时调用
    // 假设dailyQuest的任务集下有个任务是“赢得30场对局”，那么在玩家每次获得一局游戏的胜利时，可以使用UpdatePersonaQuestItem使得玩家此任务的达成值加一
    // 当达成值达到此任务的目标值30的时候，此任务会被标记为已完成
    // 这里的slugName是需要更新的任务的slugName，不是任务集的slugName。任务的slugName也是app下全局唯一的。
    var questItemSlug = "win_30";
    Quest.UpdatePersonaQuestItemResponse updatedPersonaQuestItem = await PassportFeatureSDK.Quest.UpdatePersonaQuestItem(slugName: questItemSlug, Quest.QuestItemUpdateAction.Increase, 1);

    // 领取任务奖励
    // 假设玩家已经达成了上述的“赢得30场对局”任务，即可领取此任务的奖励
    // RedeemQuestItemRewards之后，玩家的背包内就会增加相应的奖励资源
    Quest.RedeemQuestItemRewardsResponse redeemedItem = await PassportFeatureSDK.Quest.RedeemQuestItemRewards(slugName: questItemSlug);
}
catch (PassportException e)
{
    Debug.Log(e.Code);
    Debug.Log(e.ErrorMessage);
    Debug.Log(e);
}

5. 附录

核心类和接口

namespace Unity.Passport.Runtime
{
    public partial class PassportFeatureSDK
    {
        public class Quest
        {
            // 初始化角色任务
            // 推荐在玩家每次登录或刷新任务时调用，用于将任务集配置同步至玩家的数据中，同时负责任务集的定期重置
            public static async Task<List<PersonaQuest>> FetchPersonaQuests(){}

            // 获取角色任务
            // slugName: 任务集slugName
            // displayName: 任务集名称
            // questType: 任务集类型
            // start: 查询起始位置，默认为0
            // count: 查询获取的数量，默认为10，最大为50
            public static async Task<SearchPersonaQuestsResponse> SearchPersonaQuests(string slugName = null, string displayName = null, QuestType? questType = null, uint start = 0, uint count = 10){}

            // 更新玩家任务
            // slugName: 任务的唯一标识slug
            // action: 任务值修改方式，需为Increase/Reduce/Reset/Accumulate
            // value: 任务值修改方式相应的值，已达成的任务不会更新任务达成值（achievedValue）
            // customData: 自定义属性，大小默认限制为0.5KB
            public static async Task<UpdatePersonaQuestItemResponse> UpdatePersonaQuestItem(string slugName, QuestItemUpdateAction action, uint value, Dictionary<string, string> customData = null){}

            // 领取任务/积分奖励
            // slugName: 任务或积分奖励的唯一标识slug
            public static async Task<RedeemQuestItemRewardsResponse> RedeemQuestItemRewards(string slugName){}
        }
    }
}

周期任务接入指南

周期任务接入指南

1. 基本概念

2. 功能配置与管理

创建任务集

配置积分任务

配置独立任务

3. 在 Unity 中接入 SDK

1. 初始化角色任务

2. 获取角色任务

3. 更新玩家任务

4. 领取任务奖励

4. 集成示例

积分任务集成示例

独立任务集成示例

5. 附录

核心类和接口

服务端 API

客户端 API

错误码