1.2.H5 游戏开发指引

• 此功能旨在降低H5游戏接入手Q轻游戏成本，同时提供手Q相关的能力：用户信息、排行榜、分享等
• 支持版本：安卓手 Q 7.6.0 及以上，iOS 7.9.0 及以上
• H5游戏包上架与正常游戏包上架流程一致

H5游戏包说明

• H5游戏包与普通游戏包有所不同，游戏专用包地址
• gameConfig.json：游戏配置文件，H5需重点关注
• main.js：使用Bricks引擎开发的游戏的代码文件，H5游戏不用关注，但需放在游戏包中（使用示例包中的 main.js 文件）
• qqPlayCore.js：Bricks引擎库文件，H5游戏需要采用离线的方式加载 qqPlayCore
  • 加载方式为: <script src="qqPlayCore.js?_gameid=2014"></script> 。其中，gameid 需替换为对应开发的 gameId
  • 提交测试游戏包 qqPlayCore.js 可能会报 禁止上线警告，qqPlayCore.js不是最新官方版本。不影响测试开发，上线前同步我们，提供可上线的 qqPlayCore.js。
• inviteIcon.png：需改成对应游戏的图片,60*60，格式png

gameConfig.json

• enterUrl：游戏的启动链接，即H5游戏链接，需要使用离线的方式加载
• viewMode：控制横竖屏状态：1.竖屏 2.左横屏（home键在左边）3.右横屏（home键在右边）</font>

gameConfig.json 配置示例如下：

{"enterUrl":"https://www.test.com/index.html?_gameid=2011", "viewMode":1}

H5开发者概念转换

• 对于H5游戏开发者而言，不像传统h5平台，客户端层不会为每个游戏分配openkey 与appid用于启动时的校验。客户端脚本运行时可以完全信任此时环境为手Q
• 对于自建后台的QQ轻游戏开发者而言，也有一个openKey的概念，此openkey是每个用户不同的，并非每个游戏都是唯一的。通过传递此参数，客户端和服务器端都可以向QQ轻游戏后台对该用户的身份进行校验，确认其为合法的手Q用户
• 调试工具推荐使用 vConsole，可用于展示 console 日志，方便开发、调试。
• 在游戏链接后添加?_gameid=XXXX后缀，XXXX为的对应研发游戏的id，此时启动游戏会优先从本地游戏包中根目录下去读取对应文件，文件路径为从主host后开始计算，如果本地没有该资源，会走网络请求获取资源（首页 和 js 文件不会请求网络）。
  • 示例： https://www.test.com/modules/html/index.html?_gameid=2001 ，优先读取本地游戏包根目录下 modules/html/index.html

特别关注：游戏中首页和所有 js 文件必须走离线逻辑，游戏内其它资源可以使用离线方式

• 在请求中添加上 _gameid=XXXX 参数，_gameid 后填写的数据为研发游戏 id，此时访问会优先从本地游戏包中根目录下去读取对应文件，文件路径为从主host后开始计算，如果本地没有该资源，会走网络请求获取资源（首页 和 js 文件不会请求网络）。
  • 示例：通过 http://www.hudong.qq.com/pic/test.png?_gameid=2001 获取本地游戏包中根目录 pic/test.png，如果找不到这个文件，会发去网络请求获得资源。

H5游戏接口

1.启动游戏信息

• GameStatusInfo：有关游戏的全局变量，类似于H5中windows对象。
• openId：用户的唯一标识
• gameId：游戏的唯一标识

全局变量 GameStatusInfo

游戏方需要引用 qqPlayCore.js，脚本加载完成后，引擎会为开发者写入名为 GameStatusInfo 的有关游戏的全局参数，从中可获取有关用户标识符、机型等参数。

GameStatusInfo 加载流程： 游戏方需在游戏启动时实现 window.Game 的 onLoad 事件，获得游戏的基本信息。 用户打开游戏时，手 Q 会打开 gameConfig.json 中配置的游戏地址，加载游戏。 终端获取游戏信息后会注入 GameStatusInfo 变量到 JS 层，注入成功后会调用 onLoad 事件。 游戏方应在启动游戏后绘制界面等，当收到 onLoad 事件后处理与用户相关的逻辑。

具体格式如下：

示例代码：

var game = new window.Game(
    {
        // qqPlayCore 加载完成
        onLoad: function (app) { 
            BK.Script.log(0, 0, "GameStatusInfo" + JSON.stringify(GameStatusInfo));
            openid = GameStatusInfo.openId;
        },
    }
)

2.统一框架&生命周期

UI处理：

统一框架UI有横屏&竖屏模式，需要开发者如下处理

• 7.5.8及以上版本，去掉游戏自己的关闭&缩小按钮，并根据统一的关闭缩小按钮的位置对游戏UI做相应处理

生命周期：

开发者使用window.Game类可以后可以监听整体游戏生命流程。

• 程序启动，触发onLoad函数
• 点击"收起游戏"，触发onMinmize函数
• 点击"关闭"图标，触发onClose函数，开发者需处理销毁动作：上报用户成绩
• 用户按home键将手Q退至后台，触发onEnterbackground函数
• 手Q进程从后台回到前台，触发onEnterforeground函数

游戏呼起入口

在手Q中，游戏可能会在不同的入口中被呼起，开发者通过GameStatusInfo.src 参数处理用户打开游戏时体验。

大多数情况情况直接打开游戏大厅即可，在少数情况需特殊处理(聊天界面消息)</font>

GameStatusInfo.src 其他取值

工具类

打印日志

打印关键 log 到手 Q 的日志中，方便定位问题

方法：

BK.Script.log(level, errcode, info)

参数：

支持版本：

iOS 790 及以上

Android 760 及以上

示例：

BK.Script.log(0,0,"This is a log");

用户信息

用户昵称

通过用户的 openID 获取用户昵称

方法：

BK.MQQ.Account.getNick(openID,callback)

参数：

支持版本：

iOS 792 及以上

Android 760 及以上

示例：

function callback(openID,nick){
    if (openID == openID1) {
        BK.Script.log(0,0,"Nick :"+ nick);
    } else if(openID == openID2){
        ...
    }
}

BK.MQQ.Account.getNick(openID1,callback); 
BK.MQQ.Account.getNick(openID2,callback); 
BK.MQQ.Account.getNick(openID3,callback);

注意事项:

• 函数并不会为每个openId绑定一个callback函数。若多次调用getNick函数，最终只会调用最后一次绑定的callback。因此开发者需要在此函数作分发动作

用户头像

通过用户的 openID 获取用户头像

方法：

BK.MQQ.Account.getHead(openID,callback)

参数：

支持版本：

iOS 792 及以上

Android 760 及以上

示例：

function callback(openID, avatar){
    if(openID == openID1)
    {
        BK.Script.log(0,0,"Avatar :"+ avatar);
    }else if(openID == openID2){
        ...
    }
}

BK.MQQ.Account.getHead(openID1,callback);
BK.MQQ.Account.getHead(openID2,callback);
BK.MQQ.Account.getHead(openID3,callback);

注意事项

• 同getNicke函数,引擎不会为每个openId绑定一个callback函数。若多次调用getNick函数，最终只会调用最后一次绑定的callback。因此开发者需要在此函数作分发动作。

获取 openKey

获取用户开发者自建后台与QQ轻游戏后台鉴权的密钥 openKey

方法：

BK.QQ.fetchOpenKey(callback)

参数：

支持版本：

iOS 790 及以上

Android 760 及以上

示例：

BK.QQ.fetchOpenKey(function (errCode, cmd, data) {
    if (errCode == 0) {
        var openKey = data.openKey;
    }
});

分享

将游戏消息分享至手机QQ聊天窗。其他人点击该消息气泡后，会触发打开游戏。

BK.QQ.shareToArk(roomId, summary, picUrl, isSelectFriend, extendInfo, callback)

分享带自定义数据以及图片的消息气泡至聊天窗

其他用户点击此消息气泡后，带上自定义的消息启动游戏。

支持版本：

• 不带分享回调

iOS 790 及以上

Android 758 及以上

• 带分享回调

iOS 790 及以上

Android 763 及以上

参数说明：

例子：

BK.QQ.shareToArk(0, 'wording', 'http://i.hudongcdn.com/8b4e1c52e5a1b88b42ae510d4a17187c2003_20180326.png', true, 'extendInfo', function (errCode, cmd, data) {
    if (errCode == 0) {
        BK.Script.log(1, 1," ret:" + data.ret +  // 是否成功 (0:成功，1：不成功)
            " aioType:" + data.aioType + // 聊天类型 （1：个人，4：群，5：讨论组，6：热聊）
            " gameId:" + data.gameId) // 游戏 id
    }
});

shareToMQQ(title, summary, detailUrl, picUrl)

分享游戏至手Q

需要注意的是，此函数并非邀请好友进入游戏，仅是将游戏detailUrl分享出来。

其中detailUrl需游戏方自己提供，建议是该款游戏的介绍页

参数：

支持版本：

iOS 790 及以上

Android 暂不支持，计划 765 及以上支持

例子：

BK.QQ.shareToMQQ("迪斯尼过马路战绩","我获得了第1名，快来挑战我","www.xxx.com","xxx.com/xx.png");

其他

Q:其他用户如何获取分享出去后的extendInfo信息？

例如：A用户传入extendInfo为"12345",B用户点击气泡启动游戏后，从GameStatusInfo.gameParam中为"12345"

排行榜

• QQ轻游戏平台提供成绩上报与排行榜接口，用于游戏内成绩的上报与排行。开发者通过使用上报接口进行数据上报后，通过排行榜接口进行成绩的拉取、展示。H5 游戏按照自建后台的接口上报分数与拉取排行榜，说明文档

支付

• 支付按照说明文档接入，手 Q 765 版本支持获得支付结果回调，之前的版本需要游戏方兼容处理

可用接口

BK.Account.getNick
BK.Account.getHead
BK.Script.log
BK.QQ.share
BK.QQ.getRankList
BK.QQ.consumeItems
BK.QQ.getUserGameItems
BK.QQ.buyGameItems
BK.QQ.notifyCloseGame
BK.QQ.createShortCut
BK.QQ.scoreUpload
BK.QQ.uploadScoreWithoutRoom
BK.QQ.getRankListWithoutRoom
BK.QQ.qPayPurchase
BK.QQ.getGameItemList
BK.QQ.rollbackGameItems
BK.QQ.shareUpload
BK.QQ.uploadData
BK.QQ.saveGameData
BK.QQ.loadGameData
BK.QQ.reportGameResult
BK.QQ.sendB2CRedPacket
BK.Game.close
BK.Game.packUp

游戏示例包

下载地址

更新历史：

• 2018.06.12

1、添加 H5 游戏必须的 main.js 文件；

• 2018.05.29

1、增加游戏支付、排行榜、分享本地图片到 ARK 接口； 2、完善示例 demo 程序；

• 2018.05.08

1、增加游戏最大化、最小化、关闭等事件通知；

• 2018.05.07

1、支持直接取 GameStatusInfo；

2、更新 sharkToArk 接口；