Quick Start
System Requirements
- Operating System: Windows 7 or later 64-bit operating system
- Runtime Environment: Games must be launched through the TapTap launcher
- Network Requirements: Internet connection required for authorization and verification
- SDK Type: Dynamic Link Library (DLL)
Prerequisites
1. Get Developer Resources
Before starting integration, you need to:
- Register a developer account at TapTap Developer Center
- Create a game application and obtain the following information from "Your Games" → "Game Services" → "App Configuration":
- Client ID: Unique identifier for the application
- Client Public Key: Public key string for SDK initialization
2. Download SDK
Visit the TapSDK PC C++ Releases page to download the latest version of the SDK.
The SDK contains the following files:
taptap_api.h
: Header filetaptap_api.dll
: Dynamic library file (Windows)taptap_api.lib
: Import library file (Windows)
Integration Steps
Language Support
The PC SDK is provided as a Dynamic Link Library (DLL) and supports integration with multiple programming languages:
- C++: Directly include the header file
taptap_api.h
- Other Languages: Implement through each language's DLL calling mechanism
This documentation demonstrates integration steps using C++ as an example. Other languages can refer to their respective DLL calling methods.
1. Add SDK Files
Add the downloaded SDK files to your project:
C++ Project:
#include "taptap_api.h"
Other Languages:
- Place
taptap_api.dll
in the same directory as the executable or in the system path - Load the DLL and declare function signatures according to the language's characteristics
2. Initialization and Launch Verification Example
Except for TapSDK_RestartAppIfNecessary
, all other API functions must be called only after successfully calling TapSDK_Init
for initialization.
Calling other functions without initialization or after initialization failure will return errors or unexpected results.
#include "taptap_api.h"
#include <iostream>
#include <string>
int main() {
const char* clientID = "your_client_id_here";
const char* pubKey = "your_client_public_key_here";
// 1. Check if app restart is necessary
// SDK depends on launching the game from TapTap. If user runs the game executable directly, this function returns true
if (TapSDK_RestartAppIfNecessary(clientID)) {
std::cout << "App restart required, TapTap will restart the game" << std::endl;
return 0; // Exit immediately and wait for TapTap to restart
}
// 2. Initialize SDK
ErrMsg errMsg;
TapSDK_Init_Result result = TapSDK_Init(&errMsg, pubKey);
switch (result) {
case TapSDK_Init_Result::OK:
std::cout << "SDK 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;
return -1;
case TapSDK_Init_Result::NotLaunchedByPlatform:
std::cout << "Game not launched through TapTap launcher, please reopen from launcher" << std::endl;
return -1;
case TapSDK_Init_Result::PlatformVersionMismatch:
std::cout << "Platform version mismatch, please upgrade TapTap launcher or game to latest version" << std::endl;
return -1;
default:
std::cout << "Initialization failed: " << errMsg << std::endl;
std::cout << "Please close the game and reopen from TapTap" << std::endl;
return -1;
}
// 3. Game main loop
bool running = true;
while (running) {
// Process SDK callback events
TapSDK_RunCallbacks();
// Your game logic
// ...
// Control frame rate, adjust according to your game's actual needs
Sleep(1);
}
// 4. Cleanup resources
TapSDK_Shutdown();
return 0;
}
3. Login Example
Through user authorization, you can obtain authorization credentials (including Token, MAC key, etc.). You can use these credentials to call TapTap Open API on the server side to get detailed user information. For specific API calling methods, please refer to the TapTap OAuth Documentation.
#include "taptap_api.h"
// Authorization completion callback function
void T_CALLTYPE OnAuthorizeFinished(TapEventID eventID, void* data) {
if (eventID == TapEventID::AuthorizeFinished) {
AuthorizeFinishedResponse* response = (AuthorizeFinishedResponse*)data;
if (response->is_cancel) {
std::cout << "User cancelled authorization" << std::endl;
} else if (strlen(response->error) > 0) {
std::cout << "Authorization failed: " << response->error << std::endl;
} else {
std::cout << "Authorization successful" << std::endl;
// Print all content of the response
std::cout << "=== Authorization Response Details ===" << std::endl;
std::cout << "Token Type: " << response->token_type << std::endl;
std::cout << "Key ID: " << response->kid << std::endl;
std::cout << "MAC Key: " << response->mac_key << std::endl;
std::cout << "MAC Algorithm: " << response->mac_algorithm << std::endl;
std::cout << "Scope: " << response->scope << std::endl;
std::cout << "=====================================" << std::endl;
}
}
}
void RequestUserAuthorization() {
// Register authorization completion callback
TapSDK_RegisterCallback(TapEventID::AuthorizeFinished, OnAuthorizeFinished);
// Request user authorization
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 process in progress, please wait" << std::endl;
break;
case TapUser_AsyncAuthorize_Result::Unknown:
std::cout << "Authorization failed, please check SDK initialization status" << std::endl;
break;
}
}
4. DLC Management Example
// DLC status change callback
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;
// Update game features based on DLC status
if (response->is_playable) {
// Enable DLC features
EnableDLCFeatures(response->dlc_id);
} else {
// Disable DLC features
DisableDLCFeatures(response->dlc_id);
}
}
}
void CheckDLCStatus() {
// Register DLC status change callback
TapSDK_RegisterCallback(TapEventID::DLCPlayableStatusChanged, OnDLCStatusChanged);
const char* dlcID = "your_dlc_id";
// Check DLC ownership
if (TapDLC_IsOwned(dlcID)) {
std::cout << "User owns DLC: " << dlcID << std::endl;
EnableDLCFeatures(dlcID);
} else {
std::cout << "User does not own DLC: " << dlcID << std::endl;
// Can guide user to purchase
TapDLC_ShowStore(dlcID);
}
}
5. Game Status Change Monitoring Example
For premium games, when users experience refunds or other situations, the playable status of the game will change. The SDK will notify the game through callback events, and developers can prompt users or perform corresponding operations based on status changes.
// Game status change callback
void T_CALLTYPE OnGamePlayableStatusChanged(TapEventID eventID, void* data) {
if (eventID == TapEventID::GamePlayableStatusChanged) {
GamePlayableStatusChangedResponse* response = (GamePlayableStatusChangedResponse*)data;
if (response->is_playable) {
std::cout << "Game is now playable normally" << std::endl;
// Restore game features
EnableGameFeatures();
} else {
std::cout << "Game is not playable, possibly due to refund or other reasons" << std::endl;
// Show notification to user
ShowRefundNotification();
// Optional: Save user progress before exiting game
SaveUserProgress();
// Delay exit to give user time to read the notification
std::cout << "Game will exit in 10 seconds..." << std::endl;
Sleep(10000);
ExitGame();
}
}
}
void SetupGameStatusMonitoring() {
// Register game status change callback
TapSDK_RegisterCallback(TapEventID::GamePlayableStatusChanged, OnGamePlayableStatusChanged);
// Check current game ownership status
if (TapApps_IsOwned()) {
std::cout << "User owns the game, can play normally" << std::endl;
EnableGameFeatures();
} else {
std::cout << "User does not own the game or has been refunded" << std::endl;
ShowPurchasePrompt();
}
}
// Helper function examples
void ShowRefundNotification() {
std::cout << "=== Important Notice ===" << std::endl;
std::cout << "Your game has been refunded, game features will be restricted." << std::endl;
std::cout << "If you have any questions, please contact customer service or repurchase the game." << std::endl;
std::cout << "======================" << std::endl;
}
void EnableGameFeatures() {
// Enable full game features
std::cout << "Enabling full game features" << std::endl;
}
void SaveUserProgress() {
// Save user game progress
std::cout << "Saving game progress..." << std::endl;
}
void ExitGame() {
// Cleanup resources and exit game
TapSDK_Shutdown();
exit(0);
}
void ShowPurchasePrompt() {
std::cout << "Please purchase the game first to continue playing" << std::endl;
}
Development and Debugging
During the pre-release period, developers can add test users to the whitelist and download the TapTap PC client, then choose corresponding testing solutions based on different development stages.
Add Whitelist
Go to Developer Center > Store > Version Release > Testing > Internal Testing page, select "Create Test Plan" and add test user whitelist. Example video below:
Download TapTap PC Client
Download TapTap PC Client and log in with the configured whitelist account.
Local Testing Solution
This solution is suitable for self-testing during development phase, no need to upload packages to TapTap. Developers can go to TapTap Developer Center >> Game Services >> Launch Verification page and click Configuration File
, as shown:
The browser will download a text file named taptap_client_id.txt
. Developers need to move this file to the directory where the game executable is located, then they can launch the game locally and start testing related business functions.
Package Upload Testing Solution
This solution is suitable for pre-release self-testing, can upload packages to TapTap platform and download games for testing.
1. Upload Game Package
Go to Developer Center >> Store >> PC Package Management >> Package Management, click "Upload Package", select the package file, and fill in the launch configuration.
If your game has dependencies, please place the dependency installation files in the game directory and upload them together. In PC Package Management >> Basic Configuration, select the corresponding library and its launch configuration. TapTap will help complete the dependency installation when users click to download and install the game.
2. Complete Package Self-Testing
After test users download TapTap PC version locally on Windows computers and log in with test accounts, click "Start Self-Test" or copy the self-test link to browser.
Note: When releasing the game, please make sure to delete the taptap_client_id.txt
debug text file from the game directory
Pre-Release Checklist
Initialization and Launch Verification
- Exit the game when
TapSDK_RestartAppIfNecessary
returnstrue
- Prompt the user and exit the game when
TapSDK_Init
returns non-TapSDK_Init_Result::OK
- Call
TapSDK_RunCallbacks
once per frame or multiple frames - Call
TapSDK_Shutdown
when exiting the game
Login
- Prompt the user and guide them to retry when
TapUser_AsyncAuthorize
returns non-TapUser_AsyncAuthorize_Result::OK
- Properly handle user cancellation and error data returned by
TapEventID::AuthorizeFinished
event, prompt the user and guide them to retry
License Verification
- Listen to
TapEventID::GamePlayableStatusChanged
to get game unplayable events (triggered by user refunds, being blocked, etc.) - Listen to
TapEventID::DLCPlayableStatusChanged
to get user purchase and refund DLC events