Q衢付通文档中心
CP 控制台联运总后台 ↗

DEVELOPER DOCUMENTATION

接入游戏,连接全平台发行

涵盖 Android AAR、iOS Swift/ObjC 与 H5/小游戏 JS 集成,支持平台登录、实名防沉迷、悬浮球、安全收银台与服务端会话签发。

01 准备接入资料

从SDK 下载页面取得 AAR 和示例,再向接入负责人确认游戏 ID、渠道编码和后端授权配置。最低 Android API 23,Java 8。游戏保留自己的账号和角色系统。

API 基础地址:https://sdk.qufutong.com。游戏方集成 SDK 并交付母包,由发行团队生成渠道包。

02 集成 Android SDK

将 qufutong-sdk-0.1.0.aar 放入 app/libs 并添加依赖:

dependencies {
    implementation files('libs/qufutong-sdk-0.1.0.aar')
}

同一进程复用一个 SDK 实例,由稳定的生命周期持有者管理:

QufutongSdk sdk = new QufutongSdk(
    context, "https://sdk.qufutong.com",
    gameId, channelCode, false
);

AAR 声明 INTERNET 权限。渠道包内的标记提供游戏、渠道及包 ID。使用 getGameId()、getChannelCode()、getPackageId() 取得归属信息。

03 由游戏后端申请会话

后端验证玩家身份,并依据可信发行记录核对游戏、渠道和包归属。不要直接信任客户端提交的玩家 ID 或归属字段。签发接口当前信任授权调用方,发行记录核对需由游戏后端完成。

POST /api/v1/sdk-sessions
Authorization: Bearer <服务端授权凭证>
Content-Type: application/json

{
  "player_id": "已认证玩家ID",
  "game_id": "游戏ID",
  "channel_code": "渠道编码",
  "package_id": "渠道包ID"
}

成功返回 HTTP 201,包含 token 和 session。将短期 token 交给对应玩家客户端,再调用 sdk.login(playerToken, callback)。

管理员凭证、签名密钥和 AccessKey 仅保存在服务端,不能写入 APK 或前端页面。

04 绑定业务生命周期

SDK 会话验证成功后上报登录;进入游戏或回到前台上报活跃;角色创建与等级变化调用相应事件。回调在主线程,入队成功与服务端确认分别处理。

会话约一小时有效。应用重开或收到 http_401 时,向游戏后端重新获取 token 并登录 SDK。会话续期不应额外产生业务登录事件。

退出账号调用 sdk.logout(),保留原账号待发队列;持有者结束时调用 sdk.close()。完整事件字段见事件接口与补传。

05 登录、实名防沉迷、悬浮球与收银台 UI

客户端 SDK 内置平台玩家注册/密码登录/游客一键登录弹窗、国家新闻出版署(NPPA)实名认证弹窗、游戏内可拖拽悬浮球(玩家中心)与聚合收银台弹窗:

// 挂载游戏内悬浮球(玩家中心、实名状态、改密、订单记录)
QufutongSdkUi.attachFloatingBall(activity, sdk);

// 弹出平台登录/注册/游客框(未实名账号自动串联弹出实名防沉迷认证框)
QufutongSdkUi.showLoginDialog(activity, sdk, callback);

// 弹出安全收银台拉起支付(自动核验实名状态与未成年人单笔/月累计限额)
QufutongSdkUi.showCashierDialog(activity, sdk, "gem_60", "60元宝", 600, "s1", "role_1", callback);

06 集成 iOS SDK (qufutong-sdk-ios)

从下载中心获取 qufutong-ios-sdk-0.1.0.zip,通过 Swift Package Manager (Package.swift) 或将 Sources/QufutongSDK 引入 Xcode 工程。云端分包引擎会自动将渠道标识写入 Payload/*.app/qufutong/channel_id.txt 与 channel_config.json:

let sdk = try QufutongSDK(baseUrl: "https://sdk.qufutong.com", gameId: gameId, fallbackChannel: "ios-appstore")
QufutongSDKUI.attachFloatingBall(to: self, sdk: sdk)
QufutongSDKUI.showLoginModal(from: self, sdk: sdk) { result, code, msg in }
QufutongSDKUI.showCashierModal(from: self, sdk: sdk, productId: "gem_60", productName: "60元宝", amountCents: 600, serverId: "s1", roleId: "r1") { result, code, msg in }

07 集成 H5 与小游戏 JS SDK (qufutong-sdk-js)

从下载中心获取 qufutong-js-sdk-0.1.0.zip 或单文件脚本 qufutong-sdk-0.1.0.js,支持 H5 网页游戏及微信/抖音/快手小游戏。云端分包引擎处理 .zip 母包时会自动注入 qufutong/channel_env.js:

// 1. 在 H5 入口引入 qufutong/channel_env.js 与 qufutong-sdk.js
// 2. 初始化 SDK 并挂载悬浮球与登录/收银台弹窗:
const sdk = new QufutongSDK({
  baseUrl: "https://sdk.qufutong.com",
  gameId: "demo-h5",
  fallbackChannel: "h5-main"
});
sdk.mountFloatingBall();
sdk.showLoginModal((err, res) => {
  sdk.enqueueEvent({ eventId: crypto.randomUUID(), type: "login" });
});

08 平台账号、实名防沉迷与收银台 REST 接口

接口路径说明
POST /api/v1/sdk/auth/register注册平台玩家账号并签发绑定当前 game_id / channel_code / package_id 的会话令牌与玩家档案
POST /api/v1/sdk/auth/login平台玩家账号密码登录,返回会话令牌、实名状态与防沉迷策略
POST /api/v1/sdk/auth/guest根据设备标识(device_id)快速分配或恢复游客通行证
POST /api/v1/sdk/realname/verify提交真实姓名与 18 位身份证号(ISO 7064 校验位核验),自动计算年龄并执行国家防沉迷时段与充值限额策略
GET /api/v1/sdk/profile悬浮球个人中心读取账号档案、脱敏实名信息、当月累计充值与最近订单记录
POST /api/v1/sdk/profile/password修改当前玩家登录密码(或为游客账号设置正式密码)
POST /api/v1/sdk/cashier/ordersSDK 安全收银台创建充值订单(强制校验实名认证及 8/16/18 周岁未成年单笔与月度限额)
POST /api/v1/sdk/cashier/orders/{id}/complete完成收银台订单支付确认并更新月度累计充值额度

09 游戏引擎三端接入(Unity / Cocos / UE4 & UE5 虚幻引擎 · 兼容 Android、iOS、H5)

Android AAR(com.qufutong.sdk.QufutongEngineBridge)、iOS SDK(QufutongIOSEngineBridge 与 qft_ios_* C-ABI 导出)以及 H5 JS SDK(window.QufutongSDK)提供统一接口签名,下载包内自带跨平台三端自适应桥接脚本:

游戏引擎配套桥接文件(位于 sample/)Android 端机制iOS 端机制H5 / 小游戏端机制
Unity 引擎QufutongUnityBridge.csUNITY_ANDROID 自动通过 AndroidJavaClass 调用 QufutongEngineBridgeUNITY_IOS 自动通过 [DllImport("__Internal")] 调用 qft_ios_* C 接口UNITY_WEBGL 自动桥接浏览器 window.QufutongSDK
Cocos Creator / 2d-xQufutongCocosBridge.ts自动识别 Android 并通过 native.reflection / jsb.reflection 调用 Java 静态桥自动识别 iOS 并通过 reflection.callStaticMethod 调用 QufutongIOSEngineBridge自动识别 H5 / 微信 / 抖音 / 快手小游戏并调用 globalThis.QufutongSDK
Unreal Engine(UE4 / UE5 虚幻引擎)QufutongUnrealBridge.h
QufutongUnreal_UPL.xml
PLATFORM_ANDROID 通过 JNI 自动调用 QufutongEngineBridge,UPL 自动注入 AARPLATFORM_IOS 通过 extern "C" qft_ios_* 直接调用 iOS 原生桥Pixel Streaming / H5 容器可直接加载 qufutong-sdk-0.1.0.js

1. Unity (C#,兼容 Android / iOS / WebGL):

var bridge = gameObject.AddComponent<Qufutong.SDK.QufutongUnityBridge>();
bridge.OnSdkMessageJson += json => Debug.Log("SDK Callback: " + json);
bridge.InitSdk("https://sdk.qufutong.com", "your-game-id", "unity-channel");
bridge.AttachFloatingBall();
bridge.ShowLoginDialog();
bridge.ShowCashierDialog("gem_60", "60元宝", 600, "s1", "role_1001");

2. Cocos Creator / Cocos2d-x (TS/JS,兼容 Android / iOS / H5与小游戏):

import { QufutongCocosBridge } from './QufutongCocosBridge';
QufutongCocosBridge.init("https://sdk.qufutong.com", "your-game-id", "cocos-channel");
QufutongCocosBridge.attachFloatingBall();
QufutongCocosBridge.showLoginDialog();
QufutongCocosBridge.showCashierDialog("gem_60", "60元宝", 600, "s1", "role_1001");

3. Unreal Engine 虚幻引擎 UE4 / UE5 (C++,兼容 Android JNI / iOS C-ABI):

#include "QufutongUnrealBridge.h"
FQufutongUnrealBridge::Init(TEXT("https://sdk.qufutong.com"), TEXT("your-game-id"), TEXT("ue-channel"));
FQufutongUnrealBridge::AttachFloatingBall();
FQufutongUnrealBridge::ShowLoginDialog();
FQufutongUnrealBridge::ShowCashierDialog(TEXT("gem_60"), TEXT("60元宝"), 600, TEXT("s1"), TEXT("role_1001"));
FString EventJson = FQufutongUnrealBridge::PollNextEventJson();