排行榜接入指南

1. 功能配置与管理

基础配置

在 UOS Passport 服务 「排行榜 -> 排行榜管理」 处点击 「立即创建」，创建一个名为“战力榜”的排行榜：

基础配置说明：

唯一标识(leaderboardSlugName)：排行榜唯一标识ID，同一个UOS APP下可以唯一定位一个排行榜，仅支持数字与字符组合
排行目标：分为“玩家”和“自定义成员”两个选项，对于玩家以外的武器榜、装备榜等，均可选择“自定义成员”。玩家排行榜的成员ID为玩家的personaID，自定义成员排行榜的成员ID是自定义的字符串。
排序方式：分为“升序”，即排名按成绩由低到高排列，值越小排名越高；“降序”，即排名按成绩由高到低排列，值越小排名越低
成绩更新策略：有三种更新成绩的策略，分别是“保留最好成绩”，即每次更新时取最优值；“保留最新成绩”，即每次更新均替换旧值；“成绩累加”，即每次更新将新成绩值与原有成绩值相加
是否跨服：决定了不同服务器的成绩是否在一个排行榜中排榜
榜中榜：指的是在原始排行榜的基础上，按照指定规则分配小榜。分为”用户自定义“，即用户在更新成绩时需主动指定该用户隶属的小榜单；和”系统分配“，即按照配置的小榜容量，由系统在用户更新成绩时自动分配至不同的小榜两种模式
自定义属性：排行榜的自定义属性，可以用于存储排行榜属性数据，用于客户端的展示
生效/失效时间：排行榜仅允许在生效时间-失效时间的时间区间内上报成绩，其余时间尝试上报成绩会报错
是否强制区分同分排名：对于相同分数的成绩，默认以成绩更新时间升序区分排名。如果有使用到批量更新成绩的服务端API，即可能出现相同成绩的更新时间相同时，打开此配置将强行区分同分同更新时间情况下的排名，避免同分同排名的情况。

点击排行榜名称进入详情页，在此处你可以看到排行榜的基本信息，其中生效/失效时间和自定义属性可以自行修改。下方有可以自行配置的“重置管理”、“分级管理”和“奖励”三个功能模块：

用于控制排行榜的重置，重置后该榜单的所有数据清零，可以用于新开赛季等。分为“下次重置时间”和“自动重置周期”，其中“下次重置时间”的设定决定了排行榜将在该时间进行重置，而此时若是设定了“重置周期”，其第一次执行将在“下次重置时间”后的第一个周期节点执行。
如下图所示的重置计划，排行榜将在24年7月16号的18点进行重置，同时根据重置周期计算得到首次周期重置将于24年8月1号0点执行，以此类推，往后的每月1号0点均会执行。

分级管理

用于计算每个成绩归属的等级，可用于分配段位、称号等。创建分级后，返回的成绩中可以获取到对应的等级。
如下图所示的分级，分值为70的成绩将归属于“白银”，而分值为90的成绩将归属与“黄金”。

奖励

用于配置排行榜奖励，在赛季更新后给玩家发送邮件并附带奖励物品。

点击 「配置奖励发放邮件模板」，邮件模板可使用“创建空白模版”，也可“选择已有模版”（发送范围必须是“角色”），本示例选择“创建空白模版”，点击「下一步」：

填写邮件唯一标识符(SlugName)和名称（示例为：leaderboard-reward、排行榜奖励测试），选择「下一步」：

依次填写邮件标题、副标题、来源和正文内容。其中邮件正文中，系统提供了部分占位符，以在实际邮件发送过程中填入该玩家的真实数据。可点击 正文内容 下方的四个小按钮添加占位符目前系统支持的占位符如下：

角色名称（Persona_Name）: 在实际发送邮件的过程中将替换成角色真实的名称
排名（Leaderboard_Rank）: 在实际发送邮件的过程中将替换成角色真实的排名
排行榜名称（Leaderboard_Name）: 在实际发送邮件的过程中将替换成角当前排行榜的名称
分数（Leaderboard_Score）: 在实际发送邮件的过程中将替换成角色真实的分数

完成邮件模板的配置后，可点击「创建奖励规则」为该排行榜创建奖励规则：

奖励发放的结算规则分三种：

按照榜单排名结算：例如：1-10名发放奖励”金币100“，11-20名发放奖励“金币50”，21名及之后名次发放奖励“金币*20”。
桶内结算：例如：小榜内1-5名发放奖励”金币50“，6-10名发放奖励“金币20”，11名及之后名次发放奖励“金币*10”。
通过排行榜上定义的分级来结算：例如：等级为“黄金”的玩家发放奖励”金币100“，等级为“白银”的玩家发放奖励“金币50”，等级为“青铜”的玩家发放奖励“金币*20”。

默认选择“按照榜单排名结算”，点击「下一步」开始配置奖励细节：
示例按照1-20名（均为闭区间）、21-60名、61-90名以及91名及以后分四个奖励区间，奖励内容为金币，数量可自行调整，配置完毕点击「提交」即可。

2. 常用排行榜配置示例

玩家最高分数排行榜（带分级管理）

需求与简介：
假设玩家每进行一次游戏在结束后都会获得一个最终分数，想创建玩家所达成的「最高分数」排行榜，且所有玩家一起排行，不区分服务器。同时，根据玩家分数对玩家进行分级，每个级别有不同的名称。

示例游戏：
微信小游戏「跳一跳」的最高分数排行榜。

排行榜配置：

创建完排行榜后，点进排行榜详情，可在详情页面继续进行「分级管理」的配置。
如果想要将玩家的等级根据成绩高低分成三类，可配置：

黄金：分数为80-100的玩家
白银：分数为60-80的玩家（不含80分）
青铜：分数为0-60的玩家（不含60分）

至此，我们已经完成了玩家分数排行榜的所有配置。玩家会根据分数被分至三个等级之一，在查询排行榜分数时可以获得玩家相应的等级。

SDK调用方式：

完成「接入用户登录模块」之后，示例调用代码如下：

// 排行榜唯一标识（SlugName），上图配置示例中为personaBestScoreLeaderboard
var leaderboardSlugName = "personaBestScoreLeaderboard";
// 玩家本局游戏得分，假设为55
var personaScore = 55;
// 每局游戏结束后，更新玩家在「最好成绩排行榜」中的分数
// 由于此排行榜配置中的「成绩更新策略」为「保留最好成绩」，所以后续如果更新的成绩低于55，则不会覆盖玩家已有成绩，依旧会保留玩家成绩为55
Leaderboard.UpdateScoreResponse updatedScore = await PassportFeatureSDK.Leaderboard.UpdateScore(leaderboardSlugName, personaScore);
// 获取「最好成绩排行榜」的排行
Leaderboard.ListLeaderboardScoresResponse resp = await PassportFeatureSDK.Leaderboard.ListLeaderboardScores(leaderboardSlugName);
foreach (Leaderboard.LeaderboardMemberScore score in resp.Scores)
{
    // 打印玩家的名称、成绩以及所属的分级
    Debug.Log(score.DisplayName);
    Debug.Log(score.Score);
    // 此处tier对应排行榜的分级配置，如：玩家分数为55，tier则根据上面配置的分级对应为「青铜」
    Debug.Log(score.Tier);
}

带有榜中榜的成绩排行榜

需求与简介：
同样是玩家最好分数排行榜，在拥有全服总排行的情况下，想要同时获得玩家所在省份下的所有玩家分数排行信息，此时需要使用「榜中榜」功能。上报玩家成绩时，同时记录该玩家所在省份的名称，即可将同一省份下的所有玩家归为一个小榜，在拥有总榜排名的同时也可以筛选玩家所在榜中榜（同一省份）的数据。

排行榜配置：
创建一个新的排行榜，配置「榜中榜」为用户自定义。

SDK调用方式：
完成「接入用户登录模块」之后，示例调用代码如下：

// 排行榜唯一标识（SlugName），上图配置示例中为scoreWithProvince
var leaderboardSlugName = "scoreWithProvince";
// 假设玩家本局游戏得分为55
var personaScore = 55;
// 假设此玩家所在省份为上海，可以自定义bucketId为"shanghai"，相同bucketId下的成绩会被分到同一榜中榜
var bucketId = "shanghai";
// 更新玩家在「带有榜中榜的成绩排行榜」中的分数
Leaderboard.UpdateScoreResponse updatedScore = await PassportFeatureSDK.Leaderboard.UpdateScoreWithBucketId(leaderboardSlugName, personaScore, bucketId);
// 获取「带有榜中榜的成绩排行榜」的总体排行
Leaderboard.ListLeaderboardScoresResponse resp = await PassportFeatureSDK.Leaderboard.ListLeaderboardScores(leaderboardSlugName);
foreach (Leaderboard.LeaderboardMemberScore score in resp.Scores)
{
    // 打印玩家的名称、成绩
    Debug.Log(score.DisplayName);
    Debug.Log(score.Score);
    // 此处为玩家分数所属的bucketId
    Debug.Log(score.BucketId);
}
// 获取「带有榜中榜的成绩排行榜」中玩家所在小榜（即同一省份）下的所有成绩列表，由于此玩家的分数bucketId为"shanghai"，此处获得的是bucketId为"shanghai"的所有玩家分数列表
Leaderboard.ListMemberScoresInBucketResponse bucketScores = await PassportFeatureSDK.Leaderboard.GetBucket(leaderboardSlugName);

各省份通关人数排行榜

需求与简介：
需要一个排行榜记录每个省份的通关人数，并且对各个省份的通关人数进行排行。此时我们把每个省份记录为一个成员，该省份的分数则表示该省份通关的人数。

示例游戏：
微信小游戏“羊了个羊”中首页展示的各个省份的今日通关人数排行。

排行榜配置：
创建一个新的排行榜，配置「排行目标」为「自定义成员」，并且将「成绩更新策略」定义为「成绩累加」。

SDK调用方式：
完成「接入用户登录模块」之后，示例调用代码如下：

// 排行榜唯一标识（SlugName），上图配置示例中为provinceLeaderboard
var leaderboardSlugName = "provinceLeaderboard";
// 假设此玩家所在省份为上海，则玩家需要更新的是成员ID为“shanghai”的这条成绩
var memberId = "shanghai";
// 在玩家首次通关时，更新自定义成员排行榜成员分数，即更新“shanghai”这个成员在排行榜中的分数。
// 由于排行榜的成绩更新策略为「成绩累加」，所以需要更新的成绩为1，即排行榜此条成绩在原有的成绩上增加1，表示该省份新增了一位通关玩家。
Leaderboard.UpdateScoreResponse updatedScore = await PassportFeatureSDK.Leaderboard.UpdateEntityScore(leaderboardSlugName, memberId, 1);
// 获取排行
Leaderboard.ListLeaderboardScoresResponse resp = await PassportFeatureSDK.Leaderboard.ListLeaderboardScores(leaderboardSlugName);
foreach (Leaderboard.LeaderboardMemberScore score in resp.Scores)
{
    // 此时成员ID即为自定义的ID字符串，如"shanghai"等
    Debug.Log(score.MemberId);
    // 此时成绩表示该省份的通关玩家数
    Debug.Log(score.Score);
}

可以看到此排行榜的成绩组成如下：

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. 获取排行榜列表

// 获取该UOS APP下排行榜配置信息
Leaderboard.ListLeaderboardsResponse leaderboardList = await PassportFeatureSDK.Leaderboard.GetLeaderboards();
for(int i = 0; i < leaderboardList.Count; i += 1)
{
    var leaderboard = leaderboardList.Leaderboards[i];
    if (leaderboard.SlugName == "Kills")
    {
        // todo
    }
}
public class ListLeaderboardsResponse
{
    // 符合搜索条件的总数
    public uint Total;
    // 结果起始位置
    public uint Start;
    // 结果获取的数量
    public uint Count;
    // 查询结果，LeaderboardConfig列表
    public List<LeaderboardConfig> Leaderboards;
}

public class LeaderboardConfig
{
    // 排行榜id
    public string ID;
    // 排行榜名称
    public string DisplayName;
    // 排行榜所属的uos appId
    public string IdDomainID;
    // 排行榜中的排名计算方式，Desc/Asc，分别表示降序或者升序
    public Leaderboard.SortOrder SortOrder;
    // 成绩的更新策略，KeepBest/KeepLatest/Aggregate，分别表示保留最好成绩、保留最新成绩、累加成绩
    public Leaderboard.UpdateType UpdateType;
    // 排行榜的成员属性，Player/Entity，分别表示玩家或者实体
    public Leaderboard.MemberType MemberType;
    // 排行榜的版本id，当重置排行榜时会被更新
    public string VersionId;
    // 成绩是否跨域，若为false则同一排行榜下不同realm的成绩分开排序
    public bool CrossRealm;
    // 是否使用榜中榜，以及bucketId的定义方式
    public Leaderboard.BucketStrategy BucketStrategy;
    // 小榜的最大大小
    public uint BucketSize;
    // 排行榜的重置周期，格式为cron string，如：@monthly, @daily, @every 72h
    public string ResetSchedule;
    // 当重置排行榜时成绩是否需要存档
    public bool ResetArchive;
    // 排行榜最后一次重置的时间
    public Timestamp LastResetAt;
    // 分等级的策略，Score/Rank/Percent，分别表示分等级的依据是成绩范围、排名、超过的玩家百分比
    public Leaderboard.TierStrategy TierStrategy;
    // 成绩等级策略
    public List<Tier> Tiers;
    // 创建时间（UTC）
    public Timestamp CreatedAt;
    // 创建用户
    public string CreatedBy;
    // 最后修改时间（UTC）
    public Timestamp UpdatedAt;
    // 最后修改用户
    public string UpdatedBy;
    // 重置计划信息
    public ScheduleInfo ScheduleInfo;
    // 同app下排行榜的唯一标识
    public string LeaderboardSlugName;
    // 站内信模版SlugName
    public string InboxTemplateSlugName;
    // 奖励结算方式
    public Leaderboard.RewardStrategy RewardStrategy;
    // 奖励规则
    public List<RewardRuleExpanded> RewardRules;
    // 开始生效时间（UTC）
    public Timestamp StartEffectiveTime;
    // 结束生效时间（UTC）
    public Timestamp EndEffectiveTime;
    // 排行榜自定义属性
    public Dictionary<string, string> Properties;
}

public class ScheduleInfo
{
    // 重置任务id
    public string TaskId;
    // 设置重置任务的时间
    public Timestamp RequestedAt;
    // 重置任务开始时间
    public Timestamp ProcessAt;
}

public class Tier
{
    // 等级名称
    public string Name;
    // 等级计算起始值
    public uint From;
    // 等级计算结束值
    public uint To;
}

public class RewardRuleExpanded
{
    // 起始名次或tier名称（闭区间）
    public string From;
    // 结束名次或tier名称（闭区间）
    public string To;
    // 解锁成就可获得的奖励详情
    public List<ResourceDetail> Rewards;
}

public class ResourceDetail {
    // 资源唯一标识slug
    public string SlugName;
    // 资源名称
    public string DisplayName;
    // 资源类型
    public Economy.ResourceType ResourceType;
    // 资源自定义属性
    public Dictionary<string, string> CustomData;
    // 资源数量
    public uint Quantity;
}

2. 更新排行榜玩家分数

var score = 20;
// 根据排行榜配置中的「成绩更新策略」来更新玩家在此排行榜的成绩，如果排行榜的「成绩更新策略」配置为：
// 保留最好成绩：则传入的score将会与该玩家在此排行榜中已有的成绩进行对比，保留成绩最优值
// 保留最新成绩：则传入的score将会覆盖该玩家在此排行榜中已有的成绩
// 成绩累加：则传入的score将会增加至该玩家在此排行榜已有的成绩上，成绩将更新为玩家已有成绩与传入score的相加之和
Leaderboard.UpdateScoreResponse updatedScore = await PassportFeatureSDK.Leaderboard.UpdateScore(leaderboardSlugName, score);

public class UpdateScoreResponse
{
    // 成员id
    public string MemberId;
    // 成绩
    public double Score;
    // 成绩排名
    public uint Rank;
    // 成绩所属等级
    public string Tier;
    // 成绩更新时间
    public Timestamp UpdatedAt;
    // 自定义的桶名
    public string BucketId;
    // 成绩自定义属性
    public Dictionary<string, string> Properties;
}

3. 查询排行榜成绩

Leaderboard.ListLeaderboardScoresResponse scoreList = await PassportFeatureSDK.Leaderboard.ListLeaderboardScores(leaderboardSlugName);

public class ListLeaderboardScoresResponse
{
    // 符合搜索条件的总数
    public uint Total;
    // 结果起始位置
    public uint Start;
    // 结果获取的数量
    public uint Count;
    // 查询结果
    public List<LeaderboardMemberScore> Scores;
}

public class LeaderboardMemberScore
{
    // 成员id
    public string MemberId;
    // 成员成绩
    public double Score;
    // 成员排名
    public uint Rank;
    // 成员成绩所属的等级
    public string Tier;
    // key为其他排行榜leaderboardSlugName，value为该member在此排行榜下的成绩
    public Dictionary<string, double> Statistics;
    // 成员所属的小榜
    public string BucketId;
    // 如果memberType是player，此项为persona的displayName
    public string DisplayName;
    // 如果memberType是player，此项为persona的properties
    public Dictionary<string,string> PersonaProperties;
    // 如果memberType是player，此项为persona的头像地址
    public string IconUrl;
    // 成绩自定义属性
    public Dictionary<string, string> Properties;
}

也可以在 UOS Passport 所创建排行榜详情页的「榜单数据」中查看分数:

4. 查询自己及附近玩家成绩

// 查询自己及附近玩家成绩, range为0就是查询自己的成绩
var range = 0;
Leaderboard.GetMemberScoreResponse scoreList = await PassportFeatureSDK.Leaderboard.GetScore(leaderboardSlugName, range);
// 若是需要打印出自己的成绩
if (scoreList.Scores.Any())
{
    var score = scoreList.Scores[range];
    Debug.Log(score.DisplayName);
    Debug.Log(score.PersonaProperties);
    Debug.Log(score.Rank);
    Debug.Log(score.Score);
    Debug.Log(score.Tier);
}

public class GetMemberScoreResponse
{
    // 查询到的成绩列表
    public List<LeaderboardScore> Scores;
}

public class LeaderboardScore
{
    // 成员id
    public string MemberId;
    // 成绩
    public double Score;
    // 成绩排名
    public uint Rank;
    // 成绩所属等级
    public string Tier;
    // 如果memberType是player，此项为persona的displayName
    public string DisplayName;
    // 如果memberType是player，此项为persona的properties
    public Dictionary<string,string> PersonaProperties;
    // 如果memberType是player，此项为persona的头像地址
    public string IconUrl;
    // 成绩自定义属性
    public Dictionary<string, string> Properties;
}

5. 查询自己所属 bucket(榜中榜) 的全部成绩

Leaderboard.ListMemberScoresInBucketResponse bucketScoreList = await PassportFeatureSDK.Leaderboard.GetBucket(leaderboardSlugName);
// 若是想要打印自己的成绩
foreach (var score in bucketScoreList.Scores)
{
    // 可以根据MemberId和当前角色的PersonaID来获取自己的成绩
    if (score.MemberId == DemoUIController.Instance.Persona.PersonaID)
    {
        Debug.Log(score.DisplayName);
        Debug.Log(score.PersonaProperties);
        Debug.Log(score.Rank);
        Debug.Log(score.Score);
        Debug.Log(score.Tier);
    }
}

public class ListMemberScoresInBucketResponse
{
    // 符合搜索条件的总数
    public uint Total;
    // 结果起始位置
    public uint Start;
    // 结果获取的数量
    public uint Count;
    // 查询结果
    public List<MemberScoreInBucket> Scores;
    // 自定义bucketId
    public string BucketId;
    // 玩家在榜中榜的成绩信息
    public MemberScoreWithRankInBucket MemberScore;
}

public class MemberScoreInBucket
{
    // 成员id
    public string MemberId;
    // 成员成绩
    public double Score;
    // 成员排名
    public uint64 Rank;
    // 成员成绩所属的等级
    public string Tier;
    // 如果memberType是player，此项为persona的displayName
    public string DisplayName;
    // 如果memberType是player，此项为persona的properties
    public Dictionary<string,string> PersonaProperties;
    // 如果memberType是player，此项为persona的头像地址
    public string IconUrl;
    // 成绩自定义属性
    public Dictionary<string, string> Properties;
}

public class MemberScoreWithRankInBucket
{
    // 成员id
    public string MemberId;
    // 成员成绩
    public double Score;
    // 成员排名
    public uint64 Rank;
    // 成员成绩所属的等级
    public string Tier;
    // 如果memberType是player，此项为persona的displayName
    public string DisplayName;
    // 如果memberType是player，此项为persona的properties
    public Dictionary<string,string> PersonaProperties;
    // 如果memberType是player，此项为persona的头像地址
    public string IconUrl;
    // 成绩自定义属性
    public Dictionary<string, string> Properties;
    // 榜中榜内排名
    public uint BucketRank;
}

6. 用户自定义榜中榜时，更新排行榜成员分数（需指定 bucketId）

var score = 30;
Leaderboard.UpdateScoreResponse updatedScore = await PassportFeatureSDK.Leaderboard.UpdateScoreWithBucketId(leaderboardSlugName, score, "bucket1");

public class UpdateScoreResponse
{
    // 成员id
    public string MemberId;
    // 成绩
    public double Score;
    // 成绩排名
    public uint Rank;
    // 成绩所属等级
    public string Tier;
    // 成绩更新时间
    public Timestamp UpdatedAt;
    // 自定义的桶名
    public string BucketId;
    // 成绩自定义属性
    public Dictionary<string, string> Properties;
}

7. 获取某个排行榜的配置信息

Leaderboard.GetLeaderboardResponse leaderboard = await PassportFeatureSDK.Leaderboard.GetLeaderboard(leaderboardSlugName);

public class GetLeaderboardResponse
{
    // 排行榜配置信息
    LeaderboardConfig Leaderboard;
}

public class LeaderboardConfig
{
    // 排行榜id
    public string ID;
    // 排行榜名称
    public string DisplayName;
    // 排行榜所属的uos appId
    public string IdDomainID;
    // 排行榜中的排名计算方式，Desc/Asc，分别表示降序或者升序
    public Leaderboard.SortOrder SortOrder;
    // 成绩的更新策略，KeepBest/KeepLatest/Aggregate，分别表示保留最好成绩、保留最新成绩、累加成绩
    public Leaderboard.UpdateType UpdateType;
    // 排行榜的成员属性，Player/Entity，分别表示玩家或者实体
    public Leaderboard.MemberType MemberType;
    // 排行榜的版本id，当重置排行榜时会被更新
    public string VersionId;
    // 成绩是否跨域，若为false则同一排行榜下不同realm的成绩分开排序
    public bool CrossRealm;
    // 是否使用榜中榜，以及bucketId的定义方式
    public Leaderboard.BucketStrategy BucketStrategy;
    // 小榜的最大大小
    public uint BucketSize;
    // 排行榜的重置周期，格式为cron string，如：@monthly, @daily, @every 72h
    public string ResetSchedule;
    // 当重置排行榜时成绩是否需要存档
    public bool ResetArchive;
    // 排行榜最后一次重置的时间
    public Timestamp LastResetAt;
    // 分等级的策略，Score/Rank/Percent，分别表示分等级的依据是成绩范围、排名、超过的玩家百分比
    public Leaderboard.TierStrategy TierStrategy;
    // 成绩等级策略
    public List<Tier> Tiers;
    // 创建时间（UTC）
    public Timestamp CreatedAt;
    // 创建用户
    public string CreatedBy;
    // 最后修改时间（UTC）
    public Timestamp UpdatedAt;
    // 最后修改用户
    public string UpdatedBy;
    // 重置计划信息
    public ScheduleInfo ScheduleInfo;
    // 同app下排行榜的唯一标识
    public string LeaderboardSlugName;
    // 站内信模版SlugName
    public string InboxTemplateSlugName;
    // 奖励结算方式
    public Leaderboard.RewardStrategy RewardStrategy;
    // 奖励规则
    public List<RewardRuleExpanded> RewardRules;
    // 开始生效时间（UTC）
    public Timestamp StartEffectiveTime;
    // 结束生效时间（UTC）
    public Timestamp EndEffectiveTime;
    // 排行榜自定义属性
    public Dictionary<string, string> Properties;
}

8. 获取所有好友在某一个排行榜中的成绩信息

Leaderboard.GetFriendsLeaderboardResponse response = await PassportFeatureSDK.Leaderboard.GetFriendsLeaderboard(leaderboardSlugName);

public class GetFriendsLeaderboardResponse
{
    // 查询到的成绩列表
    public List<LeaderboardScore> Scores;
}

public class LeaderboardScore
{
    // 成员id
    public string MemberId;
    // 成绩
    public double Score;
    // 成绩排名
    public uint Rank;
    // 成绩所属等级
    public string Tier;
    // 如果memberType是player，此项为persona的displayName
    public string DisplayName;
    // 如果memberType是player，此项为persona的properties
    public Dictionary<string,string> PersonaProperties;
    // 如果memberType是player，此项为persona的头像地址
    public string IconUrl;
    // 成绩自定义属性
    public Dictionary<string, string> Properties;
}

9. 查询历史排行榜中玩家的成绩

// 可在UOS App - 排行榜 - 排行榜详情 - 榜单数据 下选择赛季后获取此处的赛季版本号
var versionId = "53526a03-9d40-4d8b-8f35-0e5e96f089be";
Leaderboard.GetMemberHistoryScoreResponse historyScore = await PassportFeatureSDK.Leaderboard.GetMemberHistoryScore(leaderboardSlug, versionId);
Debug.Log(historyScore.Score);

public class GetMemberHistoryScoreResponse
{
    // 历史成绩信息
    public HistoryScore Score;
}

public class HistoryScore
{
    // 成员id
    public string MemberId;
    // 成绩
    public double Score;
    // 成绩排名
    public uint Rank;
    // 如果memberType是player，此项为persona的displayName
    public string DisplayName;
    // 如果memberType是player，此项为persona的properties
    public Dictionary<string,string> PersonaProperties;
    // 如果memberType是player，此项为persona的头像地址
    public string IconUrl;
    // 成绩自定义属性
    public Dictionary<string, string> Properties;
}

10. 更新自定义成员排行榜成员分数

var score = 20;
var memberId = "entity1";
// 根据排行榜配置中的「成绩更新策略」来更新自定义成员在此排行榜的成绩，如果排行榜的「成绩更新策略」配置为：
// 保留最好成绩：则传入的score将会与该自定义成员在此排行榜中已有的成绩进行对比，保留成绩最优值
// 保留最新成绩：则传入的score将会覆盖该自定义成员在此排行榜中已有的成绩
// 成绩累加：则传入的score将会增加至该自定义成员在此排行榜已有的成绩上，成绩将更新为自定义成员已有成绩与传入score的相加之和
Leaderboard.UpdateScoreResponse updatedScore = await PassportFeatureSDK.Leaderboard.UpdateEntityScore(leaderboardSlugName, memberId, score);

public class UpdateScoreResponse
{
    // 成员id
    public string MemberId;
    // 成绩
    public double Score;
    // 成绩排名
    public uint Rank;
    // 成绩所属等级
    public string Tier;
    // 成绩更新时间
    public Timestamp UpdatedAt;
    // 自定义的桶名
    public string BucketId;
    // 成绩自定义属性
    public Dictionary<string, string> Properties;
}

11. 获取自定义成员排行榜某个历史版本中的成绩

// 可以使用listLeaderboardVersions获取排行榜历史版本号信息
var versionId = "53526a03-9d40-4d8b-8f35-0e5e96f089be";
// 指定需要查询的entityMemberId
var entityMemberId = "entity1";
Leaderboard.ListHistoryScoreSDKResponse res = await PassportFeatureSDK.Leaderboard.GetEntityHistoryScore(leaderboardSlug, versionId, entityMemberId);
foreach (var score in res.Scores)
{
    Debug.Log(score);
    Debug.Log(score.Properties);
    Debug.Log(score.Score);
    Debug.Log(score.Rank);
    Debug.Log(score.Tier);
}

public class ListHistoryScoreSDKResponse
{
    // 符合搜索条件的总数
    public uint Total;
    // 结果起始位置
    public uint Start;
    // 结果获取的数量
    public uint Count;
    // 查询结果
    public List<HistoryScoreWithRewardStatus> Scores;
}

public class HistoryScoreWithRewardStatus
{
    // 成员id
    public string MemberId;
    // 成绩
    public double Score;
    // 成绩排名
    public uint Rank;
    // 成绩所属等级
    public string Tier;
    // 如果memberType是player，此项为persona的displayName
    public string DisplayName;
    // 如果memberType是player，此项为persona的properties
    public Dictionary<string,string> PersonaProperties;
    // 如果memberType是player，此项为persona的头像地址
    public string IconUrl;
    // 成绩自定义属性
    public Dictionary<string, string> Properties;
}

12. 获取一个排行榜的历史版本列表

ListLeaderboardVersionsSDKResponse res = await PassportFeatureSDK.Leaderboard.ListLeaderboardVersions(leaderboardSlug);
Debug.Log(res.Total);
Debug.Log(res.Start);
Debug.Log(res.Count);
foreach (var config in res.HistoryConfigs)
{
    Debug.Log(config);
    Debug.Log(config.Tiers);
}

public class ListLeaderboardVersionsSDKResponse
{
    // 符合搜索条件的总数
    public uint Total;
    // 结果起始位置
    public uint Start;
    // 结果获取的数量
    public uint Count;
    // 查询结果
    public List<LeaderboardHistoryConfig> HistoryConfigs;
}

public class LeaderboardHistoryConfig
{
    // 排行榜的版本id
    public string VersionId;
    // 排行榜中的排名计算方式，Desc/Asc，分别表示降序或者升序
    public Leaderboard.SortOrder SortOrder;
    // 排行榜的成员属性，Player/Entity，分别表示玩家或者实体
    public Leaderboard.MemberType MemberType;
    // 成绩是否跨域，若为false则同一排行榜下不同realm的成绩分开排序
    public bool CrossRealm;
    // 是否使用榜中榜，以及bucketId的定义方式
    public Leaderboard.BucketStrategy BucketStrategy;
    // 小榜的最大大小
    public uint BucketSize;
    // 分等级的策略，Score/Rank/Percent，分别表示分等级的依据是成绩范围、排名、超过的玩家百分比
    public Leaderboard.TierStrategy TierStrategy;
    // 成绩等级策略
    public List<Tier> Tiers;
    // 创建时间（UTC）
    public Timestamp CreatedAt;
    // 创建用户
    public string CreatedBy;
    // 最后修改时间（UTC）
    public Timestamp UpdatedAt;
    // 最后修改用户
    public string UpdatedBy;
    // 站内信模版SlugName
    public string InboxTemplateSlugName;
    // 奖励结算方式
    public Leaderboard.RewardStrategy RewardStrategy;
    // 奖励规则
    public List<RewardRuleExpanded> RewardRules;
}

4. 附录

核心类和接口

namespace Unity.Passport.Runtime
{
    public partial class PassportFeatureSDK
    {
        public class Leaderboard
        {
            // 获取所有排行榜的配置信息
            // start: 查询起始位置 (按排名升序排列)，默认为0
            // count: 查询获取的数量，默认为10，最大为50
            // displayName: 排行榜名称，模糊搜索
            public static async Task<ListLeaderboardsResponse> GetLeaderboards(uint start=0, uint count=10, string displayName = null)

            // 更新排行榜玩家分数
            // leaderboardSlugName: 排行榜唯一标识
            // score: 需要更新的成绩数值，如20，将根据排行榜配置中的「成绩更新策略」和此数值来更新玩家在排行榜的成绩
            // properties: 成绩自定义属性，大小默认限制为0.5KB
            public static async Task<UpdateScoreResponse> UpdateScore(string leaderboardSlugName, double score, Dictionary<string, string> properties = null){}

            // 查询玩家排行榜成绩
            // leaderboardSlugName: 排行榜唯一标识
            // tierName: 需要查询的等级名称
            // includeStatistics: 可以在当前排行榜查询的同时获取每个member在其他排行榜中的成绩，此项为其他排行榜的leaderboardSlugName列表
            // start: 查询起始位置 (按排名升序排列)，默认为0
            // count: 查询获取的数量，默认为10，最大为50
            public static async Task<ListLeaderboardScoresResponse> ListLeaderboardScores(string leaderboardSlugName, string tierName = null,
            string[] includeStatistics = null, uint start=0, uint count=10){}

            // 查询自己及附近玩家成绩
            // leaderboardSlugName: 排行榜唯一标识
            // range: 带range查询某个成员附近的成员成绩，例如range=5，就查询该成员前5个+自己+后5个成员的所有成绩
            // range最大值为100，结果有多个成绩的情况下response中默认按排名升序排列，默认为0即查询自己的成绩
            public static async Task<GetMemberScoreResponse> GetScore(string leaderboardSlugName, uint range = 0){}

            // 查询自己所属bucket(榜中榜)成绩
            // start: 查询起始位置 (按排名升序排列)，默认为0
            // count: 查询获取的数量，默认为10，最大为50
            public static async Task<ListMemberScoresInBucketResponse> GetBucket(string leaderboardSlugName, uint start=0, uint count=10){}

            // 用户自定义榜中榜时，更新排行榜成员分数（需指定bucketId）
            // leaderboardSlugName: 排行榜唯一标识
            // score: 成绩数值，如20
            // bucketId: 用户自定义的榜中榜Id
            // properties: 成绩自定义属性，大小默认限制为0.5KB
            public static async Task<UpdateScoreResponse> UpdateScoreWithBucketId(string leaderboardSlugName, double score, string bucketId, Dictionary<string, string> properties = null){}

            // 获取某个排行榜的配置信息
            // leaderboardSlugName: 排行榜唯一标识
            public static async Task<GetLeaderboardResponse> GetLeaderboard(string leaderboardSlugName){}

            // 获取所有好友在某一个排行榜中的成绩信息
            // leaderboardSlugName: 排行榜唯一标识
            public static async Task<GetFriendsLeaderboardResponse> GetFriendsLeaderboard(string leaderboardSlugName){}

            // 查询历史排行榜中玩家的成绩
            // leaderboardSlugName: 排行榜唯一标识
            // versionId: 排行榜版本ID
            public static async Task<GetMemberHistoryScoreResponse> GetMemberHistoryScore(string leaderboardSlugName, string versionId){}

            // 更新自定义成员排行榜成员分数
            // leaderboardSlugName: 排行榜唯一标识
            // memberId: 需要更新成绩的自定义成员成员ID
            // score: 成员成绩数值，如20，将根据排行榜配置中的「成绩更新策略」和此数值来更新自定义成员在排行榜的成绩
            // bucketId: 用户自定义的榜中榜Id
            // properties: 成绩自定义属性，大小默认限制为0.5KB
            public static async Task<UpdateScoreResponse> UpdateEntityScore(string leaderboardSlugName, string memberId, double score, string bucketId = null, Dictionary<string, string> properties = null){}

            // 获取自定义成员排行榜某个历史版本中的成绩
            // leaderboardSlugName: 排行榜唯一标识
            // versionId: 排行榜版本ID
            // entityMemberId: 需要搜索的自定义成员memberId
            public static async Task<ListHistoryScoreSDKResponse> GetEntityHistoryScore(string leaderboardSlugName, string versionId, string entityMemberId){}

            // 获取一个排行榜的历史版本列表
            // leaderboardSlugName: 排行榜唯一标识
            // start: 查询起始位置 (按排名升序排列)，默认为0
            // count: 查询获取的数量，默认为10，最大为50
            // versionId: 排行榜版本ID，可选
            public static async Task<ListLeaderboardVersionsSDKResponse> ListLeaderboardVersions(string leaderboardSlugName, uint start = 0, uint count = 10, string versionId = null){}
        }
    }
}

排行榜接入指南

排行榜接入指南

1. 功能配置与管理

基础配置

重置管理

分级管理

奖励

2. 常用排行榜配置示例

玩家最高分数排行榜（带分级管理）

带有榜中榜的成绩排行榜

各省份通关人数排行榜

3. 在 Unity 中接入 SDK

1. 获取排行榜列表

2. 更新排行榜玩家分数

3. 查询排行榜成绩

4. 查询自己及附近玩家成绩

5. 查询自己所属 bucket(榜中榜) 的全部成绩

6. 用户自定义榜中榜时，更新排行榜成员分数（需指定 bucketId）

7. 获取某个排行榜的配置信息

8. 获取所有好友在某一个排行榜中的成绩信息

9. 查询历史排行榜中玩家的成绩

10. 更新自定义成员排行榜成员分数

11. 获取自定义成员排行榜某个历史版本中的成绩

12. 获取一个排行榜的历史版本列表

4. 附录

核心类和接口

服务端 API

客户端 API

错误码