排行榜

在游戏页面上，您可以显示个性化排行榜（排名表），展示最佳玩家的成绩以及已授权用户在排名中的位置。

要使排行榜请求正常工作，请满足以下条件：

在游戏代码中连接并配置 SDK，使其对象可通过变量 ysdk 访问；
在开发人员控制台中创建排行榜。

注意

如果开发人员控制台中没有Technical leaderboard name字段中相应名称的排行榜，请求将返回404错误。

初始化

要调用排行榜方法，请直接访问 ysdk.leaderboards。

注意

使用 ysdk.getLeaderboards() 方法初始化 lb 对象的方式已弃用。

旧方法

 1const ysdk = await YaGames.init();
 2
 3const lb = await ysdk.getLeaderboards();
 4
 5// 排行榜方法调用的新旧方式对应关系：
 6// lb.getLeaderboardDescription() → ysdk.leaderboards.getDescription()
 7// lb.setLeaderboardScore() → ysdk.leaderboards.setScore()
 8// lb.getLeaderboardPlayerEntry() → ysdk.leaderboards.getPlayerEntry()
 9// lb.getLeaderboardEntries() → ysdk.leaderboards.getEntries()

排行榜描述

要按名称获取排行榜描述，请使用 ysdk.leaderboards.getDescription() 方法。

方法签名：

 1interface ILeaderboardDescription {
 2    appID: string;
 3    default: boolean;
 4    description: {
 5        invert_sort_order: boolean;
 6        score_format: {
 7            options: {
 8                decimal_offset: number;
 9            };
10            type: 'numeric' | 'time';
11        };
12        sort_order: string;
13    };
14    name: string;
15    title: Record<Locale, string>;
16}
17
18function getDescription(
19    leaderboardName: string
20): Promise<ILeaderboardDescription> {}

接受排行榜技术名称 leaderboardName 作为唯一参数。返回包含排行榜描述的对象，包括以下字段：

参数	类型	描述
`appID`	`string`	应用程序标识符。
`default`	`boolean`	如果为 `true`，则该排行榜为主排行榜。
`invert_sort_order`	`boolean`	排序方向： `false` — 降序（得分最高的用户排在前面）。 `true` — 升序（得分最低的用户排在前面）。
`sort_order`	`string`	字符串格式的排序方向： `'DESC'` — 降序。 `'ASC'` — 升序。
`decimal_offset`	`number`	分数的小数部分大小。例如，当 `decimal_offset: 2` 时，数字 1234 将显示为 12.34。
`type`	`'numeric'` \| `'time'`	排行榜结果类型。可用值：`numeric`（数字）、`time`（毫秒）。
`name`	`string`	在控制台的 Technical leaderboard name 字段中指定的排行榜名称。
`title`	`Record<Locale, string>`	本地化名称列表。可用的语言代码列在语言与域名页面上。

示例

1const ysdk = await YaGames.init();
2
3const lb = await ysdk.leaderboards.getDescription('leaderboard2021');
4
5console.log(lb);

新成绩

注意

该请求仅适用于已授权用户。如何检查授权状态并调用登录对话框，请参见用户登录部分。

在发送请求之前，使用 ysdk.isAvailableMethod('leaderboards.setScore') 检查方法的可用性。该方法返回 Promise<Boolean>。

为了确保所有用户的成绩都能保存，无论是否授权，建议在应用程序代码中自行实现自定义排行榜。技术选择不受限制。

要为玩家设置新成绩，请使用 ysdk.leaderboards.setScore() 方法。

方法签名：

1function setScore(
2    leaderboardName: string,
3    score: number,
4    extraData?: string
5): Promise<void> {}

接受三个参数：

参数	类型	描述
`leaderboardName`	`string`	在控制台的 Technical leaderboard name 字段中指定的排行榜名称。
`score`	`number`	结果值。不能为负数，最大值仅受 JavaScript 逻辑限制。如果排行榜类型为 `time`，则该值必须以毫秒为单位传递。
`extraData`	`string`	用户描述。可选参数。

备注

请求发送频率不能超过每秒 1 次，否则将被拒绝并返回错误。

示例

1const ysdk = await YaGames.init();
2
3await ysdk.leaderboards.setScore('leaderboard2021', 120);
4
5await ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');

获取排名

注意

该请求仅适用于已授权用户。如何检查授权状态并调用登录对话框，请参见用户登录部分。

在发送请求之前，使用 ysdk.isAvailableMethod('leaderboards.getPlayerEntry') 检查方法的可用性。该方法返回 Promise<Boolean>。

为了确保所有用户的成绩都能保存，无论是否授权，建议在应用程序代码中自行实现自定义排行榜。技术选择不受限制。

要获取用户排名，请使用 ysdk.leaderboards.getPlayerEntry() 方法。

方法签名：

 1interface ILeaderboardEntry {
 2    extraData: string;
 3    rank: number;
 4    score: number;
 5    player: {
 6        publicName: string;
 7        uniqueID: string;
 8        getAvatarSrc: (size?: 'small' | 'medium' | 'large') => string;
 9        getAvatarSrcSet: (size?: 'small' | 'medium' | 'large') => string;
10    }
11}
12
13function getPlayerEntry(
14    leaderboardName: string
15): Promise<ILeaderboardEntry> {}

接受排行榜技术名称 leaderboardName 作为唯一参数。返回包含用户排名的对象，包括以下字段：

参数	类型	描述
`score`	`number`	结果值。
`rank`	`number`	用户在排行榜中的位置。
`extraData`	`string`	用户描述。
`publicName`	`string`	用户名。
`uniqueID`	`string`	用户的唯一标识符
`getAvatarSrc`	`(size?: TSize) => string`	返回指定大小的用户头像 URL。`size` 的可用值：`small`、`medium`、`large`。
`getAvatarSrcSet`	`(size?: TSize) => string`	返回适用于 Retina 显示屏的用户头像 srcset。`size` 的可用值：`small`、`medium`、`large`。

备注

请求发送频率不能超过 5 分钟内 60 次，否则将被拒绝并返回错误。

示例

 1const ysdk = await YaGames.init();
 2
 3try {
 4    const res = await ysdk.leaderboards.getPlayerEntry('leaderboard2021');
 5
 6    console.log(res);
 7} catch (err) {
 8    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
 9        // 当玩家在排行榜中没有记录时触发。
10    }
11}

排行榜记录

要显示用户排名，请使用 ysdk.leaderboards.getEntries() 方法。

方法签名：

 1interface ILeaderboardEntries {
 2    leaderboard: ILeaderboardDescription;
 3    ranges: {
 4        start: number;
 5        size: number;
 6    }[];
 7    userRank: number;
 8    entries: ILeaderboardEntry[];
 9}
10
11function getEntries(
12    leaderboardName: string,
13    options: {
14        includeUser?: boolean;
15        quantityAround?: number;
16        quantityTop?: number;
17    }
18): Promise<ILeaderboardEntries> {}

接受排行榜技术名称 leaderboardName 和可选参数 options：

选项	类型	描述
`includeUser`	`boolean`	确定是否在响应中包含已授权用户： `true` — 包含在响应中。 `false`（默认）— 不包含。
`quantityAround`	`number`	需要返回的排行榜中用户上下的记录数量。最小值为 1，最大值为 10。默认返回 5。
`quantityTop`	`number`	排行榜顶部的记录数量。最小值为 1，最大值为 20。默认返回 5。

返回包含用户排名的对象 Promise<ILeaderboardEntries>，包括以下字段：

参数	类型	描述
`leaderboard`	`ILeaderboardDescription`	排行榜描述
`ranges`	`object[]`	响应中的位置区间。
`start`	`number`	排名中的位置。从零开始计数，因此第 1 名被视为第零个元素。
`size`	`number`	请求的记录数量。如果数据不足，可能与响应不符。
`userRank`	`number`	用户在排名中的位置。如果不存在，或者是不包含用户的顶部请求，则等于 0。
`entries`	`ILeaderboardEntry[]`	排名记录数组。记录与获取排名方法返回的值相同。

备注

请求发送频率不能超过 5 分钟内 20 次，否则将被拒绝并返回错误。

示例

 1const ysdk = await YaGames.init();
 2
 3// 获取前 10 名玩家和用户附近的 3 条记录。
 4const entries = await ysdk.leaderboards.getEntries('leaderboard2021', {
 5    quantityTop: 10,
 6    includeUser: true,
 7    quantityAround: 3
 8});
 9
10console.log(entries);

方法限制

方法	描述	限制	用户授权
`ysdk.leaderboards.setScore()`	设置玩家的新结果	每秒 1 次请求	必需
`ysdk.leaderboards.getPlayerEntry()`	显示单个用户的排名	每 5 分钟 60 次请求	必需
`ysdk.leaderboards.getEntries()`	获取多个用户的排名	每 5 分钟 20 次请求	可选

其他请求的限制：5 分钟内 20 次请求。

问题解决

提示

使用 ysdk.isAvailableMethod() 和 ysdk.leaderboards.setScore() 方法组合时，未授权用户不会出现在排行榜中，也看不到自己的进度。为了确保所有玩家的成绩都能保存，建议在应用程序代码中创建自定义排行榜。技术选择不受限制。

Object already exists

尝试使用旧名称创建新排行榜时会出现此错误。请输入以前未使用过的名称。

用户已隐藏

如果玩家不允许使用其头像和名称，则会显示"用户已隐藏"。对用户数据的访问取决于其个人资料中的设置。详见初始化部分。

错误 404

如果调用排行榜 SDK 方法时出现 404 错误，请检查开发人员控制台中是否创建了 Technical leaderboard name 字段中具有相应名称的排行榜。

备注

技术支持团队将协助您将已完成的游戏发布到 Yandex 游戏平台。关于开发和测试方面的具体问题，其他开发人员将在Discord 频道中进行回答。

如果您遇到 Yandex Games SDK 方面的问题或有其他问题想要咨询，请联系支持部门：

写入聊天信息

这篇文章是否有用？

应用内购买

异步多人游戏