4.1.数据上报与排行榜
本章所列接口均需依赖手Q环境，测试工程无法正常返回值
QQ轻游戏平台提供成绩上报与排行榜接口，用于游戏内成绩的上报与排行。
开发者通过使用上报接口进行数据上报后，通过排行榜接口进行成绩的拉取，与展示。
接口说明
现QQ轻游戏平台有新旧两套上报、排行榜系统。
旧的QQ轻游戏房间(BK.Room)有关、与新的QQ轻游戏房间无关的上报系统。
旧接口不具有普遍性，必须与BK.Room的roomId等强绑定才能使用，
新接口具有普遍性，且独立，无论使用使用BK.Room都可以使用。
- 原有的与QQ轻游戏房间逻辑强绑定的QQ轻游戏后台上报不在维护更新，建议使用新接口
自建后台与使用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)强相关。
游戏正常结束
玩家中途退出
两种情况均需要将成绩上报至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 //用户积分
}
}