SDK对接文档

主题

WARNING

模块名：GameHelper.CustomRank

1. 描述 ​

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

2. 接入说明 ​

该模块为选接模块

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

  1. 上报分数

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

  • 查询排行榜

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

接口索引 ​

属性 ​

GameHelper.CustomRank.CATEGORY ​

排行榜类型枚举

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

方法 ​

上报排行榜分数 ​

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.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"
}
点我快速对接