# 排行榜

# 概述

# 功能介绍

在关键的游戏场景，设置写入用户的排行榜数据（游戏成绩信息），该数据会上传到平台服务端，通过接口可以获取用户的排行信息，目前只提供获取全局排行的接口，暂不支持获取好友排行信息

# 排行榜设置

字段	说明
游戏app id	开发者创建游戏审核通过后获取的appid，在开发者后台查询
榜单名称	榜单的描述，系统不实际使用
榜单唯一标识	大小写英文字符组合，无空格，16个字符以内，游戏内唯一，同一游戏不同国家可共用一个标识，系统会自动隔离不同国家的榜单
周期	榜单更新周期： day：日榜（当地时间自然日）， week：周榜（当地时间从周一到周日自然周）， month：月榜（当地时间从1号到月底）， activity：活动榜（开始年月日时分秒～截止年月日时分秒）：指定起始时间的活动榜单，时间均为当地时间 forever:永久有效注：一个榜单只能选择一种周期，一个游戏可以有多个榜单
排序方式	榜单排序方式: asc：按照从小到大正序排（比如需要对达成某一个目标的耗时排序，耗时越短排名越靠前）， desc：按照从大到小倒序排（比如需要对积分进行排序，积分越大排名越靠前）

以上排行榜设置信息通过联系平台运营提供

# 注意事项

在上传用户数据之前，用户必须完成登录流程，并通过授权接口ks.authorize 向用户发起授权请求，获取'scope.userInfo'权限。在测试期，开发者需要联系运营提供测试的用户ID和排行榜设置。

# 上传用户数据接口

# 语法

ks.setRankData(Object object);

# 参数说明

属性	类型	必填	说明
rankKey	string	是	排行榜设置的唯一标识，用于区分多个排行榜（需要事先在后台创建排行榜，如无创建入口，联系运营）
score	int	是	分数
group	string	否	排行榜分组，长度不超过64字节，只能使用英文字母大小写和数字组合。如果设置了分组，则用户只在组内排行，分组数据与总榜数据隔离；如果不设置，则默认返回总榜前100名数据。（例：可按照城市分组，将分数设置为分组数据）
success	function	否	接口调用成功回调函数
fail	function	否	接口调用失败回调函数
complete	function	否	接口调用结束回调函数（调用成功、失败都会执行）

# 示例代码

ks.setRankData({
    rankKey: "xxx", //排行榜标识
    score: 666, //该用户得了666分
    success() {
        console.log(`setRankData success`);
    },
    fail(res) {
        console.log(`setRankData fail res: ${res.errMsg}`);
    },
    complete() {
        console.log(`setRankData complete`);
    }
});

# 查询排行榜接口

# 功能介绍

查询全局排行榜，默认返回列表前100名

# 语法

ks.getRankData(Object object);

# 参数

属性	类型	必填	说明
rankKey	string	是	排行榜唯一标识，用于区分多个排行榜
group	string	否	排行榜分组，根据分组信息获取组内排行榜数据
pageNum	int	否	第几页，从1开始(可不填，无值时默认返回榜单前100名)
pageSize	int	否	每页大小，最大值50(可不填，无值时默认返回榜单前100名)
success	function	否	接口调用成功回调函数
fail	function	否	接口调用失败回调函数
complete	function	否	接口调用结束回调函数（调用成功、失败都会执行）

# 示例代码

ks.getRankData({
    rankKey: "xxx",
    success: (res) => {
        console.log("getRankData success")
    },
    fail: (res) => {
        console.error(`getRankData fail res: ${res.errMsg}`)
    },
    complete: () => {
        console.log(`getRankData complete`);
    }
})

# 查询排行榜成功返回数据示例

{
    "ranklist": [{
        "openId": "xxxxx",
        "nickName": "zhangsan",
        "headImage": "http://xxxxavatarxxxxxxx.jpg",
        "rank": 1, 
        "score": 666
    }, {
        "openId": "xxxxxx",
        "nickName": "lisi",
        "headImage": "http://xxxxavatarxxxxxxx.jpg",
        "rank": 2,
        "score": 666
    }],
    "userInfo": { // 当前用户排名信息
        "openId": "xxxxx",
        "nickName": "zhangsan",
        "headImage": "http://xxxxavatarxxxxxxx.jpg",
        "rank": 1, // 若没上榜，则不会返回此字段
        "score": 666 // 若没上榜，则不会返回此字段
    }
}

← 钻石分享 →