API Reference

Important Notes

Initialization Requirement

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

String Encoding

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

Data Type Definitions

Struct Types

Byte Alignment

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

TapAchievementInfo

Achievement information, used in both unlock and increment responses:

typedef struct {
    const char* id;         // Achievement ID
    const char* name;       // Achievement name
    uint64_t current_steps; // Current step count; 0 for non-incremental achievements
    bool newly_unlocked;    // Whether this request triggered the unlock for the first time
} TapAchievementInfo;

TapAchievementUnlockRequest

Unlock request, used with TapAchievement_AsyncUnlock():

typedef struct {
    const char* achievement_id; // Achievement ID; must not be NULL
} TapAchievementUnlockRequest;

TapAchievementUnlockResponse

Callback data for TapAchievement_AsyncUnlock(), returned via the TapEventID::AchievementUnlock event:

typedef struct {
    int64_t request_id;                             // Request ID; echoes the value passed by the caller
    const TapSDK_Error* error;                      // Error info. NULL = success; non-NULL = failure
    const TapAchievementInfo* achievement;          // Achievement status
    const TapAchievementInfo* platinum_achievement; // Platinum achievement status. NULL if no platinum achievement was unlocked for the first time by this request
} TapAchievementUnlockResponse;

TapAchievementIncrementRequest

Increment request, used with TapAchievement_AsyncIncrement():

typedef struct {
    const char* achievement_id; // Achievement ID; must not be NULL
    uint64_t steps;             // Number of steps to add
} TapAchievementIncrementRequest;

TapAchievementIncrementResponse

Callback data for TapAchievement_AsyncIncrement(), returned via the TapEventID::AchievementIncrement event:

typedef struct {
    int64_t request_id;                             // Request ID; echoes the value passed by the caller
    const TapSDK_Error* error;                      // Error info. NULL = success; non-NULL = failure
    const TapAchievementInfo* achievement;          // Current achievement status
    const TapAchievementInfo* platinum_achievement; // Platinum achievement status. NULL if no platinum achievement was unlocked for the first time by this request
} TapAchievementIncrementResponse;

TapEventID (Achievement)

Achievement event IDs share the TapEventID enum with other modules. See TapEventID for the full definition.

AchievementUnlock = 7001,    // Unlock achievement
AchievementIncrement = 7002, // Increment steps

Function Reference

TapAchievement

Get the achievement interface singleton.

ITapAchievement* TapAchievement();

Return value:

• The achievement interface singleton

Example:

ITapAchievement* achi = TapAchievement();

TapAchievement_AsyncUnlock

Async request to unlock the specified achievement. On success, the result is returned via the TapEventID::AchievementUnlock callback.

TapSDK_Result TapAchievement_AsyncUnlock(
    ITapAchievement* self,
    int64_t request_id,
    const TapAchievementUnlockRequest* request
);

Parameters:

• self: Achievement singleton returned by TapAchievement()
• request_id: Developer-generated request ID, echoed in the callback to match the original request
• request: Unlock request parameters; must not be NULL

Return value:

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

Example:

TapAchievementUnlockRequest req;
// Zero-initialize the struct to avoid wild pointers from uninitialized memory
// In C++11 or later, you can use TapAchievementUnlockRequest req{}; instead of memset
memset(&req, 0, sizeof(req));
req.achievement_id = "your_achievement_id";

TapSDK_Result ret = TapAchievement_AsyncUnlock(TapAchievement(), ++gRequestID, &req);
if (ret != TapSDK_Result_OK) {
    // Request failed to start; no callback will be invoked — handle accordingly
}

Notes:

• Calling unlock on an already-unlocked achievement does not create a duplicate server record; achievement->newly_unlocked will be false in the callback

TapAchievement_AsyncIncrement

Async request to add steps to an incremental achievement. On success, the result is returned via the TapEventID::AchievementIncrement callback.

TapSDK_Result TapAchievement_AsyncIncrement(
    ITapAchievement* self,
    int64_t request_id,
    const TapAchievementIncrementRequest* request
);

Parameters:

• self: Achievement singleton returned by TapAchievement()
• request_id: Developer-generated request ID, echoed in the callback
• request: Increment request parameters; must not be NULL

Return value:

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

Example:

TapAchievementIncrementRequest req;
// Zero-initialize the struct to avoid wild pointers from uninitialized memory
// In C++11 or later, you can use TapAchievementIncrementRequest req{}; instead of memset
memset(&req, 0, sizeof(req));
req.achievement_id = "your_achievement_id";
req.steps = 1; // Number of steps to add

TapSDK_Result ret = TapAchievement_AsyncIncrement(TapAchievement(), ++gRequestID, &req);
if (ret != TapSDK_Result_OK) {
    // Request failed to start; no callback will be invoked — handle accordingly
}

Notes:

• The SDK accumulates steps automatically; when the total reaches the threshold, the achievement unlocks and achievement->newly_unlocked is true in the callback
• Steps can only increase — they cannot be reduced or reset
• Calling this on a non-incremental achievement returns an error in the callback

TapAchievement_ShowAchievements

Open the achievements page in the system browser. This is a synchronous call — no request ID or callback is needed.

TapSDK_Result TapAchievement_ShowAchievements(
    ITapAchievement* self
);

Parameters:

• self: Achievement singleton returned by TapAchievement()

Return value:

• TapSDK_Result: If not TapSDK_Result_OK, the page failed to open

Example:

TapSDK_Result ret = TapAchievement_ShowAchievements(TapAchievement());
if (ret != TapSDK_Result_OK) {
    // Failed to open; handle the return value accordingly
}