Skip to main content
Version: v4

API Reference

Important Notes​

Initialization Requirement

Except for TapSDK_RestartAppIfNecessary, all other API functions must successfully call TapSDK_Init for initialization before use. Calling other functions without initialization or after initialization failure will return errors or unexpected results.

Data Type Definitions​

Basic Types​

typedef char ErrMsg[1024];       // Error message, maximum length 1023 bytes + '\0'
typedef void (T_CALLTYPE *callback_t)(TapEventID, void *);  // Callback function type
typedef int64_t TapSDK_ErrorCode; // Error code, values refer to enum TapSDK_ErrorCode_*

#pragma pack(push, 8)

// Error information structure
typedef struct {
    TapSDK_ErrorCode code; // Error code
    const char* message;   // Error message
} TapSDK_Error;

#pragma pack(pop)

Enumeration Types​

TapSDK_Init_Result​

SDK initialization result enumeration:

enum class TapSDK_Init_Result : uint32_t {
    OK = 0,                     // Initialization successful
    FailedGeneric = 1,          // Other errors
    NoPlatform = 2,             // TapTap platform not found
    NotLaunchedByPlatform = 3,  // Not launched through TapTap
    PlatformVersionMismatch = 4 // Platform version too old, please guide the user to upgrade TapTap to the latest version, then restart the game
};

TapUser_AsyncAuthorize_Result​

User authorization request result enumeration:

enum class TapUser_AsyncAuthorize_Result : uint32_t {
    Unknown = 0,    // Unknown error, usually caused by uninitialized (TapSDK_Init not called) or initialization failure
    OK = 1,         // Successfully initiated authorization flow
    Failed = 2,     // Failed to initiate authorization flow, suggest prompting user to retry
    InFlight = 3    // Authorization flow in progress, suggest ignoring error or prompting user to wait
};

TapEventID​

Event ID enumeration:

enum class TapEventID : uint32_t {
    Unknown = 0,
    AuthorizeFinished = 2002,           // Authorization completion event
    GamePlayableStatusChanged = 4001,   // Game playable status change event
    DLCPlayableStatusChanged = 4002,    // DLC playable status change event

    CloudSaveList = 6001,     // Get cloud save list
    CloudSaveCreate = 6002,   // Create cloud save
    CloudSaveUpdate = 6003,   // Update cloud save
    CloudSaveDelete = 6004,   // Delete cloud save
    CloudSaveGetData = 6005,  // Get cloud save data
    CloudSaveGetCover = 6006, // Get cloud save cover
};

TapSDK_ErrorCode​

Error code enumeration:

enum {
    TapSDK_ErrorCode_Success = 0,              // Request executed successfully
    TapSDK_ErrorCode_Unknown = 1,              // Unknown error
    TapSDK_ErrorCode_Unauthorized = 2,         // Invalid user credentials, please guide the user to re-login to TapTap
    TapSDK_ErrorCode_MethodNotAllowed = 3,     // Method not allowed
    TapSDK_ErrorCode_Unimplemented = 4,        // Method not implemented
    TapSDK_ErrorCode_InvalidArguments = 5,     // Invalid arguments
    TapSDK_ErrorCode_Forbidden = 6,            // User does not have permission for current action
    TapSDK_ErrorCode_UserIsDeactivated = 7,    // User is deactivated
    TapSDK_ErrorCode_InternalServerError = 8,  // Internal server error
    TapSDK_ErrorCode_InternalSdkError = 9,     // SDK internal error
    TapSDK_ErrorCode_NetworkError = 10,        // Network error

    TapSDK_ErrorCode_CloudSave_InvalidFileSize = 400000,               // Invalid save file/cover size
    TapSDK_ErrorCode_CloudSave_UploadRateLimit = 400001,               // Save upload rate limit exceeded
    TapSDK_ErrorCode_CloudSave_FileNotFound = 400002,                  // Save file not found
    TapSDK_ErrorCode_CloudSave_FileCountLimitPerClient = 400003,       // User's save file count limit exceeded for this app
    TapSDK_ErrorCode_CloudSave_StorageSizeLimitPerClient = 400004,     // User's storage size limit exceeded for this app
    TapSDK_ErrorCode_CloudSave_TotalStorageSizeLimit = 400005,         // User's total storage size limit exceeded
    TapSDK_ErrorCode_CloudSave_Timeout = 400006,                       // Request timeout, usually due to network lag
    TapSDK_ErrorCode_CloudSave_ConcurrentCallDisallowed = 400007,      // Concurrent call not allowed
    TapSDK_ErrorCode_CloudSave_StorageServerError = 400008,            // Storage server error
    TapSDK_ErrorCode_CloudSave_InvalidName = 400009,                   // Invalid save name
};

Structure Types​

AuthorizeFinishedResponse​

Authorization completion response structure:

struct AuthorizeFinishedResponse {
    bool is_cancel;              // Whether user canceled authorization
    char error[1024];            // Error message
    char token_type[32];         // Token type
    char kid[8*1024];            // Key ID
    char mac_key[8*1024];        // MAC key
    char mac_algorithm[32];      // MAC algorithm
    char scope[1024];            // Permission scope
};

GamePlayableStatusChangedResponse​

Game playable status change response structure:

struct GamePlayableStatusChangedResponse {
    bool is_playable;            // Whether game is playable
};

DLCPlayableStatusChangedResponse​

DLC playable status change response structure:

struct DLCPlayableStatusChangedResponse {
    char dlc_id[32];             // DLC ID
    bool is_playable;            // Whether DLC is playable
};

SDK Core Interfaces​

TapSDK_RestartAppIfNecessary​

Check if app restart is necessary.

bool TapSDK_RestartAppIfNecessary(const char *clientID);

Parameters:

  • clientID: Client ID

Return Value:

  • true: Restart required, TapTap will reopen the game, please exit the game process immediately
  • false: Restart not required, can continue initialization

Usage Example:

const char* clientID = "your_client_id";
if (TapSDK_RestartAppIfNecessary(clientID)) {
    std::cout << "App restart required" << std::endl;
    return 0; // Exit immediately
}

Notes:

  • This function must be called before TapSDK_Init
  • If it returns true, exit the program immediately and wait for TapTap to restart the game

TapSDK_Init​

Initialize SDK.

TapSDK_Init_Result TapSDK_Init(ErrMsg *errMsg, const char *pubKey);

Parameters:

  • errMsg: Error message buffer, length 1024 bytes
  • pubKey: Public key obtained from TapTap Developer Center

Return Value:

  • TapSDK_Init_Result: Initialization result enumeration

Usage Example:

ErrMsg errMsg;
const char* pubKey = "your_public_key";
TapSDK_Init_Result result = TapSDK_Init(&errMsg, pubKey);

switch (result) {
    case TapSDK_Init_Result::OK:
        std::cout << "Initialization successful" << std::endl;
        break;
    case TapSDK_Init_Result::NoPlatform:
        std::cout << "TapTap platform not found, please download and install TapTap launcher" << std::endl;
        std::cout << "Download URL: https://www.taptap.cn/mobile" << std::endl;
        break;
    case TapSDK_Init_Result::NotLaunchedByPlatform:
        std::cout << "Game not launched through TapTap launcher, please reopen the game from the launcher" << std::endl;
        break;
    case TapSDK_Init_Result::PlatformVersionMismatch:
        std::cout << "Platform version mismatch, please upgrade TapTap launcher or game to the latest version" << std::endl;
        break;
    default:
        std::cout << "Initialization failed: " << errMsg << std::endl;
        std::cout << "Please close the game and reopen it from TapTap" << std::endl;
        break;
}

TapSDK_Shutdown​

Shutdown SDK and release resources.

bool TapSDK_Shutdown();

Return Value:

  • true: Successfully shut down
  • false: Shutdown failed (usually due to uninitialized (TapSDK_Init not called) or initialization failure)

Usage Example:

if (TapSDK_Shutdown()) {
    std::cout << "SDK successfully shut down" << std::endl;
} else {
    std::cout << "SDK shutdown failed" << std::endl;
}

TapSDK_GetClientID​

Get current client ID.

bool TapSDK_GetClientID(char *buffer);

Parameters:

  • buffer: Buffer for storing client ID, fixed length 256 bytes

Return Value:

  • true: Successfully retrieved
  • false: Retrieval failed (usually due to uninitialized (TapSDK_Init not called) or initialization failure)

Usage Example:

char clientID[256];
if (TapSDK_GetClientID(clientID)) {
    std::cout << "Client ID: " << clientID << std::endl;
} else {
    std::cout << "Failed to get Client ID, please check if SDK is properly initialized" << std::endl;
}

TapSDK_RegisterCallback​

Register event callback.

void TapSDK_RegisterCallback(TapEventID eventID, callback_t callback);

Parameters:

  • eventID: Event ID
  • callback: Callback function

Usage Example:

void T_CALLTYPE OnAuthorizeFinished(TapEventID eventID, void* data) {
    if (eventID == TapEventID::AuthorizeFinished) {
        AuthorizeFinishedResponse* response = (AuthorizeFinishedResponse*)data;
        // Handle authorization completion event
    }
}

// Register callback
TapSDK_RegisterCallback(TapEventID::AuthorizeFinished, OnAuthorizeFinished);

TapSDK_UnregisterCallback​

Unregister event callback.

void TapSDK_UnregisterCallback(TapEventID eventID, callback_t callback);

Parameters:

  • eventID: Event ID
  • callback: Callback function to unregister

Usage Example:

// Unregister callback
TapSDK_UnregisterCallback(TapEventID::AuthorizeFinished, OnAuthorizeFinished);

TapSDK_RunCallbacks​

Process callback events, recommended to call every frame.

void TapSDK_RunCallbacks();

Usage Example:

// Call in game main loop
while (gameRunning) {
    TapSDK_RunCallbacks(); // Process SDK events
    
    // Game logic
    UpdateGame();
    RenderGame();
    
    Sleep(16); // Control frame rate
}

TapUser_AsyncAuthorize​

Asynchronously request user authorization (simplified version).

TapUser_AsyncAuthorize_Result TapUser_AsyncAuthorize(const char* scopes);

Parameters:

  • scopes: Permission scope string, multiple permissions separated by commas

Return Value:

  • TapUser_AsyncAuthorize_Result::Unknown: Unknown error, usually due to uninitialized or initialization failure
  • TapUser_AsyncAuthorize_Result::OK: Successfully initiated authorization flow, waiting for user confirmation
  • TapUser_AsyncAuthorize_Result::Failed: Failed to initiate authorization flow, suggest prompting user to retry
  • TapUser_AsyncAuthorize_Result::InFlight: Authorization flow in progress, suggest ignoring or prompting user to wait

Common Permission Scopes:

  • "public_profile": Basic user information
  • "user_friends": Friend information
  • "public_profile,user_friends": Multiple permissions

Usage Example:

// Register authorization completion callback
TapSDK_RegisterCallback(TapEventID::AuthorizeFinished, OnAuthorizeFinished);

// Request basic user information permission
TapUser_AsyncAuthorize_Result result = TapUser_AsyncAuthorize("public_profile");
switch (result) {
    case TapUser_AsyncAuthorize_Result::OK:
        std::cout << "Authorization request sent, waiting for user confirmation" << std::endl;
        break;
    case TapUser_AsyncAuthorize_Result::Failed:
        std::cout << "Failed to initiate authorization, please retry" << std::endl;
        break;
    case TapUser_AsyncAuthorize_Result::InFlight:
        std::cout << "Authorization flow in progress, please wait" << std::endl;
        break;
    case TapUser_AsyncAuthorize_Result::Unknown:
        std::cout << "Authorization failed, please check SDK initialization status" << std::endl;
        break;
}

TapUser_GetOpenID​

Get user OpenID.

bool TapUser_GetOpenID(char *buffer);

Parameters:

  • buffer: Buffer for storing OpenID, fixed length 256 bytes

Return Value:

  • true: Successfully retrieved
  • false: Retrieval failed (usually due to uninitialized or initialization failure)

Usage Example:

char openID[256];
if (TapUser_GetOpenID(openID)) {
    std::cout << "User OpenID: " << openID << std::endl;
} else {
    std::cout << "Failed to get OpenID, please check SDK initialization status and user authorization status" << std::endl;
}

License Verification Functions​

TapApps_IsOwned​

Check if user owns the current game.

Usage Notes
  • Only premium games need to call: Free games do not need ownership verification
  • Verified at initialization: Game ownership is verified when TapSDK_Init succeeds
  • Runtime monitoring: During game runtime, it only returns false when user loses ownership (e.g., refund)
bool TapApps_IsOwned();

Return Value:

  • true: User owns the current game
  • false: User does not own the current game (usually occurs in cases like refund)

Usage Example:

// Only premium games need to check
if (TapApps_IsOwned()) {
    std::cout << "User owns this game, can continue running" << std::endl;
    // Continue game logic
} else {
    std::cout << "User has lost game ownership (possibly refunded)" << std::endl;
    // Save progress and exit game
    SaveGameAndExit();
    return -1;
}

TapDLC_IsOwned​

Query if user owns the specified DLC.

bool TapDLC_IsOwned(const char *dlc_id);

Parameters:

  • dlc_id: DLC ID

Return Value:

  • true: User owns the DLC
  • false: User does not own the DLC

Usage Example:

const char* dlcID = "expansion_pack_1";
if (TapDLC_IsOwned(dlcID)) {
    std::cout << "User owns DLC: " << dlcID << std::endl;
    EnableDLCContent(dlcID);
} else {
    std::cout << "User does not own DLC: " << dlcID << std::endl;
    DisableDLCContent(dlcID);
}

TapDLC_ShowStore​

Show the store page for the specified DLC.

bool TapDLC_ShowStore(const char *dlc_id);

Parameters:

  • dlc_id: DLC ID

Return Value:

  • true: Successfully displayed store page
  • false: Display failed

Usage Example:

const char* dlcID = "expansion_pack_1";
if (!TapDLC_IsOwned(dlcID)) {
    // User does not own the DLC, guide the user to purchase it
    if (TapDLC_ShowStore(dlcID)) {
        std::cout << "DLC store page opened" << std::endl;
    } else {
        std::cout << "Failed to open DLC store page" << std::endl;
    }
}

Event Handling Examples​

Complete Event Handling Example​

#include "taptap_api.h"
#include <iostream>

// Authorization completion event handling
void T_CALLTYPE OnAuthorizeFinished(TapEventID eventID, void* data) {
    if (eventID == TapEventID::AuthorizeFinished) {
        AuthorizeFinishedResponse* response = (AuthorizeFinishedResponse*)data;
        
        if (response->is_cancel) {
            std::cout << "User canceled authorization" << std::endl;
        } else if (strlen(response->error) > 0) {
            std::cout << "Authorization failed: " << response->error << std::endl;
        } else {
            std::cout << "Authorization successful!" << std::endl;
            std::cout << "Token type: " << response->token_type << std::endl;
            std::cout << "Permission scope: " << response->scope << std::endl;
            
            // Get user information
            char openID[256];
            if (TapUser_GetOpenID(openID)) {
                std::cout << "User OpenID: " << openID << std::endl;
            }
        }
    }
}

// Game playable status change event handling
void T_CALLTYPE OnGameStatusChanged(TapEventID eventID, void* data) {
    if (eventID == TapEventID::GamePlayableStatusChanged) {
        GamePlayableStatusChangedResponse* response = (GamePlayableStatusChangedResponse*)data;
        
        if (response->is_playable) {
            std::cout << "Game can now continue running" << std::endl;
        } else {
            std::cout << "Game is no longer available, possibly refunded" << std::endl;
            // Should save game progress and exit
            SaveGameAndExit();
        }
    }
}

// DLC status change event handling
void T_CALLTYPE OnDLCStatusChanged(TapEventID eventID, void* data) {
    if (eventID == TapEventID::DLCPlayableStatusChanged) {
        DLCPlayableStatusChangedResponse* response = (DLCPlayableStatusChangedResponse*)data;
        
        std::cout << "DLC " << response->dlc_id 
                  << (response->is_playable ? " is now available" : " is now unavailable") << std::endl;
        
        if (response->is_playable) {
            EnableDLCFeatures(response->dlc_id);
        } else {
            DisableDLCFeatures(response->dlc_id);
        }
    }
}

void SetupEventHandlers() {
    // Register all event callbacks
    TapSDK_RegisterCallback(TapEventID::AuthorizeFinished, OnAuthorizeFinished);
    TapSDK_RegisterCallback(TapEventID::GamePlayableStatusChanged, OnGameStatusChanged);
    TapSDK_RegisterCallback(TapEventID::DLCPlayableStatusChanged, OnDLCStatusChanged);
}