必填分数、可选榜单 key 和公开展示 extra;必须符合 SubmitLeaderboardEntryPayload 的字段、数值与序列化约束。
服务端保存的当前用户最终 LeaderboardEntry。首次提交返回新记录;同分 或更差时调用仍成功,但返回原有记录,不代表本次 score / extra 已更新。
HbMiniProgramSDKError INVALID_PARAMS:options 不是对象、含未知字段,
key 不合法,score 缺失/非有限数字/超出安全范围,或 extra 不是对象、不可 JSON 序列化、
超过 2048 UTF-8 bytes。
HbMiniProgramSDKError PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED:当前运行快照
缺少或未启用 leaderboard;UNAUTHORIZED:Host 未登录、服务端会话失效,或
请求期间登录账号发生变化。
HbMiniProgramSDKError LEADERBOARD_DEFAULT_NOT_FOUND:省略 key 但当前
小程序未创建 default 榜单;LEADERBOARD_SUBMIT_LOCKED:同一用户记录正在被另一提交
更新,可在稍后重新提交。命名榜单不存在或后端拒绝时保留服务端错误码。
HbMiniProgramSDKError INVALID_STATE:canonical 小程序身份未就绪;
METHOD_FORBIDDEN / REQUEST_UNSUPPORTED:当前 Host 缺少所需账号或受信网络能力;
REQUEST_FAILED:平台请求失败;INVALID_RESPONSE:返回记录字段不符合公开合同。
其他 bridge 超时与 SDK 状态错误会保留对应错误码。
HbMiniProgramSDKError RATE_LIMITED:上游返回 403/429,或该 endpoint 处于
Runtime 熔断窗口;error.data.status 为上游状态码,error.data.retryAfterMs(可能缺失)给出
建议退避时长。
HbMiniProgramSDKError RATE_LIMITED_BY_RUNTIME:Runtime 本地配额或循环检测
拒绝,请求没有到达上游;error.data.origin 为 'budget' 或 'loop'。两者都应停止立即重试。
当前用户不来自参数。Runtime 先向 Host 读取当前登录状态,再用 Host 持有的受信会话和
canonical 小程序 identity 调用平台;页面不能指定 appUserId 或提交其他用户的成绩。
不要先调用用户资料 API 探测登录,直接处理 UNAUTHORIZED。该 API 需要声明
leaderboard,但不需要公开 network 权限或可信用户手势。
“更优”由榜单创建时的 order 决定,可通过
getInfo 查询:desc 只用更高分更新,
asc 只用更低分更新。首次合法分数创建记录;同分和更差分数不更新 score、extra 或
updatedAt。同分记录按更早达到当前分数的 updatedAt 优先,再以 appUserId 稳定排序。
extra 跟随最终保留的分数记录:首次省略时为 {};更优更新省略时保留旧值,传 {}
才清空;同分或更差时传入的新值被忽略。由于 extra 会出现在
getList 中,只能保存公开展示数据。
每次成功响应(包括同分/更差而未更新)都会失效同一小程序、同一榜单的全部列表页和
getCurrentUserEntry 五分钟
读缓存;下一次读取重新请求远端。getInfo 配置缓存和其他榜单缓存不受影响;提交前已
在途的旧读取可能仍返回给原调用方,但不会回填已失效的缓存。需要移除记录时使用
deleteCurrentUserEntry。
import hbSDK from '@heybox/hb-sdk'
const submittedScore = 1200
const entry = await hbSDK.cloud.leaderboard.submit({
key: 'weekly',
score: submittedScore,
extra: { level: 8 },
})
if (entry.score !== submittedScore) {
console.log('已有成绩更优,本次未覆盖', entry.score)
} else if (entry.ranked) {
console.log(`成绩已保存,当前排名 ${entry.rank}`)
} else {
console.log('成绩已保存,暂未获得精确名次')
}
为当前登录用户创建记录,或仅在分数更优时更新已有记录。