成绩上报与排行榜

成绩上报与排行榜

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

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

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

接口说明

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

旧的QQ轻游戏房间(BK.Room)有关、与新的QQ轻游戏房间无关的上报系统。
旧接口不具有普遍性，必须与BK.Room的roomId等强绑定才能使用，
新接口具有普遍性，且独立，无论使用使用BK.Room都可以使用。
原有的与QQ轻游戏房间逻辑强绑定的QQ轻游戏后台上报不在维护更新，建议使用新接口
1.成绩上报与排行榜（新）
- 1.1成绩上报
- 1.2拉取排行榜
  自建后台与使用QQ轻游戏后台的游戏方案使用的上报以及拉取排行榜接口均不一致。开发者需特别注意
1.QQ轻游戏后台（旧）

成绩上报与排行榜（新）

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

排序方式（从大到小、从小到大）
排行榜更新周期默认为一周（即：每周日0:00进行排行榜清空操作。并支持每月一清，永久不清，具体可以到hudong管理端配置，
必须配置好周期规则后，才能使用数据上报和排行榜功能
使用自建后台的游戏使用本接口进行成绩上报。

本接口支持两种特性

支持多榜单同时上报

对应例子代码中scoreInfo中score字段为默认榜单，a1,a2,aN等字段为开发者可自定义榜单
支持多榜单排序方式

对应data.attr中的字段 1: 从大到小 2: 从小到大 3: 累积 4: 直接覆盖四种排序方式。例如执行 a1排行榜为从小到大的排序方式，可以设置为 a1: { type: 'rank', order: 2, }

var data = {
    userData: [
        {
            openId: GameStatusInfo.openId,
            startMs: this.start_game_time.toString(),    //必填。 游戏开始时间。单位为毫秒，<font color=#ff0000>类型必须是字符串</font>
            endMs: ((new Date()).getTime()).toString(),  //必填。 游戏结束时间。单位为毫秒，<font color=#ff0000>类型必须是字符串</font>
            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: 好友排行榜，1: 群排行榜，2: 讨论组排行榜，3: C2C二人转 (手Q 7.6.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)强相关。

游戏正常结束
玩家中途退出

两种情况均需要将成绩上报至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                 //用户积分
    }
}

原文: https://hudong.qq.com/docs/engine/userInfo/rank.html

4.1.数据上报与排行榜