supersdk

文档中心

文档中心

下载文档

区服模块

区服模块提供获取服务器列表，角色列表相关功能。

一、注意事项

注意一：区服模块需申请参数，并在打包工具配置。接入完成后需确认是否接入成功。

注意二：区服模块获取的信息只做显示玩家历史角色、服务器、等级信息。

注意三：区服模块提供的信息不可作为游戏活动的依据。

注意四：游戏需要对外网预告服做进入游戏的限制。

二、配置信息（必接）

说明：部分接口需要添加权限，如下所示：

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

三、功能接口

1. 获取区服列表

接口描述：获取区服列表。

接口调用：

Map<String, Object> queryServerMap = new HashMap<String, Object>();

queryServerMap.put("opid", opid);
queryServerMap.put("opgameid", opGameId);
queryServerMap.put("yz_game_id", gameId); // 开服系统 gameId
queryServerMap.put("packageId", packageId); // 包 ID(选传)
queryServerMap.put("pageNo", "1"); // 区服分页，第多少页，值必须大于等于 1 的 int 类型。非必传参数
queryServerMap.put("pageSize", "1"); // 区服分页，每页数据条数，值须为大于等于 1 的 int 类型的值。非必须参数，
queryServerMap.put("backColums", "[]"); // 区服返回字段，值须为 JSONArray 字符串。非必传参数，如果不传，则默认返回列。具体字段请参考附录

SuperSDK.invoke("xsdk", "queryServers", queryServerMap);

接口回调：

private OnSuperSDKListener mSuperSDKListener = new OnSuperSDKListener() {

       @Override
       public void onSuperSDK(String moduleName, String funcName, String result) {
           if ("xsdk".equals(moduleName) && "queryServers".equals(funcName)) {
               try {
                   JSONObject serverQueryJson = new JSONObject(result);
                   String code = serverQueryJson.getString("code");
                   String msg = serverQueryJson.getString("msg");

                   if (!code.equals("1")) {
                       Log.d("tag", "查询区服失败，msg为：" + msg);
                   } else {
                       Log.d("tag", "查询区服成功，返回的数据为：" + serverQueryJson.getJSONArray("data"));
                   }
               } catch (JSONException e) {
                   e.printStackTrace();
               }
           }
       }
   };

日志打印：

{
 "code": 1,
 "msg": "查询区服成功",
 "data" : {
    "totalCount" : 2,
    "list" : [
          {
            "op_sid" : "1516440002",
            "type" : "44",
            "server_name" : "测试服2",
            "is_recommend" : "1",
            "first_opentime" : "1537372800",
            "server_id" : "1516440002",
            "new_style" : "3",
            "is_active" : "1",
            "server_url" : "s1516440002-sbzh.youzu.com"
          },
          {
            "op_sid" : "1516440001",
            "type" : "44",
            "server_name" : "测试服1",
            "is_recommend" : "1",
            "first_opentime" : "1537372800",
            "server_id" : "1516440001",
            "new_style" : "3",
            "is_active" : "1",
            "server_url" : "s1516440001-sbzh.youzu.com"
          }]
      },
}

2. 获取推荐服列表（选接）

接口描述：获取推荐服列表。

接口调用：

Map<String, Object> queryServerMap = new HashMap<String, Object>();

queryServerMap.put("opid", opid);
queryServerMap.put("opgameid", opGameId);
queryServerMap.put("yz_game_id", gameId); // 开服系统 gameId
queryServerMap.put("packageId", packageId); // 包 ID(选传)
queryServerMap.put("pageNo", "1"); // 推荐服分页，第多少页，值必须大于等于 1 的 int 类型。非必传参数
queryServerMap.put("pageSize", "1"); // 推荐服分页，每页数据条数，值须为大于等于 1 的 int 类型的值。非必须参数，
queryServerMap.put("isCache", "1"); // 是否使用缓存数据，1:使用，0:不使用，非必传参数，默认使用缓存
queryServerMap.put("backColums", "["cover_style"]"); // 推荐服返回字段，值须为 JSONArray 字符串。非必传参数，如果不传，则默认返回列。具体字段请参考附录

SuperSDK.invoke("xsdk", "queryRecoServers", queryServerMap);

接口回调：

private OnSuperSDKListener mSuperSDKListener = new OnSuperSDKListener() {

       @Override
       public void onSuperSDK(String moduleName, String funcName, String result) {
           if ("xsdk".equals(moduleName) && "queryRecoServers".equals(funcName)) {
               try {
                   JSONObject serverQueryJson = new JSONObject(result);
                   String code = serverQueryJson.getString("code");
                   String msg = serverQueryJson.getString("msg");

                   if (!code.equals("1")) {
                       Log.d("tag", "查询推荐服失败，msg为：" + msg);
                   } else {
                       Log.d("tag", "查询推荐服成功，返回的数据为：" + serverQueryJson.getJSONArray("data"));
                   }
               } catch (JSONException e) {
                   e.printStackTrace();
               }
           }
       }
   };

日志打印：

{
 "code": 1,
 "msg": "查询推荐服成功",
 "data" : {
    "totalCount" : 2,
    "list" : [
          {
            "op_sid" : "1516440002",
            "type" : "44",
            "server_name" : "测试服2",
            "is_recommend" : "1",
            "first_opentime" : "1537372800",
            "server_id" : "1516440002",
            "new_style" : "3",
            "is_active" : "1",
            "cover_style" : "1",
            "server_url" : "s1516440002-sbzh.youzu.com"
          },
          {
            "op_sid" : "1516440001",
            "type" : "44",
            "server_name" : "测试服1",
            "is_recommend" : "1",
            "first_opentime" : "1537372800",
            "server_id" : "1516440001",
            "new_style" : "3",
            "is_active" : "1",
             "cover_style" : "1",
            "server_url" : "s1516440001-sbzh.youzu.com"
          }]
      },
}

3. 获取最近登录角色信息（选接）

接口描述：获取最近登录角色信息。

接口调用：

Map<String, Object> queryRoleMap = new HashMap<String, Object>();

queryRoleMap.put("opid", opid);
queryRoleMap.put("yz_game_id", gameId); // 开服系统 gameId
queryRoleMap.put("osdk_user_id", userId);
queryRoleMap.put("opgameid", opgameId);
queryServerMap.put("packageId", packageId); // 包 ID(选传)
queryRoleMap.put("backColums", "[op_sid]"); // 区服返回字段，值须为 JSONArray 字符串。非必传参数，如果不传，则默认返回列。具体字段请参考附录

SuperSDK.invoke("xsdk", "queryLastRole", queryRoleMap);

接口回调：

private OnSuperSDKListener mSuperSDKListener = new OnSuperSDKListener() {

       @Override
       public void onSuperSDK(String moduleName, String funcName, String result) {
           if ("xsdk".equals(moduleName) && "queryLastRole".equals(funcName)) {
               try {
                   JSONObject roleQueryJson = new JSONObject(result);
                   String code = roleQueryJson.getString("code");
                   String msg = roleQueryJson.getString("msg");

                   if (!code.equals("1")) {
                       Log.d("tag", "查询角色失败，msg为：" + msg);
                   } else {
                       Log.d("tag", "查询角色成功，返回的数据为：" + roleQueryJson.getJSONArray("data"));
                   }
               } catch (JSONException e) {
                   e.printStackTrace();
               }
           }
       }
   };

日志打印：

{
 "code": 1,
 "msg": "查询最后角色信息成功",
 "data": {
   "extend": "",
   "yz_game_id": "",
   "level": ,
   "opid": "",
   "role_id": "",
   "role_name": "",
   "server_id": "",
   "osdk_user_id": "",
   "vip_grade": ,
   "roleCreateTime": ,
   "serverInfo": {
     "first_opentime": "",
     "is_active": "",
     "new_style": "",
     "server_id": "",
     "server_name": "",
     "type": ""
   }
}

4. 获取角色列表

接口描述：获取角色列表。

接口调用：

Map<String, Object> queryRoleMap = new HashMap<String, Object>();

queryRoleMap.put("opid", opid);
queryRoleMap.put("yz_game_id", gameId);//开服系统 gameId
queryRoleMap.put("osdk_user_id", userId);
queryRoleMap.put("opgameid", opgameId);
queryServerMap.put("packageId", packageId);//包 ID(选传)
queryRoleMap.put("backColums", "[op_sid]");// 区服返回字段，值须为 JSONArray 字符串。非必传参数，如果不传，则默认返回列。具体字段请参考附录

SuperSDK.invoke("xsdk", "queryRoles", queryRoleMap);

接口回调：

private OnSuperSDKListener mSuperSDKListener = new OnSuperSDKListener() {

       @Override
       public void onSuperSDK(String moduleName, String funcName, String result) {
           if ("xsdk".equals(moduleName) && "queryRoles".equals(funcName)) {
               try {
                   JSONObject roleQueryJson = new JSONObject(result);
                   String code = roleQueryJson.getString("code");
                   String msg = roleQueryJson.getString("msg");

                   if (!code.equals("1")) {
                       Log.d("tag", "查询角色失败，msg为：" + msg);
                   } else {
                       Log.d("tag", "查询角色成功，返回的数据为：" + roleQueryJson.getJSONArray("data"));
                   }
               } catch (JSONException e) {
                   e.printStackTrace();
               }
           }
       }
   };

日志打印：

{
 "code": 1,
 "msg": "查询角色信息成功",
 "data": [
   {
     "extend": "null",
     "yz_game_id": "94",
     "level": 120,
     "opid": "2443",
     "role_id": "1519958050",
     "role_name": "觉得就觉得",
     "server_id": "2072311068",
     "osdk_user_id": "0060015_1234",
     "vip_grade": 12,
     "roleCreateTime": 1519958050,
     "serverInfo": {
       "first_opentime": "",
       "new_style": "",
       "op_sid": "",
       "server_id": "",
       "server_name": ")",
       "type": ""
     }
   },
   {
     "extend": "null",
     "yz_game_id": "94",
     "level": 120,
     "opid": "2443",
     "role_id": "1519958050",
     "role_name": "觉得就觉得",
     "server_id": "2072311068",
     "osdk_user_id": "0060015_1234",
     "vip_grade": 12,
     "roleCreateTime": 1519958050,
     "serverInfo": {
       "first_opentime": "",
       "new_style": "",
       "op_sid": "",
       "server_id": "",
       "server_name": ")",
       "type": ""
     }
   },
   {
     "extend": "null",
     "yz_game_id": "94",
     "level": 120,
     "opid": "2443",
     "role_id": "1519958050",
     "role_name": "觉得就觉得",
     "server_id": "2072311068",
     "osdk_user_id": "0060015_1234",
     "vip_grade": 12,
     "roleCreateTime": 1519958050,
     "serverInfo": {
       "first_opentime": "",
       "new_style": "",
       "op_sid": "",
       "server_id": "",
       "server_name": ")",
       "type": ""
     }
   }
 ]
}

5. 进入游戏（必接）

接口描述：进入游戏事件，统计每个角色进入游戏的时间，用于获取列表时的排序，和上传进入游戏时间。

接口调用：

Map<String, Object> enterMap = new HashMap<String, Object>();

enterMap.put("opid", opid);
enterMap.put("yz_game_id", gameId); // 开服系统 gameId
enterMap.put("osdk_user_id", userIds[mUserView.getSelectedItemPosition()]);
enterMap.put("extend", extend); // 可选               
enterMap.put("level", roleLevel);
enterMap.put("role_id", roleId);
enterMap.put("role_name", roleName);
enterMap.put("server_id", serverId);
enterMap.put("vip_grade", roleVip);
enterMap.put("roleCreateTime", roleCreateTime); // 创角必传，游戏客户端可取服务端的时间戳，作为创角时间

SuperSDK.invoke("xsdk", "enterGame", enterMap);

6. 创建角色（必接）

接口描述：用户创建角色后调用。

接口调用：

Map<String, Object> creatRoleMap = new HashMap<String, Object>();

creatRoleMap.put("opid", opid);
creatRoleMap.put("yz_game_id", gameId); // 开服系统 gameId
creatRoleMap.put("osdk_user_id", userId);
creatRoleMap.put("extend", ""); // 可选 
creatRoleMap.put("level", roleLevelExtra);
creatRoleMap.put("role_id", roleIdExtra);
creatRoleMap.put("role_name", roleNameExtra);
creatRoleMap.put("server_id", serverId);
creatRoleMap.put("vip_grade", roleVipExtra);
creatRoleMap.put("roleCreateTime", timeStap); // 创角必传，游戏客户端可取服务端的时间戳，作为创角时间， 10 位

SuperSDK.invoke("xsdk", "createRole", creatRoleMap);

7. 更新角色（必接）

接口描述：用户角色信息存在改动的情况下调用，例如：角色等级、角色名称，等等。

接口调用：

Map<String, Object> updataMap = new HashMap<String, Object>();   
 
updataMap.put("opid", opid);
updataMap.put("yz_game_id", gameId); // 开服系统 gameId
updataMap.put("osdk_user_id", userId);
updataMap.put("extend", ""); // 可选
updataMap.put("level", grade);
updataMap.put("role_id", roleId);
updataMap.put("role_name", roleN);
updataMap.put("server_id", serverId);
updataMap.put("vip_grade", vip);
updataMap.put("roleCreateTime", roleCreateTime); // 创角必传，游戏客户端可取服务端的时间戳，作为创角时间

SuperSDK.invoke("xsdk", "updateRole", updataMap);

8. 删除角色（选接）

接口描述：删除一个已经创建的角色。

接口调用：

Map<String, Object> deleteMap = new HashMap<String, Object>();

deleteMap.put("opid", opid);
deleteMap.put("yz_game_id", gameId); // 开服系统 gameId
deleteMap.put("osdk_user_id", userId);
deleteMap.put("extend", ""); // 可选
deleteMap.put("level", grade);
deleteMap.put("role_id", roleId);
deleteMap.put("role_name", roleN);
deleteMap.put("server_id", serverId);
deleteMap.put("vip_grade", vip);
deleteMap.put("roleCreateTime", roleCreateTime); // 创角必传，游戏客户端可取服务端的时间戳，作为创角时间

SuperSDK.invoke("xsdk", "deleteRoleNew", deleteMap);

接口回调：

private OnSuperSDKListener mSuperSDKListener = new OnSuperSDKListener() {

       @Override
       public void onSuperSDK(String moduleName, String funcName, String result) {
           if ("xsdk".equals(moduleName) && "deleteRoleNew".equals(funcName)) {
               try {
                   JSONObject roleDeleteJson = new JSONObject(result);
                   String code = roleDeleteJson.getString("code");
                   String msg = roleDeleteJson.getString("msg");
                   if (!code.equals("1")) {
                       Log.d("tag", "删除角色失败：" + msg);
                   } else {
                       Log.d("tag", "删除角色成功：" + msg);
                   }
               } catch (JSONException e) {
                   e.printStackTrace();
               }
           }
       }
   };

日志打印：

{
 "code": 1,
 "msg": "删除角色成功：success"
}

9. 设置上报时间间隔（选接）

接口描述：设置更新上报角色信息的时间间隔，默认 60 秒。传 0 表示每次更新必定上报。

接口调用：

Map<String, Long> map = new HashMap<String, Long>();

map.put("seconds", 10); // 必传，为大于等于 0 的整形数字，最小为 0，最大 600，单位/秒

SuperSDK.invoke("xsdk", "setUpdateInterval", map)

附录

说明：参数为可选返回列参数，如下：

返回列 说明
socket_domain socket 域名
socket_port socket 端口
op_sid 运营商区服 ID
is_active 是否激活
is_recommend 是否推荐
server_url 区服地址
recharge_url 充值地址
recharge_opentime 充值开启时间
notice_opentime 开服预告时间
fcm_time 防沉迷时间
cover_style 是否覆盖区服状态

特殊字段说明说明：

字段名 字段说明 取值说明
type 区服类型 31：正式服、41：永测服、42：外网测试服、43：内网测试服、44：QA 测试服
new_style 新样式 1：正常开启（开服 30 天以上）、3：火爆开启（开服 1 周 - 30 天）、4：即将开启（到达预告时间或在 IP 白名单内可见）、5：停服维护、6：停止激活、7：新开服（开服 1 周）、100：推荐、101：流畅、102：拥挤
cover_style 是否覆盖区服状态 0 不覆盖，1 覆盖

FAQ

Q：接口返回无数据。

A：将请求链接在浏览器中访问，如果返回无数据，需运营在开服系统后台配置。

Q：浏览器中访问的数据，与游戏接口返回的数据不一致。

A：检查 opid，opgameid 等参数是否正确，然后确认后台配置是否有开内网限制。

 
友情链接：游族网络
接入流程
文档中心
下载中心
公司介绍
联系我们
操作指南
视频教程
联系人：余先生
联系电话：15900679660
电子邮件：yuhc@yooozoo.com

Copyright ©2015-2023 Youzu All Rights Reserved 沪ICP备09058784号-22