跳到主要内容
版本：v4

API 参考

注意事项​

初始化要求

调用排行榜任何 API 函数前，必须先成功调用 TapSDK_Init 进行初始化。未初始化或初始化失败时，调用排行榜函数将返回错误或者非预期结果。

字符串编码

排行榜所有 API 函数接受和返回的字符串参数（char*），都是 UTF-8 编码，请根据项目实际情况自行转换。

数据类型定义​

枚举类型​

TapLeaderboardCollection​

榜单集合类型，用于切换总榜与好友榜：

enum {
    TapLeaderboardCollection_Public  = 0, // 总榜
    TapLeaderboardCollection_Friends = 1, // 好友榜
};
typedef uint32_t TapLeaderboardCollection;
好友榜需先授权 user_friends

当 collection = TapLeaderboardCollection_Friends 时，必须先调用 TapUser_AsyncAuthorize("user_friends") 完成好友信息授权，否则相关接口将返回授权错误。详见申请好友信息授权。

结构体类型​

字节对齐

排行榜使用的所有结构体类型，均使用 8 字节对齐：#pragma pack(push, 8)。

TapLeaderboardPeriod​

榜单周期，永久榜的 display 为空：

typedef struct {
    const char* period_token; // 周期 token
    const char* display;      // 展示文本，如 "4月20日 - 4月26日"，永久榜为空
} TapLeaderboardPeriod;

TapLeaderboardUserInfo​

榜单用户信息：

typedef struct {
    const char* open_id;    // open_id
    const char* union_id;   // union_id
    const char* name;       // 昵称
    const char* avatar;     // 头像 URL
} TapLeaderboardUserInfo;

TapLeaderboardScore​

单条榜单成绩：

typedef struct {
    uint32_t               rank;                 // 排名
    int64_t                score;                // 分数
    TapLeaderboardUserInfo user;                 // 用户信息
    uint64_t               score_submitted_time; // 分数提交时间
} TapLeaderboardScore;

TapLeaderboardInfo​

排行榜实例：

typedef struct {
    const char*                 id;                      // 排行榜 ID
    const char*                 name;                    // 排行榜名称，如"巅峰赛战力榜"
    const TapLeaderboardPeriod* period;                  // 当前周期，NULL 表示永久榜
    uint32_t                    available_period_count;  // 可用周期数量
    const TapLeaderboardPeriod* available_periods;       // 排行榜可用周期
} TapLeaderboardInfo;

TapLeaderboardScoreItem​

单次上报中的一条分数：

typedef struct {
    const char* leaderboard_id; // 排行榜 ID
    int64_t     score;          // 分数
} TapLeaderboardScoreItem;

TapLeaderboardSubmitScoresRequest​

批量上报分数请求，用于 TapLeaderboard_AsyncSubmitScores()，单次最多 5 条：

typedef struct {
    uint32_t                       item_count; // 分数数量，最多 5 个
    const TapLeaderboardScoreItem* items;      // 分数列表
} TapLeaderboardSubmitScoresRequest;

TapLeaderboardSubmitScoreResultData​

单条分数提交结果数据：

typedef struct {
    bool    new_best;  // 是否是新成绩
    int64_t raw_score; // 原始分数
} TapLeaderboardSubmitScoreResultData;

TapLeaderboardSubmitScoreResult​

单条分数在某个周期榜单上的提交结果：

typedef struct {
    const char*                                leaderboard_id; // 榜单 ID
    const char*                                period_token;   // 榜单周期
    const TapLeaderboardSubmitScoreResultData* score_result;   // 分数提交结果
    const char*                                open_id;        // open_id
    const char*                                union_id;       // union_id
} TapLeaderboardSubmitScoreResult;

TapLeaderboardSubmitScoresResponse​

TapLeaderboard_AsyncSubmitScores() 的回调数据，通过 TapEventID::LeaderboardSubmitScores 事件返回：

typedef struct {
    int64_t                                request_id;
    const TapSDK_Error*                    error;         // NULL 表示成功
    uint32_t                               result_count;
    const TapLeaderboardSubmitScoreResult* results;
} TapLeaderboardSubmitScoresResponse;

TapLeaderboardLoadScoresRequest​

拉取榜单数据请求，用于 TapLeaderboard_AsyncLoadScores()：

typedef struct {
    const char*              leaderboard_id;     // 排行榜 ID
    TapLeaderboardCollection collection;         // 总榜 / 好友榜
    const char*              continuation_token; // 分页游标，首次传 NULL
    const char*              period_token;       // 历史周期标识，NULL 表示当前周期
} TapLeaderboardLoadScoresRequest;

TapLeaderboardLoadScoresResponse​

TapLeaderboard_AsyncLoadScores() 的回调数据，通过 TapEventID::LeaderboardLoadScores 事件返回：

typedef struct {
    int64_t                    request_id;
    const TapSDK_Error*        error;              // NULL 表示成功
    const TapLeaderboardInfo*  leaderboard;        // 排行榜元信息
    uint32_t                   score_count;
    const TapLeaderboardScore* scores;
    const char*                continuation_token; // 下一页游标
    bool                       is_truncated;       // 是否还有下一页
} TapLeaderboardLoadScoresResponse;

TapLeaderboardLoadMyScoresRequest​

拉取当前用户成绩请求，用于 TapLeaderboard_AsyncLoadMyScores()：

typedef struct {
    const char*              leaderboard_id; // 排行榜 ID
    TapLeaderboardCollection collection;     // 总榜 / 好友榜
    const char*              period_token;   // 历史周期标识，NULL 表示当前周期
} TapLeaderboardLoadMyScoresRequest;

TapLeaderboardLoadMyScoresResponse​

TapLeaderboard_AsyncLoadMyScores() 的回调数据，通过 TapEventID::LeaderboardLoadMyScores 事件返回：

typedef struct {
    int64_t                    request_id;  // 请求 ID
    const TapSDK_Error*        error;       // NULL 表示成功
    const TapLeaderboardInfo*  leaderboard; // 排行榜元信息
    const TapLeaderboardScore* score;       // 当前用户排名，NULL 表示未上榜
} TapLeaderboardLoadMyScoresResponse;

TapLeaderboardLoadMyCenteredScoresRequest​

获取用户相近分数请求，用于 TapLeaderboard_AsyncLoadMyCenteredScores()：

typedef struct {
    const char*              leaderboard_id; // 排行榜 ID
    TapLeaderboardCollection collection;     // 总榜 / 好友榜
    uint32_t                 max_results;    // 返回总数（含当前用户），0 表示服务端默认值
} TapLeaderboardLoadMyCenteredScoresRequest;

TapLeaderboardLoadMyCenteredScoresResponse​

TapLeaderboard_AsyncLoadMyCenteredScores() 的回调数据，通过 TapEventID::LeaderboardLoadMyCenteredScores 事件返回：

typedef struct {
    int64_t                    request_id;   // 请求 ID
    const TapSDK_Error*        error;        // NULL 表示成功
    const TapLeaderboardInfo*  leaderboard;  // 排行榜元信息
    uint32_t                   score_count; // 分数数量
    const TapLeaderboardScore* scores;      // 分数列表（当前用户居中）
} TapLeaderboardLoadMyCenteredScoresResponse;

TapLeaderboardShowRequest​

打开排行榜页面的请求：

typedef struct {
    const char*              leaderboard_id; // 排行榜 ID
    TapLeaderboardCollection collection;     // 打开时默认展示的集合类型
} TapLeaderboardShowRequest;

函数说明​

TapLeaderboard​

获取排行榜单例对象。

ITapLeaderboard* TapLeaderboard();

返回值： 排行榜单例对象，传入其他排行榜 API 的 self 参数。

TapLeaderboard_AsyncSubmitScores​

发起批量上报分数异步请求。请求发起成功后，结果通过 TapEventID::LeaderboardSubmitScores 事件回调返回。

TapSDK_Result TapLeaderboard_AsyncSubmitScores(
    ITapLeaderboard* self,
    int64_t request_id,
    const TapLeaderboardSubmitScoresRequest* request
);

参数：

  • self：TapLeaderboard() 返回的排行榜单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回，用于对应原始请求
  • request：上报请求参数，最多 5 条

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

使用示例：

TapLeaderboardScoreItem items[1] = {};
items[0].leaderboard_id = "your_leaderboard_id";
items[0].score          = 1999;

TapLeaderboardSubmitScoresRequest req{};
req.item_count = 1;
req.items      = items;

auto ret = TapLeaderboard_AsyncSubmitScores(TapLeaderboard(), ++gRequestID, &req);
if (ret != TapSDK_Result_OK) {
    // 请求发起失败
}

注意事项：

  • 单次请求最多 5 条记录，超出会被服务端拒绝
  • 上报会同时写入对应排行榜下的所有可用周期榜单，回调中按 (leaderboard_id, period_token) 维度返回结果
  • 服务端按排行榜规则保留更优成绩，new_best 为 true 表示本次刷新了最佳成绩

TapLeaderboard_AsyncLoadScores​

发起获取排行榜数据的异步请求，支持分页与按周期查询。结果通过 TapEventID::LeaderboardLoadScores 事件回调返回。

TapSDK_Result TapLeaderboard_AsyncLoadScores(
    ITapLeaderboard* self,
    int64_t request_id,
    const TapLeaderboardLoadScoresRequest* request
);

参数：

  • self：TapLeaderboard() 返回的排行榜单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：查询参数

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

使用示例：

TapLeaderboardLoadScoresRequest req{};
req.leaderboard_id     = "your_leaderboard_id";
req.collection         = TapLeaderboardCollection_Public;
req.continuation_token = nullptr; // 首次拉取传 NULL
req.period_token       = nullptr; // 当前周期

auto ret = TapLeaderboard_AsyncLoadScores(TapLeaderboard(), ++gRequestID, &req);
if (ret != TapSDK_Result_OK) {
    // 请求发起失败
}

注意事项：

  • 分页：回调中 is_truncated 为 true 时表示还有下一页，将 continuation_token 复制后传入下一次请求即可
  • 历史周期：把 available_periods 中某个 period_token 传入 period_token 字段，可拉取该周期的成绩

TapLeaderboard_AsyncLoadMyScores​

发起获取当前用户分数的异步请求。结果通过 TapEventID::LeaderboardLoadMyScores 事件回调返回。

TapSDK_Result TapLeaderboard_AsyncLoadMyScores(
    ITapLeaderboard* self,
    int64_t request_id,
    const TapLeaderboardLoadMyScoresRequest* request
);

参数：

  • self：TapLeaderboard() 返回的排行榜单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：查询参数

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

注意事项：

  • 当前用户未上榜时，回调中 score 为 NULL

TapLeaderboard_AsyncLoadMyCenteredScores​

发起获取用户相近分数的异步请求。结果通过 TapEventID::LeaderboardLoadMyCenteredScores 事件回调返回。

TapSDK_Result TapLeaderboard_AsyncLoadMyCenteredScores(
    ITapLeaderboard* self,
    int64_t request_id,
    const TapLeaderboardLoadMyCenteredScoresRequest* request
);

参数：

  • self：TapLeaderboard() 返回的排行榜单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：查询参数；max_results 为返回的总数（含当前用户）

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

注意事项：

  • 该接口仅返回当前周期的成绩列表，不支持指定历史周期
  • 当前用户未上榜时，返回的列表中可能不包含当前用户

TapLeaderboard_ShowLeaderboards​

打开排行榜展示页面。该接口为同步调用，排行榜展示页在 TapTap 中打开，无需等待回调。

TapSDK_Result TapLeaderboard_ShowLeaderboards(
    ITapLeaderboard* self,
    const TapLeaderboardShowRequest* request
);

参数：

  • self：TapLeaderboard() 返回的排行榜单例对象
  • request：打开排行榜的请求参数

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示打开失败

使用示例：

TapLeaderboardShowRequest req{};
req.leaderboard_id = "your_leaderboard_id";
req.collection     = TapLeaderboardCollection_Public;

auto ret = TapLeaderboard_ShowLeaderboards(TapLeaderboard(), &req);
if (ret != TapSDK_Result_OK) {
    // 打开失败
}