哔哩哔哩 PC端游(单机)SDK接口文档
接口说明
1.SDK文件名:PCGameSDK.dll
2.SDK作用:为游戏提供登录弹框,支付弹框,防沉迷检测功能。
3.目前SDK一共包含9个接口,初始化接口,设置崩溃回调接口,绑定游戏启动器接口,获取用户登录信息接口,获取用户DLC权限信息,打开支付弹框接口,打开防沉迷心跳接口,帐号退出接口,解绑启动器接口。绑定启动器,获取用户登录信息,服务端数据上报接口,获取用户dlc权限信息,防沉迷,支付接口,通过回调函数通知结果。
调用步骤
1:初始化接口SDKInit,无需重复调用,全程只调用一次即可
2: 如果游戏需要收集崩溃日志,需要调用SDKSetCrashHandler,该接口会在游戏发生崩溃的时候,将sdk获取到的崩溃信息通过回调传给游戏(注意:如果游戏不需要收集崩溃日志,则无需接入)
3:绑定游戏启动器接口SDKBindLauncher,收到回调通知返回code:0表示绑定成功。其余返回值表示失败,需要退出游戏进程。回调函数需是全局存在的,需要接收下载器通知的关闭游戏的消息
4:获取用户登录信息接口,会从游戏启动器获取已经登录好的用户的信息,返回code:0表示登录成功
5:获取用户DLC权限信息,根据用户的购买记录,返回该用户的dlc的权限列表。
6:游戏方应在每次登录成功,并选择好区服后,调用防沉迷接口SDKOpenAntiAddiction,收到防沉迷通知"code" : 1,后应将游戏下线(防沉迷接口启动后会在后台自动运行,定时检测数据)。游戏如果换服,可重复调用此接口来替换新的区服信息进行防沉迷校验。
7:游戏方创建完订单之后,调用支付接口SDKShowPayPanel
8:游戏若退出帐号,需要调用SDKLogout接口来清理SDK中游戏帐号的缓存信息,此操作会退出该账号的防沉迷检测。
9:若游戏绑定启动器成功的,游戏在退出之前需要调用SDKUnBindLauncher解绑启动器接口。
注意事项
1.为解决参数有中文的问题,接口中所要传递的字符串类型变量,需要统一使用UTF8编码。目前SDK仅支持windows系统,且系统中的IE浏览器需要IE9及以上版本。
2.U3D游戏在生成游戏包的时候需要勾选Visible In Background选项。
步骤Build Setting > Player Settings… > Settings for PC, MAC… > Visible In Background > 勾选
3.需要接入单机游戏SDK的游戏,需要接入biligame的启动器才行。
接口描述
1.初始化接口
int SDKInit(const char* szGameId, HWND hwndParent);
函数名称: | SDKInit | 注释 |
---|---|---|
输入参数: | szGameId | 端游的游戏ID,UTF8编码 |
hwndParent | 端游游戏的主窗口句柄 | |
输出参数: | 无 | |
返回值: | 0表示成功,-1表示失败,1表示之前已经初始化成功 | |
备注: | 接口采用同步方式返回数据 |
2.设置崩溃回调接口(游戏需要收集崩溃信息时接入)
int STDCALL SDKSetCrashHandler(CrashCallBackHandler CallBack);
函数名称: | SDKSetCrashHandler | 注释 |
---|---|---|
输入参数: | CallBack | 获取结果的回调函数 |
输出参数: | 无 | |
返回值: | 0表示成功,-1表示失败 | |
备注: | 当游戏程序发生崩溃的时候,sdk会生成一个dmp文件,该文件包含软件崩溃时的内存信息。接口采用异步方式返回数据,调用后立即返回,通过回调函数返回结果 |
参数详解:
CrashCallBackHandler为崩溃回调接口的结果的回调函数类型
函数模型如下:
void CrashCallBackHandler (char* szData, int nLen)
函数名称: | CrashCallBackHandler | |
---|---|---|
输入参数: | szData | 崩溃日志绝对路径,UTF8编码 |
nLen | szData的长度 | |
输出参数: | 无 | |
返回值: | 无 | |
备注: | szData的样式如下描述: |
szData内容为崩溃日志的绝对路径,文件名格式如下:
BiliGameSDK-SDK版本号-游戏id-年月日-时分秒-进程id-线程id-GUID.dmp
如:
C:\Users\NAME\AppData\Local\Temp\BiliGameSDK\BiliGameSDK-v3.4.0-5867-20210622-154431-96616-58512-0496752455DB4A22B624EF020CBB83ED.dmp
3.绑定游戏启动器接口
int SDKBindLauncher (const char* szAppKey, LauncherCallBackHandler CallBack);
函数名称: | SDKBindLauncher | |
---|---|---|
输入参数: | szAppKey | 客户端密钥,UTF8编码 |
CallBack | 绑定结果的回调函数 | |
输出参数: | 无 | |
返回值: | 0表示成功,-1表示失败 | |
备注: | 接口采用异步方式返回数据,调用后立即返回,通过回调函数返回绑定结果,回调函数需要是全局的,用来监听启动器返回的退出游戏的指令 |
参数详解:
LauncherCallBackHandler为绑定结果的回调函数类型
函数模型如下:
void LauncherCallBackHandler (char* szData, int nLen)
函数名称: | LauncherCallBackHandler | |
---|---|---|
输入参数: | szData | 绑定结果,JSON格式,UTF8编码 |
nLen | szData的长度 | |
输出参数: | 无 | |
返回值: | 无 | |
备注: | szData的样式如下描述: |
szData内容样式如下:
{
"code" : 0,
"data" : {
"message":"游戏启动器绑定成功",
"msgdetails":"错误详细信息"
}
}
code | 描述 |
---|---|
0 | 绑定成功 |
-1 | 未安装启动器 |
-2 | 启动器文件损坏,需要重新安装启动器 |
-3 | 需要从启动器打开游戏 |
-4 | 用户网络断开 |
1 | 启动器注销帐号 |
2 | 启动器更新游戏 |
3 | 启动器退出 |
100 | SDK要进行弹出对话框,需要游戏显示出鼠标 |
code为 不是0 或100,需要退出游戏。若游戏收到绑定成功的通知后,在游戏需要退出的时候,需要调用解绑启动器的接口
4.获取用户登录信息接口
int SDKGetUserInfo (const char* szAppKey, LoginCallBackHandler CallBack);
函数名称: | SDKGetUserInfo | |
---|---|---|
输入参数: | szAppKey | 客户端密钥,UTF8编码 |
CallBack | 获取登录结果的回调函数 | |
输出参数: | 无 | |
返回值: | 0表示成功,-1表示失败 | |
备注: | 接口采用异步方式返回数据,调用后立即返回,通过回调函数返回登录结果 |
参数详解:
LoginCallBackHandler为登录结果的回调函数类型
函数模型如下:
void LoginCallBackHandler (char* szData, int nLen);
函数名称: | LoginCallBackHandler | |
---|---|---|
输入参数: | szData | 登录结果,JSON格式,UTF8编码 |
nLen | szData的长度 | |
输出参数: | 无 | |
返回值: | 无 | |
备注: | szData的样式如下描述: |
szData内容样式如下:
{
"code" : 0,
"data" : {
"message":" 响应描述,code非0时返回",
"msgdetails":" 服务器返回的错误详细信息,code非0时返回",
"access_key" : "abcdefgabcdefgabcdefg",
"game_id" : "123456",
"uid" : 888888888,
"uname" : "test"
}
}
code | 描述 |
---|---|
0 | 表示登录成功 |
-1 | 表示服务器返回登录失败 |
-2 | 表示从启动器获取登录态失败 |
-3 | 表示服务器访问失败 |
-4 | 表示服务器返回错误数据 |
100 | 表示SDK要进行弹框,需要游戏显示出鼠标 |
5.获取用户单机DLC列表接口
int SDKGetDLCInfo (const char* szAppKey, DlcCallBackHandler CallBack);
函数名称: | SDKGetDLCInfo | |
---|---|---|
输入参数: | szAppKey | 订单详细内容,UTF8编码 |
CallBack | 获取结果的回调函数 | |
输出参数: | 无 | |
返回值: | 0表示成功,-1表示失败 | |
备注: | 接口采用异步方式返回数据,调用后立即返回,通过回调函数返回结果 |
参数详解:
DlcCallBackHandler为获取dlc接口的结果的回调函数类型
函数模型如下:
void DlcCallBackHandler (char* szData, int nLen);
szData内容样式如下:
{
"code" : 0,
"data" : {
"message":"", //响应描述,code非0时返回
"msgdetails":"", //服务器返回的错误详细信息,code非0时返回
"gameid" : "123456", //游戏ID
"uid" : "456789", //用户ID
"product": //用户DLC列表
[
"com.bilibili.gd.chapter01",//DLC对应的商品ID
"com.bilibili.gd.chapter02"
]
}
}
6.打开支付面板接口
int SDKShowPayPanel(const char* szPayInfo, PayCallBackHandler CallBack);
函数名称: | SDKShowPayPanel | |
---|---|---|
输入参数: | szPayInfo | 订单详细内容,UTF8编码 |
CallBack | 支付结果的回调函数 | |
输出参数: | 无 | |
返回值: | 0表示成功,-1表示失败 | |
备注: | 接口采用异步方式返回数据,调用后立即返回,通过回调函数返回支付结果 |
参数详解:
1.szPayInfo为订单详细内容,数据格式为JSON格式,内容如下:
名称 | 类型 | 是否必填 | 备注 |
---|---|---|---|
appKey | String类型 | 必填 | 客户端密钥 |
orderSign | String类型 | 必填 | 详见下方说明 |
zoneId | String类型 | 必填 | 游戏区服id |
tradeNum | String类型 | 必填 | 购买商品时端游研发方产生的订单号,不超过50字符(若单机游戏不存在订单号,可随机生成一段字符串) |
game_money | String类型 | 必填 | 游戏内的道具数量,最大值“99999999” (九千九百九十万零九千九百九十九) |
product_name | String类型 | 必填 | 商品名称,不超过100字符,如果是游戏货币类道具必须包含本次购买数量,例如:钻石200个。不能包含特殊字符%#&=? |
money | String类型 | 必填 | 商品价格,校验支付防沉迷,单位:分。最大值” 100000000”100万元 |
product_id | String类型 | 必填 | 商品ID,单机游戏必填 |
product_desc | String类型 | 非必填 | 商品描述。不能包含特殊字符%#&=? |
username | String类型 | 非必填 | 用户昵称,不超过100个字符。不能包含特殊字符%#&=? |
role_name | String类型 | 非必填 | 游戏内角色名称,不超过100个字符。不能包含特殊字符%#&=? |
extension_info | String类型 | 非必填 | 透传信息,支付完成后会跟随服务端支付回调原样返回,不超过120个字符。不能包含特殊字符%#&=? |
notify_url | String类型 | 非必填 | 自定义支付回调地址,优先级高于在平台配置的回调地址,不超过128个字符。不支持如下带参格式* * 示例:http://host/notify?a=xxx&b=xxx |
orderSign签名方式说明
将out_trade_no/money/game_money/notify_url/extension_info五个参数按照key进行字典排序,以key1=value1&key2=value2形式拼接(value要经过url encode),最后拼接secretKey,进行md5,并转为小写,如下所示:
假设secretKey = "biliGameSecret";
orderSign=MD5(game_money=game_money&money=money&out_trade_no=outTradeNoTestbiliGameSecret)
例子:
{
"appKey": "1234567890abcdefg",
"orderSign": "3e15fdf74a0c401926d6656917606f1f",
"zoneId": "8888",
"tradeNum": "123456",
"game_money": "1000",
"product_name": "端游测试商品(金币)* 1000",
"money": "1"
}
orderSign=MD5(game_money=1000&money=1&out_trade_no=123456biliGameSecret).toLowerCase()
注:
(1) URL encode 结果必须遵照 RFC3986 规范;除字母 / 数字 / "-" / "." / "_" / "~"字符外,其它字符均需要进行百分号编码。
(2) out_trade_no对应的value值是表格中的tradeNum,签名中的订单号的key值使用out_trade_no
2.PayCallBackHandler为支付结果的回调函数类型
Void PayCallBackHandler(char* szData, int nLen);
函数名称: | PayCallBackHandler | |
---|---|---|
输入参数: | szData | 支付结果,JSON格式,UTF8编码 |
nLen | szData的长度 | |
输出参数: | 无 | |
返回值: | 无 | |
备注: | szData内容如下: |
szData内容如下:
{
"code" : 0,
"data" : {
"message":" ", //响应描述
"msgdetails":" " //服务器返回的错误详细信息
}
}
code | 描述 |
---|---|
0 | 支付成功 |
-1 | 支付失败 |
-2 | 取消支付 |
1 | 重新下单 |
2 | 支付防沉迷未通过并弹框提示 |
3 | 支付防沉迷接口返回失败 |
4 | 支付中 |
5 | 支付关闭 |
100 | SDK要进行弹框,需要游戏显示出鼠标 |
7.开启防沉迷检测接口
Int SDKOpenAntiAddiction (const char* szGameInfo, AntiAddictionCallBackHandler CallBack);
函数名称: | SDKOpenAntiAddiction | |
---|---|---|
输入参数: | szGameInfo | 消息详细内容,UTF8编码 |
CallBack | 结果的回调函数 | |
输出参数: | 无 | |
返回值: | 0表示成功,-1表示失败,1表示用新的传递值做防沉迷校验 | |
备注: | 接口采用异步方式返回数据,调用后立即返回,通过回调函数返回防沉迷状态结果 |
参数详解:
1.szGameInfo为游戏的详细内容,数据格式为JSON格式,内容如下:
server_id | String类型 | 必填 |
---|---|---|
channel_id | String类型 | 必填 |
ver | String类型 | 必填 |
例子:
{
"server_id": "483",
"channel_id": "12",
"ver": "11"
}
2.CallBack为消息触发的回调调用示例
Void AntiAddictionCallBackHandler(char* szData, int nLen);
函数名称: | AntiAddictionCallBackHandler | |
---|---|---|
输入参数: | szData | 回调结果,JSON格式,UTF8编码 |
nLen | szData的长度 | |
输出参数: | 无 | |
返回值: | 无 | |
备注: | szData内容如下: |
szData内容如下:
{
"code" : 0,
"data" : {
"message":" ", //响应描述
"msgdetails":" " //服务器返回的详细信息
}
}
code | 描述 |
---|---|
0 | 表示出现在线时长弹框提示 |
1 | 表示出现防沉迷超时弹框并通知游戏下线 |
100 | 表示SDK要进行弹框,需要游戏显示出鼠标 |
8.帐号退出接口
Int SDKLogout();
函数名称: | SDKLogout | 帐号退出接口 |
---|---|---|
输入参数: | 无 | |
输出参数: | 无 | |
返回值: | 0表示成功,-1表示失败 | |
备注: | 游戏退出帐号后,使用此接口以清空此前帐号在SDK的缓存信息,以及退出此前帐号的防沉迷检测。 |
注意:游戏在切换账号和退出账号时,需要调用此接口,以退出当前账号的防沉迷检测功能。
9.解绑启动器接口
Int SDKUnBindLauncher ();
函数名称: | SDKUnBindLauncher | 解绑启动器接口 |
---|---|---|
输入参数: | 无 | |
输出参数: | 无 | |
返回值: | 0表示成功,-1表示失败 | |
备注: | 若游戏绑定启动器成功,需要在游戏退出的时候,调用解绑启动器接口。 |
注意:若游戏绑定启动器成功,需要在游戏退出的时候,调用解绑启动器接口。
调用示例
C#调用步骤如下
1.获取接口
- 定义回调函数
- 调用接口方法
注意:若unity出包采用IL2CPP模式,调用 C++ 的方法的时候,必须是静态类且要加如下的声明
c#
[MonoPInvokeCallback] static public void LoginResultCallback(string buf, int buflen)
C++调用步骤如下
1.声明函数
2.定义回调函数
3.加载SDK文件
4.函数调用
a.初始化接口
b.绑定启动器接口
c.获取用户登录信息接口
d.获取用户DLC信息的接口
e.支付接口
f.防沉迷接口
g.帐号退出接口
h.解绑启动器接口
i.设置崩溃回调接口