Skip to main content
Version: v4

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:

  1. Register a developer account at TapTap Developer Center
  2. 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 file
  • taptap_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

Initialization Requirements

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.

tip

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.

tip

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 returns true
  • 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