哔哩哔哩 PC端游SDK接口文档

接口说明

1.SDK文件名:PCGameSDK.dll

2.SDK作用:为游戏提供登录弹框,支付弹框,防沉迷检测功能。

3.目前SDK一共包含七个接口,初始化接口,打开启动器接口,打开登录弹框接口,设置崩溃回调接口,打开支付弹框接口,打开防沉迷心跳接口,帐号退出接口。登录,防沉迷,支付接口,通过回调函数通知结果。

调用步骤

1:初始化接口SDKInit,无需重复调用,全程只调用一次即可

2:如果游戏需要收集崩溃日志,需要调用SDKSetCrashHandler,该接口会在游戏发生崩溃的时候,将sdk获取到的崩溃信息通过回调传给游戏

(注意:如果游戏不需要收集崩溃日志,则无需接入

3:若游戏需要打开的游戏启动器,则在初始化后调用SDKOpenLauncher

(注意:此接口只用于需要接入哔哩哔哩 PC游戏启动器的游戏,若游戏没有接入启动器,则无需接入

4:登录接口SDKShowLoginPanel

5:游戏方应在每次登录成功,并选择好区服后,调用防沉迷接口SDKOpenAntiAddiction,收到防沉迷通知"code" : 1,后应将游戏下线(防沉迷接口启动后会在后台自动运行,定时检测数据)。游戏如果换服,可重复调用此接口来替换新的区服信息进行防沉迷校验。

6:游戏方创建完订单之后,调用支付接口SDKShowPayPanel

7:游戏若退出帐号,需要调用SDKLogout接口来清理SDK中游戏帐号的缓存信息,此操作会退出该账号的防沉迷检测。

注意事项

1.为解决参数有中文的问题,接口中所要传递的字符串类型变量,需要统一使用UTF8编码。目前SDK仅支持windows系统,且系统中的IE浏览器需要IE9及以上版本。

2.U3D游戏在生成游戏包的时候需要勾选Visible In Background选项

​ 步骤Build Setting > Player Settings… > Settings for PC, MAC… > Visible In Background > 勾选

接口描述

1.初始化接口

int SDKInit(const char* szGameId, HWND hwndParent);
函数名称: SDKInit 注释
输入参数: szGameId 端游的游戏ID,UTF8编码
hwndParent 端游游戏的主窗口句柄
输出参数:
返回值: 0表示成功,-1表示失败,1表示之前已经初始化成功
备注: 接口采用同步方式返回数据

2.打开登录面板接口

int SDKShowLoginPanel(const char* szAppKey, const bool bBackToLogin,  LoginCallBackHandler CallBack);
函数名称: SDKShowLoginPanel
输入参数: szAppKey 客户端密钥,UTF8编码
bBackToLogin 触发宵禁后,关闭宵禁弹框后是否返回到登录页面,true返回到登录页面,false退出登录
CallBack 登录结果的回调函数
输出参数:
返回值: 0表示成功,-1表示失败,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 表示取消登录
100 表示SDK要弹出对话框,游戏需要显示出鼠标

登录成功时返回,access_key(帐号信息),game_id(游戏ID),uid(用户ID),uname(账号名称)

3.设置崩溃回调接口(游戏需要收集崩溃信息时接入)

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

4.打开支付面板接口

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_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要进行弹框,需要游戏显示出鼠标

5.开启防沉迷检测接口

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要进行弹框,需要游戏显示出鼠标

6.帐号退出接口

Int SDKLogout();
函数名称: SDKLogout 帐号退出接口
输入参数:
输出参数:
返回值: 0表示成功,-1表示失败
备注: 游戏退出帐号后,使用此接口以清空此前帐号在SDK的缓存信息,以及退出此前帐号的防沉迷检测。

注意:游戏在切换账号和退出账号时,需要调用此接口,以退出当前账号的防沉迷检测功能。

7.打开启动器接口

int SDKOpenLauncher(const char* szAppKey, LauncherCallBackHandler CallBack);
函数名称: SDKOpenLauncher
输入参数: 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 表示打开启动器
100 表示SDK要进行弹出对话框,需要游戏显示出鼠标

返回值不是100,需要退出游戏

接口需求:游戏方没有自己的下载器(即启动器),需要接入的下载器,若用户自己打开了游戏程序,游戏本身没有热更的功能,判断到游戏自身不是最新的版本,需要提示给用户去下载器更新游戏包。

调用时机:游戏在打开后判断自己的版本是否为最新状态,若需要进行游戏的升级操作,则调用SDKOpenLauncher接口,接口会弹出一个对话框,让用户点击去打开下载器。对话框关闭后,会返回相应的返回值,通过回调函数的方式告知游戏。

调用示例

C#调用步骤如下

1.获取接口

获取接口

  1. 定义回调函数

1

2

  1. 调用接口方法

2

3

4

5

6

7

注意:若unity出包采用IL2CPP模式,调用 C++ 的方法的时候,必须是静态类且要加如下的声明

c# [MonoPInvokeCallback] static public void LoginResultCallback(string buf, int buflen)

C++调用步骤如下

​ 1.声明函数

1

​ 2.定义回调函数

2

3

4

5

6

​ 3.函数调用

​ a.初始化接口

7

​ b.打开启动器接口

8

​ c.登录接口

9

​ d.设置崩溃回调接口

​ e.支付接口

​ f.防沉迷接口

​ g.帐号退出接口