高级功能

IMPORTANT

本文档中所述的接口，均为可选接口。 游戏可以根据自己的需求进行调用

获取当前渠道号

如果游戏层需要获取当前渠道包的渠道号， 可以调用如下API。 对应聚合SDK后台->渠道配置中，设置的渠道号。

[[U8SDK sharedInstance] channelId];

获取当前账号的角色列表

本接口依赖角色信息上报，如果没有正确调用角色信息上报接口， 那本接口功能会异常。

调用接口：

[[U8SDK sharedInstance] fetchMyRoles];

拉取成功或失败， 聚合SDK会通过初始化时设置的U8SDKDelegate->OnEventWithCode，通知给游戏层：

-(void) OnEventWithCode:(int)code msg:(NSString*)msg
{
    switch (code){
        case U8_CODE_MY_ROLES_FETCHED::
            // 获取成功
            // 角色列表获取成功， msg为JSON Array格式的字符串：
            // [
            //  {
            //  "roleID":"1",
            //  "roleName":"test_11",
            //  "roleLevel":"1",
            //  "serverID":"1",
            //  "serverName":"测试1服",
            //  "vip":"1",
            //  "createTime":"2024-04-03 10:36:42",
            //  "lastLevelUpTime":"2024-04-03 10:36:42",
            //  "lastGameTime":"2024-04-03 10:36:42",
            //  "extraData":"111,222,333",
            //  "deviceID":"",
            //  "ip":"172.261.122.27"
            //  },
            //  {...}
            // ]                   
            Log.d("U8SDK", "fetch my roles success:"+msg);
            break;
        case U8_CODE_MY_ROLES_FETCH_FAILED:
            // 服务器列表获取失败
            Log.d("U8SDK", "fetch my roles failed:"+msg);
            break;
    }
}

角色记录中的参数说明：

参数名称	参数类型	参数说明
roleID	String	角色ID
roleName	JSONArray	角色名称
roleLevel	String	角色等级
serverID	String	服务器ID
serverName	String	服务器名称
vip	int	VIP等级
createTime	String	角色创建时间
lastLevelUpTime	String	上次角色等级升级时间
lastGameTime	String	角色上次进入游戏时间
extraData	String	调用角色上报接口传入的customData
deviceID	String	设备号
ip	String	角色上次登录时的IP

获取服务器列表

为了提效游戏研发，我们在聚合SDK后台，增加了游戏服务器列表的管理。 游戏层可以将服务器列表托管在聚合SDK后台。

如果要获取后台配置的服务器列表，可以调用如下分页拉取接口：

[[U8SDK sharedInstance] fetchServersWithPage:currPage pageSize:pageSize];     //currPage:当前页，pageSize:每页拉取的服务器条目数量（单页最大不超过2000条）

获取成功或失败， 聚合SDK会通过初始化时设置的U8SDKDelegate->OnEventWithCode，通知给游戏层：

-(void) OnEventWithCode:(int)code msg:(NSString*)msg
{
    switch (code){
        case U8_CODE_SERVERS_FETCHED::
            // 服务器列表获取成功，msg是
            Log.d("U8SDK", "fetch servers success:"+msg);
            break;
        case U8_CODE_SERVERS_FETCH_FAILED:
            // 服务器列表获取失败
            Log.d("U8SDK", "fetch servers failed:"+msg);
            break;
    }
}

当服务器列表获取成功时，即code为U8_CODE_SERVERS_FETCHED时，msg中是json array格式的服务器列表信息， 格式如下：

{
    "currentPage":"1",
    "pageSize":"10",
    "total":"11"
    "records":[
        {
            "serverID":"11",
            "serverName":"青山绿水11服",
            "serverTags":"热门,新",
            "sortIndex":"11",
            "status":2,            
            "autoOpenTime":"2024-04-03 00:00:00",
            "autoCloseTime":"",            
            "internalID":"abcdefghi11",
            "serverAddr":"172.16.3.200:5000",            
            "mergeServerIDs":"",
            "openTime":"2024-04-03 10:36:42",
            "serverGroup":"",
            "extra":""            
        },
        {...}
    ]
}

记录中的参数说明：

参数名称	参数类型	参数说明
currentPage	int	当前页
pageSize	String	每页记录数量
total	String	当前查询条件下总共的记录条数
records	JSONArray	服务器列表
serverID	String	服务器ID
serverName	String	服务器名称
serverTags	String	服务器标签
sortIndex	int	排序值，越大越靠前
autoOpenTime	String	自动开服时间，yyyy-MM-dd HH:mm:ss
autoCloseTime	String	自动关服时间，yyyy-MM-dd HH:mm:ss
internalID	String	服务器功能标记
serverAddr	String	服务器地址
mergeServerIDs	String	合服ID
openTime	String	开服时间， yyyy-MM-dd HH:mm:ss
serverGroup	String	服务器分组名称
extra	String	扩展参数

分页查询规则：

比如单页10条记录，首次分页查询时，第一页的话，currPage是1：

    int currPage = 1;
    int pageSize = 10;
    [[U8SDK sharedInstance] fetchServersWithPage:currPage pageSize:pageSize];

返回记录后，可以根据currPage、pageSize和total总数，来判断是否还有下一页， 简单判断如下：

if (currPage * pageSize > total) {
// 还有下一页：
    [[U8SDK sharedInstance] fetchServersWithPage:currPage+1 pageSize:pageSize];
} else {
// 已经是最后一页
...
}

获取公告消息列表

聚合SDK后台，支持配置公告消息。 游戏服务器可以通过API拉取公告消息进行展示：

[[U8SDK sharedInstance] fetchAllMessages:0];    //参数固定为0

获取成功或失败， 聚合SDK会通过初始化时设置的U8SDKDelegate->OnEventWithCode，通知给游戏层：

-(void) OnEventWithCode:(int)code msg:(NSString*)msg
{
    switch (code){
        case U8_CODE_MESSAGES_FETCHED:
            //公告消息获取成功，msg中是消息列表
            Log.d("U8SDK", "u8 fetch messages success:"+msg);
            break;
        case U8_CODE_MESSAGES_FETCH_FAILED:
            Log.d("U8SDK", "u8 fetch messages failed");
            break;
    }
}

msg是JSON Array格式的字符串， 每个条目中对象说明如下：

参数名称	参数类型	参数说明
id	int	消息唯一ID
title	String	公告标题
content	String	公告内容（支持html格式），自定义渲染时，请注意兼容
createTime	String	消息创建时间
popupPos	int	0： 不弹出； 1：初始化之后；2：登陆之后；3：进入游戏之后；4：支付之前
customInfo	String	自定义配置数据

获取动态参数

在U8框架初始化成功后， 如果后台有配置动态参数， 那将在U8聚合SDK框架的初始化回调中，将动态参数回调给游戏层：

-(void) OnEventWithCode:(int)code msg:(NSString*)msg
{
    switch (code){
        case U8_CODE_FRAMEWORK_INIT_SUCCESS:
            // U8框架初始化成功， msg是json格式， 是服务端添加的动态参数{"key":"value","key2":"value2"...}
            Log.d("U8SDK", "u8 init success:"+msg);
            break;
        case U8_CODE_FRAMEWORK_INIT_FAILED:
            Log.d("U8SDK", "u8 init failed");
            break;
    }
}

当U8框架初始化成功后， 会触发onResult回调，code为U8_CODE_FRAMEWORK_INIT_SUCCESS， 此时可以从data中解析动态参数、服务器时间戳等。 data格式如下：

{ 
    "gameParams":"{\"test_123\":\"测试值\"}",      //SDK后台配置的动态参数
    "ip": "172.220.49.58",                         //当前设备外网IP
    "serverTimestamp":"1712993299286",             // 服务器时间戳，单位ms
    "localTimestamp":"1712993298698"               // 获取时，客户端对应的时间戳 单位ms
}