@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 为当前登录用户创建记录,或仅在分数更优时更新已有记录。

      参数

      返回 Promise<LeaderboardEntry>

      服务端保存的当前用户最终 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'。两者都应停止立即重试。

      DOMException extra 含函数、Symbol 等不可 structured-clone 的内容时,浏览器可能 在请求发送前抛出 DataCloneError。

      当前用户不来自参数。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('成绩已保存,暂未获得精确名次')
      }

      0.5.11

      android

      ios

      ohos

      windows

      macos

      android none

      ios none

      ohos none

      windows none

      macos none