文档章节

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

TypeSDK
 TypeSDK
发布于 2017/01/21 14:02
字数 4181
阅读 55
收藏 1

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/

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

       例: 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

备用字段,传送其他可供比对的信息。


响应码说明:

       0:正常返回,结果成功

       1:正常返回,结果失败

-99:未知错误

8.推荐处理方式

游戏服务端收到该请求后优先以CP订单号为条件查询,查询不到或请求中没有CP订单号时以渠道订单号为条件查询,找到匹配的订单信息并同步返回SDK服务端。

1.5 约定

l  支付相关接口内部订单号字段长度不能超过10位,格式使用英文字母和数字的组合,需要能够区分区服。不可重复。

l  渠道返回的用户id用于用户唯一标识。单区服内不可重复。

l  支付接口返回的amount是当次支付产生的实际金额。

项目已开源,大家有兴趣可以自己研究或使用接入
项目地址:https://code.csdn.net/typesdk_code
项目地址:https://github.com/typesdk

© 著作权归作者所有

TypeSDK

TypeSDK

粉丝 3
博文 18
码字总数 30285
作品 1
高级程序员
私信 提问
手游渠道 SDK 统一接入框架--TypeSDK

TypeSDK是一个开源的统一手游渠道SDK接入框架,拥有80个海内外渠道,具备简单接入、快速出包、运营工具、分权限管理、产品数据打点等功能。实施周版本更新制度,确保每个每个使用者直接下载就...

TypeSDK
2016/11/10
1K
0
TypeSDK 手游多渠道SDK新解决方案

经历了头两年的爆发之后,手游也和端游、页游一样,进入了一个利润变薄、产业整合的过渡期。除了那些自有渠道的大厂商,如何找到新的用户来源始终是中小CP面临的最大问题,解决办法目前看来只...

TypeSDK
2016/11/10
2
0
详析手游圈从业人员必须知道的行业术语

想要入行手游,首先就需要对整个行业有一个全面的认知。刚刚接触手游行业的时候,也许你会问,业内人士口中的CPS、CPA、APRU值、迭代、冲榜都是什么意思?今天,本文就从手游圈的术语讲起,带...

牵着蜗牛去西藏
2016/03/11
701
3
运筹帷幄,手游发行行业的破局之道

近年手游市场的全新业态,让大量手游从业者在凛冬里沐浴了一抹斜阳。手游发行领域更是有人欢喜有人愁,不少手游发行公司都是热热闹闹开场,冷冷清清收场。很多人说渠道接入并不是手游开发商的...

朱颜辞却花辞树
2017/07/15
0
0
那么问题又来了,手游发行系统是?

今天小蜗跟大家普及一下手游发行系统又是什么“鬼”,简单直白的说呢,它就相当于媒婆,是游戏开发商开发出游戏产品与玩家进行邂逅的的一个渠道。 游戏开发商将游戏推广到各种的应用商店、平...

xiguhy
2017/07/26
0
0

没有更多内容

加载失败,请刷新页面

加载更多

Spring Boot + Mybatis-Plus 集成与使用(二)

前言: 本章节介绍MyBatis-Puls的CRUD使用。在开始之前,先简单讲解下上章节关于Spring Boot是如何自动配置MyBatis-Plus。 一、自动配置 当Spring Boot应用从主方法main()启动后,首先加载S...

伴学编程
昨天
7
0
用最通俗的方法讲spring [一] ──── AOP

@[TOC](用最通俗的方法讲spring [一] ──── AOP) 写这个系列的目的(可以跳过不看) 自己写这个系列的目的,是因为自己是个比较笨的人,我曾一度怀疑自己的智商不适合干编程这个行业.因为在我...

小贼贼子
昨天
7
0
Flutter系列之在 macOS 上安装和配置 Flutter 开发环境

本文为Flutter开发环境在macOS下安装全过程: 一、系统配置要求 想要安装并运行 Flutter,你的开发环境需要最低满足以下要求: 操作系统:macOS(64位) 磁盘空间:700 MB(不包含 IDE 或其余...

過愙
昨天
6
0
OSChina 周六乱弹 —— 早上儿子问我他是怎么来的

Osc乱弹歌单(2019)请戳(这里) 【今日歌曲】 @凉小生 :#今日歌曲推荐# 少点戾气,愿你和这个世界温柔以待。中岛美嘉的单曲《僕が死のうと思ったのは (曾经我也想过一了百了)》 《僕が死の...

小小编辑
昨天
2.7K
16
Excption与Error包结构,OOM 你遇到过哪些情况,SOF 你遇到过哪些情况

Throwable 是 Java 中所有错误与异常的超类,Throwable 包含两个子类,Error 与 Exception 。用于指示发生了异常情况。 Java 抛出的 Throwable 可以分成三种类型。 被检查异常(checked Exc...

Garphy
昨天
42
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部