API 参考

注意事项

初始化要求

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

字符串编码

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

数据类型定义

结构体类型

字节对齐

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

TapAchievementInfo

成就信息，在解锁和分步增长的响应中使用：

typedef struct {
    const char* id;         // 成就 ID
    const char* name;       // 成就名称
    uint64_t current_steps; // 当前步数，非分步成就时为 0
    bool newly_unlocked;    // 是否首次解锁。true 表示本次请求触发了解锁
} TapAchievementInfo;

TapAchievementUnlockRequest

解锁成就请求，用于 TapAchievement_AsyncUnlock()：

typedef struct {
    const char* achievement_id; // 成就 ID，不允许空
} TapAchievementUnlockRequest;

TapAchievementUnlockResponse

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

typedef struct {
    int64_t request_id;                             // 请求 ID，原样返回开发者调用异步接口时传入的 ID
    const TapSDK_Error* error;                      // 错误信息。NULL 表示请求成功；非 NULL 表示请求失败
    const TapAchievementInfo* achievement;          // 成就解锁情况
    const TapAchievementInfo* platinum_achievement; // 白金成就解锁情况。如果本次未首次解锁白金成就，该字段为 NULL
} TapAchievementUnlockResponse;

TapAchievementIncrementRequest

分步成就增长请求，用于 TapAchievement_AsyncIncrement()：

typedef struct {
    const char* achievement_id; // 成就 ID，不允许空
    uint64_t steps;             // 本次增加的步数
} TapAchievementIncrementRequest;

TapAchievementIncrementResponse

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

typedef struct {
    int64_t request_id;                             // 请求 ID，原样返回开发者调用异步接口时传入的 ID
    const TapSDK_Error* error;                      // 错误信息。NULL 表示请求成功；非 NULL 表示请求失败
    const TapAchievementInfo* achievement;          // 成就当前状态
    const TapAchievementInfo* platinum_achievement; // 白金成就解锁情况。如果本次未首次解锁白金成就，该字段为 NULL
} TapAchievementIncrementResponse;

函数说明

TapAchievement

获取成就接口单例对象。

ITapAchievement* TapAchievement();

返回值：

• 成就接口单例对象

使用示例：

ITapAchievement* achi = TapAchievement();

TapAchievement_AsyncUnlock

发起成就解锁异步请求。请求发起成功后，结果通过 TapEventID::AchievementUnlock 事件回调返回。

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

参数：

• self：TapAchievement() 返回的成就单例对象
• request_id：开发者生成的请求 ID，回调时原样返回，用于对应原始请求
• request：解锁成就请求参数，不允许空指针

返回值：

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

使用示例：

TapAchievementUnlockRequest req;
// 结构体"零值化"，避免内存随机值导致的野指针问题
// C++11 及以上，可以使用 TapAchievementUnlockRequest req{};，无需 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) {
    // 请求发起失败，不会触发回调，请根据返回值做相应处理
}

注意事项：

• 对已解锁的成就重复调用，服务端不会重复记录，回调中 achievement->newly_unlocked 为 false

TapAchievement_AsyncIncrement

发起分步成就步数增长异步请求。请求发起成功后，结果通过 TapEventID::AchievementIncrement 事件回调返回。

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

参数：

• self：TapAchievement() 返回的成就单例对象
• request_id：开发者生成的请求 ID，回调时原样返回
• request：分步成就增长请求参数，不允许空指针

返回值：

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

使用示例：

TapAchievementIncrementRequest req;
// 结构体"零值化"，避免内存随机值导致的野指针问题
// C++11 及以上，可以使用 TapAchievementIncrementRequest req{};，无需 memset
memset(&req, 0, sizeof(req));
req.achievement_id = "your_achievement_id";
req.steps = 1; // 本次增加的步数

TapSDK_Result ret = TapAchievement_AsyncIncrement(TapAchievement(), ++gRequestID, &req);
if (ret != TapSDK_Result_OK) {
    // 请求发起失败，不会触发回调，请根据返回值做相应处理
}

注意事项：

• SDK 自动累计步数，当步数达到成就解锁阈值时，成就自动解锁，回调中 achievement->newly_unlocked 为 true
• 分步成就的步数只能增加，不能减少或重置
• 非分步成就不支持此接口，会通过回调返回错误

TapAchievement_ShowAchievements

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

TapSDK_Result TapAchievement_ShowAchievements(
    ITapAchievement* self
);

参数：

• self：TapAchievement() 返回的成就单例对象

返回值：

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

使用示例：

TapSDK_Result ret = TapAchievement_ShowAchievements(TapAchievement());
if (ret != TapSDK_Result_OK) {
    // 打开失败，请根据返回值做相应处理
}