XDSDK v7 C++（Windows）快速接入指南
· 阅读需 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 技术支持。