登录与鉴权
玩一玩平台登录是依赖于QQ服务号
,类似微信公众号的授权登录,只是玩一玩平台在后台自动获取用户对应的openId
。
下面是详细的流程
游戏加载流程
游戏加载主要分为两个阶段,准备阶段 是由手Q进行,开发者无需理会,执行阶段为开发者可控制
的阶段。
引擎启动后,会从手Q和后台中获取当前游戏ID(gameId),用户ID(openId)等信息,并将这些参数写入到JS引擎的全局变量GameStatusInfo
中(后面会详细介绍),并执行游戏对应的main.js
文件。开发可从该参数中获取相关的游戏变量。
H5开发者概念转换
- 对于H5游戏开发者而言,不像传统h5平台,客户端层不会为每个游戏分配
openkey
与appid
用于启动时的校验。客户端脚本运行时可以完全信任此时环境为手Q - 对于自建后台的玩一玩开发者而言,也有一个
openkey
的概念,此openkey
是每个用户不同的,并非每个游戏都是唯一的。通过传递此参数,客户端和服务器端都可以向玩一玩后台对该用户的身份进行校验,确认其为合法的手Q用户。
重要变量说明
GameStatusInfo
有关游戏的全局变量,类似于H5中windows对象。
openId
用户的唯一标识
gameId
游戏的唯一标识
openKey
用户自建服务器鉴权密钥。传输数据时带给后台,通过校验openKey,确保接口调用方确定为手Q用户。
全局变量GameStatusInfo
游戏启动后,引擎会为开发者写入名为GameStatusInfo的有关游戏的全局参数,从中可获取有关用户标识符、机型、等参数
变量 | 类型 | 名称 | 备注 |
---|---|---|---|
gameId | number | 游戏id | 游戏的唯一标识 |
isMaster | number | 是否是房主 | 1为房主,0为参加者 |
roomId | number | 房间号 | 房主时为0,参加者时为具体房间号 |
gameVersion | string | 游戏版本号 | 与游戏包强绑定的版本号,手Q测依赖此进行版本更新 |
platform | string | 平台类型 | 取值为 “ios”或”android” |
openId | string | 当前用户的标识 | 用户的唯一标识 |
QQVer | string | 手机qq版本 | 形如”7.1.0.0” |
isFirstInstall | number | 是否首次安装 | 1为首次安装,0非首次安装 |
isFirstPlay | number | 是否第一次打开 | 1为第一次玩游戏 0非第一次。使用BK.Room的成员函数startGame后,置为0 |
networkType | number | 网络类型 | 游戏启动时的网络类型。 1 电信 ,2 联通 ,3 移动 0: wifi或未知 |
src | number | 游戏启动入口 | 100:实时PK,200:聊天窗游戏消息 |
spriteDesignHeight | number | 厘米秀小人spine动画的设计高度 | 具体查看厘米秀骨骼动画章节 |
skltPath | Object | 厘米秀小人spine骨骼 | 具体查看厘米秀骨骼动画章节 |
dressPath | Array | 厘米秀衣服路径 | 具体查看厘米秀骨骼动画章节 |
sex | number | 性别 | 1 男 2 女 |
osVersion | string | 操作系统版本 | 例如”11.3” 表示iOS 11.3 |
gameParam | string | 扩展参数 | 当使用其他玩家使用BK.QQ.shareToArk分享至手Q,并且填充扩展字段时,当前玩家就能从此处获取该数据。 详情 |
获取openId的示例代码如下:
var openId = GameStatusInfo.openId; //获取当前用户的唯一标识
获取openKey
GameStatusInfo中无openKey参数,使用如下例子可获取。
BK.Script.loadlib("GameRes://qqPlayCore.js") //预加载bricks js层接口
BK.QQ.fetchOpenKey(function (errCode, cmd, data) {
if (errCode == 0) {
var openKey = data.openKey;
}
});
框架与生命周期
bricks引擎代码包含原生以及JS层部分,旧版本开发者引用protocol.js来进行引擎JS层接口的引用。新的开发者推荐使用qqPlayCore.js文件进行引用。单独引用protocol.js的方法也可以正常使用。
protocol.js为qqPlayCore.js的子集,除此外qqPlayCore.js还包含webscoket.js、Game.js等文件。
推荐使用 BK.Script.loadlib('GameRes://qqPlayCore.js');
游戏配置
游戏包中使用gameConfig.json进行游戏整体配置
参数 | 说明 | 备注 |
---|---|---|
enterUrl | H5游戏链接地址 | H5游戏必填。非H5游戏不填 |
viewMode | 控制横竖屏状态 | 1.竖屏 2.左横屏(home键在左边)3.右横屏(home键在右边) |
简单示例
{
"enterUrl":"", //H5游戏链接地址,H5游戏必填。非H5游戏不填
"viewMode":1 //控制横竖屏状态:1.竖屏 2.左横屏(home键在左边)3.右横屏(home键在右边)
}
UI处理与生命周期
7.5.8及以上版本,去掉游戏自己的关闭&缩小按钮,并根据统一的关闭缩小按钮的位置对游戏UI做相应处理
开发者使用BK.Game类可以后可以监听整体游戏生命流程。
- 程序启动,触发onLoad函数
- 点击”收起游戏”,触发onMinmize函数
- 点击”关闭”图标,触发onClose函数,开发者需处理销毁动作:上报用户成绩 如果不上报成绩面板消息状态将不会改变
- 用户按home键将手Q退至后台,触发onEnterbackground函数
- 手Q进程从后台回到前台,触发onEnterforeground函数
游戏入口场景值
在手Q中,游戏可能会在不同的入口中被呼起,开发者通过GameStatusInfo.src 参数处理用户打开游戏时体验。
大多数情况情况直接打开游戏大厅即可,在少数情况需特殊处理(聊天界面消息)
实例代码如下
var SRC_AIO_BUBBLE_NORMAL = 200, //聊天窗游戏消息
var SRC_AIO_BUBBLE_SHARE = 201, //分享消息
var src = GameStatusInfo.src;
//聊天窗游戏消息
if (src == 200 /* SRC_AIO_BUBBLE_NORMAL */) {
//
var room = new BK.Room();
var roomId = GameStatusInfo.roomId;
var gameId = GameStatusInfo.gameId;
var openId = GameStatusInfo.openId;
//从聊天入口进入游戏,优先加入房间,如加入房间失败,则跳转至游戏大厅
room.queryAndJoinRoom(gameId, roomId, openId, function (statusCode, room) {
if (statusCode == 0) {
//正常加入房间
}
else {
//跳转至游戏大厅
}
};
}
//聊天面板中的大厅与 动态-玩一玩入口的 可以统一进入游戏主页
else {
//加载游戏主页
}
不同的场景值列表如下GameStatusInfo.src
场景值 | 场景描述 | 期望体验 |
---|---|---|
100 | AIO面板点击开始游戏 | 进入游戏大厅 |
108 | AIO面板点击大面板小房子按钮 | 进入游戏大厅 |
110 | AIO消息流文字识别 | 进入游戏大厅 |
202 | 热聊folder中点击进入游戏按钮 | 进入游戏大厅 |
207 | 旧版玩一玩WEB页面启动游戏 | 进入游戏大厅 |
208 | 新版玩一玩WEB页面启动游戏 | 进入游戏大厅 |
209 | 厘米城WEB页面启动游戏 | 进入游戏大厅 |
220 | 扫描二维码打开游戏 | 进入游戏大厅 |
200 | 点击AIO游戏邀请消息 | 判断roomid若可加入则直接加入游戏不可加入相应提示后打开大厅” |
204 | 在微信点击游戏邀请后打开手Q后启动游戏 | 同200 |
203 | 同200 | 将在手Q7.6.0后废弃 |
201 | 点击AIO游戏分享消息 | 根据拓展数据做相应处理 |
如有疑问欢迎留言讨论