# TapTap 排行榜接入指南

# 1. 简要说明

TapTap 排行榜服务提供了一套完整的玩家排名系统，支持多种排名规则和重置周期。

# 核心特性

无需安装 SDK：tap 是全局对象，直接使用。
灵活配置：支持按数值/时间排序，支持每日/每周/每月重置。
UI 组件：提供开箱即用的排行榜展示面板 openLeaderboard。

# 接入流程

# 2. 创建排行榜

# 第一步：访问开发者中心

进入 TapTap 开发者中心 (opens new window)。
选中你的游戏项目。
在左侧菜单找到 游戏服务 -> 游戏排行。
或者直接访问链接（请替换 ID）：https://developer.taptap.cn/{developer_id}/app/{app_id}/rank_v4

# 第二步：新建榜单

点击页面作上角的“新建榜单”，根据游戏需求配置核心规则：

排序方式：
- 降序：分数越高排名越前（如：得分、杀敌数）。
- 升序：分数越低排名越前（如：竞速时间）。
重置周期：支持日榜、周榜、月榜或永久榜。
计算方式：推荐选择“保留历史最高分”，确保玩家排名不下降。

# 第三步：配置测试白名单（可选）

在开发和测试阶段，建议开启白名单模式，避免测试数据污染线上环境。

在榜单列表中找到目标榜单，点击右侧的“发布设置”或“编辑”。
将“榜单状态”设置为 仅白名单可见。
在下方添加测试账号的 TapTap ID。

# 第四步：获取榜单 ID

创建完成后，在榜单列表中找到 排行榜ID 列。请复制这个字符串（例如 gpxbjxcc03v1u2pytg），后续客户端代码中将使用此 ID。

# 3. 主要接口说明

详细参数请参考官方 API 文档 (opens new window)

# 核心管理器

LeaderboardManager: const leaderboard = tap.getLeaderboardManager()

# 常用 API

方法	描述	文档链接
submitScores	提交玩家分数	API 详情 (opens new window)
openLeaderboard	打开排行榜标准 UI 面板	API 详情 (opens new window)
loadLeaderboardScores	获取指定排行榜的分数列表	API 详情 (opens new window)
loadCurrentPlayerLeaderboardScore	获取当前玩家在指定榜单的排名和分数	API 详情 (opens new window)

# 4. 代码示例

以下是一个封装好的排行榜服务类，简化了常用操作。

/**
 * 排行榜服务 - 封装常用操作
 */
class LeaderboardService {
  constructor() {
    this.manager = tap.getLeaderboardManager();
  }

  /**
   * 提交分数
   * @param {string} leaderboardId - 排行榜 ID
   * @param {number} score - 分数
   */
  submitScore(leaderboardId, score) {
    return new Promise((resolve, reject) => {
      this.manager.submitScores({
        scores: [{
          leaderboardId,
          score
        }],
        callback: {
          onSuccess: (res) => {
            console.log('分数提交成功', res);
            resolve(res);
          },
          onFailure: (code, message) => {
            console.error('分数提交失败', code, message);
            reject({ code, message });
          }
        }
      });
    });
  }

  /**
   * 打开排行榜 UI
   * @param {string} leaderboardId - 排行榜 ID
   */
  showLeaderboard(leaderboardId) {
    return new Promise((resolve, reject) => {
      this.manager.openLeaderboard({
        leaderboardId,
        callback: {
          onSuccess: resolve,
          onFailure: (code, message) => reject({ code, message })
        }
      });
    });
  }

  /**
   * 获取我的排名
   * @param {string} leaderboardId - 排行榜 ID
   */
  getMyRank(leaderboardId) {
    return new Promise((resolve, reject) => {
      this.manager.loadCurrentPlayerLeaderboardScore({
        leaderboardId,
        callback: {
          onSuccess: (res) => resolve(res),
          onFailure: (code, message) => reject({ code, message })
        }
      });
    });
  }

  /**
   * 获取排行榜前 N 名
   * @param {string} leaderboardId - 排行榜 ID
   * @param {number} limit - 获取数量
   */
  getTopScores(leaderboardId, limit = 10) {
    return new Promise((resolve, reject) => {
      this.manager.loadLeaderboardScores({
        leaderboardId,
        maxSize: limit,
        nextPage: undefined, // 第一页
        periodToken: undefined,
        callback: {
          onSuccess: (res) => resolve(res.scores),
          onFailure: (code, message) => reject({ code, message })
        }
      });
    });
  }
}

// 使用示例
const lbService = new LeaderboardService();
const LEADERBOARD_ID = 'weekly_challenge_01'; // 替换为你创建的排行榜 ID

// 1. 提交分数
lbService.submitScore(LEADERBOARD_ID, 5000)
  .then(() => console.log('Upload success'));

// 2. 显示面板
// lbService.showLeaderboard(LEADERBOARD_ID);

// 3. 获取我的排名
lbService.getMyRank(LEADERBOARD_ID).then(data => {
  console.log(`我的排名: ${data.rank}, 分数: ${data.score}`);
});

# 5. QA

Q: 为什么提示 "leaderboard not found" (500001)？ A: 请检查 leaderboardId 是否正确。

确保已在服务端或开发者中心成功创建排行榜。
确保使用的是排行榜的 ID (标识符)，而不是名称。

Q: 如何实现好友排行榜？ A: 在调用 openLeaderboard 或 loadLeaderboardScores 时，设置参数 collection: "friends"。

注意：使用好友榜需要在开发者中心申请 好友关系权限。

Q: 涉及好友功能的常见错误码？ A: 当使用 collection: "friends" 时可能会遇到：

1025: 小游戏没有申明使用好友关系信息。请在开发者中心检查隐私协议配置。
104: 用户未通过隐私协议。
103: 用户未授权使用其好友关系信息。

Q: 提交的分数没有更新？ A: 检查排行榜的 计算方式 配置。如果配置为 "保留历史最高分"（Best），且新提交的分数低于历史最高分，则不会更新。

« 云存档接入指南

性能优化指南 »