成绩上报与查询

优质

小牛编辑

139浏览

2023-12-01

无论是自建后台还是QQ轻游戏后台的开发者，都需要进行成绩的上报。上报的时机有两个

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

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

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

正常退出：正常上报所有人成绩
中途退出：将所有人成绩填 0 上报

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

QQ 轻游戏后台成绩上报

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

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

此处需要注意版本号的设置

版本号格式为 x.y，x、y 为整数，可以是 1 位或多位整数，点前面的x表示游戏资源版本，点后面的y用以表示排行积分是否重新计算，若 y 改变，则排行积分重新计算。

请求：

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

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

请求:

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,
}
...
]
}
}

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 //用户积分
}
}

自建后台成绩上报

使用自建后台的游戏使用本接口进行成绩上报。

注意下列例子中data.attr中的字段后台会将后台按照周期存储数据，每个周期只存储一个top分数。该种数据可以是 1: 从大到小 2: 从小到大 3: 累积 4: 直接覆盖四种排序方式

var data = {
userData: [
{
openId: GameStatusInfo.openId,
startMs: this.start_game_time.toString(), // 必填。游戏开始时间。单位为毫秒
endMs: ((new Date()).getTime()).toString(), // 必填。游戏结束时间。单位为毫秒
scoreInfo: {
score: 100, // 分数
// 附加属性，最多 8 个，从 a1 ~ a8，不是必填的
a1: 100,
...
a8: 100,
},
},
],
// type 描述附加属性的用途
// order 排序的方式，1: 从大到小, 2: 从小到大, 3: 累积
// 如score字段对应，上个属性.
attr: {
score: {
type: 'rank',
order: 1,
},
a1: {
type: 'rank',
order: 1,
}
},
};
// gameMode: 游戏模式，如果没有模式区分，直接填 1
BK.QQ.uploadScoreWithoutRoom(gameMode, data, function(errCode, cmd, data) {
// 返回错误码信息
if (errCode !== 0) {
BK.Script.log(1,1,'上传分数失败!错误码：' + errCode);
}
});

自建后台拉取排行榜

当前不支持一次同时拉取多个排行榜，需要拉取多次，而且必须等上一个拉取回来后才能拉取另外一个排行榜

// 先拉 score 排行榜
BK.QQ.getRankListWithoutRoom('score', 1, 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, 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, // 是否是自己
//};
}
}
});
});