排行榜开发指南 · 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 排名——中的类似，不再详述。

安装 SDK​

Leaderboard​

Statistic​

Ranking​

成绩管理​

用户成绩管理​

用户成绩更新​

用户成绩查询​

用户成绩删除​

Object 成绩管理​

Object 成绩查询​

Entity 成绩管理​

Entity 成绩查询​

获取排行榜结果​

获取用户排行榜结果​

获取指定区间的用户排名​

获取指定用户附近的排名​

获取 Object 排行榜结果​

获取指定区间的 Object 排名​

获取指定 Object 附近的排名​

获取 Entity 排行榜结果​

获取指定区间的 Entity 排名​

获取指定 Entity 附近的排名​