QQ玩一玩好友排行榜与世界排行榜

QQ玩一玩好友排行榜与世界排行榜

1、开发环境

CocosCreator V2.0.5
手Q版本 V7.9.0.3820（目前市场中最新版本）
qqPlayCore.js buildTime:'Fri Nov 09 2018 13:20:45 GMT+0800 (GMT+08:00)'上出现，此版本的qqPlayCore.js也是最新能正常使用的版本。

2、常见问题

如何实现好友排行榜
如何实现世界排行榜
如何上报玩家成绩
如何获取用户图像
在CocosCreator中如何加载用户的图像

3、实现好友排行榜

QQ轻游戏平台提供成绩上报与排行榜接口，用于游戏内成绩的上报与排行。

开发者通过使用上报接口进行数据上报后，通过排行榜接口进行成绩的拉取与展示。

3.1 错误码列表

排行榜/云端存储错误码

3.2 支持两种特性

支持多榜单同时上报

scoreInfo中score字段为默认榜单，a1,a2,……,a16为开发者可使用的 榜单key字段，不允许使用其他key

目前最多支持16个榜单，scoreInfo中的key字段值类型必须是整型数
支持多榜单排序方式

对应data.attr中的字段

1: 从大到小，即每次上报的分数都会与本周期的最高得分比较，如果大于最高得分则覆盖，否则忽略

2: 从小到大，即每次上报的分数都会与本周期的最低得分比较，如果低于最低得分则覆盖，否则忽略

比如酷跑类游戏的耗时，时间越短越好

3: 累积，即每次上报的积分都会累积到本周期已上报过的积分上（本质上是从大到小的一种特例）

4: 直接覆盖，每次上报的积分都会将本周期的得分覆盖，不管大小

3.3 成绩数据上报

1/**
2 * 成绩上报
3 * @param {*} level 
4 * @param {*} callback 
5 */
6function uploadScore(level, callback) {
7    if (cc.sys.platform != cc.sys.QQ_PLAY) {
8        if (callback) {
9            callback(-1, "此接口只支持QQ玩一玩平台");
10        }
11        return;
12    }
13
14    var data = {
15        userData: [{
16            openId: GameStatusInfo.openId,
17            startMs: Global.startGameTime,
18            endMs: ((new Date()).getTime()).toString(),
19            scoreInfo: {
20                score: level,//分数，类型必须是整型数
21                // 多榜单附加属性（选填），最多16个，且名称必须为a1 ~ a16，类型必须是整型数
22                //a1: 100,
23                //...
24                //a16: 100
25            },
26        }, ],
27        // type 描述附加属性的用途
28        // order 排序的方式，
29        // 1: 从大到小，即每次上报的分数都会与本周期的最高得分比较，如果大于最高得分则覆盖，否则忽略
30        // 2: 从小到大，即每次上报的分数都会与本周期的最低得分比较，如果低于最低得分则覆盖，否则忽略
31        // 3: 累积，即每次上报的积分都会累积到本周期已上报过的积分上（本质上是从大到小的一种特例）
32        // 4: 直接覆盖，每次上报的积分都会将本周期的得分覆盖，不管大小
33        // 如score字段对应，上个属性.
34        attr: {
35            score: {
36                type: 'rank',
37                order: 1,
38            }
39            //如果要支持多榜单在此添加 a1~a16
40            //a1: {
41            //    type: 'rank',
42            //    order: 2,
43        	//}
44        },
45    };
46    // gameMode: 游戏模式 1:普通，2:挑战，如果没有模式区分，直接填1 
47	// 必须配置好周期规则后，才能使用数据上报和排行榜功能
48    BK.QQ.uploadScoreWithoutRoom(1, data, function (errCode, cmd, data) {
49        log("uploadScoreWithoutRoom callback  cmd" + cmd + " errCode:" + errCode + "  data:" + JSON.stringify(data));
50        if (callback) {
51            callback(errCode, data);
52        }
53    });
54}

3.4 何时上报玩家成绩

建议在以下两个时间点上报玩家成绩

当局游戏结束时
退出游戏时

当局游戏结束时需要开发者主动调用上报操作，退出游戏时上报需要监听QQ玩一玩生命周期来实现，参考示例如下。

1 _gameCloseListener() {
2
3        //上报操作
4        let score = Utils.getRandomInt(0, 100);
5        BKTools.log('关闭游戏:' + score);
6        BKTools.uploadScore(score, function (errorCode) {
7            if (errorCode == 0) {
8                BKTools.log("数据上报成功......");
9            } else {
10                BKTools.log("数据上报失败......");
11            }
12        });
13    },

QQ玩一玩生命周期监听具体实现逻辑参考之前写的博客 QQ玩一玩广告与音效使用总结

3.5 拉取排行榜数据

排行榜数据提供昵称、头像url、积分三种数据。此接口不提供openId与昵称、头像的对应关系

图像URL参考：http://thirdqq.qlogo.cn/g?b=sdk&k=OiaMLzXmbEwq5trqsR6zd1A&s=100&t=1483310911

如果要获取多榜单数据可以多次调用此接口，只是 attr、order 这两个参数需要根据实际排行榜需求设置不同的值，rankType 目前为固定值0（好友排行榜）

1/**
2 * 拉取排行榜数据
3 * @param {*} callback 
4 */
5function getRankList(callback,attr,order) {
6    if (cc.sys.platform != cc.sys.QQ_PLAY) {
7        if (callback) {
8            callback(-1, "此接口只支持QQ玩一玩平台");
9        }
10        return;
11    }
12    if(!attr){
13       attr = "score";//使用哪一种上报数据做排行，可传入score，a1，a2等
14    }
15    if(!order){
16       order = 1;//排序的方法：[ 1: 从大到小(单局)，2: 从小到大(单局)，3: 由大到小(累积)]
17    }
18    let rankType = 0;//要查询的排行榜类型，0: 好友排行榜 目前是固定值
19    BK.QQ.getRankListWithoutRoom(attr, order, rankType, function (errCode, cmd, data) {
20        log("getRankListWithoutRoom callback  cmd" + cmd + " errCode:" + errCode);
21        if (errCode != 0) {
22            callback(errCode);
23            return;
24        }
25        if (data) {
26            let rankList = data.data.ranking_list;
27            log("data not null " + rankList.length);
28            log(JSON.stringify(data));
29            // rankList.forEach(element => {
30            //   log("....华丽的分割线....");
31            //   log("score:" + element.score);
32            //   log("nick:" + element.nick);
33            //   log("....华丽的分割线....");
34            // });
35            if (callback) {
36                callback(errCode, rankList);
37            }
38        }
39    });
40}

3.6 拉取排行榜使用示例

1BKTools.getRankList(function (errorCode, rankList) {
2    if (errorCode == 0) {
3        if (rankList && rankList.length > 0) {
4            rankList.forEach(element => {
5                BKTools.log("item:" + JSON.stringify(element));
6            });
7        } else {
8            BKTools.log("....排行榜为空....");
9        }
10    } else {
11        BKTools.log("....获取排行榜失败....");
12    }
13}.bind(this));

3.7 好友排行榜图像显示

Utils.loadImgByUrl(this.image, "http://thirdqq.qlogo.cn/g?b=sdk&k=OiaMLzXmbEwq5trqsR6zd1A&s=100&t=1483310911");

具体实现可以参考之前写的博客 QQ 玩一玩获取用户图像昵称以及CocosCreator动态加载网络图片

4、实现世界排行榜

实现世界排行榜就需要后台的支持了，简单的介绍一下实现逻辑

玩家打开游戏时通过全局参数获取到openId
通过openId获取用户的昵称
将openId以及用户信息关联上报后台
游戏结束时调用后台接口上报成绩
获取世界排行榜就可以通过后台提供的接口来查询到所有玩家的openId、昵称等(全局参数能获取到的数据都能作为排行榜排序的依据)
获取图像可以使用 BK.MQQ.Account.getHeadEx(openID,callback) 此接口会获取头像并写到本地目录

全局参考获取可以参考 QQ玩一玩广告与音效使用总结

获取用户图像并显示可以参考 QQ 玩一玩获取用户图像昵称以及CocosCreator动态加载网络图片

5、相关参考资料

CocosCreator开发小游戏示例:Brickengine_Guide

QQPlay为旧版本QQ玩一玩示例
QQPlay_New为新版本QQ玩一玩示例

官方文档关系链与用户信息

官方文档成绩上报与排行榜

官方文档排行榜/云端存储错误码

完

到这里就介绍完了，个人能力有限如有错误欢迎指正，如有遗漏欢迎补充。如有疑问欢迎留言一起交流讨论。