哔哩哔哩 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.获取接口

获取接口

  1. 定义回调函数

1

2

  1. 调用接口方法

2

3

4

5

6

7

8

9

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

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

C++调用步骤如下

​ 1.声明函数

1

​ 2.定义回调函数

2

3

​ 3.加载SDK文件

4

​ 4.函数调用

​ a.初始化接口

5

​ b.绑定启动器接口

6

​ c.获取用户登录信息接口

7

​ d.获取用户DLC信息的接口

8

​ e.支付接口

9

​ f.防沉迷接口

​ g.帐号退出接口

​ h.解绑启动器接口

​ i.设置崩溃回调接口