Skip to main content
Version: v3

排行榜功能介绍

tip

在游戏中设立排行榜功能，可以推动玩家之间的趣味性竞争，从而帮助提升游戏的玩家活跃度。

排行榜服务提供的功能包括：

  • **自动计算排名：**排行榜中玩家数据更新时，系统自动重新计算排名。
  • **获取前排数据：**获取当前排行榜中排名前 N 个玩家数据。
  • **获取当前玩家的排名：**即使当前玩家没有名列前茅，也可以获取他在排行中的具体名次，以此了解到当前玩家和前排玩家的差距。
  • **获取当前玩家附近排名的玩家：**例如为当前玩家寻找水平相当的对手或好友。
  • **数据重置：**支持自动定期重置或手动重置数据，比如在一个赛季结束之时或在指定天、周、月后自动重置排行榜，或是在应用测试阶段、应用数据出现误差的情况下进行手动重置。
  • **简便的数据更新模式：**提供三种分数更新模式，better 模式会保留玩家的最好成绩，last 会保留玩家的最新成绩，sum 会累加当前成绩。

创建排行榜​

note

我们推荐在 TapTap 开发者中心的排行榜控制台提前创建排行榜，客户端指定相应排行榜名称 statisticName 即可更新成绩。

每一个排行榜由名称 statisticName 及成员的成绩 statisticValue 组成，并可以设置排序、更新策略及重置周期。

名称​

statisticName 是排行榜名称，不可和应用下的其他排行榜重复，不可修改，只能包含字母、数字、下划线，并且以字母开头。

成员类型​

memberType 是排行榜的成员类型，目前支持三种类型的成员：

  • user 类型：值为 _User。排行榜成员对应内建账户系统（_User 表）中某一个用户的 objectId。这是唯一可以在客户端更新成绩（仅限玩家本人的成绩）的排行榜类型。
  • object 类型：值为数据存储中除了 _User 之外的 class 名称，排行榜成员对应表中一个对象的 objectId。例如你有一个 Weapon 表，可以在 memberType 中填入 Weapon，这样可以构建一个武器排行榜。
  • entity 类型：填入的值为 _Entity。排行榜成员是开发者自行指定的字符串数据，只能包含字母、数字、下划线。

注意：

  • 查询排行榜时，可以指定相关参数直接获取 user 及 object 的更多数据。
  • object 和 entity 类型的排行榜需要使用超级权限在服务端才能更新。
  • 在控制台勾选「只允许使用 Master Key 更新分数」后（默认未勾选），user 类型的排行榜同样需要使用超级权限在服务端更新。从反作弊的角度出发，建议勾选此项。

上传成绩​

statisticValue 是用户在客户端产生的成绩（数字），比如得分、击杀数、用时。

设置排序策略​

  • descending：降序，排名按成绩由高到低排列，在许多游戏中，玩家得分越高，排名越高。
  • ascending：升序，排名按成绩由低到高排列，例如在某些竞速游戏中，完成任务的时间越短排名越高。

更新策略​

updateStrategy 代表成绩的更新策略，一个排行榜可以选择下列更新策略之一：

  • better：保留玩家最好的成绩。也就是说，排序策略为降序时，成绩高于之前成绩时更新，排序策略为升序时，成绩低于之前成绩时更新。
  • last：保留玩家最新的成绩。也就是说，每次玩家更新成绩时都会覆盖掉之前的成绩。
  • sum：累加玩家的成绩。每次更新成绩时都会将本次成绩累加到当前的总成绩。

数据重置​

排行榜可以被重置，重置后线上所有数据清零，例如在赛季结束后清零所有数据。从重置时间开始的一刻起，所有老数据会被清理，排行版的版本号（Version）会更新（加一），客户端再发起的更新分数的请求将自动进入新版本的数据中。

versionChangeInterval 代表数据重置周期，共有以下选项：

  • day：每天凌晨 00:00 重置。
  • week：每周一凌晨 00:00 重置。
  • month：每月 1 日凌晨 00:00 重置。
  • never：不自动重置，在必要的时候手动重置。

查询历史数据​

在排行榜重置后，客户端通过 SDK 只能查询当前版本及前一版本的数据，更前版本的数据无法查询。 如果在排行榜控制台未勾选「保留前一版本」（默认未勾选），则排行榜重置后，客户端通过 SDK 只能查询当前版本的数据。 重置周期为 never 的排行榜还有一条额外限制，手动重置那一刻起 7 天内可以查询前一版本的数据，超过 7 天后无法查询历史数据。 例如：

  • 假设排行榜重置周期为 month，当前为 3 月，3 月 1 日排行榜重置后当前版本为 3，那么可以查询版本为 2 （2 月份）的历史数据，无法查询版本为 1 （1 月份）的数据。
  • 假设排行榜重置周期为 never，现在手动重置排行榜，排行版版本变为 3，那么 7 日内可以查询版本为 2 的历史数据，超过 7 日后无法查询历史数据。

虽然更前版本的数据无法通过 SDK 查询，但可以通过 REST API 获取归档的 CSV 文件。 不过，每个排行榜最多保存 60 个历史数据归档，超出后最老的版本会被删除。 因此，如需长期保存，请注意及时下载归档后另行备份。