哔哩哔哩小游戏SDK文档
<p>[TOC]</p>
<h1>SDK介绍</h1>
<p>SDK集成封装了部分的哔哩哔哩的前端API，直接调用SDK接口即可，无需再调用哔哩哔哩的接口；
<font color="red">无需调用获取主体access_token接口</font>，由我方提供接口获取，以免冲突；</p>
<h1>版本和渠道设置说明：</h1>
<p>SDK可以区分渠道和子渠道
(1)场景值做为渠道，SDK会自动通过[bl.getLaunchOptionsSync](<a href="https://miniapp.bilibili.com/small-game-doc/api/life/getLaunchOptionsSync.html">https://miniapp.bilibili.com/small-game-doc/api/life/getLaunchOptionsSync.html</a> "bl.getLaunchOptionsSync")().scene获取获取当前小程序场景：chid=场景值；
(2)子渠道可以在启动参数(query)按照以下格式设置参数：
via=子渠道ID或者 subchid=子渠道ID,
示例：via=111&bbb=222
<font color="red">渠道只能二选一，via优先subchid</font></p>
<h1>小游戏后台必设置：</h1>
<p>域名：https: 配置文件提供的域名地址</p>
<h2>小游戏后台</h2>
<h3>(1)域名设置</h3>
<p>在开发->开发设置->服务器域名，request合法域名增加
<code>cps.moyangmoyang.com</code></p>
<h3>(2)广告设置（如内置广告必设置）</h3>
<p>在推广->流量主->广告位管理，添加banner广告和激励视频广告，获得广告位id</p>
<h3>(3)支付设置（如开通支付必设置）</h3>
<p>在功能->虚拟支付->基本配置->游戏币配置，配置米大师相关信息</p>
<h3>(4)消息推送</h3>
<p>登录小程序后台后，在「开发」-「开发设置」-「消息推送」中，管理员扫码启用消息服务，填写服务器地址（URL）、令牌（Token） 和 消息加密密钥（EncodingAESKey）等信息。
URL: 开发者用来接收微信消息和事件的接口 URL。开发者所填写的URL 必须以 http:// 或 https:// 开头，分别支持 80 端口和 443 端口。
Token: 可由开发者可以任意填写，用作生成签名（该 Token 会和接口 URL 中包含的 Token 进行比对，从而验证安全性）。
EncodingAESKey: 由开发者手动填写或随机生成，将用作消息体加解密密钥。</p>
<h1>1.SDK包以及引入说明（重要）：</h1>
<h2>1.1.SDK文件包括</h2>
<pre><code> sdk_v版本号.js（主文件）
config.js（配置文件，接入前会提供参数表，没有参数不能接入，文档中的所有密钥指的是我们提供的研发密钥，非小程序密钥，加号或者点号表示拼接两个字符串）</code></pre>
<p><div style="background: #FFE4B5;padding: 12px; border-radius: 8px; color: #000;">⚠️ <strong>注意</strong>
配置文件config.js必须按照提供的资料填写完整，没有参数不能接入，文档中的所有密钥指的是我们提供的研发密钥，非小程序密钥，加号或者点号表示拼接两个字符串
</div></p>
<h2>1.2.SDK引入方式</h2>
<pre><code>require(&quot;./js/sdk/dybsdk_v版本号.js&quot;);
//不同的引擎可能引入方式不一致，根据需求可以自行拆解拷贝。</code></pre>
<h2>1.3.接口请求方式</h2>
<p>全部POST，支持JSON和FORM，声明header格式content-type,返回的格式，如无特殊说明，code的值1为正确，0为错误</p>
<h2>1.4.安全</h2>
<p>涉及到服务端请求的接口，如access_token等全部要在后端进行请求，平台提供的密钥secret_key，必须放在服务端后端校验，不能暴露在前端，前端代码会被爬下来破解加密。</p>
<h2>1.5.接入有问题先看文档后面的常见问题</h2>
<h1>2.获取用户信息（为确保数据同步，游戏初始化必接入，打开游戏即调用）</h1>
<h2>2.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍获取openid，无需再单独调用login接口。</p>
<p><code>getDybUserInfo(function callback)</code>
</div>
<div style="background: #FFE4B5;padding: 12px; border-radius: 8px; color: #000;">⚠️ <strong>注意</strong>
（1）整个游戏流程只能全局初始化的时候调用一次即可，不能重复调用。
重复调用可能会刷新,session_key,access_token，影响支付授权。
（2）<font color="red">保证先接入此接口，再接入后续接口，后续接口依赖于此接口，后续接口调用可放在此接口回调函数里面，或延迟调用，不要并行</font>
（3）此接口调用login授权获取openid，如需头像等信息请自行使用原生接口userInfo获取信息接口，但是保证不能调用到bl.login
</div>
<div style="background: #fda7b4;padding: 12px; border-radius: 8px; color: #000;">⚡ <strong>校验安全</strong>
1、为了防止openid泄露被直接用于游戏接口请求，授权返回的数据中有2个字段用于游戏方后端校验用户正确性-(openid, sign)
2、返回签名sign的生成方式为:<font color="red">md5('sessV2'+appid+openid+加密密钥key)</font>, 加密密钥平台方提供，+号拼接字符串
</div></p>
<h2>2.2参数说明</h2>
<ul>
<li>无需传参</li>
</ul>
<h2>2.3示例代码</h2>
<pre><code class="language-javascript">dyb.getDybUserInfo(function (callback) {
console.log(&#039;getDyUserInfo-------------:&#039; + JSON.stringify(callback));
})</code></pre>
<h2>2.4接口返回</h2>
<pre><code class="language-javascript">getDyUserInfo-------------:{&quot;user&quot;:{&quot;openid&quot;:&quot;1D763F35AEC4354069F149B4350BEABE&quot;,&quot;sign&quot;:&quot;f140efc95199c43a8d3b6d508b6ba98d&quot;},&quot;shareInfo&quot;:{}}</code></pre>
<h1>3.创角信息上报</h1>
<h2>3.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍上报创角事件</p>
<pre><code>createRole(function callback)</code></pre>
<p></div>
<div style="background: #FFE4B5;padding: 12px; border-radius: 8px; color: #000;">⚠️ <strong>注意</strong>
第一次调用依赖第2步-获取用户信息，建议创角上报在授权事件后3-5s后调起
</div></p>
<h2>3.2参数说明</h2>
<p>|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|role_name |是 |string |角色名称，没有填个昵称或者别的信息 |
|server_id |是 |int | 区服ID，没有填个默认数字 |
|server_name |否 |string | 区服名称，没有填个默认名称 |</p>
<h2>3.3示例代码</h2>
<pre><code class="language-javascript">let param = {
server_id: 1,
server_name: &#039;服务器&#039;,
role_name: &#039;默认昵称&#039;,
}
dyb.createRole(param, function (callback) {
console.log(&#039;roleData:&#039; + JSON.stringify(callback));
});</code></pre>
<h2>3.4接口返回</h2>
<pre><code class="language-javascript">roleData:{&quot;code&quot;:1,&quot;msg&quot;:&quot;角色已经上报&quot;,&quot;time&quot;:&quot;1586418685&quot;,&quot;data&quot;:null}</code></pre>
<h1>4.游戏关卡/等级</h1>
<h2>4.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍上报当前玩家所在的游戏关卡/等级；
（1）可以在玩家退出的时候进行上报最新的关卡/等级；
（2）也可以在玩家突破关卡/等级的时候上报</p>
<p><code>1、上报关卡：gameLevel(int level, callback)</code>
<code>2、上报等级：gameGrade(int grade, callback)</code>
<font color="red">如果两个接口需要同时调用，需确保其中一个先调用，另一个可放在回调函数里面调用，或延迟调用，不要并行</font>
</div>
<div style="background: #FFE4B5;padding: 12px; border-radius: 8px; color: #000;">⚠️ <strong>注意</strong>
第一次调用依赖第2步-获取用户信息，建议在授权事件后3-5s后调起
</div></p>
<h2>4.2参数说明</h2>
<p><strong>上报关卡：</strong></p>
<p>|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|level |是 |int |关卡 |</p>
<p><strong>上报等级：</strong></p>
<p>|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|grade |是 |int |等级 |</p>
<h2>4.3示例代码</h2>
<pre><code class="language-javascript">//上报关卡：
//关卡2
dyb.gameLevel(2,function (callback) {
console.log(&#039;game_level:&#039; + JSON.stringify(callback));
});
//上报等级：
//等级3
dyb.gameGrade(3, function (callback) {
console.log(&#039;game_grade:&#039; + JSON.stringify(callback));
});</code></pre>
<h2>4.4接口返回</h2>
<pre><code class="language-javascript">{
&quot;code&quot;: 1, //0调用失败，1调用成功
&quot;msg&quot;: &quot;成功&quot;
}</code></pre>
<h1>5.激励视频广告</h1>
<h2>5.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍创建激励视频接口</p>
<p><code>createVideoAd(string auditID, callback)</code>
</div>
<div style="background: #FFE4B5;padding: 12px; border-radius: 8px; color: #000;">⚠️ <strong>注意</strong>
调用一次，拉起一次广告，游戏需要根据回调状态处理奖励的发送
</div></p>
<h2>5.2参数说明</h2>
<p>|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|auditID |是 |string |视频广告ID，小程序后台生成 |</p>
<h2>5.3示例代码</h2>
<pre><code class="language-javascript">dyb.createVideoAd(&#039;8qodec75r8m7j1orib&#039;,function(call){
//call返回的state有三种状态，分别是show,close,error
//show {&quot;state&quot;:&quot;show&quot;,&quot;isEnded&quot;:false,&quot;msg&quot;:&quot;视频展示成功&quot;}
//close {&quot;state&quot;:&quot;close&quot;,&quot;isEnded&quot;:true,&quot;msg&quot;:&quot;视频广告关闭&quot;}
//error {&quot;state&quot;:&quot;error&quot;,&quot;isEnded&quot;:false,&quot;msg&quot;:&quot;视频广告错误&quot;}
console.log(JSON.stringify(call),&#039;createRewardedVideoAd&#039;)
if(call.state == &#039;close&#039; &amp;&amp; call.isEnded){
//视频完整看完，进行发送奖励
console.log(&#039;//视频完整看完，进行发送奖励&#039;)
}else{
console.log(&#039;//视频没看完1&#039;)
}
})</code></pre>
<h1>6.添加桌面</h1>
<h2>6.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍将小游戏快捷方式添加到手机桌面上</p>
<p><code>addShortcut (function callback)</code>
</div>
<div style="background: #FFE4B5;padding: 12px; border-radius: 8px; color: #000;">⚠️ <strong>注意</strong>
桌面快捷方式礼包需要每天都能领取， 同游戏内签到礼包。</p>
<p>开发者可以在 [bl.getLaunchOptionsSync](<a href="https://miniapp.bilibili.com/small-game-doc/api/life/getLaunchOptionsSync">https://miniapp.bilibili.com/small-game-doc/api/life/getLaunchOptionsSync</a> "bl.getLaunchOptionsSync") 和 [bl.onShow](<a href="https://miniapp.bilibili.com/small-game-doc/api/base/applet/onShow">https://miniapp.bilibili.com/small-game-doc/api/base/applet/onShow</a> "bl.onShow") 中获取场景值为10002(string)，进行礼包发放
</div></p>
<h2>6.2示例代码</h2>
<pre><code class="language-javascript">dyb.addShortcut(function (callback) {
console.log(&#039;添加桌面:&#039; + JSON.stringify(callback));
})</code></pre>
<h2>6.3接口返回</h2>
<pre><code class="language-javascript">{
&quot;code&quot;: 1, //(1添加成功，0添加失败，-1基础库版本不支持)
&quot;msg&quot;: &quot;&quot;
}</code></pre>
<h1>7.广告点上报</h1>
<h2>7.1接口说明</h2>
<p><div style="background: #9efca6;padding: 12px; border-radius: 8px; color: #000;">✍广告点上报，看广告时调用</p>
<p><code>adNameReward</code>
</div></p>
<h2>7.2参数说明</h2>
<p>|参数名|必选|类型|说明|
|:---- |:---|:----- |----- |
|ad_name |是 |string |广告位名称 |
|ad_is_reward |是 |int |是否获得广告奖励 0否，1是(只要看完广告就传1,没看完传0) |</p>
<h2>7.3示例代码</h2>
<pre><code class="language-javascript">//广告未看完
let ad_data = {
ad_name: &#039;广告未看完&#039;,
ad_is_reward: 0, //0未获得奖励，1获得奖励，必传((点击了广告未看完传0))
}
dyb.adNameReward(ad_data, function (callback) {
console.log(&#039;上报广告名称:&#039; + JSON.stringify(callback));
});
//广告看完
let ad_data = {
ad_name: &#039;广告看完&#039;,
ad_is_reward: 1, //0未获得奖励，1获得奖励，必传((只要看完广告就传1))
}
dyb.adNameReward(ad_data, function (callback) {
console.log(&#039;上报广告名称:&#039; + JSON.stringify(callback));
});</code></pre>
<h2>7.4接口返回</h2>
<pre><code class="language-javascript">上报广告名称:{&quot;code&quot;:1,&quot;msg&quot;:&quot;成功&quot;,&quot;time&quot;:&quot;1717141847&quot;,&quot;data&quot;:null}</code></pre>