插件接入

接入说明

本页说明插件游戏 / 纯端游戏在平台侧的完整接入流程。页游请参考登录、充值、发货等对应文档；插件与端游除服务端接口外，还需在游戏客户端接入 KiGameSDK.dll。

接入顺序建议：

1. 完成服务端发货接口
2. 游戏客户端接入 KiGameSDK，完成平台登录态校验（见下文；插件/端游无需 CP 提供登录换 token 接口，也无需配置自接入后台「登录地址」）：
   • C/C++：主线程依次主动调用 kiGameInit → kiGameLogin，成功后 kiGetLoginInfo 取得平台用户信息
   • C#（Unity）：SDK 自动 Init / Login，CP 在 IsLoggedIn 为 true 后读取 LoginInfo，无需手动调用 Login()
3. 在自接入后台配置支付回调地址，并按插件测试在平台客户端中联调验证

术语说明

平台登录态校验（插件/端游）：平台服务端签发 token，平台客户端以 --token 启动游戏 → SDK 向平台服务端校验 → CP 通过 kiGetLoginInfo / LoginInfo 取得 uid、appid、sid 等。游戏内登录（连 CP 游戏服、创角、进场景等）仍由 CP 自行实现，在取得平台用户信息之后进行。
页游仍须实现服务端登录接口，与插件/端游流程不同。具体客户端 API 见 C/C++ 或 C#（Unity）。

平台登录态校验（插件 / 端游）

插件/端游的登录态全程由平台客户端、平台服务端与 SDK 协同完成，CP 不需要实现向平台返回 token 的登录接口（该接口面向页游）。

流程

以上 ①～⑦ 步由平台客户端、平台服务端与 SDK协同完成，CP 无需实现登录换 token 接口；⑧ 读取 LoginInfo 后，⑨ 由 CP 接入游戏内进服。

CP 客户端要做的事

游戏进程内的 KiGameSDK 只负责时序图中 ⑥～⑧（校验 token 与读取 LoginInfo；CP 不参与 token 签发，也无需自行实现校验接口）：

1. 读取 --token
2. 向平台服务端校验 token（SDK 内部完成，CP 无需关心具体接口）
3. 校验通过后，通过 kiGetLoginInfo（C++）或 LoginInfo（Unity）取得 uid、appid、sid、time、utype

语言	CP 是否需要调用 kiGameLogin	如何取平台用户信息
C/C++	需要，在 kiGameInit 成功后主线程主动调用	kiGetLoginInfo()
C#（Unity）	不需要，Package 启动时自动 Init / Login	KiGameManager.Instance.LoginInfo（先判断 IsLoggedIn）

取得上述字段后，CP 再按自有逻辑连接游戏服务器（游戏内进服与本节无关）。

支付收银台（插件 / 端游）

支付订单参数、签名规则与充值接口一致。插件与纯端游戏通过客户端 SDK 拉起平台收银台，不要在游戏进程内直接打开支付 URL。

通过客户端 SDK 拉起收银台（C/C++ 见 kiShowPay，Unity 见 KiGameManager.RequestPay），参数为 UTF-8 编码的 JSON 字符串（订单字段由游戏与自有服务端交互生成并签名）：

{
  "uid": xxxxxxxx,
  "appid": "xxxxxx",
  "sid": "s1",
  "amount": 600,
  "rid": "1000",
  "pid": "1001",
  "ext": "",
  "sign": "xxxxxxxx"
}

参数名	类型	必填	说明
uid	int64	是	平台用户唯一 ID（LoginInfo / kiGetLoginInfo 中的 uid）
appid	string	是	平台游戏唯一 ID
sid	string	是	区服 ID（如 S1、S2）
amount	int	是	支付金额（分），≥ 1
rid	string	是	角色 ID，厂商自定义，最大 64 字节
pid	string	是	商品 ID，厂商自定义，最大 64 字节
ext	string	否	扩展字段，会原样透传到发货回调；出现在 URL 中时须编码
sign	string	是	签名，参与签名（uid, appid, sid, amount, rid, pid, ext），详见签名规则

支付完成后，平台仍按发货接口回调厂商。更多说明见：充值接口。

选择客户端语言

请按游戏客户端技术栈阅读对应章节：

• C/C++ 接入
• C#（Unity）接入

C/C++ 接入

概述

KiGameSDK.dll 提供 C 风格导出接口（extern "C"）。C/C++ 接入采用动态加载：只需 KiGameSDK.dll 与公开头文件 KiGameSDK.h（结构体、错误码），通过 LoadLibrary / GetProcAddress 取函数地址，无需导入库（.lib），也无需在工程中静态链接 DLL。

项目	说明
运行环境	Windows；需与游戏进程位数一致（x86 / x64）
加载方式	动态加载（LoadLibrary + GetProcAddress），仅依赖 dll + .h
调用线程	kiGameInit 必须在引擎主线程调用（SDK 通过当前线程枚举主窗口）
启动方式	须由平台客户端带命令行参数启动（含 --token 等）；本地直接双击 exe 通常无法完成初始化

接入步骤

1. 按游戏位数选择对应 KiGameSDK.dll，放入游戏可执行文件同目录（或可被 LoadLibrary 找到的路径）
2. 工程中引入公开头文件 KiGameSDK.h（用于 KiGameLoginInfo、错误码等类型定义）
3. 启动时 LoadLibrary 加载 DLL，再用 GetProcAddress 解析 kiGameInit / kiGameLogin / kiGetLoginInfo / kiShowPay / kiGameUninit
4. 游戏主窗口创建后，在主线程依次调用 kiGameInit、kiGameLogin
5. 登录校验成功后，通过 kiGetLoginInfo 取得平台用户信息，再接入 CP 游戏内进服流程
6. 充值时组装订单 JSON，调用 kiShowPay
7. 进程退出前调用 kiGameUninit，再 FreeLibrary 释放 DLL

数据结构

#pragma pack(push, 8)
typedef struct KiGameLoginInfo {
    DWORD cbSize;           // 须设为 sizeof(KiGameLoginInfo)
    int64_t uid;            // 平台用户 ID
    wchar_t appid[64];      // 游戏 appid
    wchar_t sid[64];        // 区服 ID
    int64_t time;           // 登录时间戳（秒）
    int utype;              // 用户属性：0 未实名，1 成年，2 未成年
} KiGameLoginInfo;
#pragma pack(pop)

字段	类型	说明
cbSize	DWORD	结构体大小，填写 sizeof(KiGameLoginInfo)
uid	int64_t	平台用户 ID
appid	wchar_t[64]	游戏 appid
sid	wchar_t[64]	区服 ID
time	int64_t	登录时间戳（秒）
utype	int	用户属性：0 未实名，1 成年，2 未成年

接口说明

1. kiGameInit

int kiGameInit(void);

解析启动参数、完成嵌入（如适用）并建立与平台的 IPC。须在引擎主线程、主窗口已出现后调用。

返回值	说明
0（KI_GAME_SDK_OK）	初始化成功
非 0	失败，见错误码

2. kiGameLogin

int kiGameLogin(void);

使用启动参数中的 --token 向平台服务端校验登录态。须在 kiGameInit 成功后调用。

返回值	说明
0	token 校验成功
非 0	校验失败，见错误码

3. kiGetLoginInfo

const KiGameLoginInfo* kiGetLoginInfo(void);

在 kiGameLogin 成功后有效。返回指向 SDK 内部登录信息的只读指针；未登录或失败时返回 nullptr。

返回值	说明
非空指针	可读 uid、appid、sid 等字段
nullptr	尚未登录或登录失败

4. kiShowPay

int kiShowPay(const char* order_json_utf8);

通过 IPC 请求平台弹出收银台。order_json_utf8 为 UTF-8 JSON 字符串，可为 nullptr（不推荐）；字段见上文「支付收银台」。须在 kiGameInit、kiGameLogin 均成功后调用。

返回值	说明
0	支付请求已成功投递
非 0	投递失败，见错误码

TIP

kiShowPay 返回成功仅表示请求已投递给平台客户端，不代表用户已完成支付。发货以服务端发货回调为准。

5. kiGameUninit

void kiGameUninit(void);

释放 SDK 资源，并在 UI 线程请求进程退出（PostQuitMessage / WM_QUIT）。可从工作线程调用；若消息循环未及时退出，短时间后可能回退为 ExitProcess。

错误码

kiGameInit / kiGameLogin / kiShowPay 等返回值约定：0 为成功，失败为负数。

错误码	宏名	说明
0	KI_GAME_SDK_OK	成功
-1	KI_GAME_SDK_ERR_GAME_WINDOW_NOT_FOUND	未找到游戏主窗口
-2	KI_GAME_SDK_ERR_LAUNCH_PARAMS	启动参数解析失败
-3	KI_GAME_SDK_ERR_EMBED_ATTACH	嵌入宿主窗口失败
-4	KI_GAME_SDK_ERR_IPC_GAME_START	游戏侧 IPC 启动失败
-5	KI_GAME_SDK_ERR_IPC_POST	IPC 消息投递失败
-6	KI_GAME_SDK_ERR_NOT_INITIALIZED	尚未完成初始化或登录
-10	KI_GAME_SDK_ERR_LOGIN_NO_TOKEN	启动参数中无 token
-11	KI_GAME_SDK_ERR_LOGIN_HTTP	登录校验 HTTP 请求失败
-12	KI_GAME_SDK_ERR_LOGIN_VERIFY_FAILED	token 校验未通过
-13	KI_GAME_SDK_ERR_LOGIN_PARSE_FAILED	校验响应解析失败

动态加载示例

#include <windows.h>
#include <stdint.h>
#include "KiGameSDK.h"

typedef int (*FnKiGameInit)(void);
typedef int (*FnKiGameLogin)(void);
typedef const KiGameLoginInfo* (*FnKiGetLoginInfo)(void);
typedef int (*FnKiShowPay)(const char* order_json_utf8);
typedef void (*FnKiGameUninit)(void);

HMODULE g_hKiGame = nullptr;
FnKiGameInit       g_kiGameInit = nullptr;
FnKiGameLogin      g_kiGameLogin = nullptr;
FnKiGetLoginInfo   g_kiGetLoginInfo = nullptr;
FnKiShowPay        g_kiShowPay = nullptr;
FnKiGameUninit     g_kiGameUninit = nullptr;

bool LoadKiGameSdk(const wchar_t* dllPath = L"KiGameSDK.dll")
{
    g_hKiGame = LoadLibraryW(dllPath);
    if (!g_hKiGame) {
        return false;
    }
    g_kiGameInit = (FnKiGameInit)GetProcAddress(g_hKiGame, "kiGameInit");
    g_kiGameLogin = (FnKiGameLogin)GetProcAddress(g_hKiGame, "kiGameLogin");
    g_kiGetLoginInfo = (FnKiGetLoginInfo)GetProcAddress(g_hKiGame, "kiGetLoginInfo");
    g_kiShowPay = (FnKiShowPay)GetProcAddress(g_hKiGame, "kiShowPay");
    g_kiGameUninit = (FnKiGameUninit)GetProcAddress(g_hKiGame, "kiGameUninit");
    return g_kiGameInit && g_kiGameLogin && g_kiGetLoginInfo && g_kiShowPay && g_kiGameUninit;
}

void UnloadKiGameSdk()
{
    if (g_hKiGame) {
        FreeLibrary(g_hKiGame);
        g_hKiGame = nullptr;
    }
    g_kiGameInit = nullptr;
    g_kiGameLogin = nullptr;
    g_kiGetLoginInfo = nullptr;
    g_kiShowPay = nullptr;
    g_kiGameUninit = nullptr;
}

// 用法（主线程、主窗口就绪后）：
// LoadKiGameSdk();  // 或指定完整路径
int ret = g_kiGameInit();
if (ret != KI_GAME_SDK_OK) {
    // 初始化失败，按错误码排查
    return;
}

ret = g_kiGameLogin();
if (ret != KI_GAME_SDK_OK) {
    // token 校验失败
    return;
}

const KiGameLoginInfo* login = g_kiGetLoginInfo();
if (login && login->uid > 0) {
    // 使用 login->uid / appid / sid 进入游戏
}

// 充值：orderJson 为 UTF-8 JSON 字符串
ret = g_kiShowPay(orderJson);
if (ret != KI_GAME_SDK_OK) {
    // 拉起收银台失败
}

// 进程退出前：
g_kiGameUninit();
UnloadKiGameSdk();

TIP

请通过函数指针调用导出接口，不要静态链接 .lib，也不要直接调用头文件中带 __declspec(dllimport) 的函数声明，否则仍会依赖导入库。

C#（Unity）接入

概述

Unity 通过 KiGameSDK.unitypackage 导入同一套 KiGameSDK.dll 与 C# 封装，无需 KiGameSDK.h，也无需自行 LoadLibrary、无需挂场景。Package 内含：

• KiGameBootstrap.cs：首场景加载前自动创建 [KiGameSDK] 并触发 Init
• KiGameSDK.cs：P/Invoke 声明
• KiGameManager.cs：业务单例（登录信息、支付）

接入步骤

1. Assets → Import Package → Custom Package，选择 KiGameSDK.unitypackage 并导入全部内容
2. 确认 Player Settings → Scripting Runtime 为 .NET 4.x；Build Target 为 Windows Standalone
3. 无需在场景中挂载 KiGameManager，也无需手动调用 Init() / Login()；导入 package 后，游戏启动时 SDK 会自动完成初始化与 token 校验
4. 登录校验成功后，通过 LoginInfo 取得平台用户信息，再接入 CP 游戏内进服流程；充值时组装订单 JSON，调用 RequestPay(orderJson)

业务接口说明

底层仍是 DLL 的 kiGameInit / kiGameLogin / kiGetLoginInfo / kiShowPay / kiGameUninit，已由封装类处理。厂商一般只使用 KiGameManager。

1. Init / Login（自动，无需手动调用）

导入 KiGameSDK.unitypackage 后，CP 无需在业务代码中调用 Init() 或 Login()。KiGameBootstrap 会在首场景加载前自动创建 [KiGameSDK] 节点，并在 Unity 主线程依次完成 Init() 与 Login()（解析启动参数、找主窗口 HWND、嵌入与 IPC 初始化，再向平台服务端校验 --token）。

厂商只需在 IsLoggedIn 为 true 后读取 LoginInfo 等业务接口即可。若初始化或登录失败（如 Editor 直接 Play 缺少平台启动参数），SDK 会弹出提示并退出游戏。

属性	说明
IsInitialized	kiGameInit 是否成功
IsLoggedIn	kiGameLogin 是否成功

2. LoginInfo

KiGameSDK.KiGameLoginInfo info = KiGameManager.Instance.LoginInfo;

在 IsLoggedIn 为 true 时有效，包含 uid、appid、sid、time、utype 等字段。

3. RequestPay

bool posted = KiGameManager.Instance.RequestPay(orderJson);

拉起平台收银台。orderJson 为 UTF-8 JSON 字符串，字段见上文「支付收银台」。

返回值	说明
true	支付请求已成功投递
false	失败（未完成登录或投递失败）；见 Console 错误码，含义见 错误码

TIP

RequestPay 返回成功仅表示请求已投递给平台客户端，不代表用户已完成支付。发货以服务端发货回调为准。

4. 退出

一般无需手动调用。KiGameManager 在 OnApplicationQuit 中会调用底层 kiGameUninit 释放资源。

调用示例

using UnityEngine;

public class GameShopController : MonoBehaviour
{
    void Start()
    {
        if (KiGameManager.Instance == null || !KiGameManager.Instance.IsLoggedIn)
            return;

        var login = KiGameManager.Instance.LoginInfo;
        // 使用 login.uid / appid / sid 接入 CP 游戏内进服（连游戏服、选角等）
    }

    public void OnClickPay()
    {
        if (KiGameManager.Instance == null || !KiGameManager.Instance.IsLoggedIn)
            return;

        // 订单字段由游戏与自有服务端交互生成并签名
        string orderJson =
            "{\"uid\":20000002,\"appid\":\"100191\",\"sid\":\"s1\",\"amount\":100,\"rid\":\"1000\",\"pid\":\"1000\",\"ext\":\"\",\"sign\":\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"}";

        KiGameManager.Instance.RequestPay(orderJson);
    }
}

TIP

Init() / RequestPay() 失败时，错误码与 C/C++ 一致，见上文 错误码。

游戏包打包

插件/端游在平台客户端分发前，须将游戏文件打成标准 7z 包并提交平台上传。请勿自行用不同工具或目录结构打包，以免平台下载后解压路径不一致、MD5 校验失败。

打包工具

下载 KeepIdle_GamePack.zip，解压后运行 KiPack（Windows）。

使用步骤

1. 在 KiPack 中填写游戏的 AppID（与自接入后台一致）
2. 点击「浏览」，选择游戏主程序 exe 所在目录（该目录下的全部文件将被打进包内）
3. 点击「打包」，在同目录生成 {AppID}_001.7z（例如 100013_001.7z）

KiPack 会记住上次填写的 AppID 与路径（保存在 kipack.ini）。

插件测试

当 CP 服务端发货接口以及游戏客户端 KiGameSDK 均接入完成后，可在平台客户端中联调，验证完整插件流程（选服 → 平台服务端签发 token → 启动游戏 → SDK 校验 → 拉起收银台 → 发货回调）。

前置条件

• 已按 游戏包打包 生成标准 {AppID}_001.7z 并由平台完成上传与配置（联调前须能正常下载安装）
• 已在自接入后台填写支付回调地址并保存（插件/端游无需配置 CP 登录地址）
• 游戏客户端已集成对应位数的 KiGameSDK.dll，且可执行文件与 DLL 位于同一目录（或可被加载）

测试流程

1. 获取测试地址

登录自接入后台，进入目标游戏的接入配置页，点击「打开测试」。浏览器会打开平台登录测试页，复制地址栏中的完整 URL，后续在平台客户端「添加游戏」时使用。

（测试页由平台构造登录参数；插件联调不依赖 CP 服务端登录换 token 接口。）

2. 下载平台客户端

在平台官网下载并安装平台客户端到本地。

3. 添加游戏

启动平台客户端，进入「我的游戏」，点击「添加」。在 URL 输入框中粘贴上一步复制的测试地址，游戏名称填写实际的游戏名称，保存。

4. 启动游戏并联调

在「我的游戏」列表中打开刚添加的游戏。平台客户端将按以下流程运行：平台服务端签发 token → 带 --token 启动游戏进程 → 游戏内 KiGameSDK 向平台服务端校验并返回登录信息。

联调时可重点验证：

• 游戏能否正常启动并完成 SDK 初始化与登录（kiGameInit / kiGameLogin 或 IsLoggedIn 为 true）
• 能否通过 kiGetLoginInfo / LoginInfo 正确取得 uid、appid、sid
• 游戏内充值能否拉起平台收银台（kiShowPay / RequestPay）
• 支付完成后 CP 发货接口是否收到回调

TIP

插件游戏须由平台客户端启动，不要在本地直接双击游戏 exe 验证 SDK；直接启动通常缺少 --token 等参数，会导致初始化失败。更多验证项见平台测试。

调试日志（可选）

联调时可在游戏 exe 同目录放置 KiGameSDK.ini 开启 SDK 内部日志（默认关闭，正式包请勿携带）：

[main]
log=1

日志写入 {游戏exe名}.log，仅在 SDK 初始化或支付投递失败时写入，便于联调排查；不输出完整 token 或订单内容。

工具与 SDK 下载

资源	说明	下载
游戏打包工具（Windows）	KiPack生成标准游戏包，详见 游戏包打包	下载
C/C++（32 位 / 64 位）	含 KiGameSDK.dll 与 KiGameSDK.h	下载
C#（Unity）	KiGameSDK 的 Unity Package	下载

位数须与游戏主程序一致。

相关文档

• 自接入后台
• 充值接口
• 发货接口
• 平台测试
• 签名规则