PC SDK 接入指南

流程说明

PC 版 OnlySDK 统一采用：

onlysdk.dll 作为 Core
渠道 DLL 作为可替换运行时
游戏业务统一调用 SDK 暴露的接口

当前推荐流程：

游戏研发接入 默认联调渠道（通常是 nsdk）
游戏完成联调后，交付基础包
SDK / 发行侧再替换正式渠道 DLL 与配置

也就是说：

游戏研发不用自己切正式渠道
TapTap / WeGame / 其它 PC 渠道 由 SDK / 发行侧后置替换

SDK 文件说明

PC 运行时通常包含这些文件：

文件	说明
`onlysdk.dll`	PC Core，必须
`nsdk.dll` / `taptap.dll` / `wegame.dll`	渠道 DLL，按目标渠道放置
`WebView2Loader.dll`	NSDK 登录页 / H5 能力依赖
`onlysdk_config.json`	运行时配置，必须
`login_ui.html`	NSDK 登录页资源
`qrcode.min.js`	NSDK 扫码页依赖

注意：游戏进程、onlysdk.dll、渠道 DLL 必须位数一致。
TapTap 当前按 x64 联调与出包。
Cocos Win32 本地联调默认按 x86。

onlysdk_config.json 配置

至少需要配置：

{
  "ServerUrl": "https://xxx.xxx.com",
  "FallbackUrls": [
    "https://xxx2.xxx.com"
  ],
  "AppID": "23",
  "AppKey": "填写AppKey",
  "ChannelName": "nsdk",
  "ChannelID": "23036",
  "SubChannelID": "",
  "ConsentVersion": "1",
  "PackageName": "com.huanyou.game",
  "Version": "1.0.0",
  "VersionCode": "1"
}

关键字段说明：

字段	说明
`ServerUrl`	服务端地址
`AppID`	游戏 AppID
`AppKey`	游戏 AppKey
`ChannelName`	当前渠道名，如 `nsdk` / `taptap` / `wegame`
`ChannelID`	当前渠道 ID
`PackageName`	游戏包名 / 标识
`Version`	游戏版本号
`VersionCode`	游戏版本码

正式参数请向技术或运营确认后填写。

Unity 接入

1. 导入 SDK 包

将 PC Unity 接入包导入工程：

OnlySDK-PC-Unity-*.unitypackage

导入后默认会得到：

Assets/OnlySDK/
Assets/Plugins/x86_64/onlysdk.dll
Assets/Plugins/x86_64/nsdk.dll
Assets/Plugins/x86_64/WebView2Loader.dll
Assets/Plugins/x86_64/onlysdk_config.json
Assets/Plugins/x86_64/login_ui.html
Assets/Plugins/x86_64/qrcode.min.js

默认联调渠道就是：

nsdk

2. 编写业务调用脚本

统一通过：

OnlySDK.Runtime.OnlySDK

调用示例：

using UnityEngine;
using RuntimeSDK = OnlySDK.Runtime.OnlySDK;

public class OnlyTest : MonoBehaviour
{
    private void Start()
    {
        RuntimeSDK.OnAnyEvent += OnAnyEvent;
    }

    public void OnClickInit()
    {
        RuntimeSDK.Init();
    }

    public void OnClickLogin()
    {
        RuntimeSDK.Login();
    }

    public void OnClickLogout()
    {
        RuntimeSDK.Logout();
    }

    public void OnClickExit()
    {
        RuntimeSDK.ExitSDK();
    }

    public void OnClickOpenSurvey()
    {
        RuntimeSDK.OpenSurvey(new OnlySDK.Runtime.OnlySDKSurveyRequest
        {
            userId = RuntimeSDK.LoginData?.userId ?? 0,
            serverId = "1",
            roleId = "role_001",
            roleName = "测试角色",
            formKey = "运营提供的问卷表单Key",
            extra = ""
        });
    }

    public void OnClickGetSurveyForms()
    {
        RuntimeSDK.GetSurveyForms(new OnlySDK.Runtime.OnlySDKSurveyRequest
        {
            userId = RuntimeSDK.LoginData?.userId ?? 0,
            serverId = "1",
            roleId = "role_001",
            roleName = "测试角色",
            extra = ""
        });
    }

    public void OnClickGetWelfareInfo()
    {
        RuntimeSDK.GetWelfareInfo(new OnlySDK.Runtime.OnlySDKWelfareInfoRequest
        {
            userId = RuntimeSDK.LoginData?.userId ?? 0,
            serverId = "1",
            serverName = "测试一区",
            roleId = "role_001",
            roleName = "测试角色",
            extra = ""
        });
    }

    private void OnAnyEvent(OnlySDK.Runtime.OnlySDKEvent e)
    {
        Debug.Log($"code={e.code} action={e.action} status={e.status} msg={e.message}");
    }
}

3. 本地联调

研发本地默认只需要：

导入 unitypackage
修改 Assets/Plugins/x86_64/onlysdk_config.json
写业务按钮调用脚本

打包时：

Assets/OnlySDK/Editor/OnlySDKPostBuild.cs

会自动把 Assets/Plugins/x86_64/ 下的运行时文件复制到最终运行目录。

4. 正式渠道出包

Unity 工程内通常保留默认联调态：

nsdk.dll + onlysdk_config.json

正式出包时，再由 SDK / 发行侧替换成：

taptap.dll + taptap_api.dll + TapTap 配置
或 wegame.dll + rail_api*.dll + WeGame 配置

Cocos 接入

1. 先在 Cocos Creator 中构建一次 Windows 原生工程

先执行：

构建发布
平台选 Windows
点一次 构建

生成原生目录后，再执行下一步。

2. 运行一键联调脚本

pwsh .\tools\setup-cocos-dev.ps1 -CocosProjectRoot "D:\YourCocosProject"

这条脚本会自动完成：

拷贝 OnlySDKCocosBridge.* / OnlySDKAutoRegister.*
拷贝 OnlySDK.js / OnlySDK.d.ts
修改 AppDelegate.cpp
修改 .vcxproj
把默认 nsdk 运行时注入 Debug.win32
做一轮体检，确认接入是否齐全

3. VS 重新生成并运行

执行顺序：

Cocos Build -> setup-cocos-dev.ps1 -> VS 重新生成 -> 运行

4. 业务调用示例

统一通过：

window.OnlySDK

调用示例：

OnlySDK.on('login', function (event) {
  if (event.code === 0) {
    console.log('login success', event.data);
  } else {
    console.log('login fail', event.message);
  }
});

OnlySDK.init();
OnlySDK.login();

只要 Cocos Creator 重新 Build 过，就需要重新执行一次 setup-cocos-dev.ps1。

初始化（必接）

请求参数

（无）

返回结果

参数	类型	必选	描述
`code`	int	是	状态码
`status`	string	是	`success` / `error`
`action`	string	是	固定为 `init`
`message`	string	否	提示信息

示例：

{
  "code": 0,
  "status": "success",
  "action": "init",
  "message": ""
}

登录（必接）

请求参数

（无）

返回结果

参数	类型	必选	描述
`code`	int	是	状态码
`status`	string	是	`success` / `error` / `cancel`
`action`	string	是	固定为 `login`
`message`	string	否	提示信息
`data`	JSON	否	登录结果

成功时常用字段：

参数	类型	描述
`userId`	long	OnlySDK 用户 ID
`token`	string	登录 Token
`channelId`	string/int	渠道 ID
`channelUserId`	string	渠道用户 ID
`channelUserName`	string	渠道用户名

支付

请求参数

参数	类型	必选	描述
`userId`	long	是	用户 ID
`cpOrderId`	string	是	CP 订单号
`productId`	string	是	商品 ID
`productName`	string	是	商品名称
`productDesc`	string	是	商品描述
`price`	int	是	价格，单位分
`currency`	string	是	币种，通常 `CNY`
`serverId`	string	是	区服 ID
`serverName`	string	是	区服名称
`roleId`	string	是	角色 ID
`roleName`	string	是	角色名称
`roleLevel`	int	是	角色等级

返回结果

参数	类型	描述
`status`	string	`success` / `fail` / `cancel`
`message`	string	提示信息

数据上报

请求参数

参数	类型	必选	描述
`type`	int	是	1 创建角色，2 进入游戏，3 升级，4 退出，6 充值到账
`userId`	long	是	用户 ID
`serverId`	string	是	服务器 ID
`serverName`	string	是	服务器名
`roleId`	string	是	角色 ID
`roleName`	string	是	角色名
`roleLevel`	int	是	角色等级
`money`	int	是	当前货币余额
`vip`	string	是	VIP 等级
`roleCreateTime`	long	是	角色创建时间，秒级时间戳

问卷与福利站（选接）

以下接口需要在登录成功后调用，并传入当前登录用户与角色信息。userId 建议使用 OnlySDK.LoginData.userId。

打开问卷调查

用于打开运营配置的问卷页面。PC 端会通过系统默认浏览器打开问卷链接。

请求参数：

参数	类型	必选	描述
`userId`	long	是	OnlySDK 用户 ID，登录成功后返回
`serverId`	string	是	区服 ID
`roleId`	string	是	角色 ID
`roleName`	string	是	角色名称
`formKey`	string	是	问卷表单 Key，由运营提供
`extra`	string	否	扩展参数，原样透传

调用示例：

OnlySDK.OpenSurvey(new OnlySDKSurveyRequest
{
    userId = OnlySDK.LoginData.userId,
    serverId = "1",
    roleId = "role_001",
    roleName = "测试角色",
    formKey = "运营提供的问卷表单Key",
    extra = ""
});

OnlySDK.OnOpenSurvey += evt =>
{
    Debug.Log($"open survey: success={evt.IsSuccess}, url={evt.url}, msg={evt.message}");
};

返回结果：

参数	类型	描述
`status`	string	`success` / `error`
`action`	string	固定为 `open_survey`
`url`	string	实际打开的问卷链接
`message`	string	提示信息

获取用户可填写问卷列表

用于获取当前用户可填写的问卷列表，游戏可根据返回列表决定是否展示问卷入口。

请求参数：

参数	类型	必选	描述
`userId`	long	是	OnlySDK 用户 ID，登录成功后返回
`serverId`	string	是	区服 ID
`roleId`	string	是	角色 ID
`roleName`	string	是	角色名称
`extra`	string	否	扩展参数，原样透传

调用示例：

OnlySDK.GetSurveyForms(new OnlySDKSurveyRequest
{
    userId = OnlySDK.LoginData.userId,
    serverId = "1",
    roleId = "role_001",
    roleName = "测试角色",
    extra = ""
});

OnlySDK.OnSurveyForms += evt =>
{
    Debug.Log($"survey forms: success={evt.IsSuccess}, data={evt.serverDataBodyRaw}");
};

服务端响应会放在 evt.serverDataRaw，其中常用字段如下：

参数	类型	描述
`code`	int	状态码
`msg`	string	提示信息
`data`	array	问卷表单列表

data 列表常用字段：

参数	类型	描述
`appId`	int	游戏 ID
`formKey`	string	问卷唯一标识，打开问卷时传入
`formUrl`	string	问卷表单链接
`formName`	string	问卷表单名称
`formDesc`	string	问卷表单描述
`expireTime`	long	问卷链接过期时间，秒级时间戳
`order`	int	问卷表单排序

获取企业微信-福利站信息

用于获取平台配置的企业微信 / 福利站信息。

请求参数：

参数	类型	必选	描述
`userId`	long	是	OnlySDK 用户 ID，登录成功后返回
`serverId`	string	是	区服 ID
`serverName`	string	是	区服名称
`roleId`	string	是	角色 ID
`roleName`	string	是	角色名称
`extra`	string	否	扩展参数，原样透传

调用示例：

OnlySDK.GetWelfareInfo(new OnlySDKWelfareInfoRequest
{
    userId = OnlySDK.LoginData.userId,
    serverId = "1",
    serverName = "测试一区",
    roleId = "role_001",
    roleName = "测试角色",
    extra = ""
});

OnlySDK.OnWelfareInfo += evt =>
{
    Debug.Log($"welfare info: success={evt.IsSuccess}, data={evt.serverDataBodyRaw}");
};

服务端响应会放在 evt.serverDataRaw，其中 data 常用字段如下：

参数	类型	描述
`mpUrl`	string	小程序跳转链接
`qwPicUrl`	string	添加企业微信图片
`templatePic`	string	模板图片

常见问题

现象	排查
`Failed to load onlysdk.dll`	`onlysdk.dll` 不在运行目录，或位数不匹配
`Failed to load channel plugin`	渠道 DLL 缺失，或 `ChannelName` 与当前 DLL 不匹配
登录页空白	缺 `WebView2 Runtime`，或缺 `login_ui.html / qrcode.min.js`
Unity Editor 中 `DllNotFoundException: onlysdk`	插件导入设置未启用 `Editor + Win64`
Cocos 中 `native api missing: init`	原生桥未注册成功，重新执行 `setup-cocos-dev.ps1`

正式出包说明

游戏研发交付基础包后，由 SDK / 发行侧使用渠道盖包脚本替换正式运行时，例如：

pwsh tools/stamp-cocos-channel.ps1 -GameBuild "D:\builds\GameBase" -Channel nsdk -OutDir "D:\release\nsdk" -Arch x86
pwsh tools/stamp-cocos-channel.ps1 -GameBuild "D:\builds\GameBase" -Channel taptap -OutDir "D:\release\taptap" -Arch x64

研发侧无需自己切正式渠道。

# PC SDK 接入指南

# 流程说明

# SDK 文件说明

# onlysdk_config.json 配置

# Unity 接入

# 1. 导入 SDK 包

# 2. 编写业务调用脚本

# 3. 本地联调

# 4. 正式渠道出包

# Cocos 接入

# 1. 先在 Cocos Creator 中构建一次 Windows 原生工程

# 2. 运行一键联调脚本

# 3. VS 重新生成并运行

# 4. 业务调用示例

# 初始化（必接）

# 请求参数

# 返回结果

# 登录（必接）

# 请求参数

# 返回结果

# 支付

# 请求参数

# 返回结果

# 数据上报

# 请求参数

# 问卷与福利站（选接）

# 打开问卷调查

# 获取用户可填写问卷列表

# 获取企业微信-福利站信息

# 常见问题

# 正式出包说明

PC SDK 接入指南

流程说明

SDK 文件说明

onlysdk_config.json 配置

Unity 接入

1. 导入 SDK 包

2. 编写业务调用脚本

3. 本地联调

4. 正式渠道出包

Cocos 接入

1. 先在 Cocos Creator 中构建一次 Windows 原生工程

2. 运行一键联调脚本

3. VS 重新生成并运行

4. 业务调用示例

初始化（必接）

请求参数

返回结果

登录（必接）

请求参数

返回结果

支付

请求参数

返回结果

数据上报

请求参数

问卷与福利站（选接）

打开问卷调查

获取用户可填写问卷列表

获取企业微信-福利站信息

常见问题

正式出包说明