XDSDK v7 C++（Windows）快速接入指南

2026年3月25日 · 阅读需 4 分钟

环境要求

Windows 10 x64 及以上。
MSVC（Visual Studio 2019+，即 MSVC 14.2+）。
C++17 或更高标准。
CMake ≥ 3.20（仅 CMake 接入方式需要）。

SDK 包结构

XDSDK_Win_vX.X.X/
├── include/              # C API 头文件（推荐）
│   └── xdsdk/
│       ├── xdg_common_api.h
│       └── xdg_account_api.h
├── include_cpp/          # C++ API 头文件
│   └── xdsdk/
├── lib/                  # 链接库 (.lib)
├── bin/                  # 运行时 DLL + resources/
├── cmake/                # CMake find_package 支持
├── XDSDK.props           # Visual Studio 属性表
└── XDConfig.json.template

接入配置

方式一：Visual Studio

解压 SDK 到任意目录
Visual Studio 菜单：视图 → 其他窗口 → 属性管理器
右键项目 → 添加现有属性表，选择 XDSDK.props

XDSDK.props 自动完成以下配置：

添加 include/ 到头文件搜索路径。
添加 lib/ 并链接 xdsdk_common.lib、xdsdk_account.lib。
构建后自动将 bin/ 下所有 DLL 和 resources/ 复制到输出目录。

属性表仅配置了 include/（C API）。如需使用 include_cpp/ 下的 C++ API，请在项目属性中手动添加该路径。

也可以直接编辑 .vcxproj 文件，在 <ImportGroup Label="PropertySheets"> 中添加：

<ImportGroup Label="PropertySheets">
  <Import Project="path\to\XDSDK_Win_vX.X.X\XDSDK.props" />
</ImportGroup>

同时确保项目设置了 C++17：

<PropertyGroup>
  <LanguageStandard>stdcpp17</LanguageStandard>
</PropertyGroup>

方式二：CMake

find_package(XDSDK CONFIG REQUIRED PATHS "path/to/XDSDK/cmake")

target_link_libraries(MyGame PRIVATE XDSDK::common XDSDK::account)

# 自动将运行时 DLL 和 resources/ 复制到输出目录
xdsdk_copy_runtime_dlls(MyGame)

配置文件

将 XDConfig.json.template 重命名为 XDConfig.json，填写后放到游戏 exe 同级目录：

game.exe
XDConfig.json    ← 放这里

{
  "client_id": "你的 Client ID",
  "region_type": "CN",
  "tapsdk": {
    "client_id": "TapTap Client ID",
    "client_token": "TapTap Client Token",
    "db_config": {
      "enable": true,
      "channel": "steam",
      "game_version": "1.0.0"
    }
  }
}

初始化

#include <xdsdk/xdg_common_api.h>
#include <xdsdk/xdg_account_api.h>
#include <windows.h>

// 前置声明
void on_user_status(int status_code, const char* message);
void on_init(int success, const char* msg);

int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int) {
    XDG_SetUserStatusCallback(on_user_status);
    XDG_InitSDK(on_init);

    MSG msg;
    while (GetMessage(&msg, NULL, 0, 0)) {
        TranslateMessage(&msg);
        DispatchMessage(&msg);
    }
    return 0;
}

void on_login_success(const char* user_json) {
    // user_json: {"user_id":"...","name":"...","avatar":"...","login_type":5,"token":"..."}
}

void on_login_error(const char* error_json) {
    // error_json: {"code":...,"message":"..."}
}

// 在初始化回调中发起登录
void on_init(int success, const char* msg) {
    if (!success) return;
    XDG_Login(XDG_LOGIN_TYPE_DEFAULT, on_login_success, on_login_error);
}

登录类型

常量	值	说明
`XDG_LOGIN_TYPE_DEFAULT`	0	默认（显示登录选择界面）
`XDG_LOGIN_TYPE_GUEST`	1	游客登录
`XDG_LOGIN_TYPE_TAPTAP`	5	TapTap 登录

用户状态

在调用登录前，通过 XDG_SetUserStatusCallback 注册用户状态回调。

void on_user_status(int status_code, const char* message) {
    if (status_code == XDG_USER_STATUS_LOGOUT) {
        // 返回登录页面并展示登录按钮
        // 注意：此时不要再调用自动登录接口
    }
}

状态码

常量	值	触发时机
`XDG_USER_STATUS_LOGOUT`	0	登出
`XDG_USER_STATUS_BIND`	1	绑定第三方账号完成
`XDG_USER_STATUS_UNBIND`	2	解绑第三方账号完成
`XDG_USER_STATUS_PROTOCOL_AGREED`	3	用户同意协议

API 参考

Common 模块（xdg_common_api.h）

函数	说明
`XDG_InitSDK(callback)`	初始化 SDK，从 XDConfig.json 读取配置
`XDG_InitSDKWithParam(channel, lang, pkg, callback)`	带渠道/语言/包类型参数初始化
`XDG_IsInitialized()`	是否已初始化，返回 1/0
`XDG_SetLanguage(lang)`	设置语言，使用 `XDG_LANG_*` 常量
`XDG_SetTargetCountryOrRegion(code)`	设置目标国家/地区，如 `"KR"`
`XDG_OpenWebPage(url, callback)`	打开网页
`XDG_TrackUser(user_id, props_json)`	TapDB 追踪用户
`XDG_TrackRole(role_id, name, level, server_id, props_json)`	TapDB 追踪角色
`XDG_TrackEvent(event_name, props_json)`	TapDB 追踪自定义事件
`XDG_GetDeviceId()`	获取设备 ID
`XDG_RequestAnnouncementUnread(server, channel, extra, callback)`	查询公告未读状态
`XDG_OpenAnnouncementPage(server, channel, extra, callback)`	打开公告页面
`XDG_GetVersion()`	获取 SDK 版本号

Account 模块（xdg_account_api.h）

函数	说明
`XDG_Login(type, on_success, on_error)`	登录
`XDG_Logout()`	登出
`XDG_IsLoggedIn()`	是否已登录，返回 1/0
`XDG_GetCurrentUser()`	获取当前用户 JSON，未登录返回 `"{}"`
`XDG_OpenUserCenter()`	打开用户中心
`XDG_Bind(type, callback)`	绑定第三方账号
`XDG_Unbind(type, callback)`	解绑第三方账号
`XDG_SetUserStatusCallback(callback)`	注册用户状态回调（传 NULL 取消）

语言常量

常量	值	说明
`XDG_LANG_AUTO`	-1	自动检测
`XDG_LANG_ZH_HANS`	0	简体中文
`XDG_LANG_ZH_HANT`	1	繁体中文
`XDG_LANG_EN`	2	英语
`XDG_LANG_TH`	3	泰语
`XDG_LANG_ID`	4	印尼语
`XDG_LANG_KO`	5	韩语
`XDG_LANG_JA`	6	日语
`XDG_LANG_DE`	7	德语
`XDG_LANG_FR`	8	法语
`XDG_LANG_PT`	9	葡萄牙语
`XDG_LANG_ES`	10	西班牙语
`XDG_LANG_TR`	11	土耳其语
`XDG_LANG_RU`	12	俄语
`XDG_LANG_VI`	13	越南语

日志

SDK 运行日志自动写入以下路径（相对于游戏 exe）：

resources/logs/xdsdk_<client_id>.log

注意事项

C API 返回的字符串使用内部静态缓冲区，无需释放，但请在下次调用同一函数前复制。
所有回调在 SDK 内部线程触发，如需操作 UI 请切换到主线程。

技术支持

如有问题请联系 SDK 技术支持。

环境要求​

SDK 包结构​

接入配置​

方式一：Visual Studio​

方式二：CMake​

配置文件​

初始化​

登录​

登录类型​

用户状态​

状态码​

API 参考​

Common 模块（xdg_common_api.h）​

Account 模块（xdg_account_api.h）​

语言常量​

日志​

注意事项​

技术支持​