@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 读取当前登录用户在指定排行榜中的记录。

      参数

      返回 Promise<GetCurrentUserLeaderboardEntryResult>

      当前用户的完整 LeaderboardEntry;没有记录时 resolve undefined,这是 正常空结果。返回记录但 ranked: false 时记录仍存在,rank 固定为 0。

      HbMiniProgramSDKError INVALID_PARAMS:options 不是对象、含 key 以外 的字段,或 key 不符合 1 至 64 位 [A-Za-z0-9_-] 规则。

      HbMiniProgramSDKError PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED:当前运行快照 缺少或未启用 leaderboard;UNAUTHORIZED:Host 未登录、服务端会话失效,或 请求期间登录账号发生变化。

      HbMiniProgramSDKError LEADERBOARD_DEFAULT_NOT_FOUND:省略 key 但当前 小程序未创建 default 榜单。命名榜单不存在或后端拒绝时保留服务端错误码。

      HbMiniProgramSDKError INVALID_STATE:canonical 小程序身份未就绪; METHOD_FORBIDDEN / REQUEST_UNSUPPORTED:当前 Host 缺少所需账号或受信网络能力; 其他网络失败、响应字段不合法和 bridge 超时分别保留对应 REQUEST_FAILED、 INVALID_RESPONSE 或 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 小程序身份关联的记录。页面不能指定或猜测其他 用户,也不应先调用用户资料 API 探测登录;直接处理本方法的 UNAUTHORIZED 即可。 该 API 需要声明 leaderboard,但不需要公开 network 权限或可信用户手势。

      返回的 appUserId 是当前用户在当前小程序内的隔离标识,不是黑盒用户 ID、登录凭据或 可跨小程序关联的账号字段。extra 会随 getList 返回给该榜单的其他读取者, 调用方应把它当作公开展示数据。

      ranked 同时受榜单 rankLimit 和当前用户前 5000 名精确排名上限约束:两项均满足时 ranked: true 且 rank 为正整数;任一不满足时记录仍返回,但固定为 ranked: false, rank: 0。即使 rankLimit 为 0(列表不限制),前 5000 名计算上限 仍然存在。不要用 rank === 0 判断“没有记录”,应先判断整个返回值是否为 undefined。

      当前 Runtime 最多为 3 个活跃榜单 bucket 缓存结果(包括 undefined)五分钟;超过上限的 榜单读取不进入缓存。同一时刻的重复读取仍会合并为一个远端请求。账号变化会清空全部榜单缓存,并使旧账号的 在途响应以 UNAUTHORIZED 结束;成功的 submit 或 deleteCurrentUserEntry 会使同榜单的当前用户与列表缓存立即失效,下一次读取重新请求远端。

      getCurrentUserEntry() 可以返回仍存在但未进入列表展示范围的记录;分页 getList() 中没有当前用户,不等于当前用户没有记录。需要创建或更新记录时调用 submit(),需要删除时调用 deleteCurrentUserEntry()。

      import hbSDK from '@heybox/hb-sdk'

      const entry = await hbSDK.cloud.leaderboard.getCurrentUserEntry({
      key: 'weekly',
      })

      if (!entry) {
      console.log('还没有成绩')
      } else if (entry.ranked) {
      console.log(`当前成绩 ${entry.score},排名 ${entry.rank}`)
      } else {
      console.log(`成绩 ${entry.score} 已保存,暂未获得精确名次`)
      }

      0.5.11

      android

      ios

      ohos

      windows

      macos

      android none

      ios none

      ohos none

      windows none

      macos none