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玩一玩示例

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

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

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

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

推荐阅读更多精彩内容