SDK对接文档

主题

WARNING

模块名：GameHelper.CustomRank

1. 描述 ​

通用的排行榜功能，不依赖于渠道。支持排行榜上报分数以及查询排行榜功能

2. 接入说明 ​

该模块为选接模块

提供一个上报玩家分数接口和一个查询排行榜结果的接口。

  1. 上报分数

业务层调用后会将当前用户分数上报到服务器，具体排行逻辑由后端处理，使用方法见接口介绍

  • 查询排行榜

获取排行榜数据，具体使用见下方接口介绍

接口索引 ​

属性 ​

GameHelper.CustomRank.CATEGORY ​

排行榜类型枚举

枚举参数名枚举值说明
PERMANENT1永久榜，数据不清除
DAY2天榜，每天清空排行榜里数据
WEEK3周榜，每周清空排行榜数据
MONTH4月榜，每月清空排行榜数据

GameHelper.CustomRank.PROVINCE_CODES ​

省排行榜省份类型枚举

枚举参数名枚举值
北京北京
天津天津
河北河北
山西山西
内蒙古内蒙古
辽宁辽宁
吉林吉林
黑龙江黑龙江
上海上海
江苏江苏
浙江浙江
安徽安徽
福建福建
江西江西
山东山东
河南河南
湖北湖北
湖南湖南
广东广东
广西广西
海南海南
重庆重庆
四川四川
贵州贵州
云南云南
西藏西藏
陕西陕西
甘肃甘肃
青海青海
宁夏宁夏
新疆新疆
香港香港
澳门澳门
台湾台湾

方法 ​

上报排行榜分数 ​

GameHelper.CustomRank.reportRankScore ​

  • 排行榜当前支持3种打榜模式,增量打榜,覆盖峰值打榜,覆盖盖式实时打榜

  • 增量打榜:incr=true,忽略forceUpdate参数,增量打榜下客户端传的分数会以增量的形式更新上榜,比如客户端上传了3次增量打榜,分数分别是100,200,100,则当前分数为400,由于增量数据不可控,因此永久榜不允许使用增量打榜

  • 覆盖峰值打榜:incr=false,forceUpdate=false,峰值覆盖式打榜下,榜单会比对当前榜单上的分数和当前打榜的分数,只使用分数更大的,比如客户端上传了三次打榜分数为100,200,100,则榜单分数为200

  • 覆盖式实时打榜:incr=false,forceUpdate=true,榜单分数会实时变更,排名也会实时变化,比如客户端上传了三次打榜分数为100,200,100,则当前榜单分数为100

该接口传入的success回调是以事件监听的方式触发，只有在成功上报时才会调用。网络较差时可能会出现调用了多次上报接口的success回调同时触发。建议success回调里只处理数据层逻辑

fail回调基本只会在传入参数错误时触发

参数 ​
参数类型默认值是否必填说明
optObject/是上报参数
opt.datareportParams/是上报数据
opt.successfunction/否上报的成功回调监听，由于上报可能会因为网络原因导致延迟，success回调最好只涉及数据层的逻辑，且做好安全性判断
opt.failfunction/否查询排行榜失败的回调，基本只会在传入数据检查时触发，如果执行失败回调请检查传参是否错误

reportParams

参数类型默认值是否必填说明
namestring/是排行榜名称，name和category确定一个唯一排行榜
categorystring/是排行榜类型，name和category确定一个唯一排行榜
scorenumber/是上报排行榜的分数
incrboolean/否是否增量打榜,永久榜不允许增量打榜
forceUpdateboolean/否是否覆盖打榜,强制更新score
extobject/否客户端自定义上榜数据,可以是上榜的头像和昵称,属性由客户端自己定义
示例 ​
javascript
GameHelper.CustomRank.reportRankScore({
            data: {
                "name": "test1",//排行榜名称,客户端自定义
                "category": 2,//排行榜周期类型,不同类型不同逻辑特性 1:永久榜2:天榜3:周榜4月榜
                "score": Math.random() * 100,// 打榜分数
                "incr": false,// 是否增量打榜,永久榜不允许增量打榜
                "forceUpdate": true,// 是否覆盖打榜,强制更新score
                "ext": {//客户端自定义上榜数据,可以是上榜的头像和昵称
                    "name": "test",
                    "avatar": "1001"
                }
            },
            success: (res) => {
                console.log("数据上报成功", res);
            },
            fail: (err) => {
                console.log("数据上报失败", err);
            }
        })

GameHelper.CustomRank.groupKnock ​

该接口逻辑与reportRankScore一致，但主要用于省排行榜打榜，uid需要传入省份，该接口的永久榜支持增量打榜

参数 ​
参数类型默认值是否必填说明
optObject/是上报参数
opt.datareportParams/是上报数据
opt.successfunction/否上报的成功回调监听，由于上报可能会因为网络原因导致延迟，success回调最好只涉及数据层的逻辑，且做好安全性判断
opt.failfunction/否查询排行榜失败的回调，基本只会在传入数据检查时触发，如果执行失败回调请检查传参是否错误

reportParams

参数类型默认值是否必填说明
uidstring/是打榜省份，对应PROVINCE_CODES的枚举值，如”广东“
namestring/是排行榜名称，name和category确定一个唯一排行榜
categorystring/是排行榜类型，name和category确定一个唯一排行榜
scorenumber/是上报排行榜的分数
incrboolean/否是否增量打榜,永久榜不允许增量打榜
forceUpdateboolean/否是否覆盖打榜,强制更新score
extobject/否客户端自定义上榜数据,可以是上榜的头像和昵称,属性由客户端自己定义
示例 ​
javascript
GameHelper.CustomRank.groupKnock({
            data: {
                "uid: "上海",
                "name": "test1",//排行榜名称,客户端自定义
                "category": 1,//排行榜周期类型,不同类型不同逻辑特性 1:永久榜2:天榜3:周榜4月榜
                "score": Math.random() * 100,// 打榜分数
                "incr": true,// 是否增量打榜,永久榜不允许增量打榜
                "ext": {//客户端自定义上榜数据,可以是上榜的头像和昵称
                    "name": "test",
                    "avatar": "1001"
                }
            },
            success: (res) => {
                console.log("数据上报成功", res);
            },
            fail: (err) => {
                console.log("数据上报失败", err);
            }
        })

查询排行榜 ​

GameHelper.CustomRank.queryRankList ​

获取排行榜的数据队列

参数 ​
参数类型默认值是否必填说明
optObject/是上报参数
opt.datareportParams/是上报数据
opt.successfunction/否查询排行榜的成功回调
opt.failfunction/否查询排行榜失败的回调

reportParams

参数类型默认值是否必填说明
namestring/是排行榜名称，name和category确定一个唯一排行榜
categorystring/是排行榜类型，name和category确定一个唯一排行榜
scorenumber/是上报排行榜的分数
incrboolean/否是否增量打榜,永久榜不允许增量打榜
forceUpdateboolean/否是否覆盖打榜,强制更新score
extobject/否客户端自定义上榜数据,可以是上榜的头像和昵称,属性由客户端自己定义
示例 ​
javascript
GameHelper.CustomRank.queryRankList({
            data: {
                "name": "test1",//排行榜名, 客户端自定义
                "uid": "111",//打榜唯-uid
                "category": 2,//排行榜周期类型,不同类型不同逻辑特性1:永久榜2:天榜 2:天榜3:周榜
                "offset": 0,//查询偏移量,设置该字段为1可获取上一个周期的排行榜数据
                "page": 0,//页码编号,从0开始
                "count": 10// 每页数量
            },
            success: (res) => {
                console.log("查询排行榜成功", res);
                console.log("排行榜上当前玩家分数",res.data.score);
                console.log("查询的排行榜结果列表",res.data.list);
            },
            fail: (err) => {
                console.log("查询排行榜失败", err);
            }
        })
java
//success回传的res结构
{
    code:0,
    data:{
            "name": "test",//排行榜名,客户端自定义
            "category": 2,//排行榜周期类型
            "offset": 0,// 查询偏移量
            "page": 0,//页码编号
            "count": 10,// 每页数量
            "no": 1,//自己排名,从1开始,如果为-1则未上榜
            "score": 100,// 自己上榜分数
            "list": [
                {
                    "uid": "111",
                    "score": 100,
                    "no": 1,
                    "ext": {
                        //上榜uid
                        //上榜分数
                        //上榜排名
                        // 客户端自定义上榜数据,可以是上榜的头像和昵称
                        "name": "test",
                        "avatar": "1001"
                    }
                }
            ]
        },
    msg:"OK"
}
点我快速对接
›