文档中心 | 一键联接，全心服务

更新日期：2025年 12月 12日QuickGame(App Store Unreal Engine)客户端接入文档

<h3> 1. 概述 </h3> 本⽂档介绍如何将 QuickGameSDK集成到 Unreal Engine iOS 项⽬ SDK 提供了初始化、登录、退出登录、⽀付和上传⻆⾊信息等功能 接⼊时可参考UE Demo，配合iOS原⽣接⼊⽂档：QuickGame_AppStore客户端接⼊⽂档.pdf（在下载的SDK资源里获取此文档） <h3> 2. 版本信息 </h3> SDK 版本: 2.7.0 UE 版本: 5.7 ⽀持平台: iOS 10.0+ ⽀持Xcode: 16.0+ <h3> 3. 快速开始 </h3> 最⼩集成步骤： 1. 复制 SDK ⽂件到项⽬ JySDK/iOS/SDK/ ⽬录 2. 配置 Info.plist（⻅下⽅详细说明） 3. 获取 Product Code（从 SDK 后台创建产品后获取） 4. 调⽤初始化接⼝： UJySDKManager::GetInstance()->InitializeSDK(ProductCode) 5. 绑定回调并调⽤登录： SDKManager->Login() 详细步骤请参考下⽅"8. 集成步骤"章节 <h3> 4. 架构说明 </h3> SDK 接⼝采⽤分层架构设计，接⼝调⽤层次如下： <pre class="brush:js;toolbar:false">UE 代码层 ↓ JySDKManager (UE 封装层) - 类型转换: FString ↔ std::string - 委托系统: UE 委托 ↔ std::function ↓ QuickGameSDK::SDK (标准 C++ 接⼝层) - 纯 C++ 接⼝，类似其他 SDK 的使⽤⽅式 - 使⽤标准库类型（std::string, std::function） ↓ JySDKBridge (C 接⼝层) ↓ JySDKBridge.mm (Objective-C++ 桥接层) ↓ 原⽣ iOS SDK (Objective-C)</pre>   <h3> 5. ⽂件结构 </h3> <pre class="brush:js;toolbar:false">Source/QuickGameIOS/IOS/ ├── QuickGameSDK.h         # 标准 C++ 接⼝头⽂件 ├── QuickGameSDK.cpp       # 标准 C++ 接⼝实现 ├── JySDKBridge.h         # C 接⼝头⽂件 ├── JySDKBridge.mm         # Objective-C++ 桥接实现 ├── JySDKManager.h         # UE C++ 接⼝类（暴露给蓝图） ├── JySDKManager.cpp       # UE C++ 接⼝实现（内部调⽤ QuickGameSDK） └── JySDKAppDelegate.mm   # AppDelegate URL回调处理 JySDK/iOS/SDK/ ├── JySDK.framework       # 主 SDK 框架（必需） ├── jywlRes.bundle       # SDK 资源包（必需） ├── ATAuthSDK.framework # 阿⾥云⼀键登录 SDK（必需） ├── ATAuthSDK.bundle     # ATAuthSDK 资源包（必需） ├── YTXMonitor.framework # 运营商 SDK（必需） ├── YTXOperators.framework # 运营商 SDK（必需） ├── TencentOpenAPI.framework # QQ SDK（必需，⽤于QQ登录） └── libWeChatSDK.a       # 微信 SDK 静态库（必需，⽤于微信登录）</pre> <h3> 6. 使⽤⽅法 </h3> <h4> 6.1 在蓝图中使⽤ </h4> 6.1.1 初始化SDK 1. 获取JySDKManager实例 调⽤ Get Instance 节点 2. 初始化SDK 调⽤ Initialize SDK 节点 输⼊参数： Product Code （产品Code，从QuickGameSDK后台获取） 3. 绑定初始化回调 绑定 On Init Complete 委托 检查返回的 Status ： InitSuccess (2000)  - 初始化成功 InitFail (2001)  - 初始化失败 6.1.2 登录 1. 调⽤登录 调⽤ Login 节点 2. 绑定登录回调 绑定 On Login Complete 委托 回调参数： Status  - 登录状态码 UserId  - ⽤户ID Token  - ⽤户Token（⽤于服务器验证） Message  - 消息 6.1.3 退出登录 调⽤退出登录 调⽤ Logout 节点 退出登录后，SDK 会隐藏悬浮球并清除登录状态 6.1.4 ⽀付 1. 调⽤⽀付 调⽤ Pay 节点 输⼊参数： Product Id  - 商品ID（必填） Product Name  - 商品名称（必填） Product Desc  - 商品描述（可选） Price  - 价格（必填，单位：元） Order No  - 游戏订单号（必填，必须唯⼀） Url  - 回调通知地址（可选） Extras  - 透传参数（可选） 2. 绑定⽀付回调 绑定 On Pay Complete 委托 回调参数： Status  - ⽀付状态码： OrderSuccess (3000)  - ⽀付成功 OrderFail (3001)  - ⽀付失败 OrderCancel (3002)  - ⽀付取消 OrderUnknown (3003)  - ⽀付未知状态 Order No  - 订单号 Product Id  - 商品ID Transaction Id  - 交易ID Message  - 消息 6.1.5 上传⻆⾊信息 调⽤上传⻆⾊ 调⽤ Update Role Info 节点 必填参数： Role Id  - ⻆⾊ID Role Name  - ⻆⾊名称 Server Id  - 区服ID Server Name  - 区服名称 可选参数： Role Level  - ⻆⾊等级 Vip Level  - VIP等级 Role Power  - ⻆⾊战⼒ Game Role Balance  - ⻆⾊余额 Party Name  - ⼯会名称   6.1.6 获取⽤户信息 Get User Id  - 获取⽤户ID Get User Token  - 获取⽤户Token Is Logined  - 是否已登录 Is Guest  - 是否为游客 <h4> 6.2 在C++中使⽤ </h4> ⽅式⼀：使⽤ UE 封装层（⽀持蓝图） <pre class="brush:js;toolbar:false">#include "IOS/JySDKManager.h" // 获取实例 UJySDKManager* SDKManager = UJySDKManager::GetInstance(); // 初始化 SDKManager->InitializeSDK(TEXT("YOUR_PRODUCT_CODE")); // 绑定回调 SDKManager->OnInitComplete.AddDynamic(this, &AMyGameMode::HandleInitComplete); SDKManager->OnLoginComplete.AddDynamic(this, &AMyGameMode::HandleLoginComplete); SDKManager->OnPayComplete.AddDynamic(this, &AMyGameMode::HandlePayComplete); // 登录 SDKManager->Login(); // 退出登录 SDKManager->Logout(); // ⽀付 SDKManager->Pay(    TEXT("product_id"),    TEXT("商品名称"),    TEXT("商品描述"),    1.0f,  // 价格    TEXT("order_12345"),    TEXT(""),  // URL    TEXT("")   // Extras ); // 上传⻆⾊ SDKManager->UpdateRoleInfo(    TEXT("role_123"),    TEXT("⻆⾊名"),    TEXT("server_1"),    TEXT("服务器1"),    TEXT("10"),  // Level    TEXT("1"),   // VIP    TEXT(""),    // Power    TEXT(""),    // Balance    TEXT(""),    // Party );</pre> ⽅式⼆：使⽤标准 C++ 接⼝ <pre class="brush:js;toolbar:false">#include "IOS/QuickGameSDK.h" using namespace QuickGameSDK; // 获取实例 SDK& sdk = SDK::GetInstance(); // 初始化（使⽤ lambda 回调） sdk.Initialize("YOUR_PRODUCT_CODE", [](Status status) {    if (status == Status::InitSuccess) {        // 初始化成功   } }); // 登录 sdk.Login([](Status status, const std::string& userId, const std::string& token, const std::string& message) {    if (status == Status::Success) {        // 登录成功   } }); // ⽀付 sdk.Pay(    "product_id",    "商品名称",    "商品描述",    1.0f,    "order_12345",    "",  // URL    "",  // Extras   [](Status status, const std::string& orderNo, const std::string& productId,       const std::string& transactionId, const std::string& message) {        if (status == Status::OrderSuccess) {            // ⽀付成功       }   } ); // 上传⻆⾊ sdk.UpdateRoleInfo(    "role_123",    "⻆⾊名",    "server_id",    "服务器名",    "10",  // ⻆⾊等级 );</pre> <h3> 7. API 参考 </h3> UJySDKManager 类 7.1 静态⽅法 static UJySDKManager* GetInstance()  - 获取单例实例 7.2 初始化与登录 void InitializeSDK(const FString& ProductCode)  - 初始化 SDK void Login()  - 调⽤登录 void Logout()  - 退出登录 7.3 ⽀付 void Pay(const FString& ProductId, const FString& ProductName, const FString& ProductDesc, float Price, const FString& OrderNo, const FString& Url, const FString& Extras)  - 发起⽀付 7.4 ⻆⾊信息 void UpdateRoleInfo(...)  - 上传⻆⾊信息（参数⻅上⽅说明） 7.5 ⽤户信息查询 FString GetUserId()  - 获取⽤户 ID FString GetUserToken()  - 获取⽤户 Token bool IsLogined()  - 是否已登录 bool IsGuest()  - 是否为游客账号 7.6 回调委托 FOnInitComplete OnInitComplete  - 初始化完成回调 FOnLoginComplete OnLoginComplete  - 登录完成回调 FOnPayComplete OnPayComplete  - ⽀付完成回调 7.7 状态码说明 ErrorNone (1000)  - 事件成功 InitSuccess (2000)  - 初始化成功 InitFail (2001)  - 初始化失败 OrderSuccess (3000)  - ⽀付成功 OrderFail (3001)  - ⽀付失败 OrderCancel (3002)  - ⽀付取消 OrderUnknown (3003)  - ⽀付未知状态   <h3> 8. 集成步骤 </h3> 8.1 ⽂件结构要求 确保 SDK ⽂件位于项⽬根⽬录下的 JySDK/iOS/SDK/ ⽬录： <pre class="brush:js;toolbar:false">QuickGameIOS/ └── JySDK/   └── iOS/       └── SDK/           ├── JySDK.framework       # 主 SDK 框架（必需）           ├── jywlRes.bundle       # SDK 资源包（必需）           ├── ATAuthSDK.framework   # 阿⾥云⼀键登录 SDK（必需）           ├── ATAuthSDK.bundle     # ATAuthSDK 资源包（必需）           ├── YTXMonitor.framework # 运营商 SDK（必需）           ├── YTXOperators.framework # 运营商 SDK（必需）           ├── TencentOpenAPI.framework # QQ SDK（⽤于QQ登录）           └── libWeChatSDK.a         # 微信 SDK 静态库（⽤于微信登录）</pre> 注意：所有框架和资源包都是必需的，缺少任何⼀个都可能导致编译或运⾏时错误 8.2 编译配置 SDK 框架和资源需要配置到 Source/QuickGameIOS/QuickGameIOS.Build.cs 中，可参考Demo： 主 SDK： Framework: JySDK.framework Bundle: jywlRes.bundle 依赖框架： ATAuthSDK.framework  - 阿⾥云⼀键登录 SDK（必需） ATAuthSDK.bundle  - ATAuthSDK 资源包（必需） YTXMonitor.framework  - 监控 SDK（必需） YTXOperators.framework  - 运营商 SDK（必需） TencentOpenAPI.framework  - QQ SDK（⽤于QQ登录） libWeChatSDK.a  - 微信 SDK 静态库（⽤于微信登录） 系统框架依赖： Foundation  - 基础框架 UIKit  - UI 框架 StoreKit  - 内购框架 CoreTelephony  - 运营商信息（必需） SystemConfiguration  - ⽹络配置（必需） 8.3 Info.plist 配置（重要） 需要在 Xcode的 info.plist中添加以下配置： NSAppTransportSecurity（⽹络访问权限） <pre class="brush:js;toolbar:false"><key>NSAppTransportSecurity</key> <dict> <key>NSAllowsArbitraryLoads</key> <true/> </dict></pre> LSApplicationQueriesSchemes（URL Schemes ⽩名单） ⽤于⽀持第三⽅登录（微信、QQ等），需要在⽩名单中声明： <pre class="brush:js;toolbar:false"><key>LSApplicationQueriesSchemes</key> <array> <string>mqq</string> <string>mqqopensdkapi</string> <string>mqqopensdkapiV2</string> <string>mqqopensdkapiV3</string> <string>weixin</string> <string>weixinULAPI</string> </array></pre> CFBundleURLTypes（微信和QQ回调URL Scheme） 如果使⽤微信或QQ登录，需要配置 URL Scheme ⽤于回调： <pre class="brush:js;toolbar:false"><key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleTypeRole</key> <string>Editor</string> <key>CFBundleURLSchemes</key> <array> <string>wxYOUR_WECHAT_APP_ID</string>  </array> </dict> <dict> <key>CFBundleTypeRole</key> <string>Editor</string> <key>CFBundleURLSchemes</key> <array> <string>tencentYOUR_QQ_APP_ID</string>  </array> </dict> </array></pre> 提示： 微信 URL Scheme 格式： wx[你的微信AppID] QQ URL Scheme 格式： tencent[你的QQ AppID] 如果不使⽤微信/QQ登录，可以省略此配置 NSPhotoLibraryUsageDescription（相册权限） <pre class="brush:js;toolbar:false"><key>NSPhotoLibraryUsageDescription</key> <string>需要访问相册以保存游客账号信息</string> <key>NSPhotoLibraryAddUsageDescription</key> <string>需要访问相册以保存游客账号信息</string></pre> <div style="white-space:nowrap;"> </div>