排行榜是存储 SDK 中的一个模块,要在 Objective-C 运行环境中使用排行榜功能,需要安装存储 SDK,请参考《 Objective C SDK 配置指南》。
LCLeaderboard 类是对排行榜的抽象。LCLeaderboard 实例有以下属性:
LCLeaderboard
statisticName
NSString
limit
NSInteger
20
skip
0
includeStatistics
NSArray<NSString *>
Ranking
version
returnCount
BOOL
false
排行榜是对用户的成绩进行排名的结果。SDK 提供了一个 LCLeaderboardStatistic 类来表示成绩。LCLeaderboardStatistic 实例有以下属性:
LCLeaderboardStatistic
name
value
double
user
LCUser
object
LCObject
entity
排行榜排序的结果是一个数组,数组的成员是一个叫 LCLeaderboardRanking 的类:
LCLeaderboardRanking
rank
includedStatistics
NSArray<LCLeaderboardStatistic *>
可以通过 SDK 管理 user/object/entity 的成绩。
可以通过 SDK 更新、查询、删除 LCUser 的成绩。
当 user 完成了一局游戏后,你可以更新该 user 的成绩:
[LCLeaderboard updateCurrentUserStatistics:@{ @"score" : @3458, @"kills" : @28, } callback:^(NSArray<LCLeaderboardStatistic *> * _Nullable statistics, NSError * _Nullable error) { if (statistics) { // statistics 是更新后你的最好/最新成绩 } else if (error) { // 处理错误 } }];
+[LCLeaderboard updateCurrentUserStatistics:callback:] 方法的第一个参数是一个 NSDictionary 的对象,key 为要更新的 statisticName,value 为要更新的成绩。你可以一次更新多个不同的成绩。
+[LCLeaderboard updateCurrentUserStatistics:callback:]
NSDictionary
更新成绩需要用户登录,且用户只能更新自己的成绩。
你可以查询某 user 的在某些排行榜成绩:
[LCLeaderboard getStatisticsWithUserId:user.objectId statisticNames:@[@"score", @"kills"] callback:^(NSArray<LCLeaderboardStatistic *> * _Nullable statistics, NSError * _Nullable error) { if (statistics) { // statistics 是查询的成绩结果 } else if (error) { // 处理错误 } }];
你也可以省略 statisticNames 选项用来查询某 user 的所有成绩:
statisticNames
[LCLeaderboard getStatisticsWithUserId:user.objectId statisticNames:nil callback:^(NSArray<LCLeaderboardStatistic *> * _Nullable statistics, NSError * _Nullable error) { if (statistics) { // statistics 是查询的成绩结果 } else if (error) { // 处理错误 } }];
你还可以查询某个排行榜的一组 user 的成绩:
LCLeaderboard *leaderboard = [[LCLeaderboard alloc] initWithStatisticName:@"score"]; [leaderboard getStatisticsWithUserIds:@[user.objectId] callback:^(NSArray<LCLeaderboardStatistic *> * _Nullable statistics, NSError * _Nullable error) { if (statistics) { // statistics 是查询的成绩结果 } else if (error) { // 处理错误 } }];
你可以删除当前登录用户在某些排行榜的成绩:
[LCLeaderboard deleteCurrentUserStatistics:@[@"score", @"kills"] callback:^(BOOL succeeded, NSError * _Nullable error) { if (succeeded) { // 删除成功 } else if (error) { // 处理错误 } }];
删除成绩需要用户登录,且用户只能删除自己的成绩。
可以通过 SDK 查询 LCObject 的成绩。
你可以查询某 object 的在某些排行榜成绩:
[LCLeaderboard getStatisticsWithObjectId:object.objectId statisticNames:@[@"score", @"kills"] option:nil callback:^(NSArray<LCLeaderboardStatistic *> * _Nullable statistics, NSError * _Nullable error) { if (statistics) { // statistics 是查询的成绩结果 } else if (error) { // 处理错误 } }];
你也可以省略 statisticNames 选项用来查询某 object 的所有成绩:
[LCLeaderboard getStatisticsWithObjectId:object.objectId statisticNames:nil option:nil callback:^(NSArray<LCLeaderboardStatistic *> * _Nullable statistics, NSError * _Nullable error) { if (statistics) { // statistics 是查询的成绩结果 } else if (error) { // 处理错误 } }];
你还可以查询某个排行榜的一组 object 的成绩:
LCLeaderboard *leaderboard = [[LCLeaderboard alloc] initWithStatisticName:@"score"]; [leaderboard getStatisticsWithObjectIds:@[object.objectId] option:nil callback:^(NSArray<LCLeaderboardStatistic *> * _Nullable statistics, NSError * _Nullable error) { if (statistics) { // statistics 是查询的成绩结果 } else if (error) { // 处理错误 } }];
可以通过 SDK 查询 entity 的成绩。
你可以查询某 entity 的在某些排行榜成绩:
[LCLeaderboard getStatisticsWithEntity:entity statisticNames:@[@"score", @"kills"] callback:^(NSArray<LCLeaderboardStatistic *> * _Nullable statistics, NSError * _Nullable error) { if (statistics) { // statistics 是查询的成绩结果 } else if (error) { // 处理错误 } }];
你也可以省略 statisticNames 选项用来查询某 entity 的所有成绩:
[LCLeaderboard getStatisticsWithEntity:entity statisticNames:nil callback:^(NSArray<LCLeaderboardStatistic *> * _Nullable statistics, NSError * _Nullable error) { if (statistics) { // statistics 是查询的成绩结果 } else if (error) { // 处理错误 } }];
你还可以查询某个排行榜的一组 entity 的成绩:
LCLeaderboard *leaderboard = [[LCLeaderboard alloc] initWithStatisticName:@"score"]; [leaderboard getStatisticsWithEntities:@[entity] callback:^(NSArray<LCLeaderboardStatistic *> * _Nullable statistics, NSError * _Nullable error) { if (statistics) { // statistics 是查询的成绩结果 } else if (error) { // 处理错误 } }];
可以通过 SDK 获取 user/object/entity 的排行榜结果。
可以通过 SDK 获取 LCUser 的排行榜结果。
获取排行榜结果最常见的使用场景是获取排名前 N 的用户成绩:
LCLeaderboard *leaderboard = [[LCLeaderboard alloc] initWithStatisticName:@"world"]; leaderboard.limit = 10; leaderboard.skip = 0; [leaderboard getUserResultsWithOption:nil callback:^(NSArray<LCLeaderboardRanking *> * _Nullable rankings, NSInteger count, NSError * _Nullable error) { if (error) { // 处理错误 } else { // 处理 rankings 和 count } }];
默认情况下返回的排行榜结果中的 user 是一个只有 objectId 属性的 LCUser Pointer。如果想要在排行榜结果中显示用户名或者其他的用户属性(对应 _User 表中的属性),甚至一个 Pointer 属性的全部数据,那么需要使用 LCLeaderboardQueryOption 选项:
objectId
_User
LCLeaderboardQueryOption
LCLeaderboardQueryOption *option = [[LCLeaderboardQueryOption alloc] init]; option.selectKeys = @[@"username", @"objectPointer"]; option.includeKeys = @[@"objectPointer"]; LCLeaderboard *leaderboard = [[LCLeaderboard alloc] initWithStatisticName:@"world"]; [leaderboard getUserResultsWithOption:option callback:^(NSArray<LCLeaderboardRanking *> * _Nullable rankings, NSInteger count, NSError * _Nullable error) { if (error) { // 处理错误 } else { // 处理 rankings 和 count } }];
如果想要在排行榜结果中包含用户的其他成绩,可以使用 includeStatistics 选项:
leaderboard.includeStatistics = @[@"kills"];
另一种常见的需求是获取当前登录用户附近的排名:
[leaderboard getUserResultsAroundUser:user.objectId option:nil callback:^(NSArray<LCLeaderboardRanking *> * _Nullable rankings, NSInteger count, NSError * _Nullable error) { if (error) { // 处理错误 } else { // 处理 rankings 和 count } }];
各参数的适用场景与用法与上文——获取指定区间的用户排名——中的类似,不再详述。
可以通过 SDK 获取 LCObject 的排行榜结果。
获取排行榜结果最常见的使用场景是获取排名前 N 的 object 成绩:
LCLeaderboard *leaderboard = [[LCLeaderboard alloc] initWithStatisticName:@"world"]; leaderboard.limit = 10; leaderboard.skip = 0; [leaderboard getObjectResultsWithOption:nil callback:^(NSArray<LCLeaderboardRanking *> * _Nullable rankings, NSInteger count, NSError * _Nullable error) { if (error) { // 处理错误 } else { // 处理 rankings 和 count } }];
默认情况下返回的排行榜结果中的 object 是一个只有 objectId 属性的 LCObject Pointer。如果想要在排行榜结果中显示其它的属性(对应表中的属性),甚至一个 Pointer 属性的全部数据,那么需要使用 LCLeaderboardQueryOption 选项:
LCLeaderboardQueryOption *option = [[LCLeaderboardQueryOption alloc] init]; option.selectKeys = @[@"username", @"objectPointer"]; option.includeKeys = @[@"objectPointer"]; LCLeaderboard *leaderboard = [[LCLeaderboard alloc] initWithStatisticName:@"world"]; [leaderboard getObjectResultsWithOption:option callback:^(NSArray<LCLeaderboardRanking *> * _Nullable rankings, NSInteger count, NSError * _Nullable error) { if (error) { // 处理错误 } else { // 处理 rankings 和 count } }];
如果想要在排行榜结果中包含 object 的其他成绩,可以使用 includeStatistics 选项:
另一种常见的需求是获取某个 object 附近的排名:
[leaderboard getObjectResultsAroundObject:object.objectId option:nil callback:^(NSArray<LCLeaderboardRanking *> * _Nullable rankings, NSInteger count, NSError * _Nullable error) { if (error) { // 处理错误 } else { // 处理 rankings 和 count } }];
各参数的适用场景与用法与上文——获取指定区间的 Object 排名——中的类似,不再详述。
可以通过 SDK 获取 entity 的排行榜结果。
获取排行榜结果最常见的使用场景是获取排名前 N 的 entity 成绩:
LCLeaderboard *leaderboard = [[LCLeaderboard alloc] initWithStatisticName:@"world"]; leaderboard.limit = 10; leaderboard.skip = 0; [leaderboard getEntityResultsWithCallback:^(NSArray<LCLeaderboardRanking *> * _Nullable rankings, NSInteger count, NSError * _Nullable error) { if (error) { // 处理错误 } else { // 处理 rankings 和 count } }];
如果想要在排行榜结果中包含 entity 的其他成绩,可以使用 includeStatistics 选项:
另一种常见的需求是获取某个 entity 附近的排名:
[leaderboard getEntityResultsAroundEntity:entity callback:^(NSArray<LCLeaderboardRanking *> * _Nullable rankings, NSInteger count, NSError * _Nullable error) { if (error) { // 处理错误 } else { // 处理 rankings 和 count } }];
各参数的适用场景与用法与上文——获取指定区间的 Entity 排名——中的类似,不再详述。
排行榜开发指南 · Objective-C
安装 SDK
排行榜是存储 SDK 中的一个模块,要在 Objective-C 运行环境中使用排行榜功能,需要安装存储 SDK,请参考《 Objective C SDK 配置指南》。
Leaderboard
LCLeaderboard
类是对排行榜的抽象。LCLeaderboard
实例有以下属性:statisticName
NSString
limit
NSInteger
20
skip
NSInteger
limit
一起可以实现翻页,默认为0
includeStatistics
NSArray<NSString *>
Ranking
中需要包含的其他成绩version
NSInteger
0
returnCount
BOOL
false
Statistic
排行榜是对用户的成绩进行排名的结果。SDK 提供了一个
LCLeaderboardStatistic
类来表示成绩。LCLeaderboardStatistic
实例有以下属性:name
NSString
statisticName
version
NSInteger
value
double
user
LCUser
user
,则可通过此属性获取该LCUser
object
LCObject
object
,则可通过此属性获取该LCObject
entity
NSString
entity
,则可通过此属性获取该entity
Ranking
排行榜排序的结果是一个数组,数组的成员是一个叫
LCLeaderboardRanking
的类:statisticName
NSString
statisticName
rank
NSInteger
0
开始value
double
includedStatistics
NSArray<LCLeaderboardStatistic *>
user
/object
/entity
的其他成绩user
LCUser
user
,则可通过此属性获取该LCUser
object
LCObject
object
,则可通过此属性获取该LCObject
entity
NSString
entity
,则可通过此属性获取该entity
成绩管理
可以通过 SDK 管理
user
/object
/entity
的成绩。用户成绩管理
可以通过 SDK 更新、查询、删除
LCUser
的成绩。用户成绩更新
当
user
完成了一局游戏后,你可以更新该user
的成绩:+[LCLeaderboard updateCurrentUserStatistics:callback:]
方法的第一个参数是一个NSDictionary
的对象,key 为要更新的statisticName
,value 为要更新的成绩。你可以一次更新多个不同的成绩。更新成绩需要用户登录,且用户只能更新自己的成绩。
用户成绩查询
你可以查询某
user
的在某些排行榜成绩:你也可以省略
statisticNames
选项用来查询某user
的所有成绩:你还可以查询某个排行榜的一组
user
的成绩:用户成绩删除
你可以删除当前登录用户在某些排行榜的成绩:
删除成绩需要用户登录,且用户只能删除自己的成绩。
Object 成绩管理
可以通过 SDK 查询
LCObject
的成绩。Object 成绩查询
你可以查询某
object
的在某些排行榜成绩:你也可以省略
statisticNames
选项用来查询某object
的所有成绩:你还可以查询某个排行榜的一组
object
的成绩:Entity 成绩管理
可以通过 SDK 查询
entity
的成绩。Entity 成绩查询
你可以查询某
entity
的在某些排行榜成绩:你也可以省略
statisticNames
选项用来查询某entity
的所有成绩:你还可以查询某个排行榜的一组
entity
的成绩:获取排行榜结果
可以通过 SDK 获取
user
/object
/entity
的排行榜结果。获取用户排行榜结果
可以通过 SDK 获取
LCUser
的排行榜结果。获取指定区间的用户排名
获取排行榜结果最常见的使用场景是获取排名前 N 的用户成绩:
默认情况下返回的排行榜结果中的
user
是一个只有objectId
属性的LCUser
Pointer。如果想要在排行榜结果中显示用户名或者其他的用户属性(对应_User
表中的属性),甚至一个 Pointer 属性的全部数据,那么需要使用LCLeaderboardQueryOption
选项:如果想要在排行榜结果中包含用户的其他成绩,可以使用
includeStatistics
选项:获取指定用户附近的排名
另一种常见的需求是获取当前登录用户附近的排名:
各参数的适用场景与用法与上文——获取指定区间的用户排名——中的类似,不再详述。
获取 Object 排行榜结果
可以通过 SDK 获取
LCObject
的排行榜结果。获取指定区间的 Object 排名
获取排行榜结果最常见的使用场景是获取排名前 N 的
object
成绩:默认情况下返回的排行榜结果中的
object
是一个只有objectId
属性的LCObject
Pointer。如果想要在排行榜结果中显示其它的属性(对应表中的属性),甚至一个 Pointer 属性的全部数据,那么需要使用LCLeaderboardQueryOption
选项:如果想要在排行榜结果中包含
object
的其他成绩,可以使用includeStatistics
选项:获取指定 Object 附近的排名
另一种常见的需求是获取某个
object
附近的排名:各参数的适用场景与用法与上文——获取指定区间的 Object 排名——中的类似,不再详述。
获取 Entity 排行榜结果
可以通过 SDK 获取
entity
的排行榜结果。获取指定区间的 Entity 排名
获取排行榜结果最常见的使用场景是获取排名前 N 的
entity
成绩:如果想要在排行榜结果中包含
entity
的其他成绩,可以使用includeStatistics
选项:获取指定 Entity 附近的排名
另一种常见的需求是获取某个
entity
附近的排名:各参数的适用场景与用法与上文——获取指定区间的 Entity 排名——中的类似,不再详述。