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

Posted 2020-08-28

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了高效率完成一次接入80个手游渠道SDK——游戏接入SDK服务端篇相关的知识，希望对你有一定的参考价值。

1 概要
通常，游戏开发商并不会只在一个渠道上线他们的游戏，接入越多的渠道，代表着可能获取越多的用户，但同时也代表着越多的接入SDK工作量、工期和费用。一款游戏要有足够的用户，甚至需要接入30家以上的各种渠道，以保障自己的市场覆盖率。

单个SDK接入流程在一位有经验的全职客户端程序、一位全职服务端程序员、一位全职QA处理的情况下，需要3天时间才能完成。因此当一款产品面对30个甚至更多不同需求的渠道SDK时，人员成本和时间成本就会急剧增加。所以我们需要一个通用接口，来处理各种渠道的需求，这就是统一渠道SDK接入框架。

本部分主要提供平台SDK服务器与CP方游戏服务器交互的接口规范

1.2 支付基本流程

1.2.1 渠道支付流程

游戏客户端在每次用户点击购买时向服务端请求生成内部订单。并需要采用特定机制（例如一定时间内禁止连续点击购买）防止用户频繁操作对服务器造成过高负载。

游戏服务端生成的所有内部订单需要存储待查。并在得到渠道返回的外部订单后异步处理发货操作并以特定机制通知客户端更新数据显示。

渠道支付接口负责完成货币交易操作，生成并存储外部订单，供对账查询使用。

SDK服务端转发请求时额外存储一份订单日志数据，存储内部订单号，外部订单号及订单状态，供对账及查找BUG时作为参考。

1.2.2 一般渠道支付流程图

技术分享

1.3 协议说明

1.3.1 通信协议

SDK服务器采用HTTP协议作为通信协议，游戏服务器通过构造HTTP请求（POST方式）向SDK服务器发起接口请求。

1.3.2 数据协议

1.数据格式

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

2.字符编码

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

3.签名规则

请求和响应中的签名均使用md5哈希进行，算法如下：

MD5(签名内容 + ”|” + apiKey)

说明：

·MD5使用RFC1321标准，编码后需转换成全小写。

·描述签名的表达式中，”+”表示做字符串连接，实际产生的待签名字符串中并不存在。

·签名内容指各接口请求数据中若干字段的拼接。基本格式为各字段值以 ”|” 符号分隔后直接连接。注意，由于”|”符号用作分隔字段，签名内容中需避免出现该符号，换行符(回车或换行)等特殊符号也需要预先剔除。如果对应字段为空，仍然需要保留“|”符号占位。

·计算MD5签名时，应以UTF8编码取字符串的字节值。

·appid及apiKey由打包工具分配，打包工具使用方法请参考使用文档。

4.签名示例

假设请求数据为：

“data:{

“id” : 123,

“name” : “test”

“value” : “something”

“other” : “blarblar”

}

要求的签名内容为:

id + name + value

则拼接后得出要签名的内容串为

123|test|something

假定apiKey=aabbcc，则需要进行MD5哈希的字符串为：

123|test|something|aabbcc

1.4 接口说明

1.4.1 用户会话验证

1.请求地址：http://TypeSDK:PORT/{appid}/{channelid}/Login/

说明：URL中的{appid}代表游戏代码，由打包工具生成，{channelid}代表渠道代码，渠道代码列表可以参考打包工具说明，可以从客户端提交的参数中获取当前渠道代码。

例： http://192.168.0.1:40000/1000/1/Login/

2.调用方式：HTTP POST

3.接口描述：

验证用户登录结果。

A) 游戏客户端通过SDK客户端的登录动作获取用户登录信息。

B) 游戏客户端将获取的用户登录信息传送至游戏服务端。

C) 游戏服务端通过本请求将用户登录信息传送到SDK服务端，验证该登录信息是否有效。

D) SDK服务端返回验证结果及其他信息，供游戏服务器使用。

4.请求方：游戏服务端

5.响应方：SDK服务端

6.请求内容（JSON格式）：

字段名称	字段说明	类型	备注
id	用户唯一标识	string	对应渠道的用户ID。并非必传，未作说明的情况下传空字符串。
token	用户登录会话标识	string	本次登录标识。并非必传，未作说明的情况下传空字符串。
data	附加信息	JSON	附加信息。并非必传，根据渠道不同，该字段含义不同，未作说明的情况下传空字符串。
sign	签名参数	string	MD5(签名内容 + ”\|” + apiKey) 签名内容： Id + ”\|” + token + ”\|” + data

7.返回内容（JSON格式）：

字段名称	字段说明	类型	备注
code	响应码	int	本次请求结果标志
id	用户唯一标识	string	对应渠道的用户ID
nick	用户在渠道的昵称	string	对应渠道的用户昵称
token	用户登录会话标识	string	本次登录标识
msg	响应信息	string	如果请求出错，描述错误信息。
value	渠道返回信息	JSON	渠道返回的原始结果信息。

响应码说明：

0：渠道正常返回，结果成功

1：渠道正常返回，结果失败

2：渠道服务端请求错误

-1：提交的请求参数错误

-2：提交的请求转换成渠道参数错误

-3：提交的请求参数签名错误

-99：未知错误

id,nick,token说明：

根据不同渠道定义的返回字段不同，此三个字段不一定有值。渠道未返回对应字段时，该字段值为空字符串。

1.4.2 充值结果回调

1.请求地址：

该地址为充值结果通知地址，由游戏服务端在下文的SaveOrder接口中通过notifyurl字段提交至SDK服务端。

2.调用方式：HTTP POST

3.接口描述：

通知用户充值结果。

A) 用户在游戏中向SDK客户端提交充值请求。

B) SDK客户端将充值请求转发渠道方

C) 渠道方异步执行充值。

D) 渠道方将充值结果发送给SDK服务端

E) SDK服务端通过该接口将充值结果发送给游戏服务端。

F) 游戏服务端处理充值逻辑。

G) 游戏服务端向SDK服务端返回处理结果。

H) SDK服务端向渠道方返回处理结果。

4.请求方：SDK服务端

5.响应方：游戏服务端

6.请求内容（JSON格式）：

字段名称	字段说明	类型	备注
code	响应码	int	渠道返回的充值结果。
id	用户唯一标识	string	对应渠道的用户ID。
order	渠道订单号	string	渠道返回的订单号。
cporder	CP订单号	string	游戏客户端在提交订单时传送的内部订单号。如果该渠道未接收该参数，则该字段为空字符串。
info	订单附加信息	string	游戏客户端在提交订单时传送的附加信息。如果该渠道未接收该参数，则该字段为空字符串。
sign	签名参数	string	MD5(签名内容 + ”\|” + apiKey) 签名内容： code + ”\|” + id + ”\|” + order+ ”\|” + cporder + ”\|” + info
amount	订单金额	string	该笔订单价值折算为人民币的金额（以分为单位）供服务端校验使用，不参与签名。

7.返回内容（JSON格式）：

字段名称	字段说明	类型	备注
code	响应码	int	本次请求结果标志
msg	响应信息	string	如果请求出错，描述错误信息。

响应码说明：

0：正常返回，结果成功

1：正常返回，结果失败

-99：未知错误

8.推荐处理方式

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

1.4.3 充值信息提交

1.请求地址：http://TypeSDK:PORT/{appid}/{channelid}/SaveOrder/

说明：URL中的{appid}代表游戏代码，由打包工具生成，{channelid}代表渠道代码，渠道代码列表可以参考打包工具文档，可以从客户端提交的参数中获取当前渠道代码。

例： http://192.168.0.1:40000/1000/1/SaveOrder/

2.调用方式：HTTP POST

3.接口描述：

充值信息存档待查。

A) 用户在游戏中向游戏服务端提交充值请求。

B) 游戏服务端生成内部充值订单号及相关充值信息

C) 游戏服务端将内部充值订单号及相关充值信息返回游戏客户端，供其提交给渠道方。

D) 游戏服务端异步将内部充值订单号，该笔订单回调url及相关充值信息发送给SDK服务端。

E) SDK服务端将充值信息存档待查并返回处理结果。

4.请求方：游戏服务端

5.响应方：SDK服务端

6.请求内容（JSON格式）：

字段名称	字段说明	类型	备注
cporder	CP订单号	string	游戏客户端在提交订单时传送的内部订单号。
data	订单信息	string	由CP生成订单时自定义的附加信息,不能为空及空字符串。
sign	签名参数	string	MD5(签名内容 + ”\|” + apiKey) 签名内容： cporder + ”\|” + data
notifyurl	订单回调url	string	该笔订单回调通知游戏服务端的url，不参与签名。
verifyurl	订单查询url	string	该笔订单向游戏服务端查询详情的url，不参与签名。

7.返回内容（JSON格式）：

字段名称	字段说明	类型	备注
code	响应码	int	本次请求结果标志
msg	响应信息	string	如果请求出错，描述错误信息。

响应码说明：

0：正常返回，存档成功

1：正常返回，存档失败

-1：系统错误

-2：参数错误

-3：签名校验错误

-99：未知错误

注意：SaveOrder接口在服务端生成内部订单号时请求。只有获取到该请求成功返回，才能允许客户端作后续充值动作。

1.4.4 充值信息确认

1.请求地址：http://TypeSDK:PORT/{appid}/{channelid}/CheckOrder/

例： http://192.168.0.1:40000/1000/1/CheckOrder/

2.调用方式：HTTP POST

3.接口描述：

充值信息查询。

A) SDK服务端向游戏服务端转发充值结果回调。

B) 游戏服务端向SDK发送充值信息查询请求，目的是确认该充值结果有效性。

C) SDK服务端根据提交的内部充值订单号查询充值信息并返回游戏服务端。

D) 游戏服务端根据查询结果进行逻辑处理。

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

4.请求方：游戏服务端

5.响应方：SDK服务端

6.请求内容（JSON格式）：

字段名称

字段说明

类型

备注

cporder

CP订单号

string

游戏客户端在提交订单时传送的内部订单号。

sign

签名参数

string

MD5(签名内容 + ”|” + apiKey)

签名内容：

cporder

7.返回内容（JSON格式）：

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

响应码说明：

0：正常返回，获取订单信息成功

1：正常返回，没有获取到订单信息

2：正常返回，获取订单信息错误

-1：系统错误

-2：参数错误

-3：签名校验错误

-99：未知错误

1.4.5 游戏订单查询

1.请求地址：

该地址为订单查询地址，在SaveOrder接口中通过verifyurl字段提交至SDK服务端。

2.调用方式：HTTP POST

3.接口描述：

SDK服务端向游戏服务端查询收到的订单信息。

A) 用户在游戏中向SDK客户端提交充值请求。

B) SDK客户端将充值请求转发渠道方

C) 渠道方异步执行充值。

D) 渠道方将充值结果发送给SDK服务端

E) SDK服务端通过该接口向游戏服务端查询该充值请求是否合法。

F) 游戏服务端处理查询逻辑。

G) 游戏服务端向SDK服务端返回查询结果。

H) SDK服务端比对订单信息并依此确定下一步处理流程。

4.请求方：SDK服务端

5.响应方：游戏服务端

6.请求内容（JSON格式）：

字段名称	字段说明	类型	备注
code	操作类型	string	预留字段，区分本次查询操作类型。目前统一传0
id	用户唯一标识	string	对应渠道的用户ID。
order	渠道订单号	string	渠道返回的订单号。
cporder	CP订单号	string	游戏客户端在提交订单时传送的内部订单号。如果该渠道未接收该参数，则该字段为空字符串。
info	订单附加信息	string	游戏客户端在提交订单时传送的附加信息。如果该渠道未接收该参数，则该字段为空字符串。
sign	签名参数	string	MD5(签名内容 + ”\|” + apiKey) 签名内容： code + ”\|” + id + ”\|” + order+ ”\|” + cporder + ”\|” + info

7.返回内容（JSON格式）：

字段名称	字段说明	类型	备注
code	响应码	int	本次请求结果标志
msg	响应信息	string	如果请求出错，描述错误信息。
id	用户唯一标识	string	对应渠道的用户ID。
order	渠道订单号	string	渠道返回的订单号。
cporder	CP订单号	string	游戏客户端在提交订单时传送的内部订单号。如果该渠道未接收该参数，则该字段为空字符串。
amount	订单金额	string	该笔订单价值折算为人民币的金额（以分为单位）。
createtime	订单创建时间	string	该笔订单创建时间。
Itemid	道具id	string	该笔订单的道具id，如果没有传空字符串。 (该字段标识订单中的商品ID，需要与客户端下订单时对应的字段匹配，验证对比不符时不发货)
Itemquantity	道具数量	Int	该笔订单道具数量，没有传0。（该字段标识客户端提交的订单中的道具数量，渠道不接受该字段时，客户端提交的订单没有该字段，此时直接传0或1均可）
status	订单状态	int	订单状态码。
info	其他信息	string	备用字段，传送其他可供比对的信息。