跳到主要内容
版本:v3

排行榜功能介绍

提示

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

TapSDK 排行榜为你提供更多功能,包括:

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

创建排行榜

备注

我们推荐在 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 个历史数据归档,超出后最老的版本会被删除。 因此,如需长期保存,请注意及时下载归档后另行备份。