成绩上报与排行榜

本章所列接口均需依赖手Q环境,测试工程无法正常返回值

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

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

接口说明

现QQ轻游戏平台有新旧两套上报、排行榜系统。

  • 旧的QQ轻游戏房间(BK.Room)有关、与新的QQ轻游戏房间无关的上报系统。

  • 旧接口不具有普遍性,必须与BK.Room的roomId等强绑定才能使用,

  • 新接口具有普遍性,且独立,无论使用使用BK.Room都可以使用。

  • 原有的与QQ轻游戏房间逻辑强绑定的QQ轻游戏后台上报不在维护更新,建议使用新接口
  • 1.成绩上报与排行榜(新)

自建后台与使用QQ轻游戏后台的游戏方案使用的上报以及拉取排行榜接口均不一致。

成绩上报与排行榜(新)

开发者可自定义成绩的支持以下特性:

  • 排序方式 (从大到小、从小到大)
  • 排行榜更新周期默认为永不清除 (支持每周一清,每月一清,永久不清,具体可以到hudong管理端配置)
  • 必须配置好周期规则后,才能使用数据上报和排行榜功能

使用自建后台/单机类型的游戏使用本接口进行成绩上报。

本接口支持两种特性

  • 支持多榜单同时上报

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

    目前最多支持16个榜单
  • 支持多榜单排序方式

    对应data.attr中的字段

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

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

    (比如酷跑类游戏的耗时,时间越短越好)
    

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

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

    总共四种排序方式。

    举例:指定a1使用从大到小的排序方式,可以设置为 a1: { type: 'rank', order: 1 }

var data = {
    userData: [
        {
            openId: GameStatusInfo.openId,
            startMs: this.start_game_time.toString(),    //必填,游戏开始时间,单位为毫秒,字符串类型
            endMs: ((new Date()).getTime()).toString(),  //必填,游戏结束时间,单位为毫秒,字符串类型
            scoreInfo: {
                score: 100, //分数,类型必须是整型数
                // 附加属性(选填),最多16个,且名称必须为a1 ~ a16,类型必须是整型数
                a1: 100,
                ...
                a16: 100
            },
        },
    ],
    // type 描述附加属性的用途
    // order 排序的方式,
    // 1: 从大到小,即每次上报的分数都会与本周期的最高得分比较,如果大于最高得分则覆盖,否则忽略
    // 2: 从小到大,即每次上报的分数都会与本周期的最低得分比较,如果低于最低得分则覆盖,否则忽略
    // 3: 累积,即每次上报的积分都会累积到本周期已上报过的积分上(本质上是从大到小的一种特例)
    // 4: 直接覆盖,每次上报的积分都会将本周期的得分覆盖,不管大小
    // 如score字段对应,上个属性.
    attr: {
        score: {   
            type: 'rank',
            order: 1,
        },
        a1: {
            type: 'rank',
            order: 2,
        }
    },
};

// gameMode: 游戏模式,如果没有模式区分,直接填 1
// 必须配置好周期规则后,才能使用数据上报和排行榜功能
BK.QQ.uploadScoreWithoutRoom(gameMode, data, function(errCode, cmd, data) {
    // 返回错误码信息
    if (errCode !== 0) {
        BK.Script.log(1,1,'上传分数失败!错误码:' + errCode);
    }
});

错误码

错误码

拉取排行榜

使用排行榜数据的拉取,展示的样式交由开发者自定设计,QQ轻游戏平台不做要求。

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

// 当前不支持一次同时拉取多个排行榜,需要拉取多次,而且必须等上一个拉取回来后才能拉取另外一个排行榜
// 先拉 score 排行榜
var attr = "score";//使用哪一种上报数据做排行,可传入score,a1,a2等
var order = 1;     //排序的方法:[ 1: 从大到小(单局),2: 从小到大(单局),3: 由大到小(累积)]
var rankType = 0; //要查询的排行榜类型,0: 好友排行榜
// 必须配置好周期规则后,才能使用数据上报和排行榜功能
BK.QQ.getRankListWithoutRoom(attr, order, rankType, function(errCode, cmd, data) {
    BK.Script.log(1,1,"getRankListWithoutRoom callback  cmd" + cmd + " errCode:" + errCode + "  data:" + JSON.stringify(data));
    // 返回错误码信息
    if (errCode !== 0) {
        BK.Script.log(1,1,'获取排行榜数据失败!错误码:' + errCode);
        return;
    }
    // 解析数据
    if (data) {
        for(var i=0; i < data.data.ranking_list.length; ++i) {
            var rd = data.data.ranking_list[i];
            // rd 的字段如下:
            //var rd = {
            //    url: '',            // 头像的 url
            //    nick: '',           // 昵称
            //    score: 1,           // 分数
            //    selfFlag: false,    // 是否是自己
            //};
        }
    }

    // 再拉 a1 的排行榜
    BK.QQ.getRankListWithoutRoom('a1', 1, rankType, function(errCode, cmd, data) {
        BK.Script.log(1,1,"getRankListWithoutRoom callback  cmd" + cmd + " errCode:" + errCode + "  data:" + JSON.stringify(data));

        // 返回错误码信息
        if (errCode !== 0) {
            BK.Script.log(1,1,'获取排行榜数据失败!错误码:' + errCode);

            return;
        }

        // 解析数据
        if (data) {
            for(var i=0; i < data.data.ranking_list.length; ++i) {
                var rd = data.data.ranking_list[i];
                /// rd 的字段如下:
                //var rd = {
                //    url: '',            // 头像的 url
                //    nick: '',           // 昵称
                //    a1: 1,              // 分数
                //    selfFlag: false,    // 是否是自己
                //};
            }
        }
    });
});

例子: 下面为引力球使用本接口进行排行榜展示的例子

错误码

错误码

1.1 QQ轻游戏后台成绩上报

使用QQ轻游戏后台,指使用BK.Room接口进行房间的创建、加入、退出房间等操作。上报的成绩与房间id(roomId)强相关。

  1. 游戏正常结束

  2. 玩家中途退出

两种情况均需要将成绩上报至QQ轻游戏后台。需要注意的是无论正常退出还是中途退出,都需要将当局游戏内所有的人的成绩都进行上报。

例ABCD,四人参加游戏,A中途退出,A需将ABCD四人成绩一律上传。如是单人游戏,也需要将单人成绩上传。

正常退出:正常上报所有人成绩

中途退出:将所有人成绩填0上报

此处需要特别注意的是,游戏使用QQ轻游戏后台与使用自建后台,引擎侧使用的上报接口不一致

为防止游戏数据造假,开发进行游戏成绩上报时,需上报游戏内所有人的游戏成绩。

请求:

//具体的得分数据数组。数组中每个元素为一个用户的得分
var data = [
    {
        //第一个用户的得分
        "openId":"4558665DATRGFGFS455",
        "scoreInfo":{
            "score":4455,   //用户得分,<font color=#ff0000>必须上报,类型必须是整型数</font>
            //附加参数,上报和使用都由第三方决定,最多支持5个附加参数,可选,<font color=#ff0000>类型必须是整型数</font>
            "a1":1,
            "a2":2,
        },
        "actInfo":{     //活动数据由第三方配置定义,key值统一用p1,p2,...此数据只用于活动,不会保存到用户的房间数据里, 现支持最多支持16个
            "p1":1,    //参数0
           "p2":5,    //参数1
        },
    },
    {
        //第二个用户的得分
        "openId":"SDJIIWJIEQWJ232389DA",
        "scoreInfo":{
            "score":4455,   //用户得分,<font color=#ff0000>必须上报,类型必须是整型数</font>
            //附加参数,上报和使用都由第三方决定,最多支持5个附加参数,可选,<font color=#ff0000>类型必须是整型数</font>
            "a1":1,
            "a2":2,
        },
        "actInfo":{     
            //活动数据由第三方配置定义,key值统一用p1,p2,...此数据只用于活动,不会保存到用户的房间数据里, 现支持最多支持16个
            "p1":1,    //参数0
            "p2":5,    //参数1
         },

           //第n个用户的得分 ...
    }]

BK.QQ.scoreUpload(data,function(err,cmd,data){
//errCode ,0表示成功其他为异常
//data = {}
});

1.2 QQ轻游戏后台拉取排行榜

BK.QQ.getRankList(function (errCode, cmd, data) {

    BK.Script.log(1, 1, "getRankList demo callback  cmd" + cmd + " errCode:" + errCode + "  data:" + JSON.stringify(data));
    if(data)
    {
      var rankList = data.data.rankList;
      for(var i=0;i<rankList.length;i++){
             var rankNode = rankList[i];
          BK.Script.log(1, 1, "rankList i:" + i + 
          " nick:" + rankNode.nick +  //昵称
          "  head:" + rankNode.head + //头像url
          " accPoint:"+rankNode.busData.accPoint) //积分
      }
    }
});

1.3.获取房间内的用户成绩数据

请求:

 var data = {
        "from" : "xxxxx",       //描述请求来源或场景 h5.xxx.yyy/ios.xxx.yyy/android.xxx.yyy 用于后台统计
        "gameId":1,           //游戏ID
       "version":"2.0",      //游戏版本
        "roomId": 123,      //房间ID
    };

    BK.QQ.getRoomUserScoreInfo(data,function(errCode,cmd,data){
         if(data.data){
            var userRank = data.data.userRank;
            for (var idx = 0; idx < userRank.length; idx++) {
                var singleUserRank = userRank[idx];
                var openId = singleUserRank.openId;
                var score  = singleUserRank.score;
                var rank   = singleUserRank.rank;
                //可选
                // var a1 = singleUserRank.a1;
                // var a2 = singleUserRank.a2;
                // ...
                //
            }
         }
    });

回包

errCode ,0表示成功其他为异常
data =
{
    "data": {
        "userRank": [
            {
                "openId":"100001", 
                "score":560,
                "rank":1,
                "a1":123,
                 ...
                "a5":123,
            }
             ...
        ]       
    }
}

1.3.查询某个用户在一款游戏中的积分

请求:

var data = {
        "from" : "xxxxx",     //描述###请求来源或场景 h5.xxx.yyy/ios.xxx.yyy/android.xxx.yyy 用于后台统计
        "gameId":1,           //游戏ID
       "toOpenId":"123",     //需要查询的openId(如果是查自己的数据,则不用传, 注意此参数仅在游戏当天有用)
       "version":"2.0",      //游戏版本
        "cycleNum":0           //周期序号 【0-本周期, 1-上一周期, 2-上两周期】 目前后台会保存三个周期的游戏数据,例如若一个周期为1星期,则0代表本星期的数据。
    }; 
BK.QQ.getUserGameinfo(data,function(err,cmd,data){
    //回包数据
});

回包数据

errCode ,0表示成功其他为异常
data = {
"data": {
         "toOpenId":"12345556645DAGADFGAD"  //###请求有传入toOpenId则有返回,没传入则无此字段返回
        "myPoint":800                 //用户积分
    }
}

results matching ""

    No results matching ""