game_chart_guide

排行榜是用户在游戏内参与活动后产生挑战时间/分数成绩的排行
游戏使用成就系统提供的 API，获取所有榜单数据、榜单排名区间数据、取角色排名数据，
更新角色排行分数，获取当前用户头像地址、昵称等接口。

二、接入准备

如何获取接口公钥/key

向 SDK 开发人员提交游戏 Game Key，和 APK 签名的 sha256摘要，SDK 对接人员会协助填写，
并将最后得到的公钥给游戏开发，游戏应妥善保管此类参数

如何定义榜单

三、接口调用

0、前置接口

1、服务初始化

内容	定义	说明
排行榜名称	榜单名称	后台需要上传，仅作为排行ID对应的名称记录
排行榜标识	排行榜唯一标识	通过标识返回对应排行榜的数据（仅限数字+英文，最多100个字符）
排行榜周期	榜单更新周期	凌晨0点更新，仅限日榜,周榜,月榜,季榜,年榜,无限制
排行顺序	排行榜排序顺序	支持正序或倒序
排行策略	排行上报数据的更新策略	支持累计（上报数据直接累加）、最新（只记录最新数据）、最好（只记录最好数据）

GameChart.init，初始化公钥，在使用排行榜其他接口前，应调用此接口进行初始化

/**
 * 服务初始化
 *
 * @param publicKey 接口公钥，完成游戏服务配置得到
 */
public static void init(String publicKey)

//参数：publicKey，开发者后台的游戏公钥，可联系相应的运营获取
GameChart.init(String publicKey);

2、获取游戏榜单数据

/**
 * 获取所有榜单数据
 *
 * @param listener 回调对象
 */
public static void getGameChart(OpeDataListener<List<ChartDescriptor>> listener);

GameChart.getGameChart(new OpeDataListener<List<ChartDescriptor>>() {
    @Override
    public void onFinished(int code, String message, List<ChartDescriptor> data) {
    }
});

接口调用后通过接口OpeDataListener<List<ChartEntity>>返回游戏榜单列表
OpeDataListener，通用泛型回调接口，接入方调用方法后通过接口方法接收并处理调用结果
ChartDescriptor，角色成就数据模型，里面包含了游戏所定义的成就列表信息
两个类的具体信息在本文档后文的 API 详情部分，接口示例中涉及的其他类也是如此

3、获取榜单排名区间数据

GameChart.getChartByRange，获取榜单排名区间数据，区间用起始、结束值确定

/**
 * 获取榜单排名区间数据
 *
 * @param rankId   榜单id，必须
 * @param serverId 区服id，未分服传0
 * @param start    榜单排名区间起始index，包括此位置值对应的项
 * @param end      榜单排名区间结束index，包括此位置值对应的项
 * @param listener 回调对象
 */
public static void getChartByRange(String rankId, int serverId,
                                   int start, int end,
                                   OpeDataListener<List<ChartItem>> listener)

GameChart.getChartByRange(String rankId, int serverId, int start, int end,
    new OpeDataListener<List<ChartItem>>() {
        @Override
        public void onFinished(int code, String message, List<ChartItem> data) {
    }
});

4、获取角色附近排名数据

GameChart.getChartAroundRole，获取角色附近排名数据，角色附近的范围，通过指定本角色之前多少位、之后多少位确定

/**
 * 获取角色排名数据
 *
 * @param rankId   榜单id，必须
 * @param serverId 区服id，未分服传字符串0
 * @param roleId   游戏角色id, 游戏不分角色传字符串0
 * @param before   当前角色前几名，包括此位置值对应的项
 * @param after    当前角色后几名，包括此位置值对应的项
 * @param listener 回调对象
 */
public static void getChartAroundRole(String rankId, int serverId, String roleId,
                                      int before, int after,
                                      OpeDataListener<List<ChartItem>> listener);

GameChart.getChartAroundRole(String rankId, int serverId, String roleId,
    int before,int after, new OpeDataListener<List<ChartItem>>() {
        @Override
        public void onFinished(int code, String message, List<ChartItem> data) {
        }
});

5、更新角色排行数据

/**
 * 更新角色排行分数
 *
 * @param rankId    排行榜id
 * @param serverId  区服id，未分服传字符串0
 * @param roleId    游戏角色id，游戏不分角色传字符串0
 * @param roleAvatar 头像地址，无头像或不需要时，可传null
 * @param roleName  角色名/昵称，无角色名/昵称或不需要时，可传null
 * @param score     排名数值
 * @param listener  回调对象
 */
public static void updateByRole(String rankId, int serverId, String roleId,
                                String roleAvatar, String roleName, float score,
                                OpeDataListener<Boolean> listener)

GameChart.updateByRole(String rankId, int serverId, String roleId, String avatar,
    String roleName,float score, new OpeDataListener<Boolean>() {
        @Override
        public void onFinished(int code, String message, Boolean data) {
        //data为true代表更新角色分数成功,反之为更新失败
        }
});

6、获取当前用户在平台的信息

GameChart.getPtUser，获取当前已登录用户在平台的信息，这些信息是对登录后的用户信息的补充

/**
 * 获取当前用户头像地址、昵称
 */
public static PtUser getPtUser()

何时使用接口：如果游戏在排行榜中展示角色头像、昵称等信息，但是游戏本身没有相关信息，
则可以获取用户平台信息，并通过GameChart.updateByRole更新到排行数据中

PtUser ptUser = GameChart.getPtUser();

API 详情

OpeDataListener


/**
 * 数据监听器
 */
public interface OpeDataListener<T> {
    /**
     * @param code    0为请求成功，并返回数据, 其他code均为失败，失败时数据可能为空
     * @param message 说明文案
     * @param data    返回数据
     */
    void onFinished(int code, @Nullable String message, @Nullable T data);
}

code 列表

ChartDescriptor

code	含义
0	成功
1	取消
2	处理中，可能是延迟
3	失败，可从message中了解更多信息
4	接口返回超时
5	数据加密解密错误

/**
 * 排行榜描述信息，游戏可能有多个排行榜
 */
public class ChartDescriptor {
    /** 排行榜ID */
    public final String rankId;
    /** 排行榜名称 */
    public final String rankName;
    /** 游戏key */
    public final String gameKey;
    /** 排行周期 */
    public final String interval;
    /** 排行策略 */
    public final String strategy;
    /** 排行顺序 */
    public final String order;
    /** 当前版本 */
    public final String version;
    /** 是否维护，1为维护中 */
    public final String maintain;
    /** 排行榜过期时间 */
    public final String expiredAt;
    /** 排行榜激活时间 */
    public final String activatedAt;
}

ChartItem

/**
 * 一个排行榜中某一项的信息
 */
public class ChartItem {
    /** 排名 */
    public final String rank;
    /** 角色头像地址 */
    public final String roleAvatar;
    /** 角色ID */
    public final String roleId;
    /** 角色名 */
    public final String roleName;
    /** 成绩 */
    public final float score;
}

PtUser

/**
 * 平台用户信息，作为登录信息的补充
 */
public class PtUser {

  /** 平台用户 id */
  public final String ptUid;

  /** 头像地址 */
  public final String sFace;

  /** 昵称 */
  public final String nick;
}

运营SDK排行榜接入文档

一、功能描述