高效率完成一次接入80个手游渠道SDK——游戏接入SDK服务端篇

[align=left][color=#555555][font="][size=15px].1 概要 通常，游戏开发商并不会只在一个渠道上线他们的游戏，接入越多的渠道，代表着可能获取越多的用户，但同时也代表着越多的接入SDK工作量、工期和费用。一款游戏要有足够的用户，甚至需要接入30家以上的各种渠道，以保障自己的市场覆盖率。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]单个SDK接入流程在一位有经验的全职客户端程序、一位全职服务端程序员、一位全职QA处理的情况下，需要3天时间才能完成。因此当一款产品面对30个甚至更多不同需求的渠道SDK时，人员成本和时间成本就会急剧增加。所以我们需要一个通用接口，来处理各种渠道的需求，这就是统一渠道SDK接入框架。 本部分主要提供平台SDK服务器与CP方游戏服务器交互的接口规范[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]1.2 支付基本流程[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]1.2.1 渠道支付流程[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]游戏客户端在每次用户点击购买时向服务端请求生成内部订单。并需要采用特定机制（例如一定时间内禁止连续点击购买）防止用户频繁操作对服务器造成过高负载。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]游戏服务端生成的所有内部订单需要存储待查。并在得到渠道返回的外部订单后异步处理发货操作并以特定机制通知客户端更新数据显示。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]渠道支付接口负责完成货币交易操作，生成并存储外部订单，供对账查询使用。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] SDK服务端转发请求时额外存储一份订单日志数据，存储内部订单号，外部订单号及订单状态，供对账及查找BUG时作为参考。[/size][/font][/color][/align] [align=left][color=#555555][font="][size=15px]1.2.2 一般渠道支付流程图[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px][img=805,100]https://static.oschina.net/uploads/img/201701/17172344_nyWQ.png[/img][/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]1.3 协议说明[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]1.3.1 通信协议[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] SDK服务器采用HTTP协议作为通信协议，游戏服务器通过构造HTTP请求（POST方式）向SDK服务器发起接口请求。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]1.3.2 数据协议[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]1.数据格式[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 请求消息和响应消息的内容都使用JSON表示数据。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]2.字符编码[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 请求与相应内容均采用UTF-8字符编码[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]3.签名规则[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 请求和响应中的签名均使用md5哈希进行，[color=rgb(223, 52, 52)][b]算法[/b][/color]如下：[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] MD5(签名内容 + ”|” + apiKey)[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 说明：[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] ·MD5使用RFC1321标准，编码后需转换成全小写。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] ·描述签名的表达式中，”+”表示做字符串连接，实际产生的待签名字符串中并不存在。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] ·签名内容指各接口请求数据中若干字段的拼接。基本格式为各字段值以 ”|” 符号分隔后直接连接。注意，由于”|”符号用作分隔字段，签名内容中需避免出现该符号，换行符(回车或换行)等特殊符号也需要预先剔除。如果对应字段为空，仍然需要保留“|”符号占位。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] ·计算MD5签名时，应以UTF8编码取字符串的字节值。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] ·appid及apiKey由打包工具分配，打包工具使用方法请参考使用文档。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]4.签名示例[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 假设请求数据为：[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] “data:{[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] “id” : 123,[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] “name” : “test”[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] “value” : “something”[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] “other” : “blarblar”[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] }[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 要求的签名内容为:[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]id + name + value[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]则拼接后得出要签名的内容串为[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]123|test|something[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]假定apiKey=aabbcc，则需要进行MD5哈希的字符串为：[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]123|test|something|aabbcc [/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]1.4 接口说明[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]1.4.1 用户会话验证[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]1.请求地址：[color=rgb(12, 137, 207)]http://TypeSDK:PORT/{appid}/{channelid}/Login/[/color][/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 说明：URL中的{appid}代表游戏代码，由打包工具生成，{channelid}代表渠道代码，渠道代码列表可以参考打包工具说明，可以从客户端提交的参数中获取当前渠道代码。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 例： [color=rgb(12, 137, 207)]http://192.168.0.1:40000/1000/1/Login/[/color][/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]2.调用方式：HTTP POST[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]3.接口描述：[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 验证用户登录结果。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]A) 游戏客户端通过SDK客户端的登录动作获取用户登录信息。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]B) 游戏客户端将获取的用户登录信息传送至游戏服务端。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]C) 游戏服务端通过本请求将用户登录信息传送到SDK服务端，验证该登录信息是否有效。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]D) SDK服务端返回验证结果及其他信息，供游戏服务器使用。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]4.请求方：游戏服务端[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]5.响应方：SDK服务端[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]6.请求内容（JSON格式）：[/size][/font][/color][/align][table] [tr][td]字段名称 [/td][td]字段说明 [/td][td]类型 [/td][td]备注 [/td][/tr] [tr][td]id [/td][td]用户唯一标识 [/td][td]string [/td][td]对应渠道的用户ID。并非必传，未作说明的情况下传空字符串。 [/td][/tr] [tr][td]token [/td][td]用户登录会话标识 [/td][td]string [/td][td]本次登录标识。并非必传，未作说明的情况下传空字符串。 [/td][/tr] [tr][td]data [/td][td]附加信息 [/td][td]JSON [/td][td]附加信息。并非必传，根据渠道不同，该字段含义不同，未作说明的情况下传空字符串。 [/td][/tr] [tr][td]sign [/td][td]签名参数 [/td][td]string [/td][td]MD5(签名内容 + ”|” + apiKey) 签名内容： Id + ”|” + token + ”|” + data [/td][/tr] [/table] [align=left][color=#555555][font="][size=15px]7.返回内容（JSON格式）：[/size][/font][/color][/align][table] [tr][td]字段名称 [/td][td]字段说明 [/td][td]类型 [/td][td]备注 [/td][/tr] [tr][td]code [/td][td]响应码 [/td][td]int [/td][td]本次请求结果标志 [/td][/tr] [tr][td]id [/td][td]用户唯一标识 [/td][td]string [/td][td]对应渠道的用户ID [/td][/tr] [tr][td]nick [/td][td]用户在渠道的昵称 [/td][td]string [/td][td]对应渠道的用户昵称 [/td][/tr] [tr][td]token [/td][td]用户登录会话标识 [/td][td]string [/td][td]本次登录标识 [/td][/tr] [tr][td]msg [/td][td]响应信息 [/td][td]string [/td][td]如果请求出错，描述错误信息。 [/td][/tr] [tr][td]value [/td][td]渠道返回信息 [/td][td]JSON [/td][td]渠道返回的原始结果信息。 [/td][/tr] [/table][align=left][color=#555555][font="][size=15px] 响应码说明：[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 0：渠道正常返回，结果成功[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 1：渠道正常返回，结果失败[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 2：渠道服务端请求错误[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] -1：提交的请求参数错误[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] -2：提交的请求转换成渠道参数错误[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] -3：提交的请求参数签名错误[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] -99：未知错误[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]id,nick,token说明：[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 根据不同渠道定义的返回字段不同，此三个字段不一定有值。渠道未返回对应字段时，该字段值为空字符串。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]1.4.2 充值结果回调[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]1.请求地址：[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 该地址为充值结果通知地址，由游戏服务端在下文的SaveOrder接口中通过notifyurl字段提交至SDK服务端。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]2.调用方式：HTTP POST[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]3.接口描述：[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 通知用户充值结果。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]A) 用户在游戏中向SDK客户端提交充值请求。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]B) SDK客户端将充值请求转发渠道方[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]C) 渠道方异步执行充值。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]D) 渠道方将充值结果发送给SDK服务端[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]E) SDK服务端通过该接口将充值结果发送给游戏服务端。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]F) 游戏服务端处理充值逻辑。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]G) 游戏服务端向SDK服务端返回处理结果。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]H) SDK服务端向渠道方返回处理结果。[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]4.请求方：SDK服务端[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]5.响应方：游戏服务端[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]6.请求内容（JSON格式）：[/size][/font][/color][/align][table] [tr][td]字段名称 [/td][td]字段说明 [/td][td]类型 [/td][td]备注 [/td][/tr] [tr][td]code [/td][td]响应码 [/td][td]int [/td][td]渠道返回的充值结果。 [/td][/tr] [tr][td]id [/td][td]用户唯一标识 [/td][td]string [/td][td]对应渠道的用户ID。 [/td][/tr] [tr][td]order [/td][td]渠道订单号 [/td][td]string [/td][td]渠道返回的订单号。 [/td][/tr] [tr][td]cporder [/td][td]CP订单号 [/td][td]string [/td][td]游戏客户端在提交订单时传送的内部订单号。如果该渠道未接收该参数，则该字段为空字符串。 [/td][/tr] [tr][td]info [/td][td]订单附加信息 [/td][td]string [/td][td]游戏客户端在提交订单时传送的附加信息。如果该渠道未接收该参数，则该字段为空字符串。 [/td][/tr] [tr][td]sign [/td][td]签名参数 [/td][td]string [/td][td]MD5(签名内容 + ”|” + apiKey) 签名内容： code + ”|” + id + ”|” + order+ ”|” + cporder + ”|” + info [/td][/tr] [tr][td]amount [/td][td]订单金额 [/td][td]string [/td][td]该笔订单价值折算为人民币的金额（以分为单位）供服务端校验使用，不参与签名。 [/td][/tr] [/table][align=left][color=#555555][font="][size=15px] 7.返回内容（JSON格式）：[/size][/font][/color][/align][table] [tr][td]字段名称 [/td][td]字段说明 [/td][td]类型 [/td][td]备注 [/td][/tr] [tr][td]code [/td][td]响应码 [/td][td]int [/td][td]本次请求结果标志 [/td][/tr] [tr][td]msg [/td][td]响应信息 [/td][td]string [/td][td]如果请求出错，描述错误信息。 [/td][/tr] [/table] [align=left][color=#555555][font="][size=15px]响应码说明：[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 0：正常返回，结果成功[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px] 1：正常返回，结果失败[/size][/font][/color][/align][align=left][color=#555555][font="][size=15px]-99：未知错误[/size][/font][/color][/align]