更新时间:2017-2-22

TypeSDK服务端聚合原理


相对TypeSDK客户端和打包工具,TypeSDK服务器端聚合原来相对简单,即使用一套标准接口完成与游戏服务端的对接,并判读每个请求的渠道标识完成与各个渠道服务端的对接。因为服务端不区分Andorid与iOS,故只每款游戏只需要一套服务端环境。

服务端接入准备工作


TypeSDK服务端接入需要服务端与客户端配合完成,请与接入前与客户端SDK接入程序员做好充分沟通工作。

您可能需要了解以下参数,请与TypeSDK聚合工具部署配置人员及客户端开发人员联系协商获取。

  1. 通讯密钥(gkey),用以签名游戏服务器与聚合服务器之间的通讯请求。需同时配置于游戏服务端和打包工具中。
  2. 聚合服务器IP和服务端口,您通过拼接游戏客户端发送请求中携带的cp_id、channel_id,以获取您向聚合服务器请求的URL地址。例:登录验证URL http://[聚合服务器IP]:[端口]/[cp_id]/[channel_id]/Login
  3. 渠道编号(channel_id) 由打包工具在渠道参数中配置,并同时保存于游戏客户端配置文件中,聚合SDK客户端提供接口查询channe_id,游戏服务端需要使用时由游戏客户端将channel_id包含在请求内发送。
  4. 游戏编号(cp_id或也称之为game_id) 由打包工具在渠道参数中配置,并同时保存于游戏客户端配置文件中,并提供客户端接口查询cp_id,游戏服务端需要使用时由游戏客户端将cp_id包含在请求内发送。因为cp_id对游戏来说不会变化,也可配置于游戏服务端配置文件中,以便游戏直接获取。
  5. token在客户端登录回调中提供,用以向渠道接口进行用户登录验证,需要将token包含在游戏客户端登录验证请求内发送至游戏服务端。
  6. user_id在游戏服务器通过token进行登录验证响应返回结果中获取。需要游戏服务端在游戏客户端登录token验证响应内结果返回,以备在游戏客户端提交用户信息接口使用。
  7. access_token在游戏服务器通过token进行登录验证响应返回结果中获取,如果返回为空则此渠道不使用access_token。需要游戏服务端在游戏客户端登录token验证响应内结果返回,以备在游戏客户端提交用户信息接口使用。
  8. 了解SDK相关事件的流程顺序

协议说明


一、通讯协议

SDK服务器采用HTTP协议作为通信协议,游戏服务器通过构造HTTP请求(POST JSON方式)向SDK服务器发起接口请求。虽然我们也保留了GET请求,但只作为在线活跃检测使用。

二、数据协议

1. 数据格式

请求消息和响应消息的内容都使用JSON表示数据。

2. 字符编码

请求与相应内容均采用UTF-8字符编码。

3. 签名规则

请求和响应中的签名均使用md5哈希进行,算法如下: MD5(签名内容 + ”|” + gKey) 说明: MD5使用RFC1321标准,编码后需转换成全小写。 描述签名的表达式中,”+”表示做字符串连接,实际产生的待签名字符串中并不存在。 签名内容指各接口请求数据中若干字段的拼接。基本格式为各字段值以 ”|” 符号分隔后直接连接。注意,由于”|”符号用作分隔字段,签名内容中需避免出现该符号,换行符(回车或换行)等特殊符号也需要预先剔除。如果对应字段为空,仍然需要保留“|”符号占位。 计算MD5签名时,应以UTF8编码取字符串的字节值。 gKey由打包工具分配,打包工具使用方法请参考使用文档。 范例: 假设请求数据为: “data:{ “id” : 123, “name” : “test” “value” : “something” “other” : “blarblar” } 要求的签名内容为: id + name + value 则拼接后得出要签名的内容串为 123|test|something 假定gKey=aabbcc,则需要进行MD5哈希的字符串为: 123|test|something|aabbcc

在服务端配置渠道参数


如何同步打包工具和服务端参数

接口说明


一、用户会话token验证(必接)

1.请求地址:http://{typesdk_server_ip}:40000/{cp_id}/{channel_id}/Login/ 官方接入调试地址:http://demo.typesdk.com:40000/1001/{channel_id}/Login/ 2.调用方式:HTTP POST 3.接口描述: 4.请求方:游戏服务端 5.响应方:SDK服务端 6.请求内容(JSON格式):
字段名称 字段说明 类型 备注
id 用户唯一标识 string 对应渠道的用户ID。并非必传,未作说明的情况下传空字符串。
token 用户登录会话标识 string 本次登录标识。并非必传,未作说明的情况下传空字符串。
data 附加信息 JSON 附加信息。并非必传,根据渠道不同,该字段含义不同,未作说明的情况下传空字符串。
sign 签名参数 string MD5(签名内容 + ”|” + gKey)签名内容: Id + ”|” + token + ”|” + data
7.返回内容(JSON格式):
字段名称 字段说明 类型 备注
code 响应码 int 本次请求结果标志
id 用户唯一标识 string 对应渠道的用户ID
nick 用户在渠道的昵称 string 对应渠道的用户昵称
token 用户登录会话标识 string 本次登录标识
msg 响应信息 string 如果请求出错,描述错误信息。
value 渠道返回信息 JSON 渠道返回的原始结果信息。
id,nick,token说明:
根据不同渠道定义的返回字段不同,此三个字段不一定有值。渠道未返回对应字段时,该字段值为空字符串。
要求服务端务必将此三个字段,传递至客户端,并要求客户端在SDK上传用户信息时,传入此三个字段。否则可能造成部分渠道无法支付

二、服务端支付下单接口(必接)

1.请求地址:http://192.168.0.1:3000/{cp_id}/{channel_id}/SaveOrder/ 官方接入调试地址:http://demo.typesdk.com:40000/1001/{channel_id}/SaveOrder/ 说明:URL中的{cp_id}代表游戏代码,{channelid}代表渠道代码,客户端可在过初始化回调返回值中获取cp_id和channel_id。并在提交游戏服务器的请求中包含cp_id和channel_id,由游戏服务器最终拼接出请求地址。 例: http://192.168.0.1:3000/1000/1/SaveOrder/ 2.调用方式:HTTP POST 3.接口描述: 4.请求方:游戏服务端 5.响应方:SDK服务端 6.请求内容(JSON格式):
字段名称 字段说明 类型 备注
cporder CP订单号 string 游戏客户端在提交订单时传送的内部订单号。需要保证全局唯一,长度小于12位,由字母数字组成。
data 订单信息 string {"itemid":"100123", "itemname":"60钻石", "price":"600"}必须包含itemid、itemname、price(单位:分)三个参数,并确保与游戏客户端提交的一致。
sign 签名参数 string MD5(签名内容 + ”|” + gKey)签名内容: cporder + ”|” + data
notifyurl 订单回调url string 该笔订单回调通知游戏服务端的url,不参与签名。
verifyurl 订单查询url string 该笔订单向游戏服务端查询详情的url,不参与签名。(可选,如不使用则传入空字符串,支付流程将跳过verify步骤)
uid 渠道用户ID string 该笔订单的发起用户ID,注意此处需传登录时返回的id字段,即渠道用户ID,不参与签名。(可选,如不使用则传入空字符串,该字段关系到后台统计功能,如不传该字段,统计时将无法精确到具体用户的支付数据,只能统计支付总额)
7.返回内容(JSON格式):
字段名称 字段说明 类型 备注
code 响应码 int 本次请求结果标志
msg 响应信息 string 如果请求出错,描述错误信息。
注意:SaveOrder接口在服务端生成内部订单号时请求。只有获取到该请求成功返回,才能允许客户端作后续充值动作。

三、游戏订单查询verify (选接)

1.请求地址: 该地址为游戏订单查询地址,由游戏服务器实现,在SaveOrder接口中通过verifyurl字段提交至SDK服务端。 2.调用方式:HTTP POST 3.接口描述: 在接收到游戏服务器提交订单信息,以及渠道支付成功回调消息后,SDK服务器会通过此接口向游戏服务器核实订单真实性。 4.请求方:SDK服务端 5.响应方:游戏服务端 6.请求内容(JSON格式):
字段名称 字段说明 类型 备注
code 操作类型 string 预留字段,区分本次查询操作类型。目前统一传0
id 用户唯一标识 string 对应渠道的用户ID。
order 渠道订单号 string 渠道返回的订单号。游戏服务器需判断此渠道订单号是否重复。
cporder CP订单号 string 游戏内部订单号。游戏服务器需判断内部订单号是否存在。
info 订单附加信息 string 渠道提供的额外信息,有时为空。仅供日志记录。
sign 签名参数 string MD5(签名内容 + ”|” + gKey) 签名内容:code + ”|” + id + ”|” + order+ ”|” + cporder + ”|” + info
7.返回内容(JSON格式):
字段名称 字段说明 类型 备注
code 响应码 int 本次请求结果标志
msg 响应信息 string 如果请求出错,描述错误信息。
id 用户唯一标识 string 对应渠道的用户ID。SDK服务器不对此信息进行核对。
order 渠道订单号 string 渠道返回的订单号。SDK服务器不对此信息进行核对
cporder CP订单号 string 游戏客户端在提交订单时传送的内部订单号。SDK服务器将核对是否与请求的订单相同。
amount 订单金额 string 该笔订单价值折算为人民币的金额(以分为单位)。SDK服务器将核对与渠道返回金额是否匹配。
createtime 订单创建时间 string 该笔订单创建时间。SDK服务器不对此信息进行核对
Itemid 道具id string 该笔订单的道具id。SDK服务器不对此信息进行核对
Itemquantity 道具数量 Int 该笔订单道具数量,SDK服务器不对此信息进行核对。
status 订单状态 int 游戏内订单状态,1正常 0拒绝发货退款。
info 其他信息 string 备用字段,目前未使用。
8.推荐处理方式 游戏服务端收到该请求后优先以CP订单号为条件查询,查询不到或请求中没有CP订单号时以渠道订单号为条件查询,找到匹配的订单信息并同步返回SDK服务端。

四、服务端支付结果回调(必接)

游戏服务器常规支付回掉处理.png

常规游戏支付回调处理逻辑中,通常需要在渠道后台填写一个游戏接收支付回调地址。游戏需要针对不同渠道开发多套支付回调接口来接收各个渠道的支付回调,多渠道协议和多游戏服务器是主要面对的问题。

TypeSDK聚合支付回调处理模式一.png

如果您的游戏还没有设计开发游戏的支付服务,建议您使用此模式,TypeSDK聚合服务器已经完成了支付服务器的所有功能。

TypeSDK聚合支付回调处理模式二.png

如果您的游戏已经完成了支付服务的开发工具,您可以选择模式二,在游戏支付服务器中添加聚合支付回调接口及提交订单信息请求。以保证游戏服务端架构变动最小。 1.请求地址:

该地址为游戏服务器接收充值结果通知地址,由游戏服务端实现,并在每一次订单中通过提交订单信息接口SaveOrder中notifyurl字段提交至SDK服务端。

2.调用方式:HTTP POST

3.接口描述:

4.请求方:SDK服务端

5.响应方:游戏服务端

6.请求内容(JSON格式):

字段名称 字段说明 类型 备注
code 响应码 int 渠道返回的充值结果。
id 用户唯一标识 string 对应渠道的用户ID。
order 渠道订单号 string 渠道返回的渠道对账订单号。
cporder CP订单号 string 游戏客户端在提交订单(SaveOrder)时发送的游戏内部订单号。
info 订单附加信息 string 游戏客户端在提交订单时传送的附加信息。如果该渠道未接收该参数,则该字段为空字符串。
sign 签名参数 string MD5(签名内容 + ”|” + gKey)签名内容: code + ”|” + id + ”|” + order+ ”|” + cporder + ”|” + info
amount 订单金额 string 该笔订单价值折算为人民币的金额(以分为单位)供服务端校验使用,不参与签名。
  7.返回内容(JSON格式):
字段名称 字段说明 类型 备注
code 响应码 int 本次请求结果标志
msg 响应信息 string 如果请求出错,描述错误信息。

8.推荐处理方式

游戏服务端收到该请求后可保存该次请求参数,随即返回code=0,表明成功收到消息。之后异步处理充值或发放道具逻辑。

五、充值信息确认(选接)

1.请求地址:http://192.168.0.1:3000/{cp_id}/{channel_id}/CheckOrder/

说明:URL中的{cp_id}代表游戏代码,{channelid}代表渠道代码,客户端可在过初始化回调返回值中获取cp_id和channel_id。并在提交游戏服务器的请求中包含cp_id和channel_id,由游戏服务器最终拼接出请求地址。

例: http://192.168.0.1:3000/1000/1/CheckOrder/

2.调用方式:HTTP POST

3.接口描述:

说明:部分渠道提供信息查询接口,本接口将优先使用渠道的信息查询接口处理请求。如果该渠道没有提供信息查询接口,则查询 3.3.3 充值信息提交 接口中保存的充值信息,如果创建充值信息时没有调用该接口,或者没有查询到目标订单对应的充值信息,则会返回未查询到相应充值信息。

4.请求方:游戏服务端

5.响应方:SDK服务端

6.请求内容(JSON格式):

字段名称 字段说明 类型 备注
cporder CP订单号 string 游戏客户端在提交订单时传送的内部订单号。
sign 签名参数 string MD5(签名内容 + ”|” + gKey)签名内容:

cporder

7.返回内容(JSON格式):

字段名称 字段说明 类型 备注
code 响应码 int 本次请求结果标志
msg 响应信息 string 如果请求出错,描述错误信息。
value 订单详细信息 JSON 根据渠道不同,返回相应订单信息。

约定


  • 支付相关接口内部订单号字段长度不能超过10位,格式使用英文字母和数字的组合,需要能够区分区服。不可重复。
  • 渠道返回的用户id用于用户唯一标识。单区服内不可重复。
  • 支付接口返回的amount是当次支付产生的实际金额。
  • 游戏客户端在每次用户点击购买时向服务端请求生成内部订单。并需要采用特定机制(例如一定时间内禁止连续点击购买)防止用户频繁操作对服务器造成过高负载。