排行榜
您可以在游戏页面上显示个性化的排行榜，展示顶级玩家的成绩以及登录用户的排名。
要让以下请求生效，请确保：
注意
如果开发者仪表板中的技术排行榜名称字段中没有该名称的排行榜，请求将返回 404 错误。
初始化
如需直接调用排行榜方法，请访问 ysdk.leaderboards。
注意
通过 ysdk.getLeaderboards() 方法初始化 lb 对象的方式已弃用。
旧方法
var lb;
ysdk.getLeaderboards()
.then(_lb => lb = _lb);
// 通过旧方式调用排行榜方法：
// lb.getLeaderboardDescription() → ysdk.leaderboards.getDescription()
// lb.setLeaderboardScore() → ysdk.leaderboards.setScore()
// lb.getLeaderboardPlayerEntry() → ysdk.leaderboards.getPlayerEntry()
// lb.getLeaderboardEntries() → ysdk.leaderboards.getEntries()
排行榜描述
要通过名称获取排行榜的描述，请使用 ysdk.leaderboards.getDescription()：
getDescription(
leaderboardName: string
)
|
参数 |
描述 |
|
|
排行榜名称。 |
ysdk.leaderboards.getDescription('leaderboard2021')
.then(res => console.log(res));
const work = async () => {
const res = await ysdk.leaderboards.getDescription('leaderboard2021');
console.log(res);
}
work();
响应格式
{
appID: string,
default: boolean,
description: {
invert_sort_order: boolean,
score_format: {
options: {
decimal_offset: integer
},
type: string
}
},
name: string,
title: {
en: string,
ru: string
}
}
|
参数 |
描述 |
|
|
应用 ID。 |
|
|
如果为 |
|
|
排列顺序：
|
|
|
得分偏移量。例如，当设置为 |
|
|
排行榜结果类型。可用参数： |
|
|
排行榜名称。 |
|
|
本地化名称。合法数组参数： |
最新得分
注意
请求仅适用于已授权用户。如有需要，请使用授权。
要检查用户是否有权访问某个方法，您可以使用 ysdk.isAvailableMethod('leaderboards.setScore') 方法，该方法返回一个 Promise<Boolean>，逻辑值表示方法是否可用。
为了确保结果对所有用户进行保存，无论其是否已授权，建议在应用程序代码中自定义设置排行榜。技术选择不受限制。
要为玩家设置最新得分，请使用 ysdk.leaderboards.setScore()：
setScore(
leaderboardName: string,
score: number,
extraData?: string
)
|
参数 |
描述 |
|
|
排行榜名称。 |
|
|
得分。只接受 |
|
|
用户描述。可选。 |
备注
请求的发送频率不能超过每秒一次。否则，请求会被拒绝并引发错误。
// 不包含 extraData
ysdk.leaderboards.setScore('leaderboard2021', 120);
// 包含 extraData
ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');
const work = async () => {
// 不包含 extraData
await ysdk.leaderboards.setScore('leaderboard2021', 120);
// 包含 extraData
await ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');
}
work();
获取排名
注意
请求仅供授权用户使用。必要时，请使用授权。
要检查用户对该方法的可用性，您可以使用ysdk.isAvailableMethod('leaderboards.getPlayerEntry')方法，它返回一个Promise<Boolean>，逻辑值表示方法的可用性。
为了确保结果被保存并对所有用户可见，无论其是否已授权，建议在应用程序代码中自行设置自定义排行榜。技术选择并无限制。
要获取用户排名，请使用 ysdk.leaderboards.getPlayerEntry()：
getPlayerEntry(
leaderboardName: string
)
|
参数 |
描述 |
|
|
排行榜名称。 |
备注
每5分钟最多发送60次请求。否则请求将被拒绝并显示错误信息。
ysdk.leaderboards.getPlayerEntry('leaderboard2021')
.then(res => console.log(res))
.catch(err => {
if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
// 在排行榜不包含玩家条目的情况下触发
}
});
const work = async () => {
try {
const res = await ysdk.leaderboards.getPlayerEntry('leaderboard2021');
console.log(res);
} catch (err) {
if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
// 在排行榜不包含玩家条目的情况下触发
}
}
}
work();
响应格式
{
score: integer,
extraData: string,
rank: integer,
player: {
getAvatarSrc: (size: string) => string,
getAvatarSrcSet: (size: string) => string,
lang: string,
publicName: string,
scopePermissions: {
avatar: string,
public_name: string
},
uniqueID: string,
},
formattedScore: string
}
|
参数 |
描述 |
|
|
得分。只接受 |
|
|
用户描述。可选。 |
|
|
返回用户头像的 URL。 |
|
|
返回适合 Retina 显示屏的用户头像的 srcset。 |
排行榜条目
要显示用户排名，请使用 ysdk.leaderboards.getEntries()：
getEntries(
leaderboardName: string,
{
includeUser: boolean,
quantityAround: integer,
quantityTop: integer
}
)
|
参数 |
描述 |
|
|
排行榜名称。 |
|
|
定义是否在响应中包括登录用户：
|
|
|
返回在排行榜中低于和高于该用户排名的条目数。最小值为 1，最大值为 10。默认值为 5。 |
|
|
排行榜前列的条目数。最小值为 1，最大值为 20。默认值为 5。 |
备注
每5分钟最多可发送请求20次。否则请求将被拒绝并出现错误。
// 使用所有默认值
ysdk.leaderboards.getEntries('leaderboard2021')
.then(res => console.log(res));
// 返回排名前 10 的条目
ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10 })
.then(res => console.log(res));
// 返回排名前 10 的条目和排在用户前后的 3 个条目
ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 })
.then(res => console.log(res));
const work = async () => {
let res;
// 使用所有默认值
res = await ysdk.leaderboards.getEntries('leaderboard2021');
console.log(res);
// 获取排名前 10 的条目
res = await ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10 });
console.log(res);
// 返回排名前 10 的条目和排在用户前后的 3 个条目
res = await ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 });
console.log(res);
}
work();
响应格式
{
leaderboard: {
...
},
ranges: [
{
start: integer,
size: integer
}
],
userRank: integer,
entries: [
{
score: integer,
extraData: string,
rank: integer,
player: {
getAvatarSrc: (size: string) => string,
getAvatarSrcSet: (size: string) => string,
lang: string,
publicName: string,
scopePermissions: {
avatar: string,
public_name: string
},
uniqueID: string,
},
formattedScore: string
},
...
]
}
|
参数 |
描述 |
|
|
|
|
|
响应中的排名范围。 |
|
|
排名中的位置。计数从 0 开始，因此将第 1 名视为第 0 个元素。 |
|
|
请求的条目数。如果没有足够的数据，则返回的数量可能不是所请求的数量。 |
|
|
用户的排名。如果没有排名，或者请求是针对表中排名前列的用户而不包括该用户，则返回 0。 |
|
|
请求的条目。 |
|
|
得分。只接受 |
|
|
用户描述。可选。 |
|
|
返回用户头像的 URL。 |
|
|
返回适合 Retina 显示屏的用户头像的 srcset。 |
方法限制
|
方法 |
描述 |
限制 |
用户授权 |
|
|
每秒1次请求 |
必需 |
|
|
|
5分钟内每秒最多60次请求 |
必需 |
|
|
|
5分钟内每5分钟最多20次请求 |
可选 |
其他请求的限制：5分钟内最多20次请求。
与排行榜相关的问题
提示
当使用 ysdk.isAvailableMethod() 和 ysdk.leaderboards.setScore() 方法组合时，未经授权的用户不会出现在排行榜中，也看不到自己的进度。我们建议在代码中创建一个单独的排行榜表，记录任何用户的成绩，并向所有用户显示其结果。您可以自行在应用程序中创建自定义排行榜，技术选择没有限制。
对象已存在
尝试使用已存在的排行榜名称创建新排行榜时会出现此错误。请使用之前未使用过的名称。
用户已隐藏
如果玩家未授权使用其头像和名称，则会显示"用户已隐藏"字样。访问用户数据取决于其个人资料中的设置。详见初始化章节。
错误404
尝试调用排行榜SDK方法时出现404错误，请检查开发者控制台中 Technical leaderboard name 字段中是否存在相应名称的排行榜。
备注
技术支持团队将协助您将已完成的游戏发布到 Yandex 游戏平台。关于开发和测试方面的具体问题，其他开发人员将在Discord 频道中进行回答。
如果您遇到 Yandex Games SDK 方面的问题或有其他问题想要咨询，请联系支持部门：
排行榜名称。
应用 ID。
如果为 true，则是主排行榜。
排列顺序 ：
false：排名按降序排列。true：排名按升序排列。
得分偏移量。
例如，当设置为 decimal_offset: 2 时，1234 将显示为 12.34。
排行榜结果类型 。可用参数：numeric（数字）、time（秒）。
本地化名称 。合法数组参数：ru、en、be、uk、kk、uz、tr。
得分。只接受 integer 类型。必须大于 0。如果排行榜类型为 time，则必须在几毫秒内传递值。
用户描述。可选。
排行榜结果类型 。可用参数：numeric（数字）、time（秒）。
返回用户头像的 URL。Size 的可用值：Small、medium 和 large。
返回适合 Retina 显示屏的用户头像的 srcset。Size 的可用值：Small、medium 和 large。
定义是否在响应中包括登录用户 ：
true：在响应中包括。false（默认）：不包括。
返回在排行榜中低于和高于该用户排名的条目数。最小值为 1，最大值为 10。默认值为 5。
排行榜前列的条目数。最小值为 1，最大值为 20。默认值为 5。
响应中的排名范围。
排名中的位置 。计数从 0 开始，因此将第 1 名视为第 0 个元素。
请求的条目数 。如果没有足够的数据，则返回的数量可能不是所请求的数量。
用户的排名。如果没有排名，或者请求是针对表中排名前列的用户而不包括该用户，则返回 0。
请求的条目。