排行榜服务总览

排行榜是每款游戏的必备功能，通过 LeanCloud 可以非常简单的实现排行榜，帮助您迅速提升用户活跃。

功能简介

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

功能详解

每一个排行榜由名称（statisticName）及成员的成绩（statisticValue）组成，并可以设置排序、更新策略及重置周期。我们推荐您在控制台提前创建排行榜，客户端更新分数时，通过指定排行榜名称（statisticName）来更新分数。

名称

statisticName 是排行榜唯一名称，不可修改，只能包含字母、数字、下划线，并且以字母或数字开头。

排行榜成员

memberType 是排行榜的成员类型，不同的成员类型会对应不同的成员 id，支持三种类型的成员：

• user 类型：填入的值为 _User。排行榜成员对应 _User 表中某一个用户数据的的 objectId。
• object 类型：填入的值为数据存储中除了 _User 之外的 class 名称，排行榜成员对应表中某一个对象数据的 objectId。例如你有一个 Weapon 表，可以在 memberType 中填入 Weapon ，这样排行榜成员会对应该表中的 objectId。
• entity 类型：填入的值为 _Entity。排行榜成员是自己指定的字符串数据，只能包含字母、数字、下划线，并且以字母或数字开头。

在查询成员成绩或排行榜结果的时候，可以使用相关参数方便直接地获取 user 及 object 的更多数据。

成绩

statisticValue 是用户在客户端产生的成绩，可以是整数，也可以带有小数点。

排序策略

• descending：排名按分数由高到低排列，例如在《跳一跳》中，玩家的分数越大排名越高。
• ascending：则排名按分数由低到高排列，例如在某些竞速游戏中，完成任务的时间越短排名越高。

更新策略

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

• better：根据 order（排序策略） 来判断是否更新玩家的分数，总是保留玩家最好的成绩。
  • order 为 descending：只会更新比之前成绩更大的分数。例如当前玩家要更新的成绩为 100 ，排行榜中的成绩为 200，排行榜保留最大的分数 200。
  • order 为 ascending：只会更新比之前成绩更小的分数。例如当前玩家要更新的成绩为 1.2，排行榜中的成绩为 1.5，排行榜会将数据更新为 1.2。
• last：每次玩家更新分数时都会覆盖掉服务端之前的数据，即总是保留玩家最新的成绩。
• sum：每次玩家更新分数时都会将本次分数累加到当前的的总分数。

数据重置

重置时间及周期

排行榜可以被重置，重置后线上所有数据清零。例如您可以每月开展赛季，赛季结束后所有数据清零，所有玩家重新开始比赛排名；也可以在发现当前比赛数据有失平衡时清零数据重新开始。从重置时间开始的一刻起，所有老数据被清理，客户端再发起的更新分数的请求将自动进入新版本的数据中。

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

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

重置时间

请注意，国内版和国际版重置时间不同，对于需要在凌晨 00:00 重置的周期（day/week/month）：

• 国内版应用会在北京时间 00:00 重置。
• 国际版应用会在 UTC 标准时间 00:00 重置。

历史数据

查询

排行榜重置后，您可以通过 API 查询最新一个历史版本的数据，例如重置后当前版本为 3，那么版本为 2 的历史数据可以通过查询请求获取到，版本为 1 及 0 的数据查询会报错。

• 重置周期为 day/week/month 的排行榜，您可以在下一次重置之前随时查询历史数据。
• 重置设置为 never 的排行榜，从手动重置的一刻起，7 天内可以查询历史数据，超过 7 天后无法再查询。

归档

• 历史数据被重置后将会保存在 csv 文件中供您下载。
• 每个排行榜最多保存 60 个历史数据文件，超出后最老的版本文件会被删掉，因此请及时处理您的历史数据。

价格

价格请参考官网。

开始使用

JavaScript

• 快速入门：展示了如何快速接入排行榜功能。
• Demo ：通过一个 Demo 来展示排行榜功能。
• JavaScript 排行榜开发指南：对如何开发排行榜进行了详细介绍。

C#

• 快速入门：展示了如何快速接入排行榜功能。
• C# 排行榜开发指南：对如何开发排行榜进行了详细介绍。

Objective-C

• Objective-C 排行榜开发指南：对如何开发排行榜进行了详细介绍。

在线交流

为了能及时解答大家的疑问，进一步了解游戏开发者的需求和使用场景，我们建立了游戏开发群，欢迎各位游戏开发者加入。详情 >>>