单机联网模块CP接入规范V321.docx
《单机联网模块CP接入规范V321.docx》由会员分享，可在线阅读，更多相关《单机联网模块CP接入规范V321.docx（30页珍藏版）》请在冰豆网上搜索。
单机联网模块CP接入规范V321
单机游戏联网模块CP合作模块接口
深圳腾讯计算机系统有限公司
版权所有不得复制
修订记录
日期
修订版本
修改描述
作者
审核
2009-8-31
V1.0
初稿
Juanerliu
2009-8-31
V1.0
初稿
Micahcai
2009-11-13
V1.1
初始化版本号
bohrsong
2009-11-19
V1.2
增加对榜单数据获取的描述
juanerliu
2009-12-04
V1.3
修改API函数说明格式及内容,增加部分说明.归类API函数.
Bensonchen
2009-12-4
V1.4
1，修改榜单数据的字符串描述
2，去除末尾联系资料
Bohrsong
2009-12-29
V1.5
1.细化一些接口的参数含义
2.颜色设置接口有一些改动
Bensonchen
2010-01-15
V1.6
对于CP合包时，对于腾讯提供的类加了目录结构要求
一些界面UI的优化和美化
Bensonchen
2010-1-27
V1.7
更换示例图片
Bohrsong
2010-2-4
V1.8
更新QQForm内容检查说明
Bohrsong
2010-2-4
V2.0
更新QQForm接口命名
增加数据接口功能
删除界面颜色设置接口功能
Bohrsong
Bensonchen
2010-1-15
V2.2
ForRPG游戏合作的接口
清理部分老接口
上传积分接口加多参数
GetFeedInfo方法改名，加分类参数，私有数据结构体回传都带上dataValue
Timtinliu
2010-4-30
V2.3
补充上传积分时的扩展信息描述及示例
Bohrsong
2010-5-13
V3.0
完善游戏界面规范章节
bohrsong
2010-12-10
V3.2
重构联网模块接口
allenlian
2011-01-26
V3.2.1
修正性别定义笔误
yihongli
一、概述
腾讯手机QQ单机联网模块为单机游戏KJava版提供了联网模块开发接口，将以jar包的方式为合作方提供相应的接口调用，同时模块采用KJava服务C/S调用的方式响应合作方的请求，真正实现第三方程序可以只做少量的修改即可方便地实现联网功能。
二、目的
在单机游戏中增加联网模块的目的：
1、提供更多的支付方式，拉动收入。
2、增加单机游戏的互动性,为玩家提供更丰富的游戏、社区等体验。
3、挖掘单机游戏更大的商业价值。
拓宽CP的利益链。
三、范围
所有合作伙伴在KJAVA平台开发的单机游戏。
四、功能
模块实现的功能如下：
1、增加与游戏相关的辅助功能，包括游戏攻略、积分上传、通关数据等（如游戏中不存在积分或关卡信息则可现实无此信息）。
2、增加游戏推荐专区,CP游戏推荐板块，CP可以自行推荐自己的游戏（限在QQ游戏中心上线的游戏）。
3、增加基础社区化功能（交互论坛、个人信息的浏览）。
4、购买游戏道具时选择Q币或者金豆支付
5、积分挑战，排行查询
五、合作流程
1、合作伙伴与腾讯沟通，确定接入的游戏
2、腾讯提供联网模块jar包以及相关规范
3、合作伙伴开发接入
4、腾讯根据合作伙伴提供的单机软件包进行联调测试
5、测试通过后发布上线
六、开发接入
腾讯公司提供联网模块扩展包和Demo程序。
1、UI是在游戏中：
合作伙伴通过开发包使用Q币支付、金豆支付、积分关卡信息上传、积分排行查询几个接口。
这几个功能一般是在游戏中使用，所以UI和逻辑需要合作伙伴自己调用我们提供的接口来实现。
注意这几个接口都是通过先调用对应方法，然后按照指定回调接口notify（）中取返回值。
因此合作伙伴必须在代码中实现InfoListener接口，并将实现此接口的对象当作一个参数传入模块的构造函数中。
2、UI在腾讯的联网模块中：
如果发起挑战，查看个人信息、游戏论坛、游戏攻略、游戏推荐等功能，是模块自身已经做好的功能，这些内容合作伙伴只需执行一个初始化接口，提供总入口菜单，用户进入即可全部使用，不需要合作伙伴开发。
1.客户端接口函数
数据接口类定义：
1，用户信息
publicclassUserInfo
{
publicStringuid;/*用户ID*/
publicStringnickName;/*用户昵称*/
publicintsex;/*性别，0：
未知，1：
女，2：
男*/
publicintage;/*年龄*/
publicintscore;/*游戏最高分*/
publicintstatus;/*挑战状态：
0：
未挑战，1挑战中*/
publicintwin;/*胜场*/
publicintlost;/*负场*/
publicinthonor;/*荣誉点*/
publicintlevel;/*用户等级（备用）*/
publicStringdataKey;/*游戏中私有数据Key值*/
publicStringdataValue;/*游戏中私有数据value值*/
}
2，对手信息
publicclassOppUserInfo
{
publicStringuid;/*用户ID*/
publicStringnickName;/*用户昵称*/
publicintsex;/*性别，0：
未知，1：
女，2：
男*/
publicintage;/*年龄*/
publicintscore;/*被挑战的分数*/
publicintlevel;/*用户等级（备用）*/
publicStringdataKey;/*游戏中私有数据的Key*/
publicStringdataValue;/*游戏中私有数据的Value*/
}
3，Player信息
publicclassPlayerInfo
{
publicStringuid;/*用户ID*/
publicStringnickName;/*用户昵称*/
publicintsex;/*性别，0：
未知，1：
女，2：
男*/
publicintage;/*年龄*/
publicStringcity;/*归属地*/
publicintscore;/*用户分数*/
publicinttime;/*获得该分数的时间（整数，秒）*/
publicinttype;/*战报信息的类型，0：
未知1：
好友2：
仇家3：
相近4：
榜单用户（高手）*/
publicStringdataKey;/*游戏中私有数据Key值*/
publicStringdataValue;/*游戏中私有数据value值*/
}
构造函数
MBoxClient（）
入口类构造器，启动模块之前必须先构造该入口类的实例，调用类中的接口
publicMBoxClient（MIDletapp,
Displaydisplay,
Displayabledis,
InfoListenerinfo,
intw,
inth
intleftSoftKey,
intrightSoftKey,
intgameID,
intcpID,
Stringchannel）
参数说明:
app:
调用模块的运行应用midlet对象
display:
屏幕显示接口对象
dis:
模块调用前,当前屏幕显示类对象
info:
实现InfoListener接口的对象
leftSoftKey:
左软键参数值
rightSoftKey:
右软键参数值
w:
屏幕宽度
h:
屏幕高度
GameID:
游戏的id
CpID:
合作伙伴cp公司的编号，一般是腾讯事先统一分配
Channel：
渠道，暂时可填用空“”
返回值:
无
描述:
当你调用此函数,是用来获取cp游戏的相关的程序的运行实类对象midlet,屏幕控制的实例对象display,以便我们接口程序获取程序运行的控制权,其中Displaydis是我们返回给cp游戏当前的屏幕类对象。
强调，本方法务必在最开始执行，即在调用任何腾讯接口前执行他，以便初始化cpid和gameid，后续的接口的内部逻辑都需要的。
如果这两个值没有初始化，就调用其他接口，对应逻辑都不会成功。
调用需求:
class:
MBoxClient
进入联网模块页面
startMBox（）
启动模块，直接进入某个页面
publicvoidstartMBox（intconnType,intpageId）
参数说明:
connType:
联网类型定义
CONN_TYPE_DIRECT_NETWORK直接联网（一般采用）
pageId:
表示进哪个页面
PAGE_MAIN专区首页
PAGE_SHOWSCORES积分排行页
PAGE_USERINFO个人信息页
PAGE_ONLINE_LIST在线人员列表页
返回值:
无
描述:
当函数被调用,屏幕就直接切换至联网模块画面.
调用需求:
class:
MBoxClient
数据功能（取一些本地缓存信息，不联网）
getUserInfo（）
获取用户信息，包括用户ID号，昵称，性别，当前游戏最高分等。
publicUserInfogetUserInfo（）
参数说明:
无
返回值:
类：
UserInfo
描述:
用户信息在联网模块内有缓存，因此调用该函数不会进行联网操作。
调用该函数前需要预先调用requestData（）来联网获取相应数据，如果未预先获取或获取失败，则返回null。
参见requestData（）相关介绍。
调用需求:
class:
MBoxClient
getOppUserInfo（）
获取当前玩家正在挑战的对手玩家用户信息。
publicOppUserInfogetOppUserInfo（）
参数说明:
无
返回值:
类：
OppUserInfo
描述:
对手用户信息在联网模块内有缓存，因此调用该函数不会进行联网操作。
调用该函数前需要预先调用requestData（）来联网获取相应数据，如果未预先获取或获取失败，则返回null。
参见requestData（）相关介绍。
调用需求:
class:
MBoxClient
getPlayersInfo（）
获取部分其他玩家战况Feed信息。
publicPlayerInfo[]getPlayersInfo（）
返回值:
类：
PlayerInfo数组,一般小于等于10个
描述:
玩家Feed信息在联网模块内有缓存，因此调用该函数不会进行联网操作。
调用该函数前需要预先调用requestPlayerInfo（）来联网获取相应数据，如果未预先获取或获取失败，则返回null。
参见requestPlayerInfo（）相关介绍。
调用需求:
class:
MBoxClient
getServerTime（）
获取服务器时间。
publicStringgetServerTime（）
返回值:
String类型
描述:
服务器时间在联网模块内有缓存，因此调用该函数不会进行联网操作。
调用该函数前需要预先调用requestData（）来联网获取相应数据，如果未预先获取或获取失败，则返回null。
参见requestData（）相关介绍。
调用需求:
class:
MBoxClient
数据交互功能（向腾讯服务器发请求，联网。
通过异步回调取结果）
requestData（）
获取各类信息，调用该方法会联网，从服务端取最新的数据。
publicvoidrequestData（intdataType）
参数说明:
dataType:
获取数据的类型
REQUEST_TYPE_USER_INFO请求个人信息
REQUEST_TYPE_OPP_USER_INFO请求挑战对手信息
REQUEST_TYPE_SERVER_TIME请求服务器时间
REQUEST_TYPE_RANK_NEAR请求相近排名数据
REQUEST_TYPE_RANK_FRIEND请求好友排名数据
REQUEST_TYPE_RANK_WEEK请求周榜排名数据
返回值:
无
描述:
调用该函数会进行联网操作。
不进入联网模块页面。
其中请求个人信息，挑战对手信息，相近排行，好友排行，需要玩家先登录。
如果当前玩家已经登录，则返回相应信息，如果当前玩家未登录（包括登录后注销），则取不到。
通过回调接口InfoListener（notify方法）返回服务器响应。
只有在得到服务器响应之后才可从缓存中取得相应数据。
相应的取缓存函数为：
取个人信息getUserInfo（）
取挑战对手信息getOppUserInfo（）
取服务器时间getServerTime（）
取相近排名数据ResponseInfo.getMessage（）详见notify（）
取好友排名数据ResponseInfo.getMessage（）详见notify（）
取周榜排名数据ResponseInfo.getMessage（）详见notify（）
其中的排名数据是一个String对象，其数据格式为:
"分数值1|昵称1|#|分数值2|昵称2|#|……|#|"。
分隔符：
|#|:
分隔不同记录
|:
分隔同一记录内两个字段,第一个字段是分数，第二个字段是用户昵称
排序：
按照用户积分从高到低降序排列。
数据示例:
"130028|黑小麦|#|24677|王志彬|#|9016|泡泡|#|2539|kiki~|#|"
ResponseInfo.getCode（）取到的返回内容意义如下：
0：
调用成功
-1：
调用失败
调用需求:
class:
MBoxClient
requestPlayerInfo（）
获取部分其他玩家战况信息,提供给当前玩家进行挑战。
publicvoidrequestPlayerInfo（inttype,intsize,intwithDataValue）
参数说明:
Type:
表示取得的战况列表类型0：
未知
1：
好友
2：
仇家
3：
相近
4：
榜单用户（高手）
size：
表示取多少条，返回的可能等于这个，也可能少于这个，不会多于这个
withDataValue:
返回的PlayerInfo信息是否带上dataValue内容,0:
不带，1：
带
返回值:
无
描述:
调用该函数会进行联网操作。
不进入联网模块页面。
该函数用于获取与当前登录用户相关的一些PlayerInfo信息，外部调用方可一次性获取一些指定的PlayerInfo信息，然后选择集中展示，或轮播的方式推给用户。
并可以直接挑战对方。
通过回调接口InfoListener（notify方法）返回服务器响应,具体参InfoListener说明。
只有在得到服务器响应之后才可以从缓存中取得PlayerInfo数据，使用的方法是getPlayersInfo（）。
ResponseInfo.getCode（）取到的返回内容意义如下：
0：
调用成功
-1：
调用失败
调用需求:
class:
MBoxClient
joinChallenge（）
参加挑战。
publicvoidjoinChallenge（StringoppUin,StringdataKey,intoppScore）
参数说明:
oppUin:
挑战对手的ID号
dataKey:
游戏的私有数据，例如某赛道，某音乐等
oppScore:
挑战对手的分数
返回值:
无
描述:
调用该函数会进行联网操作，并进入联网模块页面。
如果用户处于未登录状态，会进入登录页面；如果用户已处于登录状态，会自动返回原游戏中，并通过InfoListener接口的notify（）方法返回服务器响应。
通过回调接口InfoListener（notify方法）的回调取得服务器响应数据,具体参考InfoListener和ResponseInfo说明。
ResponseInfo.getCode（）取到的返回内容意义如下：
0:
参加挑战成功
-1:
参加挑战失败，上次挑战未完成
-2:
参加挑战失败，后台接口异常或超时
-3:
参加挑战失败，网络异常
-4:
参加挑战失败，其他未知错误或异常
调用需求:
class:
MBoxClient
giveUpChallenge（）
放弃当前的挑战。
publicintgiveUpChallenge（StringoppUin）
参数说明:
oppUin:
正在挑战的对手UIN
返回值:
无
描述:
调用该函数会进行联网操作，并进入联网模块页面。
在游戏中放弃挑战。
一个可能的场景是用户在游戏中的Feed看到其他玩家的战况信息，点击挑战，发现挑战失败，于是，我们可以获取该玩家正在挑战的对手，并放弃当前挑战，这样才可以进行挑战新的对手。
如果用户处于未登录状态，会进入登录页面；如果用户已处于登录状态，会自动返回原游戏中，并通过InfoListener接口的notify（）方法返回服务器响应。
通过回调接口InfoListener（notify方法）的回调取得服务器响应数据,具体参考InfoListener和ResponseInfo说明。
ResponseInfo.getCode（）取到的返回内容意义如下：
0：
放弃成功
-1：
放弃失败，该用户没有挑战的对手
-2：
放弃失败，后台接口异常或超时
-3：
放弃失败，网络异常
-4：
放弃失败，其他未知错误或异常
调用需求:
class:
MBoxClient
uploadUserData（）
该函数用于上传用户数据，包括：
游戏积分，挑战对手，对手分数，私有数据，扩展数据等。
调用方可根据游戏特点，灵活选择参数进行上传。
publicstaticvoiduploadUserData（
intcurScore,
StringoppUin,
intoppScore,
intwinner,
StringdataKey,
StringdataValue,
StringextInfo）
参数说明:
curScore:
当前玩家在游戏中的积分值（CP注意，用户游戏得分大于0，才给用户提供上传，如果用户游戏玩的差，最终得的是0分，则不提供积分上传功能给他们）
oppUin:
对手的伪QQ号码，（如果没有挑战谁，则用空串“”）
OppScore:
对手的分数，（如果没有挑战谁，则用0分）
Winner:
如果有挑战谁，表示自己胜利还是失败
0自动判断（服务器根据分数判断，）
1：
挑战者胜利
2：
挑战者失败
dataKey:
上传积分时，可选的私有数据Key值
dataValue:
上传积分时，可选的私有数据Value值
extInfo:
通用的附加扩展信息，可以上传成就，装备，奖励等游戏中特有东西，并会在Feed中传播。
字符串格式：
类型:
名称|类型:
名称
其中多个内容分隔符为竖线”|”,类型和名称分隔符为冒号”:
”,分隔符均为半角符号，为避免格式错乱，类型和名称本身不可包含上述两个分隔符。
支持的类型：
1：
成就【示例：
1:
富甲天下】
2：
装备【示例：
2:
青龙宝刀】
4：
奖励【示例：
4：
金币100个】
255:
其他，特殊类型不属于上面类别或者不希望系统的解析，希望使用纯文字来描述的物品或方法【示例：
255：
青龙宝刀一把】
示例1：
extInfo=”1:
富甲天下”
Feed内容可能为：
（1小时前）在游戏XXXX中获得了xxxx分！
并得到成就【富甲天下】
示例2：
extInfo=”1:
富甲天下|2:
青龙宝刀”
Feed内容可能为：
（1小时前）在游戏XXXX中获得了xxxx分！
并得到成就【富甲天下】、装备【青龙宝刀】
如果你不想系统加上成就，装备等字样，可以用255类型来传，但是一定要保证Feed信息的可读性。
示例3
extInfo=”255:
富甲天下成就|255:
青龙宝刀一把”
Feed内容可能为：
（1小时前）在游戏XXXX中获得了xxxx分！
并得到富甲天下成就、青龙宝刀一把
注意事项：
1，请完全按照指定格式传送字符，并详细测试各种可能的组合。
2，单个成就，装备名称请注意表述清晰简洁，控制在5个汉字左右为佳。
3，用户一次上传积分时，附加信息不易过多，1~2个为宜，字数太多一方面影响界面的美观，另一方面可能会造成Feed读写失败，影响用户体验。
返回值:
无
描述:
调用该函数会进行联网操作，并进入联网模块页面。
本函数是用来上传积分或挑战等其他相关信息。
如果用户处于未登录状态，会跳转到模块的登录页面；如果用户已处于登录状态，会自动返回原游戏中，并通过InfoListener接口的notify（）方法返回服务器响应。
通过回调接口InfoListener（notify方法）的回调取得服务器响应数据,具体参考InfoListener和ResponseInfo说明。
ResponseInfo.getCode（）取到的返回内容意义如下：
0：
上传成功
-1：
上传失败
调用需求:
class:
MBoxClient
支付功能
*****************************************************************
支付流程说明：
用户在游戏中选择了商品和支付方式，确认支付后如果用户没有登录则会跳转到模块的登录验证页面，登录验证成功后才会成功发送支付请求到Server，模块一收到Server应答就会跳转回游戏界面，同时模块回调InfoListener接口。
*****************************************************************
unifyPay
支付函数
publicvoidunifyPay（intpayType,
intamount,
StringgoodsID,
Stringgoodsname,
StringextInfo）
参数说明:
payType
升级会员 