API Reference

Important Notes

Initialization Requirement

You must successfully call TapSDK_Init before calling any Leaderboard API. Calling leaderboard functions without initialization or after initialization failure will return errors or unexpected results.

String Encoding

All string parameters (char*) accepted and returned by Leaderboard APIs are UTF-8 encoded. Convert as needed for your project.

Data Type Definitions

Enum Types

TapLeaderboardCollection

Collection type — switches between the public board and the friends board:

enum {
    TapLeaderboardCollection_Public  = 0, // Public board
    TapLeaderboardCollection_Friends = 1, // Friends board
};
typedef uint32_t TapLeaderboardCollection;

Friends collection requires user_friends authorization

When collection = TapLeaderboardCollection_Friends, call TapUser_AsyncAuthorize("user_friends") first to obtain friend-info authorization; otherwise the corresponding APIs return an authorization error. See Request Friend-Info Authorization.

Struct Types

Byte Alignment

All struct types used by the leaderboard module use 8-byte alignment: #pragma pack(push, 8).

TapLeaderboardPeriod

Leaderboard period. display is empty for permanent boards:

typedef struct {
    const char* period_token; // Period token
    const char* display;      // Display text, e.g. "Apr 20 - Apr 26"; empty for permanent boards
} TapLeaderboardPeriod;

TapLeaderboardUserInfo

User information shown on the leaderboard:

typedef struct {
    const char* open_id;    // open_id
    const char* union_id;   // union_id
    const char* name;       // Nickname
    const char* avatar;     // Avatar URL
} TapLeaderboardUserInfo;

TapLeaderboardScore

A single leaderboard score entry:

typedef struct {
    uint32_t               rank;                 // Rank
    int64_t                score;                // Score
    TapLeaderboardUserInfo user;                 // User info
    uint64_t               score_submitted_time; // Submission timestamp
} TapLeaderboardScore;

TapLeaderboardInfo

Leaderboard metadata:

typedef struct {
    const char*                 id;                      // Leaderboard ID
    const char*                 name;                    // Leaderboard name
    const TapLeaderboardPeriod* period;                  // Current period; NULL means permanent board
    uint32_t                    available_period_count;  // Number of available periods
    const TapLeaderboardPeriod* available_periods;       // Available periods
} TapLeaderboardInfo;

TapLeaderboardScoreItem

A single score entry in a submission:

typedef struct {
    const char* leaderboard_id; // Leaderboard ID
    int64_t     score;          // Score
} TapLeaderboardScoreItem;

TapLeaderboardSubmitScoresRequest

Batch submission request for TapLeaderboard_AsyncSubmitScores(). Up to 5 items per call:

typedef struct {
    uint32_t                       item_count; // Number of items, max 5
    const TapLeaderboardScoreItem* items;      // Score list
} TapLeaderboardSubmitScoresRequest;

TapLeaderboardSubmitScoreResultData

Per-score submission result data:

typedef struct {
    bool    new_best;  // Whether this submission set a new personal best
    int64_t raw_score; // Raw score value
} TapLeaderboardSubmitScoreResultData;

TapLeaderboardSubmitScoreResult

Submission result for a score on a single (leaderboard, period) pair:

typedef struct {
    const char*                                leaderboard_id; // Leaderboard ID
    const char*                                period_token;   // Period token
    const TapLeaderboardSubmitScoreResultData* score_result;   // Submission result
    const char*                                open_id;        // open_id
    const char*                                union_id;       // union_id
} TapLeaderboardSubmitScoreResult;

TapLeaderboardSubmitScoresResponse

Callback data for TapLeaderboard_AsyncSubmitScores(), returned via the TapEventID::LeaderboardSubmitScores event:

typedef struct {
    int64_t                                request_id;
    const TapSDK_Error*                    error;         // NULL on success
    uint32_t                               result_count;
    const TapLeaderboardSubmitScoreResult* results;
} TapLeaderboardSubmitScoresResponse;

TapLeaderboardLoadScoresRequest

Load-scores request for TapLeaderboard_AsyncLoadScores():

typedef struct {
    const char*              leaderboard_id;     // Leaderboard ID
    TapLeaderboardCollection collection;         // Public / Friends
    const char*              continuation_token; // Pagination cursor; NULL for the first page
    const char*              period_token;       // Historical period token; NULL means current period
} TapLeaderboardLoadScoresRequest;

TapLeaderboardLoadScoresResponse

Callback data for TapLeaderboard_AsyncLoadScores(), returned via the TapEventID::LeaderboardLoadScores event:

typedef struct {
    int64_t                    request_id;
    const TapSDK_Error*        error;              // NULL on success
    const TapLeaderboardInfo*  leaderboard;        // Leaderboard metadata
    uint32_t                   score_count;
    const TapLeaderboardScore* scores;
    const char*                continuation_token; // Cursor for the next page
    bool                       is_truncated;       // Whether there is a next page
} TapLeaderboardLoadScoresResponse;

TapLeaderboardLoadMyScoresRequest

Load-current-user-score request for TapLeaderboard_AsyncLoadMyScores():

typedef struct {
    const char*              leaderboard_id; // Leaderboard ID
    TapLeaderboardCollection collection;     // Public / Friends
    const char*              period_token;   // Historical period token; NULL means current period
} TapLeaderboardLoadMyScoresRequest;

TapLeaderboardLoadMyScoresResponse

Callback data for TapLeaderboard_AsyncLoadMyScores(), returned via the TapEventID::LeaderboardLoadMyScores event:

typedef struct {
    int64_t                    request_id;  // Request ID
    const TapSDK_Error*        error;       // NULL on success
    const TapLeaderboardInfo*  leaderboard; // Leaderboard metadata
    const TapLeaderboardScore* score;       // Current user's rank; NULL means user is not on the board
} TapLeaderboardLoadMyScoresResponse;

TapLeaderboardLoadMyCenteredScoresRequest

Load nearby scores request for TapLeaderboard_AsyncLoadMyCenteredScores():

typedef struct {
    const char*              leaderboard_id; // Leaderboard ID
    TapLeaderboardCollection collection;     // Public / Friends
    uint32_t                 max_results;    // Total entries returned (including current user); 0 means server default
} TapLeaderboardLoadMyCenteredScoresRequest;

TapLeaderboardLoadMyCenteredScoresResponse

Callback data for TapLeaderboard_AsyncLoadMyCenteredScores(), returned via the TapEventID::LeaderboardLoadMyCenteredScores event:

typedef struct {
    int64_t                    request_id;   // Request ID
    const TapSDK_Error*        error;        // NULL on success
    const TapLeaderboardInfo*  leaderboard;  // Leaderboard metadata
    uint32_t                   score_count; // Number of scores
    const TapLeaderboardScore* scores;      // Nearby scores around the current user
} TapLeaderboardLoadMyCenteredScoresResponse;

TapLeaderboardShowRequest

Open-leaderboard request:

typedef struct {
    const char*              leaderboard_id; // Leaderboard ID
    TapLeaderboardCollection collection;     // Default collection to display when opening
} TapLeaderboardShowRequest;

API Functions

TapLeaderboard

Get the leaderboard singleton.

ITapLeaderboard* TapLeaderboard();

Return value: The leaderboard singleton, passed as the self argument to other leaderboard APIs.

TapLeaderboard_AsyncSubmitScores

Start an async batch score-submission request. On success, the result is returned via the TapEventID::LeaderboardSubmitScores event callback.

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

Parameters:

• self: Leaderboard singleton returned by TapLeaderboard()
• request_id: Developer-generated request ID; echoed in the callback to match the original request
• request: Submission parameters; up to 5 items

Return value:

• TapSDK_Result: If not TapSDK_Result_OK, the request failed to start and no callback will be invoked

Example:

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) {
    // Failed to start the request
}

Notes:

• Up to 5 items per request; exceeding this will be rejected by the server
• A submission writes to all available period boards under the leaderboard; the callback returns one result per (leaderboard_id, period_token) pair
• The server keeps the better score per the leaderboard's rules; new_best == true means this submission set a new personal best

TapLeaderboard_AsyncLoadScores

Start an async request to load leaderboard scores. Supports pagination and querying historical periods. The result is returned via the TapEventID::LeaderboardLoadScores event callback.

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

Parameters:

• self: Leaderboard singleton returned by TapLeaderboard()
• request_id: Developer-generated request ID; echoed in the callback
• request: Query parameters

Return value:

• TapSDK_Result: If not TapSDK_Result_OK, the request failed to start and no callback will be invoked

Example:

TapLeaderboardLoadScoresRequest req{};
req.leaderboard_id     = "your_leaderboard_id";
req.collection         = TapLeaderboardCollection_Public;
req.continuation_token = nullptr; // First page
req.period_token       = nullptr; // Current period

auto ret = TapLeaderboard_AsyncLoadScores(TapLeaderboard(), ++gRequestID, &req);
if (ret != TapSDK_Result_OK) {
    // Failed to start the request
}

Notes:

• Pagination: when is_truncated is true in the callback, copy continuation_token and pass it back into the next request to fetch the next page
• Historical periods: pass one of the period_token values from available_periods into the period_token field to query that period

TapLeaderboard_AsyncLoadMyScores

Start an async request to fetch the current user's score. The result is returned via the TapEventID::LeaderboardLoadMyScores event callback.

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

Parameters:

• self: Leaderboard singleton returned by TapLeaderboard()
• request_id: Developer-generated request ID; echoed in the callback
• request: Query parameters

Return value:

• TapSDK_Result: If not TapSDK_Result_OK, the request failed to start and no callback will be invoked

Notes:

• When the current user is not on the board, score in the callback is NULL

TapLeaderboard_AsyncLoadMyCenteredScores

Start an async request to load nearby scores around the current user. The result is returned via the TapEventID::LeaderboardLoadMyCenteredScores event callback.

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

Parameters:

• self: Leaderboard singleton returned by TapLeaderboard()
• request_id: Developer-generated request ID; echoed in the callback
• request: Query parameters; max_results is the total number of entries returned (including the current user)

Return value:

• TapSDK_Result: If not TapSDK_Result_OK, the request failed to start and no callback will be invoked

Notes:

• This API only returns scores for the current period; specifying a historical period is not supported
• If the current user is not on the board, the returned list may not include the current user

TapLeaderboard_ShowLeaderboards

Open the leaderboard display page. This is a synchronous call — the page opens in TapTap and no callback is needed.

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

Parameters:

• self: Leaderboard singleton returned by TapLeaderboard()
• request: Open-leaderboard parameters

Return value:

• TapSDK_Result: If not TapSDK_Result_OK, the open request failed

Example:

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

auto ret = TapLeaderboard_ShowLeaderboards(TapLeaderboard(), &req);
if (ret != TapSDK_Result_OK) {
    // Failed to open
}