Quick Start

Integration Steps

• This document demonstrates basic feature integration steps using C++ as an example. Other languages can refer to the corresponding DLL calling methods.
• Before starting integration, please ensure you have completed Integration Preparation and Basic Integration Steps.

1. Initialization and Launch Verification Example

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.

#include <iostream>
#include <string>

#include "taptap_api.h"

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 the 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 the game from the launcher" << std::endl;
            return -1;
        case TapSDK_Init_Result::PlatformVersionMismatch:
            std::cout << "Platform version mismatch, please upgrade TapTap launcher or game to the latest version" << std::endl;
            return -1;
        default:
            std::cout << "Initialization failed: " << errMsg << std::endl;
            std::cout << "Please close the game and reopen it 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;
}

2. 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 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 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;
            
            // Print all content of 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;
    }
}

3. 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);
    }
}

4. Game Ownership Status Change Monitoring Example

For premium games, when users refund or other situations occur, 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 ownership 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" << std::endl;
            // Restore game features
            EnableGameFeatures();
        } else {
            std::cout << "Game is not playable, possibly due to refund or other reasons" << std::endl;
            
            // Display notification to user
            ShowRefundNotification();
            
            // Optional: Save user progress before exiting game
            SaveUserProgress();
            
            // Delay exit to give user time to view notification
            std::cout << "Game will exit in 10 seconds..." << std::endl;
            Sleep(10000);
            ExitGame();
        }
    }
}

void SetupGameStatusMonitoring() {
    // Register game ownership 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 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 to continue playing" << std::endl;
}

Development and Debugging

During the pre-release period, developers can add test users to the whitelist and download TapTap PC client, then choose the corresponding test solution according to 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 and does not require uploading 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 features.

Package Upload Testing Solution

This solution is suitable for self-testing before release. You can upload packages to TapTap platform and download the game 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 client locally on Windows and log in with test account, click "Self-Test Now" or copy the self-test link to browser.

tip

Note: When releasing the game, please be sure to delete the taptap_client_id.txt debug text file in the game directory

Game 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 a value other than TapSDK_Init_Result::OK
• Call TapSDK_RunCallbacks once per frame or multiple frames
• Call TapSDK_Shutdown when exiting the game

Login

• Guide the user to retry when TapUser_AsyncAuthorize returns a value other than TapUser_AsyncAuthorize_Result::OK
• Properly handle user cancellation and error data returned by TapEventID::AuthorizeFinished event, guide the user to retry

License Verification (Premium Games)

• Listen to TapEventID::GamePlayableStatusChanged to get game unplayable events (triggered by user refunds, being blocked, etc.)
• Listen to TapEventID::DLCPlayableStatusChanged to get user purchase/refund DLC events