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 成绩数据上报

/**
 * 成绩上报
 * @param {*} level 
 * @param {*} callback 
 */
function uploadScore(level, callback) {
    if (cc.sys.platform != cc.sys.QQ_PLAY) {
        if (callback) {
            callback(-1, "此接口只支持QQ玩一玩平台");
        }
        return;
    }

    var data = {
        userData: [{
            openId: GameStatusInfo.openId,
            startMs: Global.startGameTime,
            endMs: ((new Date()).getTime()).toString(),
            scoreInfo: {
                score: level,//分数，类型必须是整型数
                // 多榜单附加属性（选填），最多16个，且名称必须为a1 ~ a16，类型必须是整型数
                //a1: 100,
                //...
                //a16: 100
            },
        }, ],
        // type 描述附加属性的用途
        // order 排序的方式，
        // 1: 从大到小，即每次上报的分数都会与本周期的最高得分比较，如果大于最高得分则覆盖，否则忽略
        // 2: 从小到大，即每次上报的分数都会与本周期的最低得分比较，如果低于最低得分则覆盖，否则忽略
        // 3: 累积，即每次上报的积分都会累积到本周期已上报过的积分上（本质上是从大到小的一种特例）
        // 4: 直接覆盖，每次上报的积分都会将本周期的得分覆盖，不管大小
        // 如score字段对应，上个属性.
        attr: {
            score: {
                type: 'rank',
                order: 1,
            }
            //如果要支持多榜单在此添加 a1~a16
            //a1: {
            //    type: 'rank',
            //    order: 2,
            //}
        },
    };
    // gameMode: 游戏模式 1:普通，2:挑战，如果没有模式区分，直接填1 
    // 必须配置好周期规则后，才能使用数据上报和排行榜功能
    BK.QQ.uploadScoreWithoutRoom(1, data, function (errCode, cmd, data) {
        log("uploadScoreWithoutRoom callback  cmd" + cmd + " errCode:" + errCode + "  data:" + JSON.stringify(data));
        if (callback) {
            callback(errCode, data);
        }
    });
}

3.4 何时上报玩家成绩

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

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

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

 _gameCloseListener() {

        //上报操作
        let score = Utils.getRandomInt(0, 100);
        BKTools.log('关闭游戏:' + score);
        BKTools.uploadScore(score, function (errorCode) {
            if (errorCode == 0) {
                BKTools.log("数据上报成功......");
            } else {
                BKTools.log("数据上报失败......");
            }
        });
    },

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

3.5 拉取排行榜数据

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

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

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

/**
 * 拉取排行榜数据
 * @param {*} callback 
 */
function getRankList(callback,attr,order) {
    if (cc.sys.platform != cc.sys.QQ_PLAY) {
        if (callback) {
            callback(-1, "此接口只支持QQ玩一玩平台");
        }
        return;
    }
    if(!attr){
       attr = "score";//使用哪一种上报数据做排行，可传入score，a1，a2等
    }
    if(!order){
       order = 1;//排序的方法：[ 1: 从大到小(单局)，2: 从小到大(单局)，3: 由大到小(累积)]
    }
    let rankType = 0;//要查询的排行榜类型，0: 好友排行榜 目前是固定值
    BK.QQ.getRankListWithoutRoom(attr, order, rankType, function (errCode, cmd, data) {
        log("getRankListWithoutRoom callback  cmd" + cmd + " errCode:" + errCode);
        if (errCode != 0) {
            callback(errCode);
            return;
        }
        if (data) {
            let rankList = data.data.ranking_list;
            log("data not null " + rankList.length);
            log(JSON.stringify(data));
            // rankList.forEach(element => {
            //   log("....华丽的分割线....");
            //   log("score:" + element.score);
            //   log("nick:" + element.nick);
            //   log("....华丽的分割线....");
            // });
            if (callback) {
                callback(errCode, rankList);
            }
        }
    });
}

3.6 拉取排行榜使用示例

BKTools.getRankList(function (errorCode, rankList) {
    if (errorCode == 0) {
        if (rankList && rankList.length > 0) {
            rankList.forEach(element => {
                BKTools.log("item:" + JSON.stringify(element));
            });
        } else {
            BKTools.log("....排行榜为空....");
        }
    } else {
        BKTools.log("....获取排行榜失败....");
    }
}.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玩一玩示例

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

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

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

完

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