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

更新日期：2026年 09月 14日QuickGame(Unity)客户端接入文档

<h4> </h4> <h4> </h4> <h4> </h4> <h4> </h4> <h4> </h4> <h4> 一、 Unity部分 </h4> 1. 概述 QuickGameSDK 为 Unity 游戏提供了一套覆盖Android、 iOS、WebGL（小游戏）、Windows PC全平台的接入方案。CP 只需按如下步骤操作出包： 1. 集成 Unity 脚本与平台插件   2. 配置 QKSettings.asset 3. 实现 QuickListener 接收回调   4. 调用 QKGame完成初始化、登录、支付、角色上报等   5. 按目标平台 Build，导出对应平台的包 2. 环境与版本 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 项 </td> <td> 说明 </td> </tr> <tr> <td> Unity  </td> <td> 建议2018.4 LTS及以上（参考工程 2022.3 LTS） </td> </tr> <tr> <td> 脚本运行时 </td> <td> .NET 4.x / 兼容 Unity 默认 API Level  </td> </tr> <tr> <td> JSON </td> <td> 依赖Newtonsoft.Json（发版包 Assets/Plugins/JsonNet/Newtonsoft.Json.dll） </td> </tr> <tr> <td> 参考工程 </td> <td> unitybridgecn（本仓库） </td> </tr> <tr> <td> Demo 场景 </td> <td> Assets/Scenes/QuickGameDemo.unity </td> </tr> <tr> <td> 统一配置 </td> <td> Assets/Resources/QKSettings.asset`（菜单 QuickSDK → Settings） </td> </tr> </tbody> </table> 3. 工程集成 3.1 拷贝到自有 Unity 工程 必选（所有平台） Assets/QuickGameSDK/Scripts/     # QKGame.cs、QuickListener.cs、各平台 Bridge Assets/Plugins/JsonNet/Newtonsoft.Json.dll Assets/Resources/QKSettings.asset        # 或通过 QuickSDK → Settings 创建 按平台追加 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td style="text-align:left;width:6%;"> 平台 </td> <td style="text-align:left;">  额外目录 / 资源  </td> </tr> <tr> <td style="text-align:left;"> Android </td> <td style="text-align:left;"> Assets/Plugins/Android/（QKConnector.java、libs/*.aar、AndroidManifest.xml、Gradle 模板）+ `Editor/AndroidPreprocessBuild.cs、AndroidPostGenerateGradle.cs </td> </tr> <tr> <td style="text-align:left;"> iOS  </td> <td style="text-align:left;"> Assets/QuickGameSDK/Editor/IOSPostProcessBuild.cs、QuickGameIOSIntegrationSettings.cs；原生 SDK 放iOS/releaseSDK（或设 UNITY_QUICKGAME_SDK_ROOT） </td> </tr> <tr> <td style="text-align:left;"> 小游戏  </td> <td style="text-align:left;"> Assets/QuickGameSDK/Channels/<渠道>/QGSDK.js + Editor/QuickGameWebGLChannelBuilder.cs + Assets/Plugins/WebGL/ </td> </tr> <tr> <td style="text-align:left;"> PC </td> <td style="text-align:left;"> Assets/Plugins/Windows/（含 WindowsQGAdapter.cs）+ StreamingAssets/Quicksdk/PCSDK_release/PCSDKUI.exe </td> </tr> </tbody> </table> 3.2 参考工程目录结构 Assets/ │   ├── QuickGameSDK/ │   │   ├── Scripts/          # QKGame、QuickListener、Android/WebGL Bridge │   │   ├── Editor/           # iOS / Android / WebGL 构建脚本 │   │   ├── Channels/         # wx、ali 等 QGSDK.js │   │   └── Demo/             # QuickGameDemoController / Listener ├── Plugins/ │   ├── Android/              # Java 桥接、AAR、Manifest │   ├── Windows/              # PC SDK + PackageSettings 定义 │   ├── WebGL/                # QuickGameWebGL.jslib、Bootstrap.jspre │   └── JsonNet/ ├── Resources/QKSettings.asset └── Scenes/QuickGameDemo.unity iOS/releaseSDK/               # 默认 iOS SDK（须含 iOS/SDK/JySDK.framework） 注意：iOS 的 QKConnector.mm在 Build 时由 IOSPostProcessBuild 从releaseSDK/Unity3d/1. Xcode/拷贝到导出工程，无需事先放在 Assets/Plugins/iOS/ 3.3 命名空间 using quickgame; // QKGame、QuickListener <pre class="brush:js;toolbar:false">// Windows / Android 配置类在 quicksdk 命名空间：PackageSettings（QKSettings.asset）</pre> 3.4 GameObject 命名 QKGame.setListener会把Listener 所在 GameObject 的名称 传给原生/宿主层，通过 UnitySendMessage回调。请保证： 1. 该物体在场景中名称固定（不要用运行时随机名）   2. 物体上挂载继承自 QuickListener的脚本   4. 接入流程 4.1 标准时序（全平台推荐） <pre class="brush:js;toolbar:false">启动 → setListener(QuickListener) // Awake → startSdk() // 读 QKSettings；iOS 自动三方登录；WebGL 自动 onSetHost + onInit → onInitSuccess / onInitFailed → onLogin() / onGuestLogin() → onUpdateRole(...) // Windows 支付前必调 → onPayOrder(QKPayOrderInfo) // 四端统一支付结构 → onLogout()</pre> startSdk(productCode, host)` 可覆盖 QKSettings 中的productCode/ baseUrl。仍可直接调用 onInit / onSetHost/ configureThirdPartyLogin（高级用法） Build 前在 QuickSDK → Settings 配置 baseUrl、productCode、（iOS 可选）微信/QQ 字段、miniGameChannel；WebGL 须 Rebuild WebGL Bridge或直接 WebGL Build。详见 WebGL.md 4.2 最小代码示例 <pre class="brush:js;toolbar:false">using UnityEngine; using quickgame; public class GameSdkListener : QuickListener { public override void onInitSuccess() { /* 进入登录流程 */ } public override void onInitFailed(ErrorMsg message) { } public override void onLoginSuccess(UserInfo userInfo) { /* uid / token */ } public override void onLoginFailed(ErrorMsg errMsg) { } public override void onLogoutSuccess() { } public override void onPaySuccess(PayResult payResult) { } public override void onPayFailed(PayResult payResult) { } public override void onPayCancel(PayResult payResult) { } } public class GameEntry : MonoBehaviour { [SerializeField] GameSdkListener listener; void Awake() => QKGame.setListener(listener); public void StartSdk() => QKGame.startSdk(); }</pre> 5. API 说明（QKGame） 入口类：Assets/QuickGameSDK/Scripts/QKGame.cs 接口分为两类： <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 分类 </td> <td> 说明 </td> </tr> <tr> <td> 全平台公共接口 </td> <td> Android/ iOS / 小游戏 / PC 四端签名与用法一致，业务代码可直接写、用 #if 区分初始化/支付即可 </td> </tr> <tr> <td> 平台专有接口 </td> <td> 仅特定平台可用，或各平台初始化/支付/查询方式不同 </td> </tr> </tbody> </table> 5.1 调用约定 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 约定 </td> <td> 说明 </td> </tr> <tr> <td> 回调注册 </td> <td> setListener须在 Awake最早调用，且 Listener 所在 GameObject 名称固定 </td> </tr> <tr> <td> 初始化 </td> <td> 公共业务前先 startSdk()（或手动 onInit/ WebGL onSetHost） </td> </tr> <tr> <td> 登录时机 </td> <td> 收到 onInitSuccess 后再 onLogin </td> </tr> <tr> <td> 角色上报 </td> <td> 创角、进入游戏、升级、换服等节点均须 onUpdateRole；Windows 支付前必须先上报 </td> </tr> <tr> <td> 支付  </td> <td> 推荐全平台onPayOrder；onPay仍作原生兼容别名 </td> </tr> <tr> <td> 支付发货 </td> <td> 客户端 onPaySuccess仅供参考，游戏发货必须以服务端异步通知为准 </td> </tr> <tr> <td> 登出后流程 </td> <td> onLogoutSuccess 后清除本地角色信息、回到登录界面，可按业务再调 onLogin() </td> </tr> </tbody> </table> 5.2 全平台公共接口 以下接口在Android、iOS、小游戏、PC 四端均可调用，方法名与参数一致 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 方法 </td> <td> 返回值 </td> <td> 回调 </td> <td> 说明 </td> </tr> <tr> <td> setListener(QuickListener) </td> <td> void  </td> <td> — </td> <td> 注册回调；必须最先调用 </td> </tr> <tr> <td> startSdk(productCode?, host?) </td> <td> void </td> <td> init 成功/失败  </td> <td> 推荐：读 QKSettings 并一站式初始化  </td> </tr> <tr> <td> onPayOrder(QKPayOrderInfo) </td> <td> void  </td> <td> pay 成功/失败/取消 </td> <td> 推荐：全平台统一支付  </td> </tr> <tr> <td> onLogin() </td> <td> void </td> <td> onLoginSuccess / onLoginFailed </td> <td> 调起 SDK 登录 </td> </tr> <tr> <td> onUserCenter() </td> <td> void  </td> <td> onUserCenterClose（可选） </td> <td> 打开用户中心 </td> </tr> <tr> <td> onLogout() </td> <td> void </td> <td> onLogoutSuccess </td> <td> 登出 </td> </tr> <tr> <td> onUpdateRole(...) </td> <td> void  </td> <td> —  </td> <td> 上报角色信息 </td> </tr> </tbody> </table> setListener(QuickListener listener) <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 参数 </td> <td> 类型 </td> <td> 必填 </td> <td> 说明 </td> </tr> <tr> <td> listener </td> <td> QuickListener </td> <td> 是 </td> <td> 继承 QuickListener 的组件；将 listener.gameObject.name 传给原生/宿主供 SendMessage 回调 </td> </tr> </tbody> </table> onLogin() / onUserCenter() / onLogout() 无参数。必须在 onInitSuccess 之后调用登录相关接口 onUpdateRole(roleId, role_name, server_Id, sv_name, role_level, vipLevel, role_power) <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 参数 </td> <td> 类型 </td> <td> 必填 </td> <td> 说明 </td> </tr> <tr> <td> roleId </td> <td> string </td> <td> 是 </td> <td> 角色 ID </td> </tr> <tr> <td> role_name </td> <td> string </td> <td> 是 </td> <td> 角色名 </td> </tr> <tr> <td> server_Id </td> <td> string </td> <td> 是 </td> <td> 区服 ID </td> </tr> <tr> <td> sv_name </td> <td> string </td> <td> 是 </td> <td> 区服名 </td> </tr> <tr> <td> role_level </td> <td> string </td> <td> 是 </td> <td> 角色等级 </td> </tr> <tr> <td> vipLevel </td> <td> string </td> <td> 否 </td> <td> VIP 等级；无则传""或 "0" </td> </tr> <tr> <td> role_power </td> <td> string </td> <td> 否 </td> <td> 战力等；WebGL 可解析为 userRoleBalance </td> </tr> </tbody> </table> 注意：创角、进游戏、升级、换服等节点均应调用。字符串勿传 null 。Windows 支付前必须先调用本接口 四端公共调用示例： <pre class="brush:js;toolbar:false">void Awake() => QKGame.setListener(this); void StartSdk() => QKGame.startSdk(); void OnEnterGame() { QKGame.onUpdateRole(id, name, sid, sname, lv, vip, power); QKGame.onLogin(); } void OnPay() => QKGame.onPayOrder(new QKGame.QKPayOrderInfo { /* 见 5.2.3 字段 */ });</pre> 5.3 平台专有接口 5.3.1 Android / iOS / Windows 公共（原生三端） 适用于 Android、iOS、Windows；WebGL **不使用本节初始化与支付接口 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 方法 </td> <td> 返回值 </td> <td> 回调 </td> <td> 说明 </td> </tr> <tr> <td> onInit() </td> <td> void  </td> <td> onInitSuccess / onInitFailed </td> <td> 初始化；无参时读 QKSettings 或桥接默认 productCode </td> </tr> <tr> <td> onInit(productCode) </td> <td> void  </td> <td> 同上 </td> <td> iOS 传产品码；Android 仍走无参 Init（见 5.2.2） </td> </tr> <tr> <td> onPay(...) </td> <td> void  </td> <td> pay 成功/失败/取消  </td> <td> 定额支付，见下表 </td> </tr> <tr> <td> onUserID() </td> <td> string  </td> <td> — </td> <td> 同步用户 ID；未登录返回 "" </td> </tr> <tr> <td> onUserToken() </td> <td> string  </td> <td> — </td> <td> 同步 token  </td> </tr> <tr> <td> onUserName() </td> <td> string  </td> <td> — | </td> <td> 同步用户名 </td> </tr> </tbody> </table> onPay 参数 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 参数 </td> <td> 类型 </td> <td> 必填 </td> <td> 说明 </td> </tr> <tr> <td> productId </td> <td> string </td> <td> 是  </td> <td> 商品 ID（iOS 为 App Store 商品 ID） </td> </tr> <tr> <td> productName </td> <td> string </td> <td> 是 </td> <td> 商品名；建议传「元宝」「月卡」等，不带数量 </td> </tr> <tr> <td> amount </td> <td> float </td> <td> 是  </td> <td> 金额（元） </td> </tr> <tr> <td> orderNo </td> <td> string </td> <td> 是 </td> <td> CP 订单号 </td> </tr> <tr> <td> callBackUrl </td> <td> string </td> <td> 否 </td> <td> 服务端回调 URL，可 ""，如果游戏下单时设置支付回调，建议支付回调地址加上IP白名单，防止被攥改！！！ </td> </tr> <tr> <td> extrasParams </td> <td> string </td> <td> 否  </td> <td> 透传，回调在 PayResult.extras </td> </tr> </tbody> </table> 5.3.2 iOS 专有 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 方法 </td> <td> 返回值 </td> <td> 说明 </td> </tr> <tr> <td> onInit(productCode) </td> <td> void </td> <td> 与 5.2.1 相同签名；iOS 真机将 productCode 传入QKConnector；空则读 QKSettings/ 桥接默认 </td> </tr> <tr> <td> configureThirdPartyLogin(wxAppId, wxAppSecret, wxUniversalLink, qqAppId, qqUniversalLink) </td> <td> void </td> <td> 微信/QQ 登录；必须 onInit() 之前；不用的渠道传 "" </td> </tr> <tr> <td> onDeviceIdfa() </td> <td> string </td> <td> 同步 IDFA；非 iOS 返回 "" </td> </tr> </tbody> </table> configureThirdPartyLogin 参数须与 Info.plist、开放平台后台一致；导出时 QuickGameIOSIntegrationSettings 会写入 URL Scheme 5.3.3 WebGL 专有（小游戏） <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 方法 </td> <td> 返回值 </td> <td> 回调 </td> <td> 说明 </td> </tr> <tr> <td> onSetHost(host) </td> <td> void  </td> <td> —  </td> <td> 设置 SDK 网关；须在 onInit(productCode) 之前 </td> </tr> <tr> <td> onInit(productCode) </td> <td> void  </td> <td> init 成功/失败 </td> <td> 带产品码初始化；勿用无参 onInit() </td> </tr> <tr> <td> onPayOrder(QKPayOrderInfo) </td> <td> void  </td> <td> pay 成功/失败/取消 </td> <td>  小游戏支付；order 不可 null </td> </tr> </tbody> </table> <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> onSetHost参数 </td> <td> 类型 </td> <td> 说明 </td> </tr> <tr> <td> host </td> <td> string </td> <td> SDK 地址，如 https://qkgamesdk.quickapi.net；可与 QKSettings.baseUrl 一致 </td> </tr> </tbody> </table> <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> onInit参数 </td> <td> 类型 </td> <td> 说明 </td> </tr> <tr> <td> productCode </td> <td> string </td> <td> 后台产品码；可与 QKSettings.productCode 一致 </td> </tr> </tbody> </table> QKPayOrderInfo 字段见 5.4 WebGL 调用顺序：setListener → onSetHost → onInit(productCode) → onLogin → … 5.3.4 Android + iOS 共有（Windows / WebGL 无） <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 方法 </td> <td> 返回值 </td> <td> 说明 </td> </tr> <tr> <td> onGuestLogin() </td> <td> void </td> <td> 游客/静默登录 </td> </tr> <tr> <td> onIsBindPhone() </td> <td> bool </td> <td> 是否已绑定手机 </td> </tr> <tr> <td> onBindPhone() </td> <td> void </td> <td> 调起绑定手机 </td> </tr> <tr> <td> onDeviceId() </td> <td> string </td> <td> 同步设备 ID </td> </tr> </tbody> </table> 5.3.5 Android + iOS + WebGL 共有（Windows 无） <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 方法 </td> <td> 返回值 </td> <td> 说明 </td> </tr> <tr> <td> onRestoreNonConsumptionProducts() </td> <td> void </td> <td> 恢复非消耗型内购 / 补单；回调 onRestoreSuccess（可选） </td> </tr> </tbody> </table> 5.3.6 Windows 说明 1. 初始化、支付、用户查询与 5.2.1 相同（onInit、onPay、onUserID 等） 2. 不支持onGuestLogin（见 5.2.4） 3. 支付前必须先onUpdateRole（见5.1） 4. 配置来自 QKSettings.asset（baseUrl、productCode） 5.4 数据类型 ErrorMsg 用于 onInitFailed、onLoginFailed 等失败回调 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 字段 </td> <td> 类型 </td> <td> 说明 </td> </tr> <tr> <td> errMsg </td> <td> string </td> <td> 错误描述 </td> </tr> </tbody> </table> UserInfo 用于 onLoginSuccess；继承自 ErrorMsg <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 字段 </td> <td> 类型 </td> <td> 说明 </td> </tr> <tr> <td> uid </td> <td> string </td> <td> 用户 ID </td> </tr> <tr> <td> token </td> <td> string </td> <td> 登录 token </td> </tr> <tr> <td> userName </td> <td> string </td> <td> 账号名 </td> </tr> <tr> <td> timeLeft </td> <td> long </td> <td> 防沉迷剩余时间（秒）；-1 表示无限制  </td> </tr> <tr> <td> isNewUser </td> <td> bool </td> <td> 是否新用户 </td> </tr> <tr> <td> errMsg </td> <td> string </td> <td> 附加信息（继承字段） </td> </tr> </tbody> </table> 原生 JSON 字段映射：userId→uid，userToken→token，timeleft /timeLeft→timeLeft，isNewUser（"1"/"true"）→isNewUser PayResult 用于 onPaySuccess / onPayFailed / onPayCancel <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 字段 </td> <td> 类型 </td> <td> 说明 </td> </tr> <tr> <td> code </td> <td> string </td> <td> 状态码 </td> </tr> <tr> <td> message </td> <td> string </td> <td> 状态描述 </td> </tr> <tr> <td> orderNo </td> <td> string </td> <td> SDK 订单号 </td> </tr> <tr> <td> cpOrderNo </td> <td> string </td> <td> CP 订单号 </td> </tr> <tr> <td> extras </td> <td> string </td> <td> 下单时 extrasParams 透传回游戏 </td> </tr> </tbody> </table> QKPayOrderInfo（WebGL 小游戏） QKGame.QKPayOrderInfo，用于 onPayOrder <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 字段 </td> <td> 类型 </td> <td> 必填 </td> <td> 说明 </td> </tr> <tr> <td> cpOrderNo </td> <td> string </td> <td> 是 </td> <td> CP 订单号 </td> </tr> <tr> <td> subject </td> <td> string </td> <td> 是 </td> <td> 商品标题 </td> </tr> <tr> <td> desc </td> <td> string </td> <td> 是 </td> <td>  商品描述 </td> </tr> <tr> <td> goodsId </td> <td> string </td> <td> 是 </td> <td> 商品 ID </td> </tr> <tr> <td> amount </td> <td> string </td> <td> 是 </td> <td> 金额（字符串，如 "6.00"） </td> </tr> <tr> <td> userRoleId </td> <td> string </td> <td> 是 </td> <td> 角色 ID  </td> </tr> <tr> <td> userRoleName </td> <td> string </td> <td> 是 </td> <td> 角色名 </td> </tr> <tr> <td> serverId </td> <td> string </td> <td> 是 </td> <td> 区服 ID </td> </tr> <tr> <td> serverName </td> <td> string </td> <td> 是 </td> <td> 区服名 </td> </tr> <tr> <td> userLevel </td> <td> string </td> <td> 是 </td> <td> 角色等级 </td> </tr> <tr> <td> extrasParams </td> <td> string </td> <td> 是 </td> <td> 透传参数（可传 ""） </td> </tr> <tr> <td> callbackUrl </td> <td> string </td> <td> 否 </td> <td> 支付回调 URL，可空，如果游戏下单时设置支付回调，建议支付回调地址加上IP白名单，防止被攥改！！！ </td> </tr> <tr> <td> goods_category </td> <td> string </td> <td> 视渠道 </td> <td> 商品类目（部分渠道必填） </td> </tr> <tr> <td> buy_quantity </td> <td> string </td> <td> 视渠道 </td> <td> 购买数量（部分渠道必填）  </td> </tr> </tbody> </table> 5.5 接口速查 全平台公共 <pre class="brush:js;toolbar:false" style="font-size:14px;">方法 setListener onLogin onUserCenter onLogout onUpdateRole </pre> 平台专有 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 归属 </td> <td> 方法 </td> </tr> <tr> <td> iOS / Android / Windows </td> <td> onInit()、onPay、onUserID、onUserToken、onUserName </td> </tr> <tr> <td> iOS 专有 </td> <td> configureThirdPartyLogin、onDeviceIdfa </td> </tr> <tr> <td> WebGL 专有 </td> <td> onSetHost、onInit(productCode)、onPayOrder </td> </tr> <tr> <td> iOS + Android </td> <td> onGuestLogin、onIsBindPhone、onBindPhone、onDeviceId </td> </tr> <tr> <td> iOS + Android + WebGL </td> <td> onRestoreNonConsumptionProducts </td> </tr> </tbody> </table> 6. 回调说明（QuickListener） 继承 QuickListener（Assets/QuickGameSDK/Scripts/QuickListener.cs），实现抽象方法。原生/宿主以 JSON 字符串调用 public void onXxx(string msg) 重载，基类内部解析后转调你实现的强类型方法 数据类型（ErrorMsg、UserInfo、PayResult）见 5.3* 6.1 全平台公共回调（必须实现） <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 回调 </td> <td> 参数 </td> <td> 触发时机 </td> </tr> <tr> <td> onInitSuccess </td> <td> — </td> <td> onInit / onInit(productCode) 成功 </td> </tr> <tr> <td> onInitFailed(ErrorMsg) </td> <td> errMsg  </td> <td> 初始化失败 </td> </tr> <tr> <td> onLoginSuccess(UserInfo) </td> <td> uid、token 等 </td> <td> onLogin / onGuestLogin 成功 </td> </tr> <tr> <td> onLoginFailed(ErrorMsg) </td> <td> errMsg  </td> <td> 登录失败或取消 </td> </tr> <tr> <td> onLogoutSuccess() </td> <td> — </td> <td> onLogout 完成 </td> </tr> <tr> <td> onPaySuccess(PayResult) </td> <td>  orderNo、cpOrderNo、extras  </td> <td> 支付成功 </td> </tr> <tr> <td> onPayFailed(PayResult) </td> <td> code、message  </td> <td> 支付失败 </td> </tr> <tr> <td> onPayCancel(PayResult) </td> <td> — </td> <td> 用户取消支付 </td> </tr> </tbody> </table> 6.2 平台相关回调（可选实现） <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 回调 </td> <td> 适用平台 </td> <td> 说明 </td> </tr> <tr> <td> onRestoreSuccess() </td> <td> iOS / Android / WebGL </td> <td> onRestoreNonConsumptionProducts 恢复成功 </td> </tr> <tr> <td> onUserCenterClose() </td> <td> 部分平台 </td> <td> 用户中心关闭 </td> </tr> <tr> <td> onDeviceIdfa() </td> <td> iOS  </td> <td> 设备 IDFA </td> </tr> <tr> <td> onDeviceId() </td> <td>  iOS / Android </td> <td> 设备 ID </td> </tr> </tbody> </table> 6.3 回调与 API 对照 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 调用的 API  </td> <td> 可能收到的回调 </td> </tr> <tr> <td> onInit() / onInit(productCode) </td> <td> onInitSuccess / onInitFailed </td> </tr> <tr> <td> onLogin() / onGuestLogin()  </td> <td> onLoginSuccess / onLoginFailed </td> </tr> <tr> <td> onLogout() </td> <td> onLogoutSuccess </td> </tr> <tr> <td> onPay() / onPayOrder() </td> <td> onPaySuccess / onPayFailed / onPayCancel </td> </tr> <tr> <td> onRestoreNonConsumptionProducts() </td> <td> onRestoreSuccess </td> </tr> </tbody> </table> 7. QKSettings 统一配置 菜单：QuickSDK → Settings→ 编辑 Assets/Resources/QKSettings.asset <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 字段 </td> <td> iOS </td> <td style="width:22%;"> Android </td> <td> WebGL </td> <td style="width:12%;"> Windows </td> </tr> <tr> <td> productCode </td> <td> QKSettings/ onInit(code)/桥接默认 </td> <td> Build 前写入 Manifest </td> <td> onInit(productCode) </td> <td> QKSettings </td> </tr> <tr> <td> baseUrl </td> <td> — </td> <td> 写入StreamingAssets/quickgame_sdk/ qg_ipconfig.txt </td> <td> onSetHost </td> <td> SDK 请求域名 </td> </tr> <tr> <td> miniGameChannel </td> <td> — </td> <td> — </td> <td> 选择 Channels/<渠道>/QGSDK.js </td> <td> — </td> </tr> <tr> <td> channelCode 等 UI 字段 </td> <td> — </td> <td> — </td> <td> — </td> <td> PC 登录/支付窗体 </td> </tr> </tbody> </table> 注意：iOS 推荐 QKSettings + onInit(productCode) 或导出时写入桥接默认；Android 使用无参 onInit()（productCode 在 Build 写入 Manifest）；WebGL 须 onSetHost + onInit(productCode) 8. 分平台导出说明 Unity 脚本接入完成后，必须完成对应原生/宿主配置。详细步骤见后面的分平台操作文档 8.1 iOS 要点摘要 - releaseSDK 查找顺序：QuickGameIOSIntegrationSettings.ReleaseSdkRoot（默认 iOS/releaseSDK）→ UNITY_QUICKGAME_SDK_ROOT → ../quickgame/releaseSDK - Unity Build iOS 后，IOSPostProcessBuild 自动拷贝 SDK 到 Frameworks/QuickGameSDK/、写 -ObjC、DevAny 签名、微信/QQ plist 与 URL 回调   - Unity 2019.3+：.framework / .a → UnityFramework；.bundle → Unity-iPhone - productCode 写在 QKConnector.mm 或由发版包预写入   - Unity 不能直接出 IPA，须在 Xcode Archive   8.2 Android 要点摘要 - Assets/Plugins/Android/libs/ 放置商务 AAR（如 app-release.aar）   - Build 前 AndroidPreprocessBuild 从 QKSettings 写入 productCode 与 qg_ipconfig.txt - QKConnector.java 位于 com/quickgame/unity/，经 AndroidPostGenerateGradle 参与编译   - 支付使用 onPay(...)，回调 JSON 字段与 iOS 一致   8.3 WebGL 要点摘要 - 渠道 SDK 放在 Assets/QuickGameSDK/Channels/wx|ali/QGSDK.js - QuickSDK → Settings → Rebuild WebGL Bridge 生成 QuickGameWebGLBootstrap.jspre + QuickGameWebGL.jslib - 须 onSetHost + onInit(productCode)；支付使用 onPayOrder，不用 onPay - 微信：Import 微信 unitypackage → WebGL Build → 微信开发者工具转包（见 [WebGL.md](./WebGL.md)）   8.4 Windows 要点摘要 - QKGame 经 WindowsQGAdapter 对接 Assets/Plugins/Windows/ 下 PC SDK   - onInit() 读取 QKSettings；支付前须 onUpdateRole - 将 PCSDKUI.exe 放到 StreamingAssets/Quicksdk/PCSDK_release/ - 须在 Windows 环境 Build 与运行   9. productCode 与渠道参数 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 参数 </td> <td> 获取方式 </td> <td> 使用位置 </td> </tr> <tr> <td> productCode  </td> <td> QuickGame 后台 </td> <td> iOS：QKConnector.mm；Android：QKSettings → Manifest；WebGL：onInit；Windows：QKSettings </td> </tr> <tr> <td> baseUrl </td> <td> 平台运营人员 </td> <td> Android：qg_ipconfig.txt；WebGL：onSetHost；Windows：QKSettings </td> </tr> <tr> <td> 微信 AppId / Secret / Universal Link </td> <td> 微信开放平台 </td> <td> configureThirdPartyLogin、Info.plist </td> </tr> <tr> <td> QQ AppId / Universal Link </td> <td> QQ 互联 </td> <td> 同上 </td> </tr> <tr> <td> 内购商品 ID </td> <td> App Store / 后台 </td> <td> onPay 的 productId </td> </tr> <tr> <td> miniGameChannel </td> <td> 平台运营人员 </td> <td> WebGL：Channels/<渠道>/QGSDK.js </td> </tr> </tbody> </table> 10. Demo 与自测 10.1 参考场景 打开 Assets/Scenes/QuickGameDemo.unity： 物体挂载 QuickGameDemoListener + QuickGameDemoController   自动读取 QKSettings 填充 demoHost / demoProductCode   真机/对应平台运行后按按钮测试：Init → Login → 上传角色 → Pay → Logout   10.2 建议验收项 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 项 </td> <td> iOS </td> <td> Android </td> <td> WebGL </td> <td> Windows </td> </tr> <tr> <td> Init </td> <td> onInitSuccess </td> <td> 同左 </td> <td> onSetHost + onInit 后成功 </td> <td> 同 iOS </td> </tr> <tr> <td> Login </td> <td> uid/token 非空 </td> <td> 同左 </td> <td> 同左 </td> <td> 同左 </td> </tr> <tr> <td> 上传角色 </td> <td> onUpdateRole 无崩溃 </td> <td> 同左 </td> <td> 同左 </td> <td> 支付前必调 </td> </tr> <tr> <td> Pay </td> <td> 成功/失败/取消回调 </td> <td> 同左 </td> <td> onPayOrder 回调 </td> <td> 同左 </td> </tr> <tr> <td> 渠道 </td> <td> 微信/QQ 回调（若已接） </td> <td> — </td> <td> 微信/支付宝宿主内登录支付 </td> <td> PC 弹窗流程 </td> </tr> </tbody> </table> 11. 常见问题 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 现象 </td> <td> 处理 </td> </tr> <tr> <td> Editor 下无回调 </td> <td> 正常；须真机或对应平台 Player </td> </tr> <tr> <td> setListener 后仍无回调 </td> <td> 检查 GameObject 名称、Listener 是否挂在该物体上 </td> </tr> <tr> <td> iOS：JySDKManager.h not found </td> <td> 未找到 releaseSDK；确认 iOS/releaseSDK 或设 UNITY_QUICKGAME_SDK_ROOT 后重新 Build iOS </td> </tr> <tr> <td> iOS：jywlNamed / HXTextView 崩溃 </td> <td> UnityFramework 缺少 -ObjC </td> </tr> <tr> <td> iOS：Xcode 中 SDK 文件夹红色 </td> <td> 确认磁盘存在 Frameworks/QuickGameSDK，重新导出 </td> </tr> <tr> <td> 微信/QQ 无法回调 </td> <td> 检查 configureThirdPartyLogin、URL Scheme、Universal Link </td> </tr> <tr> <td> Android Build 失败：productCode 为空 </td> <td> 在 QuickSDK → Settings 填写 QKSettings </td> </tr> <tr> <td> WebGL Build 失败：渠道无效 </td> <td> 检查 Channels/<miniGameChannel>/QGSDK.js 是否存在，Rebuild Bridge </td> </tr> <tr> <td> WebGL 初始化无效 </td> <td> 是否先 onSetHost 再 onInit(productCode) </td> </tr> <tr> <td> Windows 支付无反应 </td> <td> 是否先 onUpdateRole；PCSDKUI.exe 是否在 StreamingAssets </td> </tr> </tbody> </table> 12. 文件索引 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 文件 </td> <td> 作用 </td> </tr> <tr> <td> Plugins/QuickGameSDK/Scripts/QKGame.cs </td> <td> 全平台 API 入口 </td> </tr> <tr> <td> Plugins/QuickGameSDK/Scripts/QuickListener.cs </td> <td> 回调基类与 JSON 解析 </td> </tr> <tr> <td> Plugins/QuickGameSDK/Scripts/QuickGameAndroidBridge.cs </td> <td> Android JNI 桥 </td> </tr> <tr> <td> Plugins/QuickGameSDK/Scripts/QuickGameWebGLBridge.cs </td> <td> WebGL jslib 桥 </td> </tr> <tr> <td> Plugins/Android/com/quickgame/unity/QKConnector.java </td> <td> Android 原生桥 </td> </tr> <tr> <td> Plugins/Windows/Plugins/script/WindowsQGAdapter.cs </td> <td> Windows 适配层 </td> </tr> <tr> <td> Plugins/QuickGameSDK/Editor/IOSPostProcessBuild.cs </td> <td> iOS 导出后自动集成 SDK </td> </tr> <tr> <td> Plugins/QuickGameSDK/Editor/QuickGameIOSIntegrationSettings.cs </td> <td> iOS 微信/QQ、ReleaseSdkRoot </td> </tr> <tr> <td> Plugins/QuickGameSDK/Editor/AndroidPreprocessBuild.cs </td> <td> Android Build 前写配置 </td> </tr> <tr> <td> Plugins/QuickGameSDK/Editor/AndroidPostGenerateGradle.cs </td> <td> Android Gradle 合并 </td> </tr> <tr> <td> Plugins/QuickGameSDK/Editor/QuickGameWebGLChannelBuilder.cs </td> <td> 小游戏渠道 jspre/jslib 构建 </td> </tr> <tr> <td> Plugins/QuickGameSDK/Channels/*/QGSDK.js </td> <td> 小游戏各渠道资源 </td> </tr> <tr> <td> Plugins/WebGL/QuickGameWebGL.jslib </td> <td> WebGL 原生插件 </td> </tr> <tr> <td> Plugins/Windows/Plugins/script/PackageSettings.cs </td> <td> QKSettings 字段定义 </td> </tr> <tr> <td> Resources/QKSettings.asset </td> <td> 运行时 / 构建配置 </td> </tr> <tr> <td> Plugins/QuickGameSDK/Demo/QuickGameDemoController.cs </td> <td> Demo 按钮逻辑 </td> </tr> <tr> <td> Plugins/QuickGameSDK/Demo/QuickGameDemoListener.cs </td> <td> Demo 回调实现 </td> </tr> <tr> <td> iOS/releaseSDK/ </td> <td> 默认 iOS 原生 SDK 目录 </td> </tr> </tbody> </table> <h4> 二、Android 部分说明 </h4> 1. 架构概览 <pre class="brush:js;toolbar:false"> CP 游戏代码 ↓ QKGame.cs（统一 API，与 iOS 相同） ↓ QuickGameAndroidBridge.cs（C# → Java 反射调用） ↓ QKConnector.java（Unity 桥接层，对接 QGManager） ↓ QuickGame Android SDK（AAR：app-release.aar 等） ↓ UnitySendMessage → QuickListener（回调）</pre> 2. Android Studio 对接 SDK 并封装接口 2.1 工程结构（QuickGame_unity） Android Studio 侧以 Library Module 形式封装，供 Unity 合并 AAR： <pre class="brush:js;toolbar:false">QuickGame_unity/ ├── app/ # 主模块，导出 AAR │ ├── libs/ # SDK 本地 jar/aar + unity-classes.jar（compileOnly） │ ├── src/main/ │ │ ├── AndroidManifest.xml # SDK Activity / Provider / meta-data 模板 │ │ └── java/com/qk/game/ │ │ ├── GameApplication.java # Application，调用 QGManager.initMsa │ │ └── MainActivity.java # 继承 QuickUnityPlayerproxyActivity │ └── build.gradle.kts ├── aarlib/ # flatDir 本地 aar（编译用，需同步拷贝到 Unity） └── unity_export/ # exportUnitySdk 任务输出目录</pre> 2.2 SDK 依赖接入 本地 AAR/JAR（打进 AAR 或 Unity libs）： app-release.aar（QuickGame SDK 主包，含 QGManager、LoginActivity 等） 渠道/统计依赖：channelsdk、oaid_sdk、auth_number_product、巨量系列 AAR 等 Maven 依赖（不会自动打进 AAR，Unity mainTemplate.gradle 需同步声明）： <pre class="brush:js;toolbar:false">implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.7.21' implementation 'androidx.appcompat:appcompat:1.2.0' implementation 'androidx.core:core:1.6.0' implementation 'io.reactivex.rxjava2:rxandroid:2.1.1' implementation 'com.taptap.sdk:tap-login:4.8.2' implementation 'com.taptap.sdk:tap-core:4.8.2' implementation 'com.taptap.sdk:tap-update:4.8.2' implementation 'com.taptap.sdk:tap-review:4.8.2' implementation 'com.google.android.flexbox:flexbox:3.0.0' implementation 'com.tencent.vasdolly:helper:3.0.4'</pre> 注意： unity-classes.jar 仅 compileOnly，不得打入 AAR；Unity 导出工程由 mainTemplate.gradle 以 implementation files('libs/unity-classes.jar') 提供 2.3 导出 AAR 到 Unity 在 Android Studio 工程根目录执行： <pre class="brush:js;toolbar:false">./gradlew :app:exportUnitySdk</pre> 输出到 unity_export/，包含： quickgame-unity-bridge.aar（即 app-release.aar 重命名） aarlib/ 下各 flat AAR 将上述 AAR 全部拷贝到 Unity 工程： <pre class="brush:js;toolbar:false">Assets/Plugins/Android/libs/</pre> 2.4 Unity 桥接类 QKConnector.java 桥接类职责：对接 QGManager，通过 UnitySendMessage 回调 Unity QuickListener <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> Java 静态方法 </td> <td> 对应 QGManager </td> <td> Unity 回调 </td> </tr> <tr> <td> setListener(name) </td> <td> — </td> <td> 注册 listener GameObject 名 </td> </tr> <tr> <td> init() </td> <td> QGManager.init(activity, productCode, cb) </td> <td> onInitSuccess / onInitFailed </td> </tr> <tr> <td> login() </td> <td> QGManager.login </td> <td> onLoginSuccess / onLoginFailed </td> </tr> <tr> <td> loginAsGuest() </td> <td> QGManager.slienceLogin </td> <td> 同上 </td> </tr> <tr> <td> userCenter() </td> <td> QGManager.showUserCenter </td> <td> — </td> </tr> <tr> <td> logout() </td> <td> QGManager.logout </td> <td> onLogoutSuccess </td> </tr> <tr> <td> pay(...) </td> <td> QGManager.pay </td> <td> onPaySuccess / onPayFailed </td> </tr> <tr> <td> updateRole(...) </td> <td> QGManager.setGameRoleInfo </td> <td> — </td> </tr> <tr> <td> bindPhone() </td> <td> QGManager.showBind </td> <td> — </td> </tr> </tbody> </table> 关键实现要点： 1. 所有 SDK UI 调用必须在 UI 线程（runOnUiThread） 2. init() 从 Manifest meta-data QKproductCode 读取 productCode 3. 注册 ActivityLifecycleCallbacks：Resume 时 QGManager.showFloat(true)，Pause 时 hideFloat() 4. 回调 JSON 字段与 iOS / QuickListener 字符串重载一致 productCode 读取（防 Float 精度丢失）： Manifest 中写入 code:65195142454045007867755657815091 前缀格式；Java 侧 readProductCode() 去掉 code: 前缀后再传给 SDK 2.5 AndroidManifest 模板（AS 侧完整版） AS 工程 app/src/main/AndroidManifest.xml 包含 SDK 所需的完整声明，Unity 侧需按需合并，至少包括： 权限：INTERNET、READ_PHONE_STATE、REQUEST_INSTALL_PACKAGES 等 queries：微信、支付宝、TapTap 等包名 Application：com.qk.game.GameApplication（QGManager.initMsa） MainActivity：com.qk.game.MainActivity（继承 Unity 代理 Activity）+ MAIN/LAUNCHER SDK Activity：LoginActivity、PayActivity、DownloadActivity 等（缺少会导致 ClassNotFoundException） Provider：QGFileProvider 渠道 meta-data：QQ_APP_ID、WX_APP_ID、TAP_ID 等（按 CP 实际参数替换 QK0 占位符） 3. 导入资源到 Unity 工程 3.1 目录清单 将以下内容放入 Unity 工程 Assets/： <pre class="brush:js;toolbar:false">Assets/ ├── QuickGameSDK/ │ ├── Scripts/ │ │ ├── QKGame.cs # 统一 API 入口（CP 只调此类） │ │ ├── QuickListener.cs # 回调基类 │ │ └── QuickGameAndroidBridge.cs # Android C# 桥接 │ ├── Editor/ │ │ ├── AndroidPreprocessBuild.cs # Build 前写 productCode / baseUrl │ │ └── AndroidPostGenerateGradle.cs # Gradle 生成后拷贝 QKConnector.java │ └── Demo/ # 可选 Demo 场景 │ ├── QuickGameDemoController.cs │ └── QuickGameDemoListener.cs ├── Plugins/ │ ├── Android/ │ │ ├── AndroidManifest.xml # 自定义 Manifest │ │ ├── mainTemplate.gradle # unityLibrary 依赖模板 │ │ ├── baseProjectTemplate.gradle # AGP 7.4.2 + R8 │ │ ├── gradleTemplate.properties │ │ ├── com/quickgame/unity/ │ │ │ └── QKConnector.java # 桥接源码（Build 后拷贝到 Gradle 工程） │ │ └── libs/ │ │ ├── app-release.aar # SDK 主 AAR │ │ ├── unity-classes.jar # Unity 运行时（implementation，非 compileOnly） │ │ └── *.aar # 其他依赖 AAR │ └── JsonNet/ # Newtonsoft.Json（QuickListener 解析 JSON） ├── QuickGameSDK/Windows/Plugins/script/ │ └── PackageSettings.cs # QKSettings ScriptableObject 定义 ├── QuickGameSDK/Windows/Editor/ │ └── PackageSettingsWindow.cs # QuickSDK → Settings 菜单 └── Resources/ └── QKSettings.asset # 运行时/构建配置</pre> 3.2 Unity Project Settings 必开项 Edit → Project Settings → Player → Android → Publishing Settings： <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 选项 </td> <td> 值 </td> </tr> <tr> <td> Custom Main Manifest </td> <td> ✅ </td> </tr> <tr> <td> Custom Main Gradle Template </td> <td> ✅ </td> </tr> <tr> <td> Custom Base Gradle Template </td> <td> ✅ </td> </tr> <tr> <td> Custom Gradle Properties Template </td> <td> ✅ </td> </tr> </tbody> </table> Edit → Preferences → External Tools： JDK：建议 JDK 17（Unity 2022 + AGP 7.4.2；sdkmanager 亦需 JDK 17） 3.3 Gradle 模板要点 mainTemplate.gradle： 使用 apply plugin: 'com.android.library'（Unity 2022.3 导出为 library 模式） implementation files('libs/unity-classes.jar') — 必须是 implementation，否则运行时找不到 UnityPlayer aaptOptions.noCompress 使用 **BUILTIN_NOCOMPRESS** + unityStreamingAssets.tokenize(', ')（不要用旧版 aaptOptions { noCompress ... } 单行写法） Maven 依赖与 AS 工程保持一致 注释中不要写 **DEPS** 字样（Unity 模板替换会误伤注释） baseProjectTemplate.gradle： <pre class="brush:js;toolbar:false">classpath 'com.android.tools:r8:8.3.37' id 'com.android.application' version '7.4.2' apply false id 'com.android.library' version '7.4.2' apply false</pre> 3.4 AndroidManifest（Unity 侧） Unity 自定义 Manifest 位于 Assets/Plugins/Android/AndroidManifest.xml，需包含： <pre class="brush:js;toolbar:false"><meta-data android:name="QKproductCode" android:value="code:PLACEHOLDER_PRODUCT_CODE" /> <activity android:name="com.qk.game.MainActivity" ...> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> ... </activity></pre> Build 前 AndroidPreprocessBuild 会将 PLACEHOLDER_PRODUCT_CODE 替换为 QKSettings 中的 productCode（带 code: 前缀） SDK Activity 声明：若运行时出现 LoginActivity / PayActivity 等 ActivityNotFoundException，需从 AS 工程 Manifest 补全对应 <activity> 节点 3.5 QKConnector.java 编译机制 Unity 2022.3 导出 Gradle 时，Plugins/Android/*.java 不一定自动参与 unityLibrary 编译 已通过 AndroidPostGenerateGradle.cs 解决：Gradle 工程生成后，自动将 QKConnector.java 拷贝到： <pre class="brush:js;toolbar:false"><导出目录>/unityLibrary/src/main/java/com/quickgame/unity/QKConnector.java</pre> 4. Unity C# 接口调用与 QKSettings 配置 4.1 QKSettings 配置 菜单：QuickSDK → Settings <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 字段 </td> <td> Android 用途 </td> <td> 示例 </td> </tr> <tr> <td> baseUrl </td> <td> Build 前写入 StreamingAssets/quickgame_sdk/qg_ipconfig.txt </td> <td> https://qkgamesdk.quickapi.net </td> </tr> <tr> <td> productCode </td> <td> Build 前写入 Manifest </td> <td> QKproductCode 65195142454045007867755657815091 </td> </tr> <tr> <td> channelCode </td> <td> 子渠道标识（按 SDK 文档配置） </td> <td> cps001，cps002 </td> </tr> </tbody> </table> 配置文件路径：Assets/Resources/QKSettings.asset Build 前自动处理（AndroidPreprocessBuild）： 1. 校验 baseUrl、productCode 非空（为空则 Build 失败） 2. 替换 Manifest 中 QKproductCode 值 3. 生成 Assets/StreamingAssets/quickgame_sdk/qg_ipconfig.txt 4.2 CP 接入代码 4.2.1. 继承 QuickListener <pre class="brush:js;toolbar:false">using quickgame; using UnityEngine; public class MyGameListener : QuickListener { public override void onInitSuccess() { Debug.Log("Init OK"); } public override void onInitFailed(ErrorMsg message) { Debug.Log("Init Fail: " + message.errMsg); } public override void onLoginSuccess(UserInfo userInfo) { Debug.Log("Login: " + userInfo.uid); } public override void onLoginFailed(ErrorMsg errMsg) { Debug.Log("Login Fail: " + errMsg.errMsg); } public override void onLogoutSuccess() { } public override void onPaySuccess(PayResult r) { } public override void onPayFailed(PayResult r) { } public override void onPayCancel(PayResult r) { } }</pre>      4.2.2. 注册 Listener 并调用 SDK <pre class="brush:js;toolbar:false">// Awake 中（必须在 init 之前） QKGame.setListener(myListenerComponent); // Android：无参 init，productCode 已由 QKSettings + Manifest 注入 QKGame.onInit(); QKGame.onLogin(); // 支付（Android 使用 onPay，不是 WebGL 的 onPayOrder） QKGame.onPay(productId, productName, amount, orderNo, callbackUrl, extrasParams); // 上报角色（支付前建议先调用） QKGame.onUpdateRole(roleId, roleName, serverId, serverName, roleLevel, vipLevel, rolePower); QKGame.onLogout(); </pre> 4.2.3. Demo 参考 场景：QuickGameDemo.unity 脚本：QuickGameDemoController.cs / QuickGameDemoListener.cs Android Build 下按钮流程：Init → Login → Pay → Logout（与 iOS 相同，无 WebGL 的 SetHost 步骤） 4.3 回调 JSON 约定 原生通过 UnityPlayer.UnitySendMessage(gameObjectName, method, jsonString) 调用 QuickListener 的字符串重载（QuickListener.cs 内自动解析 JSON） 登录成功： <pre class="brush:js;toolbar:false">{ "userId": "123456", "userToken": "xxx", "userName": "player1", "msg": "success", "timeleft": "-1", "isNewUser": "0" }</pre> 登录/初始化失败： <pre class="brush:js;toolbar:false">{ "msg": "错误描述" }</pre> 支付结果： <pre class="brush:js;toolbar:false">{ "code": "0", "message": "success", "orderNo": "SDK订单号", "cpOrderNo": "游戏订单号", "extras": "透传参数" }</pre> 4.4 调用链路（代码层） <pre class="brush:js;toolbar:false">QKGame.onInit() → QuickGameAndroidBridge.Init() → AndroidJavaClass("com.quickgame.unity.QKConnector").CallStatic("init") → QGManager.init(activity, productCode, callback) → UnitySendMessage("ListenerGO", "onInitSuccess", "")</pre> 5. 构建与验收 5.1 构建步骤 1. QuickSDK → Settings 填写 baseUrl、productCode 2. File → Build Settings → Android 3. 选择 Export Project 或直接 Build And Run 4. 首次 Build 建议在 Unity Console 确认日志： [QuickGame] Android 预处理完成：productCode=... [QuickGame] 已拷贝 QKConnector.java -> ... 5.2 验收清单 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 步骤 </td> <td> 操作 </td> <td> 预期 </td> </tr> <tr> <td> Init </td> <td> QKGame.onInit() </td> <td> onInitSuccess </td> </tr> <tr> <td> Login </td> <td> QKGame.onLogin() </td> <td> onLoginSuccess，含 userId / userToken </td> </tr> <tr> <td> Guest </td> <td> QKGame.onGuestLogin() </td> <td> 静默登录回调 </td> </tr> <tr> <td> Pay </td> <td> QKGame.onPay(...) </td> <td> onPaySuccess 或 onPayFailed，含 orderNo / cpOrderNo </td> </tr> <tr> <td> Role </td> <td> QKGame.onUpdateRole(...) </td> <td> 无崩溃，SDK 收到角色信息 </td> </tr> <tr> <td> Logout </td> <td> QKGame.onLogout() </td> <td> onLogoutSuccess </td> </tr> <tr> <td> 浮球 </td> <td> 登录后进游戏 </td> <td> Resume 显示浮球，Pause 隐藏 </td> </tr> </tbody> </table> 5.3 日志关键字 <pre class="brush:js;toolbar:false">adb logcat | grep -E "QKConnector|QGManager|QuickGame"</pre> 6. 注意事项与常见问题 6.1 配置相关 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 问题 </td> <td> 原因 </td> <td> 处理 </td> </tr> <tr> <td> productCode 变成错误数字 </td> <td> 纯数字 meta-data 被 Android 解析为 Float </td> <td> Manifest 使用 code: 前缀 + Java readMetaDataString </td> </tr> <tr> <td> Init 报 productCode 为空 </td> <td> QKSettings 未填或 Build 预处理未执行 </td> <td> 检查 Settings + Console 预处理日志 </td> </tr> <tr> <td> baseUrl 未生效 </td> <td> 未生成 qg_ipconfig.txt </td> <td> 确认 StreamingAssets/quickgame_sdk/qg_ipconfig.txt 存在 </td> </tr> </tbody> </table> 6.2 编译 / Gradle <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 问题 </td> <td> 原因 </td> <td> 处理 </td> </tr> <tr> <td> UnityPlayer / IUnityPlayerLifecycleEvents 找不到 </td> <td> unity-classes.jar 为 compileOnly </td> <td> 改为 implementation files('libs/unity-classes.jar') </td> </tr> <tr> <td> Gradle 注释语法错误 </td> <td> 注释中含 **DEPS** 被 Unity 替换 </td> <td> 注释改用其他写法 </td> </tr> <tr> <td> AAR 重复类 </td> <td> fileTree + DEPS 双重引入 </td> <td> 去掉 fileTree('*.aar')，仅保留 Unity DEPS 机制 </td> </tr> <tr> <td> AGP / JDK 版本不匹配 </td> <td> Unity 2022 需 AGP 7.x + JDK 17 </td> <td> 检查 External Tools JDK 与 baseProjectTemplate </td> </tr> </tbody> </table> 6.3 运行时 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 问题 </td> <td> 原因 </td> <td> 处理 </td> </tr> <tr> <td> QKConnector ClassNotFoundException </td> <td> java 未参与 unityLibrary 编译 </td> <td> 确认 AndroidPostGenerateGradle 拷贝成功 </td> </tr> <tr> <td> LoginActivity ClassNotFoundException </td> <td> Manifest 未声明 SDK Activity </td> <td> 从 AS 工程 Manifest 补全 Activity </td> </tr> <tr> <td> 桌面无应用图标 </td> <td> MainActivity 缺少 LAUNCHER </td> <td> Manifest 为 MainActivity 添加 MAIN/LAUNCHER </td> </tr> <tr> <td> Manifest 合并冲突 </td> <td> configChanges / screenOrientation 与 AAR 冲突 </td> <td> 使用 tools:replace 显式覆盖 </td> </tr> <tr> <td> 回调无响应 </td> <td> 未 setListener 或 GameObject 名错误 </td> <td> Awake 中先 QKGame.setListener(this)，物体名与 SendMessage 一致 </td> </tr> <tr> <td> Init 成功但 Listener 收不到 </td> <td> init 早于 setListener </td> <td> QKConnector 已缓存 init 状态，setListener 后会补发 </td> </tr> </tbody> </table> 6.4 与其他平台共存 QKGame.cs / QuickListener.cs 为全平台公共 API，Android 改动不影响 iOS / Windows / WebGL 分支 Android 支付用 onPay()；WebGL 小游戏用 onPayOrder() Android init 无参；WebGL 需 onSetHost + onInit(productCode) 6.5 SDK 升级流程 使用新版 SDK AAR → 替换 Assets/Plugins/Android/libs/ 对比 AS 工程 Manifest diff，补全新增 Activity / Provider / meta-data 若 QGManager API 有变，同步修改 QKConnector.java 重新 Export AAR（如有 AS 工程变更）→ Unity Build 真机回归 7. 扩展 QuickGame SDK Android 接口 当 CP 需要接入 SDK 新增的 QGManager 能力时，需按「Java 桥接 → C# Bridge → QKGame 对外 API →（可选）QuickListener 回调」四层逐层暴露 本模块以 QGManager.getChannelId() 为例（同步返回值），并补充异步回调类接口的通用写法 7.1 先判断接口类型 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 类型 </td> <td> SDK 特征 </td> <td> Unity 暴露方式 </td> <td> 现有参考 </td> </tr> <tr> <td> 同步查询 </td> <td> public static String/Bool/Int xxx()，立即返回 </td> <td> Java 静态方法 → C# 直接 CallStatic<T> 返回 </td> <td> getUID() → onUserID() </td> </tr> <tr> <td> 异步操作 </td> <td> 带 QGCallBack 或回调参数 </td> <td> Java 调 SDK 后在回调里 UnitySendMessage </td> <td> login() → onLoginSuccess </td> </tr> <tr> <td> UI 操作 </td> <td> 需 Activity、弹 SDK 界面 </td> <td> Java 内 runOnUiThread + 可选回调 </td> <td> showUserCenter()、pay() </td> </tr> </tbody> </table> getChannelId() 属于同步查询，与 userId() / deviceId() 同一模式，不需要改 QuickListener（除非 CP 希望用事件推送而非主动查询） 7.2 扩展链路总览 <img src="https://staticsite.quickapi.net/data/newFiles/20260623/20260623170353cHWw683.png" alt="" style="font-size:14px;" /> 异步接口在 QKConnector 与 QuickListener 之间多一条 UnitySendMessage 回路（见 7.5） 7.3 示例一：同步接口 getChannelId()（完整四步） Step 0：在 QuickGame_unity 中确认 SDK API（可选但推荐） 在 Android Studio 工程引入最新 AAR 后，可先写一段原生测试代码验证 API 可用（不必提交，仅用于确认签名与返回值）： <pre class="brush:js;toolbar:false">// QuickGame_unity/app/src/main/java/com/qk/game/MainActivity.java（临时验证） Log.d("Test", "channelId=" + com.quickgamesdk.QGManager.getChannelId());</pre> 确认无误后，正式桥接代码写在 Unity 侧的 QKConnector.java（Build 时由 AndroidPostGenerateGradle 拷贝进 Gradle 工程） 说明： QKConnector.java 维护在 Unity 工程 Assets/Plugins/Android/com/quickgame/unity/，不在 QuickGame_unity 的 app 模块内。QuickGame_unity 主要负责 AAR 打包与 Manifest 模板；Unity 桥接层在 unitybridgecn 维护 Step 1：QKConnector.java — 封装 QGManager 调用 文件：Assets/Plugins/Android/com/quickgame/unity/QKConnector.java 在现有同步方法（如 userId()）附近新增： <pre class="brush:js;toolbar:false">/** 获取 SDK 渠道 ID，对应 QGManager.getChannelId() */ public static String channelId() { return safeString(QGManager.getChannelId()); }</pre> 命名约定： Java 侧用 camelCase，与现有 userId()、userToken() 保持一致 必须用 safeString() 包装，避免向 Unity 返回 null 若 SDK 要求先 init 才能调用，可在方法内加判断并打 Log，或返回空串 Step 2：QuickGameAndroidBridge.cs — C# 反射调用 Java 文件：Assets/QuickGameSDK/Scripts/QuickGameAndroidBridge.cs <pre class="brush:js;toolbar:false">public static string ChannelId() { return Bridge.CallStatic<string>("channelId"); }</pre> 同时在 #else 分支（Editor / 非 Android）补 stub，避免 Editor 编译报错： <pre class="brush:js;toolbar:false">public static string ChannelId() { return ""; }</pre> Step 3：QKGame.cs — 对外统一 API 文件：Assets/QuickGameSDK/Scripts/QKGame.cs 参照 onUserID() 增加 Android 分支： <pre class="brush:js;toolbar:false">/// <summary>获取 SDK 渠道 ID（Android 登录后可用；其他平台返回空串）。</summary> public static string onChannelId() { #if UNITY_ANDROID && !UNITY_EDITOR return QuickGameAndroidBridge.ChannelId(); #elif UNITY_STANDALONE_WIN return quicksdk.QuickSDK.getInstance().getChannelId(); // Windows 若已有同名能力可一并暴露 #else return ""; #endif }</pre> 约定： CP 只调用 QKGame，不直接调 Bridge 方法名与 iOS / Windows 对齐时，用 #if 分平台实现；Android 独有接口可仅写 UNITY_ANDROID 分支 Step 4：CP 侧调用与验收 <pre class="brush:js;toolbar:false">// 建议在 onInitSuccess / onLoginSuccess 之后调用 string channelId = QKGame.onChannelId(); Debug.Log("[CP] channelId=" + channelId);</pre> 验收： 1. Unity Android Build 安装到真机 2. 走完 onInit → onLogin 3. 调用 QKGame.onChannelId()，Logcat 过滤 QKConnector / CP 日志，确认返回值与原生 SDK 一致 <pre class="brush:js;toolbar:false">adb logcat | grep -E "channelId|QKConnector"</pre> 7.4 同步接口扩展检查清单 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 文件 </td> <td> 动作 </td> </tr> <tr> <td> QKConnector.java </td> <td> 新增 public static 方法，内部调 QGManager.xxx() </td> </tr> <tr> <td> QuickGameAndroidBridge.cs </td> <td> 新增 CallStatic<T>("方法名") 封装 </td> </tr> <tr> <td> QKGame.cs </td> <td> 新增 public static API，#if UNITY_ANDROID 分支 </td> </tr> <tr> <td> Demo（可选） </td> <td> QuickGameDemoController 增加测试按钮 </td> </tr> <tr> <td> 文档 </td> <td> 更新CP 接入文档中的 API 表 </td> </tr> </tbody> </table>   无需修改： AndroidPostGenerateGradle.cs（仍拷贝整个 QKConnector.java）、QuickListener.cs（纯同步返回时） 7.5 示例二：异步接口扩展（带 Unity 回调） 若新接口形如 QGManager.doSomething(Activity, QGCallBack callback)，需增加 UnitySendMessage → QuickListener 回路。以虚构的 queryChannelInfo 为例： Step 1：QKConnector.java <pre class="brush:js;toolbar:false">public static void queryChannelInfo() { runOnUiThread(new Runnable() { @Override public void run() { Activity activity = UnityPlayer.currentActivity; if (activity == null) { sendQueryChannelFailed("Unity activity is null"); return; } QGManager.queryChannelInfo(activity, new QGCallBack() { @Override public void onSuccess() { try { JSONObject json = new JSONObject(); json.put("channelId", safeString(QGManager.getChannelId())); json.put("msg", "success"); sendMessage("onQueryChannelSuccess", json.toString()); } catch (Exception e) { sendQueryChannelFailed(e.getMessage()); } } @Override public void onFailed(String msg) { sendQueryChannelFailed(msg); } }); } }); } private static void sendQueryChannelFailed(String msg) { sendMessage("onQueryChannelFailed", "{"msg":"" + escapeJson(msg) + ""}"); }</pre> Step 2：QuickGameAndroidBridge.cs <pre class="brush:js;toolbar:false">public static void QueryChannelInfo() { Bridge.CallStatic("queryChannelInfo"); }</pre> Step 3：QKGame.cs <pre class="brush:js;toolbar:false">public static void onQueryChannelInfo() { #if UNITY_ANDROID && !UNITY_EDITOR QuickGameAndroidBridge.QueryChannelInfo(); #elif UNITY_EDITOR Debug.Log("[QKGame] onQueryChannelInfo (Editor)"); #endif }</pre> Step 4：QuickListener.cs — 增加回调契约 <pre class="brush:js;toolbar:false">// 1) 抽象方法（CP 必须实现） public abstract void onQueryChannelSuccess(string channelId); public abstract void onQueryChannelFailed(ErrorMsg errMsg); // 2) 字符串重载（Java SendMessage 入口，解析 JSON） public void onQueryChannelSuccess(string msg) { var data = JObject.Parse(msg); onQueryChannelSuccess(data["channelId"]?.Value<string>() ?? ""); } public void onQueryChannelFailed(string msg) { var data = JObject.Parse(msg); var err = new ErrorMsg { errMsg = data["msg"]?.Value<string>() ?? "" }; onQueryChannelFailed(err); }</pre> JSON 字段命名须与 Java JSONObject.put 一致，并参考现有 onLoginSuccess / onPaySuccess 的字段风格（Android 与 iOS 尽量统一） Step 5：CP 实现 Listener <pre class="brush:js;toolbar:false">public override void onQueryChannelSuccess(string channelId) { Debug.Log("[CP] query channel ok: " + channelId); } public override void onQueryChannelFailed(ErrorMsg errMsg) { Debug.Log("[CP] query channel fail: " + errMsg.errMsg); } // 触发 QKGame.onQueryChannelInfo();</pre> 7.6 异步接口扩展检查清单 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 文件 </td> <td> 动作 </td> </tr> <tr> <td> QKConnector.java </td> <td> UI 线程调 SDK；成功/失败 sendMessage(method, json) </td> </tr> <tr> <td> QuickGameAndroidBridge.cs </td> <td> CallStatic 触发 </td> </tr> <tr> <td> QKGame.cs </td> <td> 对外 public static void onXxx() </td> </tr> <tr> <td> QuickListener.cs </td> <td> 新增 abstract + string 重载（JSON 解析） </td> </tr> <tr> <td> CP Listener 子类 </td> <td> 实现新 abstract 方法 </td> </tr> <tr> <td> 真机验收 </td> <td> 成功/失败路径各测一遍 </td> </tr> </tbody> </table> 7.7 常见问题 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 问题 </td> <td> 原因 </td> <td> 处理 </td> </tr> <tr> <td> CallStatic 报 method not found </td> <td> Java 方法名与 C# 字符串不一致 </td> <td> 核对大小写，Java 为 channelId 则 C# 传 "channelId" </td> </tr> <tr> <td> 返回空串 </td> <td> 未 init / 未 login 就查询 </td> <td> 文档注明调用时机；Java 侧打 Log 辅助排查 </td> </tr> <tr> <td> 异步回调进不来 </td> <td> Listener 未注册或方法名不匹配 </td> <td> SendMessage 的方法名须与 QuickListener 的 public void onXxx(string msg) 完全一致 </td> </tr> <tr> <td> Editor 下无法测试 </td> <td> #if UNITY_ANDROID && !UNITY_EDITOR </td> <td> 正常；仅真机或 Android Player 验证 </td> </tr> <tr> <td> 改 Java 后未生效 </td> <td> 未重新 Build </td> <td> 重新 Android Build，确认 Console 有拷贝 QKConnector.java 日志 </td> </tr> </tbody> </table> 7.8 与 QuickGame_unity 的协作关系 QuickGame_unity（AS）                                unitybridgecn（Unity） ─────────────────────                    ──────────────────── 商务 SDK AAR 接入                                        QKConnector.java 桥接 QGManager exportUnitySdk → libs/*.aar      ──拷贝──► Plugins/Android/libs/ Manifest 模板（Activity 等）     ──合并──► Plugins/Android/AndroidManifest.xml                                                                 QuickGameAndroidBridge.cs                                                                 QKGame.cs → CP 调用 分工建议： SDK 版本升级、AAR 导出、Manifest 大段合并 → 在 QuickGame_unity 完成 Unity 可调用的具体 API、回调 JSON 格式 → 在 unitybridgecn 的 QKConnector + QKGame 完成 每新增一个 CP 可见接口，至少改动 3 个文件（同步）或 4～5 个文件（异步含 Listener） 相关文件速查 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 类型 </td> <td> 路径 </td> </tr> <tr> <td> C# API </td> <td> Assets/QuickGameSDK/Scripts/QKGame.cs </td> </tr> <tr> <td> C# Bridge </td> <td> Assets/QuickGameSDK/Scripts/QuickGameAndroidBridge.cs </td> </tr> <tr> <td> 回调基类 </td> <td> Assets/QuickGameSDK/Scripts/QuickListener.cs </td> </tr> <tr> <td> Java Bridge </td> <td> Assets/Plugins/Android/com/quickgame/unity/QKConnector.java </td> </tr> <tr> <td> Manifest </td> <td> Assets/Plugins/Android/AndroidManifest.xml </td> </tr> <tr> <td> Gradle 模板 </td> <td> Assets/Plugins/Android/mainTemplate.gradle </td> </tr> <tr> <td> Build 预处理 </td> <td> Assets/QuickGameSDK/Editor/AndroidPreprocessBuild.cs </td> </tr> <tr> <td> Gradle 后处理 </td> <td> Assets/QuickGameSDK/Editor/AndroidPostGenerateGradle.cs </td> </tr> <tr> <td> 配置 </td> <td> Assets/Resources/QKSettings.asset </td> </tr> <tr> <td> Settings 窗口 </td> <td> Assets/QuickGameSDK/Windows/Editor/PackageSettingsWindow.cs </td> </tr> <tr> <td> SDK AAR </td> <td> Assets/Plugins/Android/libs/app-release.aar </td> </tr> <tr> <td> AS 导出源 </td> <td> QuickGame_unity/app/build.gradle.kts </td> </tr> </tbody> </table> 8. 附录：Android Studio 导出命令 <pre class="brush:js;toolbar:false"># 在 QuickGame_unity 工程根目录 ./gradlew :app:exportUnitySdk # 拷贝到 Unity cp unity_export/*.aar <Unity工程>/Assets/Plugins/Android/libs/ cp unity_export/aarlib/*.aar <Unity工程>/Assets/Plugins/Android/libs/</pre> <h4> 三、iOS 部分说明 </h4> Unity 接口以 Assets/QuickGameSDK/Scripts/ 为准；原生 SDK 目录默认 iOS/releaseSDK 1. 接入说明 1.1 前提 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 项 </td> <td> 说明 </td> </tr> <tr> <td> Unity 侧 </td> <td> 实现 QuickListener，调用 QKGame.setListener、QKGame.startSdk 等 API </td> </tr> <tr> <td> Build 产物 </td> <td> Xcode 工程（.xcodeproj），非 IPA </td> </tr> <tr> <td> Xcode </td> <td> 配置签名、真机运行； </td> </tr> <tr> <td> 验证环境 </td> <td> 须 iOS 真机；Editor Play 不调用原生 SDK </td> </tr> </tbody> </table> 1.2 标准接入流程 采用路径 A（自动集成）。工程准备可使用 unitybridgecn 参考工程，或将发版资源集成至自有工程（文件清单见 2.3） <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 步骤 </td> <td> 操作 </td> </tr> <tr> <td> 1 </td> <td> 向运营人员获取 releaseSDK、productCode；按需获取微信/QQ 参数、内购商品 ID </td> </tr> <tr> <td> 2 </td> <td> 集成 Unity 脚本、Newtonsoft.Json.dll、IOSPostProcessBuild.cs；解压 iOS/releaseSDK（含 JySDK.framework） </td> </tr> <tr> <td> 3 </td> <td> QuickSDK → Settings 配置 QKSettings；Player Settings → iOS 设置 Bundle ID </td> </tr> <tr> <td> 4 </td> <td> 实现 QuickListener；Awake 中 setListener；合适时机调用 startSdk </td> </tr> <tr> <td> 5 </td> <td> Build Settings → iOS → Build </td> </tr> <tr> <td> 6 </td> <td> Xcode 配置签名，真机 Run </td> </tr> </tbody> </table> 调用时序：setListener → startSdk → onInitSuccess → onLogin → onUpdateRole（支付前）→ onPayOrder。 Build 失败 JySDK/JySDKManager.h not found：确认 iOS/releaseSDK 或 UNITY_QUICKGAME_SDK_ROOT（§4）后重新 Build iOS 1.3 接入方式 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> </td> <td> 路径 A：自动集成（推荐） </td> <td> 路径 B：手动集成 </td> </tr> <tr> <td> 条件 </td> <td> 含 IOSPostProcessBuild.cs 且配置 releaseSDK </td> <td> 未使用导出脚本 </td> </tr> <tr> <td> Unity Build 后 </td> <td> 自动集成 SDK、桥接、链接参数、微信/QQ 配置 </td> <td> 仅生成基础 Xcode 工程 </td> </tr> <tr> <td> Xcode 工作 </td> <td> 签名与真机运行 </td> <td> 手动集成 SDK 与桥接 </td> </tr> </tbody> </table> 2. CP 须手动配置清单 2.1 参数配置 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 配置项 </td> <td> 获取方 </td> <td> 配置位置 </td> <td> 说明 </td> </tr> <tr> <td> productCode </td> <td> QuickGame 后台 </td> <td> QuickSDK → Settings 写入 QKSettings.asset；导出时 PostProcess 写入 QKConnector 的 kQKDefaultProductCode </td> <td> 运行时推荐 QKGame.startSdk()；亦可 onInit(productCode) </td> </tr> <tr> <td> Bundle ID </td> <td> CP 自有 </td> <td> Unity Player Settings → iOS → Bundle Identifier </td> <td> 须与苹果开发者后台、描述文件、微信/QQ 应用配置一致 </td> </tr> <tr> <td> 内购商品 ID </td> <td> App Store Connect </td> <td> onPayOrder 的 goodsId（或 onPay 的 productId） </td> <td> 与 App Store Connect 商品 ID 一致 </td> </tr> </tbody> </table> 2.2 Unity 工程内（CP 代码与资源） <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td style="width:15%;"> 配置项 </td> <td> 配置位置 </td> <td> 说明 </td> </tr> <tr> <td> 回调监听 </td> <td> 继承 QuickListener，Awake 最早调用 QKGame.setListener(this) </td> <td> GameObject 名称固定，勿运行时改名 </td> </tr> <tr> <td> 初始化 </td> <td> QKGame.startSdk()（推荐） </td> <td> 自动读 QKSettings、配置微信/QQ、再 onInit；收到 onInitSuccess 后再 onLogin </td> </tr> <tr> <td> 微信/QQ（运行时） </td> <td> QKSettings 中 wxAppId 等字段，由 startSdk() 自动 configureThirdPartyLogin </td> <td> 亦可手动调用 configureThirdPartyLogin（须在 onInit 前） </td> </tr> <tr> <td> 微信/QQ（导出 plist） </td> <td> QuickGameIOSIntegrationSettings.cs </td> <td> 修改 WxAppId、WxUniversalLink、QqAppId 等；正式包勿用 Demo 默认值 </td> </tr> <tr> <td> releaseSDK 路径 </td> <td> ReleaseSdkRoot（默认 iOS/releaseSDK）→ UNITY_QUICKGAME_SDK_ROOT → ../quickgame/releaseSDK </td> <td> 须含 iOS/SDK/JySDK.framework </td> </tr> </tbody> </table> 推荐代码（无平台 #if）： <pre class="brush:js;toolbar:false">void Awake() => QKGame.setListener(this); public void StartSdk() { QKGame.startSdk(); // 读 QKSettings（含 productCode、微信/QQ） // 或覆盖：QKGame.startSdk("你的productCode", null); } </pre> 支付推荐全平台统一： <pre class="brush:js;toolbar:false">QKGame.onPayOrder(new QKGame.QKPayOrderInfo { cpOrderNo = "...", subject = "元宝", goodsId = "com.xxx.item1", amount = "6", /* 其余角色字段见总文档 §6.2.3 */ });</pre> 2.3 拷贝到自有 Unity 工程（首次集成） 必选 <pre class="brush:js;toolbar:false">Assets/QuickGameSDK/Scripts/ # QKGame.cs、QuickListener.cs 等 Assets/Plugins/JsonNet/Newtonsoft.Json.dll</pre> iOS 强烈建议（自动集成，免 Xcode 手拖 SDK） <pre class="brush:js;toolbar:false">Assets/QuickGameSDK/Editor/IOSPostProcessBuild.cs Assets/QuickGameSDK/Editor/QuickGameIOSIntegrationSettings.cs iOS/releaseSDK/ # 默认原生 SDK 目录（发版包解压）</pre> 桥接文件（QKConnector / QuickGameLifecycle） 推荐：不放入 Assets/Plugins/iOS/；Build 时由 IOSPostProcessBuild 从 releaseSDK/Unity3d/1. Xcode/ 拷贝到导出工程 Libraries/QuickGame/ 手动路径 B：若不用 PostProcess，须自行将桥接文件放入 Assets/Plugins/iOS/ 或导出后拖入 Xcode 发版包等价路径：releaseSDK/Unity3d/1. Xcode/、releaseSDK/Unity3d/2. U3D/ 2.4 本机证书与签名（无法由 Unity 生成） <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td style="width:17%;"> 配置项 </td> <td> 操作 </td> </tr> <tr> <td> Apple 开发者账号 </td> <td> Xcode → Settings → Accounts 登录 </td> </tr> <tr> <td> 证书 </td> <td> 安装 Development / Distribution 证书 </td> </tr> <tr> <td> 描述文件 </td> <td> 下载与 Bundle ID 匹配的 Profile；参考工程默认名 DevAny </td> </tr> <tr> <td> Team / Profile 名写入工程 </td> <td> 环境变量 UNITY_IOS_DEVELOPMENT_TEAM、UNITY_IOS_PROVISIONING_PROFILE，或改 IOSPostProcessBuild.cs 中 DefaultTeamId / DefaultProvisioningProfile </td> </tr> </tbody> </table> <pre class="brush:js;toolbar:false"># 从终端启动 Unity 前设置（Hub 直接点开 Unity 读不到终端环境变量时，可用 launchctl / 脚本包装） export UNITY_IOS_DEVELOPMENT_TEAM=你的TeamId export UNITY_IOS_PROVISIONING_PROFILE=你的描述文件名 export UNITY_QUICKGAME_SDK_ROOT=/path/to/releaseSDK </pre> 2.5 微信 / QQ 开放平台（服务器与后台，Unity 外） <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 平台 </td> <td> 配置 </td> </tr> <tr> <td> 微信开放平台 </td> <td> iOS 应用 AppId、Universal Link 域名 </td> </tr> <tr> <td> 微信 </td> <td> 服务器部署 apple-app-site-association（与 WxUniversalLink 域名一致） </td> </tr> <tr> <td> QQ 互联 </td> <td> iOS AppId、Universal Link（若使用） </td> </tr> <tr> <td> 与 Unity 一致 </td> <td> configureThirdPartyLogin 与 QuickGameIOSIntegrationSettings 中参数须与后台完全一致 </td> </tr> </tbody> </table> 2.6 Info.plist 隐私描述（须 CP 按游戏补充） PostProcess 不会自动写入以下键；按 SDK / 苹果审核要求在 Unity Player Settings → iOS → Other Settings 或导出后 Info.plist 添加： <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> Key </td> <td> 何时需要 </td> </tr> <tr> <td> NSPhotoLibraryUsageDescription </td> <td> 相册选图 </td> </tr> <tr> <td> NSCameraUsageDescription </td> <td> 相机 </td> </tr> <tr> <td> NSMicrophoneUsageDescription </td> <td> 麦克风 </td> </tr> <tr> <td> NSUserTrackingUsageDescription </td> <td> ATT 追踪（若接广告归因） </td> </tr> <tr> <td> NSLocationWhenInUseUsageDescription </td> <td> 定位（若 SDK/游戏使用） </td> </tr> </tbody> </table> 2.7 出包与验证 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 步骤 </td> <td> 说明 </td> </tr> <tr> <td> Unity Build iOS </td> <td> 产出 Xcode 工程，不是 IPA </td> </tr> <tr> <td> Xcode 真机 Run </td> <td> 日常联调；JySDK 为真机库，模拟器无法完整验证 </td> </tr> <tr> <td> Archive → 导出 IPA </td> <td> 内测 / 上架 </td> </tr> </tbody> </table> 3. 参考工程（unitybridgecn） 1. 配置 QKSettings 2. 打开 Assets/Scenes/QuickGameDemo.unity 3. Build iOS → Xcode 真机 Run → 执行 Demo 按钮流程 4. releaseSDK 路径与环境变量 4.1 查找顺序（IOSPostProcessBuild.ResolveSdkRoot） 1. QuickGameIOSIntegrationSettings.ReleaseSdkRoot（默认 iOS/releaseSDK，相对 Unity 工程根目录） 2. 环境变量 UNITY_QUICKGAME_SDK_ROOT 3. 工程内 <工程>/iOS/releaseSDK 4. 同级目录 ../quickgame/releaseSDK（研发联调兜底） 解析失败时 Console 会打印已尝试的完整路径列表 4.2 环境变量（可选） <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 变量 </td> <td> 作用 </td> <td> 默认 </td> </tr> <tr> <td> — </td> <td> releaseSDK 根目录（代码常量） </td> <td> ReleaseSdkRoot = "iOS/releaseSDK" </td> </tr> <tr> <td> UNITY_QUICKGAME_SDK_ROOT </td> <td> 覆盖 SDK 路径 </td> <td> 见 4.1 顺序 </td> </tr> <tr> <td> UNITY_IOS_DEVELOPMENT_TEAM </td> <td> 签名 Team ID </td> <td> X29G7GACDM </td> </tr> <tr> <td> UNITY_IOS_PROVISIONING_PROFILE </td> <td> 描述文件名称 </td> <td> DevAny </td> </tr> </tbody> </table> 5. Build iOS 后自动完成（IOSPostProcessBuild） 使用参考工程或已拷贝 IOSPostProcessBuild.cs 时，每次 Build iOS 后自动执行，一般无需在 Xcode 重复操作： <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 自动项 </td> <td> 说明 </td> </tr> <tr> <td> 拷贝 releaseSDK/iOS/SDK/* </td> <td> → Frameworks/QuickGameSDK/ </td> </tr> <tr> <td> 链接 JySDK.framework、.a </td> <td> UnityFramework Target </td> </tr> <tr> <td> 拷贝 .bundle </td> <td> Unity-iPhone Target </td> </tr> <tr> <td> Other Linker Flags -ObjC </td> <td> UnityFramework + Unity-iPhone </td> </tr> <tr> <td> 拷贝 QKConnector.mm </td> <td> 从 releaseSDK/Unity3d/1. Xcode/（若存在） </td> </tr> <tr> <td> kQKDefaultProductCode </td> <td> 若存在 QKSettings.productCode，写入导出工程内 QKConnector.mm </td> </tr> <tr> <td> 微信/QQ URL Scheme </td> <td> Info.plist </td> </tr> <tr> <td> LSApplicationQueriesSchemes </td> <td> Info.plist </td> </tr> <tr> <td> URL / Universal Link </td> <td> 补丁 UnityAppController.mm </td> </tr> <tr> <td> Team / Profile 名称 </td> <td> project.pbxproj </td> </tr> </tbody> </table> 导出成功标志：Console 无红色编译错误；目录含 Unity-iPhone.xcodeproj；日志含 [QuickGame] iOS 导出完成 JySDK 为静态 framework。缺少 -ObjC 时常见崩溃： +[UIImage jywlNamed:]: unrecognized selector、Unknown class HXTextView in Interface Builder file      若报 'JySDK/JySDKManager.h' file not found：未找到 releaseSDK → 确认 iOS/releaseSDK 存在或设置 UNITY_QUICKGAME_SDK_ROOT 后重新 Build iOS（只改 Unity 不会更新已导出的 Xcode 目录） 6. 未使用导出脚本时的手动 Xcode 接入 仅当未使用 IOSPostProcessBuild 时按下列步骤在 Xcode 操作 6.1 桥接文件 将以下文件加入工程（Unity 导出后通常在 Libraries/Plugins/iOS/ 或自行放在 Libraries/QuickGame/）： QKConnector.h / QKConnector.mm QuickGameLifecycle.h / QuickGameLifecycle.mm 来源：Assets/Plugins/iOS/ 或 releaseSDK/Unity3d/1. Xcode/ 6.2 原生 SDK 将 releaseSDK/iOS/SDK/ 下 framework / .a / .bundle 拖入 Xcode   Unity 2019.3+：.framework、.a → UnityFramework；.bundle → Unity-iPhone   UnityFramework → Build Settings → Other Linker Flags 添加 -ObjC 6.3 productCode 编辑 QKConnector.mm 中 kQKDefaultProductCode（与 QuickGame 后台一致）；或在 Unity 配置 QKSettings 后重新 Build iOS 由 PostProcess 写入 6.4 微信 / QQ Unity：configureThirdPartyLogin（见 2.2） Xcode Info.plist 手动添加： CFBundleURLTypes → CFBundleURLSchemes：wx你的AppId、tencent你的QQAppId LSApplicationQueriesSchemes：weixin、weixinULAPI、mqq、mqqopensdkapi 等 UnityAppController.mm（对照 releaseSDK/iOS/Demo/AppDelegate.m）： <pre class="brush:js;toolbar:false">#import "QuickGameLifecycle.h" // application:openURL:options: 内、转发给 Unity 之前： if (QuickGameForwardOpenURL(app, url, options)) return YES; // application:continueUserActivity:restorationHandler: 内： if (QuickGameForwardContinueUserActivity(application, userActivity, restorationHandler)) return YES;</pre> 6.5 签名 在 Xcode 为 Unity-iPhone 选择 Team、Provisioning Profile；或使用与 PostProcess 相同的 Manual 签名项 7. 常见问题 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 现象 </td> <td> 处理 </td> </tr> <tr> <td> Build Unknown 0 秒、Xcode 目录为空 </td> <td> Unity Editor 脚本编译失败；修 Console 红字（如 IOSPostProcessBuild.cs API 不兼容）后重导 </td> </tr> <tr> <td> JySDK/JySDKManager.h not found </td> <td> 将 SDK 放到 iOS/releaseSDK 或设置 UNITY_QUICKGAME_SDK_ROOT，重新 Build iOS </td> </tr> <tr> <td> jywlNamed / HXTextView 崩溃 </td> <td> UnityFramework 缺 -ObjC；确认 PostProcess 已执行或手动添加 </td> </tr> <tr> <td> 缺少证书 / provisioning profile </td> <td> 本机安装证书与描述文件 </td> </tr> <tr> <td> Unity 无登录回调 </td> <td> 未 setListener 或 Listener 物体名与原生不一致 </td> </tr> <tr> <td> 链接 QKInit 失败 </td> <td> 未加入 QKConnector.mm </td> </tr> <tr> <td> 微信/QQ 授权后无回调 </td> <td> 检查2.5 后台与 Universal Link；Info.plist Scheme；UnityAppController 转发 </td> </tr> <tr> <td> Editor Play 无 SDK </td> <td> 正常；必须真机 Build </td> </tr> <tr> <td> 想要 IPA </td> <td> Unity 只出 Xcode 工程；须 Xcode Archive 或 CI </td> </tr> </tbody> </table> 8. 相关文件 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 文件 </td> <td> 作用 </td> </tr> <tr> <td> Assets/QuickGameSDK/Scripts/QKGame.cs </td> <td> Unity API </td> </tr> <tr> <td> Assets/QuickGameSDK/Editor/IOSPostProcessBuild.cs </td> <td> 导出后自动集成 SDK、桥接、签名 </td> </tr> <tr> <td> Assets/QuickGameSDK/Editor/QuickGameIOSIntegrationSettings.cs </td> <td> ReleaseSdkRoot、微信/QQ 默认参数 </td> </tr> <tr> <td> Assets/QuickGameSDK/Demo/QuickGameDemoController.cs </td> <td> 参考 Demo </td> </tr> <tr> <td> iOS/releaseSDK/ </td> <td> 默认原生 SDK 目录 </td> </tr> <tr> <td> releaseSDK/Unity3d/1. Xcode/QKConnector.* </td> <td> 桥接源（Build 时拷贝） </td> </tr> <tr> <td> releaseSDK/Unity3d/1. Xcode/QuickGameLifecycle.* </td> <td> URL 回调转发源 </td> </tr> <tr> <td> releaseSDK/iOS/Demo/AppDelegate.m </td> <td> 原生 Demo 对照 </td> </tr> </tbody> </table> <h4> 四、WebGL(小游戏)部分说明 </h4> 架构概览 CP 游戏代码 <pre class="brush:js;toolbar:false"> ↓ QKGame.cs（统一 API） ↓ QuickGameWebGLBridge.cs（C# → jslib DllImport） ↓ QuickGameWebGL.jslib（mergeInto，转发 QuickGameJS.dispatch） ↓ QuickGameWebGLBootstrap.jspre（构建时生成，内联 QGSDK.js + QuickGameJS 适配层） ↓ QGManager（商务 QGSDK.js，wx / ali 等渠道版） ↓ SendMessage → QuickListener（回调）</pre> 1. 准备渠道 QGSDK.js 1.1 目录结构 每个小游戏渠道对应一个目录，内含平台运营人员提供的 QGSDK.js： <pre class="brush:js;toolbar:false">Assets/QuickGameSDK/Channels/ ├── wx/ │ └── QGSDK.js # 微信小游戏 SDK └── ali/ └── QGSDK.js # 支付宝小游戏 SDK</pre> 1.2 QGSDK.js 格式要求 文件末尾须包含导出标记（构建脚本用于识别标准 QGSDK 源文件）： <pre class="brush:js;toolbar:false">module.exports.QGManager = QGManager;</pre> 构建时 QuickGameWebGLChannelBuilder 会： 1. 去掉上述 module.exports 行 2. 将 QGSDK 主体缩进后嵌入 IIFE 3. 追加 QuickGameJS 适配层（dispatch / SendMessage） 4. 生成 QuickGameWebGLBootstrap.jspre 1.3 新增渠道 在 Assets/QuickGameSDK/Channels/ 下新建目录，如 tt（抖音） 放入运营人员提供的 QGSDK.js QuickSDK → Settings 中即可在下拉列表看到新渠道 2. 导入 Unity 工程资源 2.1 目录清单 <pre class="brush:js;toolbar:false">Assets/ ├── QuickGameSDK/ │ ├── Scripts/ │ │ ├── QKGame.cs # CP 统一 API │ │ ├── QuickListener.cs # 回调基类 │ │ └── QuickGameWebGLBridge.cs # WebGL C# 桥接 │ ├── Editor/ │ │ └── QuickGameWebGLChannelBuilder.cs # 渠道构建 + WebGLPreprocessBuild │ ├── Channels/ │ │ ├── wx/QGSDK.js │ │ └── ali/QGSDK.js │ └── Demo/ # 可选 ├── Plugins/ │ ├── WebGL/ │ │ ├── QuickGameWebGL.jslib # 自动生成（可入库） │ │ └── QuickGameWebGLBootstrap.jspre # 自动生成（.gitignore 忽略） │ └── JsonNet/ # Newtonsoft.Json ├── QuickGameSDK/Windows/Plugins/script/ │ └── PackageSettings.cs # QKSettings 字段定义 ├── QuickGameSDK/Windows/Editor/ │ └── PackageSettingsWindow.cs # QuickSDK → Settings └── Resources/ └── QKSettings.asset # 运行时 / 构建配置</pre> 2.2 自动生成文件说明 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 文件 </td> <td> 生成时机 </td> <td> 是否入库 </td> </tr> <tr> <td> QuickGameWebGLBootstrap.jspre </td> <td> Rebuild / WebGL Build 前 </td> <td> 通常 .gitignore 忽略，拉代码后需 Rebuild </td> </tr> <tr> <td> QuickGameWebGL.jslib </td> <td> 同上 </td> <td> 建议入库，保证未 Rebuild 时结构正确 </td> </tr> </tbody> </table> 首次拉工程或切换渠道后，在 Unity 菜单执行： QuickSDK → Settings → Rebuild WebGL Bridge (jspre/jslib) 或直接执行 WebGL Build（构建前会自动 Rebuild） 3. QKSettings 配置 菜单：QuickSDK → Settings <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 字段 </td> <td> 用途 </td> <td> 对应 JS </td> </tr> <tr> <td> baseUrl </td> <td> SDK 服务器地址 </td> <td> QGManager.setHost(host)，CP 调用 QKGame.onSetHost(baseUrl) </td> </tr> <tr> <td> productCode </td> <td> 产品码（32 位） </td> <td> QGManager.init(productCode, cb)，CP 调用 QKGame.onInit(productCode) </td> </tr> <tr> <td> miniGameChannel </td> <td> 构建渠道 </td> <td> 选择内联 Channels/<channel>/QGSDK.js（wx / ali） </td> </tr> </tbody> </table> 配置文件：Assets/Resources/QKSettings.asset WebGL Build 前校验（WebGLPreprocessBuild）： 1. baseUrl 不能为空 2. productCode 不能为空 3. miniGameChannel 必须对应存在的 Channels/<channel>/QGSDK.js 校验通过后自动按当前渠道重生 jspre / jslib 4. CP 接入代码 4.1 继承 QuickListener <pre class="brush:js;toolbar:false">using quickgame; using UnityEngine; public class MyGameListener : QuickListener { public override void onInitSuccess() { Debug.Log("Init OK"); } public override void onInitFailed(ErrorMsg message) { Debug.Log("Init Fail: " + message.errMsg); } public override void onLoginSuccess(UserInfo userInfo) { Debug.Log("Login: " + userInfo.uid); } public override void onLoginFailed(ErrorMsg errMsg) { Debug.Log("Login Fail: " + errMsg.errMsg); } public override void onLogoutSuccess() { } public override void onPaySuccess(PayResult r) { Debug.Log("Pay OK: " + r.cpOrderNo); } public override void onPayFailed(PayResult r) { Debug.Log("Pay Fail: " + r.message); } public override void onPayCancel(PayResult r) { } }</pre> 4.2 标准调用顺序（WebGL 专用） <pre class="brush:js;toolbar:false">void Start() { // 1. 注册回调（Awake 中亦可，必须在 init 之前） QKGame.setListener(myListener); // 2. 从 QKSettings 读取（或直接写死测试值） var settings = Resources.Load<quicksdk.PackageSettings>("QKSettings"); string host = settings.baseUrl; string productCode = settings.productCode; // 3. 两步初始化（顺序不可颠倒） QKGame.onSetHost(host); QKGame.onInit(productCode); // 4. 登录 QKGame.onLogin(); } </pre> 注意： WebGL 下调用无参 QKGame.onInit() 不会初始化 SDK，只会打 Warning。必须先 onSetHost 再 onInit(productCode) 4.3 支付 WebGL 使用 onPayOrder，参数类型为 QKGame.QKPayOrderInfo（不是 Android 的 onPay）： <pre class="brush:js;toolbar:false">QKGame.onPayOrder(new QKGame.QKPayOrderInfo { cpOrderNo = "order_" + DateTime.UtcNow.Ticks, subject = "60钻石", desc = "购买描述", goodsId = "goods_001", amount = "6", // 金额（字符串） extrasParams = "透传参数", userRoleId = "role_001", userRoleName = "玩家名", serverId = "s1", serverName = "一区", userLevel = "10", callbackUrl = "", // 可空，如果游戏下单时设置支付回调，建议支付回调地址加上IP白名单，防止被攥改！！！ buy_quantity = "1" });</pre> 4.4 其他 API <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> QKGame 方法 </td> <td> 说明 </td> </tr> <tr> <td> onGuestLogin() </td> <td> 游客 / 静默登录（内部与 login 走同一 JS 分支） </td> </tr> <tr> <td> onLogout() </td> <td> 登出 </td> </tr> <tr> <td> onUpdateRole(...) </td> <td> 上报角色（支付前建议调用） </td> </tr> <tr> <td> onUserCenter() </td> <td> 小游戏侧暂不支持，JS 层仅打 Log </td> </tr> <tr> <td> onRestoreNonConsumptionProducts() </td> <td> 小游戏侧 noop，直接回调 onRestoreSuccess </td> </tr> </tbody> </table> 4.5 Demo 参考 场景：QuickGameDemo.unity WebGL Build 下按钮：SetHost → Init(productCode) → Login → Pay (onPayOrder) 5. 构建与导出小游戏 5.1 Unity WebGL Build 1.QuickSDK → Settings 填写 baseUrl、productCode，选择 Mini Game Channel 2.（可选）点击 Rebuild WebGL Bridge 3.File → Build Settings → WebGL → Build 4. Console 确认日志： <pre class="brush:js;toolbar:false">[QuickGame] WebGL bridge rebuilt: channel=wx, jspre=...B, jslib=...B</pre> 5.2 转小游戏工程 使用对应平台官方工具链将 Unity WebGL 产物转为小游戏 5.3 与旧方案的区别 新方案（当前工程）： QGSDK 已通过 jspre 内联进 Unity WebGL 产物 不需要在宿主 game.js 手动 import QuickGame_Bridge.js 不需要在小游戏工程根目录单独放一份 QGSDK.js 旧方案（母仓早期 Demo）： 宿主侧引入 QuickGame_Bridge.js + 商务 QGSDK.js Unity jslib 仅转发 window._CallMiniGameMethod 6. 回调 JSON 约定 JS 侧通过 GameGlobal.unityInstance.SendMessage(gameObjectName, method, jsonString) 回调 Unity QuickListener.cs 中的字符串重载负责 JSON 解析 初始化 成功： onInitSuccess <pre class="brush:js;toolbar:false">{ "msg": "init ok" }</pre> 失败： onInitFailed <pre class="brush:js;toolbar:false">{ "msg": "错误描述" }</pre> 登录 成功： onLoginSuccess <pre class="brush:js;toolbar:false">{ "userId": "123456", "userToken": "xxx", "userName": "player1", "msg": "login ok", "timeleft": "-1", "isNewUser": "0" }</pre> 失败： onLoginFailed <pre class="brush:js;toolbar:false">{ "msg": "错误描述" }</pre> 支付 成功 / 失败 / 取消（字段与 Android 一致）： <pre class="brush:js;toolbar:false">{ "code": "0", "message": "success", "orderNo": "SDK订单号", "cpOrderNo": "游戏订单号", "extras": "透传参数" }</pre> 登出 成功： onLogoutSuccess <pre class="brush:js;toolbar:false">{ "msg": "logout" }</pre> 7. 内部调用链路（供维护者参考） 以 onLogin() 为例： <pre class="brush:js;toolbar:false">QKGame.onLogin() → QuickGameWebGLBridge.Login() → CallMiniGameMethod("login", "") → jslib: QuickGameJS.dispatch("login", "") → QGManager.login(callback) → send("onLoginSuccess", { userId, userToken, ... }) → Unity SendMessage → QuickListener.onLoginSuccess(string msg) → CP 实现的 onLoginSuccess(UserInfo)</pre> jspre / jslib 分层原因： jspre（--pre-js）：可写任意顶层 JS，内联 QGSDK + 适配层 jslib：Unity 要求顶层只能是 mergeInto(LibraryManager.library, {...})，因此仅放 DllImport 入口 8. 扩展 WebGL 接口 当 CP 需要接入 QGSDK.js 新增能力时，按以下四层扩展（以 QGManager.getChannelId() 为例） 8.1 判断接口类型 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 类型 </td> <td> 处理方式 </td> </tr> <tr> <td> 同步返回值 </td> <td> dispatch 内直接 return 或通过 SendMessage 一次性回传 </td> </tr> <tr> <td> 异步回调 </td> <td> dispatch 内调 QGManager，在 callback 里 send(method, json) </td> </tr> <tr> <td> 纯 C# 查询 </td> <td> Bridge 增加方法 → jslib 增加导出（复杂，优先走 dispatch） </td> </tr> </tbody> </table> 小游戏侧推荐统一走 CallMiniGameMethod(method, param) → QuickGameJS.dispatch，与现有 login / pay 一致 8.2 示例：同步查询 getChannelId() Step 1：QuickGameWebGLChannelBuilder.cs — 在 AdapterSuffixTemplate 的 dispatch 中增加分支 <pre class="brush:js;toolbar:false">if (method === 'getChannelId') { var cid = ''; try { if (QGManager && typeof QGManager.getChannelId === 'function') cid = String(QGManager.getChannelId() || ''); } catch (e) { console.error('[QuickGame] getChannelId', e); } send('onChannelIdResult', { channelId: cid, msg: 'ok' }); return; }</pre> 修改 AdapterSuffixTemplate 后须 Rebuild WebGL Bridge 重生 jspre Step 2：QuickGameWebGLBridge.cs <pre class="brush:js;toolbar:false">public static void GetChannelId() { CallMiniGameMethod("getChannelId", string.Empty); }</pre> Step 3：QKGame.cs <pre class="brush:js;toolbar:false">public static void onGetChannelId() { #if UNITY_WEBGL && !UNITY_EDITOR QuickGameWebGLBridge.GetChannelId(); #elif UNITY_EDITOR Debug.Log("[QKGame] onGetChannelId (Editor)"); #endif }</pre> Step 4：QuickListener.cs — 增加回调（异步通知模式） <pre class="brush:js;toolbar:false">public virtual void onChannelIdResult(string channelId) { } public void onChannelIdResult(string msg) { var data = JObject.Parse(msg); onChannelIdResult(data["channelId"]?.Value<string>() ?? ""); }</pre> Step 5：CP 触发 <pre class="brush:js;toolbar:false">QKGame.onGetChannelId(); // 在 Listener.onChannelIdResult 中接收结果</pre> 8.3 扩展检查清单 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 文件 </td> <td> 动作 </td> </tr> <tr> <td> QuickGameWebGLChannelBuilder.cs </td> <td> dispatch 增加 method 分支 </td> </tr> <tr> <td> QuickGameWebGLBridge.cs </td> <td> 增加 Bridge 方法 </td> </tr> <tr> <td> QKGame.cs </td> <td> 增加对外 API </td> </tr> <tr> <td> QuickListener.cs </td> <td> 增加回调（若有异步结果） </td> </tr> <tr> <td> — </td> <td> Rebuild WebGL Bridge → WebGL Build 验证 </td> </tr> </tbody> </table> 无需修改： QuickGameWebGL.jslib（通用转发 dispatch，Rebuild 时自动覆盖） 9. 注意事项与常见问题 9.1 配置与构建 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 问题 </td> <td> 原因 </td> <td> 处理 </td> </tr> <tr> <td> Build 失败：baseUrl / productCode 为空 </td> <td> QKSettings 未填 </td> <td> QuickSDK → Settings 补全 </td> </tr> <tr> <td> Build 失败：miniGameChannel 无效 </td> <td> 渠道目录缺少 QGSDK.js </td> <td> 检查 Channels/<channel>/QGSDK.js </td> </tr> <tr> <td> jspre 未生成 </td> <td> 未 Rebuild 且 .gitignore 忽略 </td> <td> Settings 点 Rebuild 或 WebGL Build </td> </tr> <tr> <td> 切换 ali 后仍是 wx SDK </td> <td> 未 Rebuild </td> <td> 改 channel 后 Rebuild + 重新 WebGL Build </td> </tr> </tbody> </table> 9.2 运行时 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 问题 </td> <td> 原因 </td> <td> 处理 </td> </tr> <tr> <td> QuickGameJS not found </td> <td> jspre 未注入 </td> <td> 确认 WebGL Build 前 Rebuild 成功 </td> </tr> <tr> <td> QuickGameJS.dispatch missing </td> <td> bootstrap 未完成或 QGSDK 语法错误 </td> <td> 查 Console [QuickGame] bootstrap done </td> </tr> <tr> <td> listener 未设置 </td> <td> 未调 setListener </td> <td> Awake 中 QKGame.setListener(this) </td> </tr> <tr> <td> Unity 未就绪 </td> <td> init 过早，Unity 实例未创建 </td> <td> 延迟到首帧 / Loading 完成后再 init </td> </tr> <tr> <td> init 报 productCode is empty </td> <td> 未调 onInit 或传空 </td> <td> 检查 QKSettings 与 CP 传参 </td> </tr> <tr> <td> init 报请初始化 host </td> <td> 未调 onSetHost </td> <td> 先 onSetHost 再 onInit </td> </tr> <tr> <td> 支付 JSON 解析失败 </td> <td> QKPayOrderInfo 字段缺失 </td> <td> 必填字段勿传 null，用 "" </td> </tr> <tr> <td> Editor 下无法测 SDK </td> <td> #if UNITY_WEBGL && !UNITY_EDITOR </td> <td> 必须 WebGL Build + 小游戏开发者工具 </td> </tr> </tbody> </table> 9.3 与其他平台共存 QKGame.cs / QuickListener.cs 为全平台公共文件，WebGL 改动在 #elif UNITY_WEBGL 分支内 Android / iOS / Windows 不受 WebGL 渠道构建影响 PackageSettings.miniGameChannel 仅 WebGL Build 使用，Android 忽略此字段 9.4 微信小游戏专项 确保 MP 后台配置 request 合法域名（与 baseUrl 一致） Console 搜索 [QuickGame] 排查 dispatch / SendMessage 日志 iOS 端微信小游戏支付走米大师等特殊逻辑，以商务 QGSDK 文档为准 9.5 SDK 升级流程 商务提供新版 QGSDK.js → 替换 Channels/<channel>/QGSDK.js Rebuild WebGL Bridge WebGL Build → 转小游戏 → 开发者工具验证 Init / Login / Pay 全链路 10. 验收清单 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 步骤 </td> <td> 操作 </td> <td> 预期 </td> </tr> <tr> <td> 配置 </td> <td> Settings 选 wx，填 baseUrl / productCode </td> <td> 保存成功 </td> </tr> <tr> <td> Rebuild </td> <td> Rebuild WebGL Bridge </td> <td> Console  输出 channel=wx、jspre/jslib 大小 </td> </tr> <tr> <td> Init </td> <td> onSetHost → onInit </td> <td> onInitSuccess </td> </tr> <tr> <td> Login </td> <td> onLogin </td> <td> onLoginSuccess，含 userId / userToken </td> </tr> <tr> <td> Pay </td> <td> onPayOrder </td> <td> onPaySuccess 或 onPayFailed，含 orderNo / cpOrderNo </td> </tr> <tr> <td> 切渠道 </td> <td> 改 miniGameChannel=ali，Rebuild，重打 </td> <td> 包内 SDK 行为随渠道变化 </td> </tr> <tr> <td> Logout </td> <td> onLogout </td> <td> onLogoutSuccess </td> </tr> </tbody> </table> 相关文件速查 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 类型 </td> <td> 路径 </td> </tr> <tr> <td> C# API </td> <td> Assets/QuickGameSDK/Scripts/QKGame.cs </td> </tr> <tr> <td> C# Bridge </td> <td> Assets/QuickGameSDK/Scripts/QuickGameWebGLBridge.cs </td> </tr> <tr> <td> 回调基类 </td> <td> Assets/QuickGameSDK/Scripts/QuickListener.cs </td> </tr> <tr> <td> 渠道构建 </td> <td> Assets/QuickGameSDK/Editor/QuickGameWebGLChannelBuilder.cs </td> </tr> <tr> <td> jslib </td> <td> Assets/Plugins/WebGL/QuickGameWebGL.jslib </td> </tr> <tr> <td> jspre </td> <td> Assets/Plugins/WebGL/QuickGameWebGLBootstrap.jspre </td> </tr> <tr> <td> 微信 QGSDK </td> <td> Assets/QuickGameSDK/Channels/wx/QGSDK.js </td> </tr> <tr> <td> 支付宝 QGSDK </td> <td> Assets/QuickGameSDK/Channels/ali/QGSDK.js </td> </tr> <tr> <td> 配置 </td> <td> Assets/Resources/QKSettings.asset </td> </tr> <tr> <td> Settings 窗口 </td> <td> Assets/QuickGameSDK/Windows/Editor/PackageSettingsWindow.cs </td> </tr> <tr> <td> Demo </td> <td> Assets/QuickGameSDK/Demo/QuickGameDemoController.cs </td> </tr> </tbody> </table> 11. 附录：打微信 / 支付宝包快速流程 1. QuickSDK → Settings    ├── baseUrl        = https://qkgamesdk.quickapi.net    ├── productCode    = 你的32位产品码    └── miniGameChannel = wx 或 ali 2. Rebuild WebGL Bridge（可选，Build 前也会自动执行） 3. Build Settings → WebGL → Build 4. 官方工具转小游戏 → 开发者工具导入 → 真机验证 <h4> 五、Windows PC 接入说明 </h4> 1. 推荐方式（与 iOS 统一） 使用 QuickGameDemo.unity + QKGame <pre class="brush:js;toolbar:false">QKGame.setListener(this); QKGame.onInit(); QKGame.onUpdateRole(...); // 支付前必须先上报角色 QKGame.onPay(...);</pre> 2. Windows资源路径说明 <table style="width:1000px;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 项 </td> <td> 路径 </td> </tr> <tr> <td> PC SDK 脚本 </td> <td> Assets/QuickGameSDK/Windows/ </td> </tr> <tr> <td> 配置 </td> <td> Assets/Resources/QKSettings.asset </td> </tr> <tr> <td> Webview程序 </td> <td> Assets/StreamingAssets/Quicksdk/PCSDK_release/ </td> </tr> </tbody> </table> 3. Build Build Settings → PC, Mac & Linux Standalone → Target Windows 在 Windows 环境构建与运行 4. QKSettings 字段 baseUrl、productCode、channelCode 菜单 QuickSDK → Settings（Editor）可编辑 QKSettings.asset 5. 验收 Windows Build 运行 QuickGameDemo Init → Login → UpdateRole → Pay 回调正常