快游戏统一 SDK 接入文档

一、SDK 简介

快游戏统一 SDK 封装了登录、支付与广告的兼容逻辑，助力开发者在 vivo / OPPO / 小米 / 荣耀 四大平台上快速实现核心功能接入。

SDK 分为两部分：

• 客户端 SDK：下载 sdk 打包文件、源码包下载
• 服务端 SDK：提供 Java、Node、PHP 三种语言版本 点击下载

提供测试用 DEMO：下载地址

二、客户端 SDK 接入指南

若直接使用sdk打包文件可以忽略2.1源码安装与打包

2.1 源码安装与打包

1. 进入 clientsdk 目录，安装依赖：

npm install

1. 打包生成 SDK 文件：

npm run build
# 生成路径：clientsdk/dist/unionSdk.js

2.2 引入与初始化

将代码拷贝到快游戏项目中，在游戏启动阶段引入 unionSdk.js 并初始化：

import unionSdk from "./unionSdk.js";
window.unionSdkInit({ config, adInfo });

2.3 配置说明

将 config.json（登录、支付配置）与 ad-info.json（广告配置）文件放入游戏资源目录，并在初始化中加载。

⚠️ 示例中以 Cocos 引擎为例，文件需放在 assets 目录下

2.4 SDK 接口调用示例

// 登录
qg.unionLogin({ success(res) { console.log(res); } });

// 支付
qg.unionPay({ orderInfo: { ... } });

// 原生广告
qg.createCustomAd({ adUnitId: qg.adInfo.customAd.id1 });

三、客户端配置说明

3.1 config.json 配置

示例

{
  "version": "1.0.0",
  "oppoConfig": {
    "appid": "30849125",
    "version": "1.0.0",
    "sdkPayUrl": "http://localhost:8080/pay_oppo"
  },
  "vivoConfig": {
    "appKey": "xxx",
    "appSecret": "xxx",
    "version": "1.0.0",
    "sdkPayUrl": "http://localhost:8080/pay_vivo"
  },
  "miConfig": {
    "appid": "xxx",
    "version": "1.0.0",
    "sdkPayUrl": "http://localhost:8080/pay_mi"
  },
  "honorConfig": {
    "appid": "xxx",
    "appSecret": "xxx",
    "version": "1.0.0",
    "sdkLoginUrl": "https://hnoauth-login.cloud.honor.com/oauth2/v3/token"
  }
}

3.2 ad-info.json 示例

在配置好 ad-info.json 文件后 ，广告 id 处的值填写 qg.adInfo.customAd.id 即可兼容各厂商的广告位获取

{
  "oppo": {
    "customAd": {
      "id1": "oppo原生广告id"
    },
    "bannerAd": {
      "id1": "oppo激励视频广告id"
    }
  },
  "vivo": {
    "customAd": {
      "id1": "vivo原生广告id"
    }
  },
  "mi": {
    "customAd": {
      "id1": "小米原生广告id"
    }
  },
  "rong": {
    "customAd": {
      "id1": "荣耀原生广告id"
    }
  }
}

3.3 客户端 SDK API 使用

登录方法 qg.unionLogin(Object object)

参数 object：

success(res) 回调函数返回值

fail(res) 回调函数返回值

支付方法 qg.unionPay(Object object)

支付流程：

• 客户端 SDK 会请求配置的 sdkPayUrl，该地址为开发者服务器接口
• 开发者服务器需要将服务器 sdk 引入，将支付下单的订单信息下发到客户端
• 客户端拿到订单信息后会直接调用 qg.pay 请求支付
• 用户支付完成， 服务器 sdk 以及客户端收到支付成功的回调，建议以服务器收到的支付结果为准。

参数 object：

orderInfo（签名涉及密钥信息，建议在服务器后台生成）

success(res) 回调函数返回值

fail(res) 回调函数返回值

code 字段值

四、服务端 SDK 接入指南

4.1 配置文件路径

• Node：server/js/serversdk/routes/config.json
• Java：server/java/.../resources/config.json
• PHP：server/php/.../config.json

4.2 支持平台配置字段

示例

{
  "version": "1.0.0",
  "oppoConfig": {
    "pkgName": "String",
    "appId": "String",
    "appKey": "String",
    "appSecret": "String",
    "callBackUrl": "http://41234",
    "privateKey": "MIICXQIBAAKBgQCjAFh6nQyVFX8U/Cv7GDT1xOARO5IPH+nW7CblMCPozrKY1hVb3FwMkcNLavpgH75EUE+OPyCxr0BoU3mMDybiXGppOSqBvaOnYWT+88nMKNGwwfsYT54lCVB20OYYaTBr7Uq9wrjatf+9yjSHAHKXlHJlOarg7zCS+3VCyT4sVQIDAQABAoGBAInFhAN29KiZ98Tj88SSzEii9AR8xlJUVhCbn7B9xQxEkL4PzRPMqFzTYy8+p4tRqT8SZnvDrb2hdB352DVipSi7K3idnpIrQOByz9+Hhrabb1u3ChbFIOk42vLfmufRf7dA18lVQ9NqMipSdsMc3Ko/TnVHDyVKhYX1FgrPZdQtAkEA0S8IUSioG895Zkr/oQs+QFax7BGLFdp1Bqd7/zRM3eR95HtVW0taIdXwiZPCZDHPzEPMDqCbiG87FI2/IKuo6wJBAMd7V2Y+RdwZ9OzL5F0xR0R41iVX5DJzM70dV3pj7gJzatFL2JwW2aY2V5l1OKrzVRlYuIXT9kOTuzmUKmV4L78CQBxK4DUZ6qLYTPMo8ao2exT4pNfpB4bNJUbhIERELqFUZjKg+8p9RpOM/BufgItMsW5PPSo9TswFP1hoU5F3pkECQQCc/xLjMiGTP46HC1U4jz8SwbNwgoLjvc07iqs9dQZuQV4RSQs6lbVIXj6FVT97M7WHFE9tbEvGFa/lehn/8B5LAkBgwCuXLhb+n4RA+K0tI/gmFesln+SVLl1SM8YxKGfu2rHVY0yNHKu3ZKFDAABpWbcXGt2uAq4Vvh7OTcLssEfz"
  },
  "vivoConfig": {
    "pkgName": "com.jovi.wuziqi.vivominigame",
    "appId": "100002162",
    "appKey": "635fd8fd145fcec02749cb4ee7b4a744",
    "account_appSecret": "0e169ad37148d220cb4411f1ca2afed3",
    "appSecret": "17756692d9c419a21e76050f9a44d5f0",
    "notifyUrl": "http://172.27.49.77:8080/pay_callback_vivo"
  },
  "miConfig": {
    "pkgName": "com.xxx.cocos.mini",
    "appSecret": "xxx",
    "appId": "xxx",
    "loginValidateUrl": "https://mis.migc.xiaomi.com/api/biz/service/loginvalidate",
    "queryOrderStateUrl": "https://mis.migc.xiaomi.com/api/biz/service/queryOrder.do"
  },
  "honorConfig": {
    "appId": "String",
    "publicKey": "String"
  }
}

4.3 服务端接口列表

4.3.1 登录接口 /login

接口参数 object:

接口返回值 object:

4.3.2 支付接口

备注

• 若是 php 版本服务端，接口名后需加 .php 后缀，如 oppo 在 php 版本的服务端接口名为 /pay_oppo.php。
• 荣耀无支付接口，但有支付回调接口
• 支付接口的实现逻辑在各家都有差异，客户端 sdk 中配置好 config.json 文件中的支付接口地址后，客户端执行 qg.unionPay(object)即可调用此支付接口，返回支付相关信息，并在客户端拉起支付页面

五、Unity 引擎接入

• 安装快游戏插件，启用“统一 SDK”选项，自动集成客户端 SDK
• 配置账号、支付、广告信息，自动写入配置文件

5.1 登录接口示例：

QG.Login(
  res => Debug.Log("登录成功:" + JsonUtility.ToJson(res)),
  err => Debug.Log("登录失败:" + err.errMsg)
);

5.2 支付接口示例：

PayParam param = new PayParam() {
  productName = "xxx",
  orderAmount = 100
};
QG.Pay(param,
  res => Debug.Log("支付成功: " + JsonUtility.ToJson(res)),
  err => Debug.Log("支付失败: " + err.errMsg),
  done => Debug.Log("支付完成: " + JsonUtility.ToJson(done))
);

5.3 广告接口示例：

//需要使用QG.GetAdInfo()获取当前运行平台的广告位列表
(string)QG.GetAdInfo()["bannerAd"]["id1"]
//创建bannerAd广告
var bannerAd = QG.CreateBannerAd(new QGCreateBannerAdParam() {
  adUnitId = (string)QG.GetAdInfo()["bannerAd"]["id1"]
});
bannerAd.OnLoad(() => bannerAd.Show());

六、FAQ

Q: 是否支持自定义 SDK 内容？ A: 是的，SDK 为开源形式，开发者可根据需求进行裁剪与修改。

Q: 广告 id 如何统一管理？ A: 在 ad-info.json 中配置多个广告类型与平台 ID，通过 qg.adInfo.xxx.id 动态读取，qg.adInfo 会根据当前运行的平台直接获取到对应的广告位列表

Q: SDK 是否可用于 Web 端？ A: 当前仅适用于快游戏平台，不支持浏览器 Web 运行。