单机联网模块CP接入规范V321.docx
- 文档编号:6953671
- 上传时间:2023-01-13
- 格式:DOCX
- 页数:30
- 大小:174.25KB
单机联网模块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
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 单机 联网 模块 CP 接入 规范 V321