排行榜开发指南 · 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:@{
    @"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 为要更新的成绩。你可以一次更新多个不同的成绩。

更新成绩需要用户登录，且用户只能更新自己的成绩。

用户成绩查询

你可以查询某 user 的在某些排行榜成绩：

[LCLeaderboard getStatisticsWithUserId:user.objectId
                        statisticNames:@[@"score", @"kills"]
                              callback:^(NSArray<LCLeaderboardStatistic *> * _Nullable statistics, NSError * _Nullable error) {
    if (statistics) {
        // statistics 是查询的成绩结果
    } else if (error) {
        // 处理错误
    }
}];

你也可以省略 statisticNames 选项用来查询某 user 的所有成绩：

[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) {
        // 处理错误
    }
}];

删除成绩需要用户登录，且用户只能删除自己的成绩。

Object 成绩管理

可以通过 SDK 查询 LCObject 的成绩。

Object 成绩查询

你可以查询某 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) {
        // 处理错误
    }
}];

Entity 成绩管理

可以通过 SDK 查询 entity 的成绩。

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 选项：

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
    }
}];

各参数的适用场景与用法与上文——获取指定区间的用户排名——中的类似，不再详述。

获取 Object 排行榜结果

可以通过 SDK 获取 LCObject 的排行榜结果。

获取指定区间的 Object 排名

获取排行榜结果最常见的使用场景是获取排名前 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 选项：

leaderboard.includeStatistics = @[@"kills"];

获取指定 Object 附近的排名

另一种常见的需求是获取某个 object 附近的排名：

[leaderboard getObjectResultsAroundObject:object.objectId
                                   option:nil
                                 callback:^(NSArray<LCLeaderboardRanking *> * _Nullable rankings, NSInteger count, NSError * _Nullable error) {
    if (error) {
        // 处理错误
    } else {
        // 处理 rankings 和 count
    }
}];

各参数的适用场景与用法与上文——获取指定区间的 Object 排名——中的类似，不再详述。

获取 Entity 排行榜结果

可以通过 SDK 获取 entity 的排行榜结果。

获取指定区间的 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 选项：

leaderboard.includeStatistics = @[@"kills"];

获取指定 Entity 附近的排名

另一种常见的需求是获取某个 entity 附近的排名：

[leaderboard getEntityResultsAroundEntity:entity
                                 callback:^(NSArray<LCLeaderboardRanking *> * _Nullable rankings, NSInteger count, NSError * _Nullable error) {
    if (error) {
        // 处理错误
    } else {
        // 处理 rankings 和 count
    }
}];

各参数的适用场景与用法与上文——获取指定区间的 Entity 排名——中的类似，不再详述。