阅文游戏中心《h5游戏 CP接口规范》

接口要求规范

游戏方接口说明：游戏方需按照规范提供，阅文进行调用

阅文接口说明：阅文提供，游戏方调用

参数 time 为Unix 时间戳(January 1 1970 00:00:00 GMT 起的秒数) ，单位为秒

编码统一使用 UTF-8

接口请求方式为 GET

参数sign里的md5 加密要把md5后的字符串转成小写

key双方协定或是一方处理完知会另一方

php中.号，java和c#中 +号代表字符串连接

接口标记为必接的接口是接入阅文平台的最低标准，没有达标无法上线，请悉

对接H5游戏必须先接入登录接口，然后才能加载出游戏，请注意接口返回格式的正确写法

时序图

游戏登录时序图

游戏充值时序图

游戏方接口规范

查询用户接口(角色等级验证)(可选)

URL?username=laodao789&serverid=1&timestamp=1232553600&flag=ed03c2ef6f711c117a94242a7aea50c3

参数说明:

名称

类型

说明

范例

username

string

阅文集团用户标识

qq83883

serverid

int

游戏区服id标识,所属服务器

一区填写1,二区填写2,依此类推(可忽略的参数,区服以游戏内的区服为准)

timestamp

long

Unix时间戳(秒)

1495073622

flag

string

key是表示平台和游戏双方提前协商约定好的密钥,请转换为小写字母

php MD5(serverid.username.timestamp.key) java或者C# MD5(serverid+username+timestamp+key)

以json格式返回查询信息，格式如下:

{"ReturnCode":0,"ReturnMessage":"成功","ReturnData":{"userinfo":[{"name":"雷宏茂","server":1,"level":43},{"name":"雷公","server":1,"level":48},{"name":"雷嘉丝","server":1,"level":41},{"name":"雷玮晴","server":1,"level":40}]}}`返回值

说明

ReturnCode

0成功 -1未创建角色 -2无法识别的服务器 -8网络异常

ReturnMessage

提示信息

ReturnData

返回数据数组 name 角色名 server区服号 level等级

游戏登录接口 (必接)

URL/login.php?username={登陆账号}&serverid={游戏服标识}&timestamp={LINUX时间戳,单位为秒}&isadult={防沉迷标记}&clientid=122&flag={加密签名}

请注意接口返回格式

参数说明:

名称

类型

说明

范例

username

string

阅文集团用户标识

qq99389

serverid

int

游戏区服id标识,所属服务器

一区填写1,二区填写2,依此类推

timestamp

long

Unix时间戳(秒)

1495073622

isadult

int

玩家是否成年(1成年,0未成年，如果运营商不知道该用户是否成年默认传-1表示未知是否成年)

0

clientid

int

渠道编号

阅文为 1

flag

string

key是表示平台和游戏双方提前协商约定好的密钥,请转换为小写字母

php md5($username.$serverid.$timestamp.$key.$clientid) java或者C# md5(username+serverid+timestamp+key+clientid)

以json格式返回信息，格式如下:

{"ReturnCode":0,"ReturnMessage":"\u6210\u529f","ReturnData":"https:\/\/slth.xxxx.net\/G\/egret.html?token=55435A47589ea20519509ed97e&appId=91284&channelId=18365&egret.runtime.spid=18365"}返回值

说明

ReturnCode

0成功

ReturnMessage

提示信息

ReturnData

返回登录游戏url地址

充值游戏币接口 (必接)

URL?username={账号}&clientid={合作商编号}&serverid={游戏服}&orderid={阅文订单号}&gorderid ={游戏订单号}&itemid={道具id}&money={充值金额}&timestamp = LINUX时间戳,单位为秒}&flag={加密签名}

注意：此接口中游戏方必须验证订单号与发货金额的一致性, 防止非法操作对游戏收入影响

参数说明：

名称

类型

说明

范例

username

string

阅文集团用户标识

qq99389

clientid

int

渠道编号

比如阅文为 1

serverid

int

游戏区服id标识,所属服务器

一区填写1,二区填写2,依此类推

orderid

string

阅文订单号

AC403131801030814

gorderid

string

游戏方订单号

不要有特殊符号,更不能有中文,长度不要超过50字符

money

float

充值金额 ,(单位)人民币

66

itemid

int

游戏道具或者金币等id

1 (如果未在运营同学处配置充值档, 则不需要传该字段)

timestamp

long

Unix时间戳(秒)

1495073622

flag

string

key是表示平台和游戏双方提前协商约定好的密钥,请转换为小写字母

php md5($username.$serverid.$clientid.$orderid.$timestamp.$itemid.$money.$key) java或者C# md5(username+serverid+clientid+orderid+timestamp+itemid+money+key)

以json格式返回信息，格式如下:

{

"ReturnCode":0,

"ReturnMessage":"成功",

"ReturnData":""

}返回值

说明

ReturnCode

0成功 -1未创建角色 -2无法识别的充值服务器 -8网络异常,1表示订单重试成功后返回值(注:订单重试请求成功后返回为1，状态0和1我们作为成功处理的，掉单可重复请求)

ReturnMessage

提示信息

ReturnData

无

阅文 js 接口规范

js接口说明

由于存在不同域问题，因此需要采用跨域通信的方式和业务页面保持通信。这里采用的方式是postMessage的方案

发起充值游戏币或者道具请求 (必接)

参数说明：

名称

类型

说明

范例

action_yw

string

请填写pay

pay

data

json

充值请求数据

{'serverid':1,'orderid':'6406548075898863641(不能有中文)','money':6,'goodname':'元宝','itemid':12}

data数据参数说明：

名称

类型

说明

范例

serverid

int

游戏区服id

1

orderid

string

游戏方订单号最多50个字符

6406548075898863641

money

float

(单位)人民币

6

goodname

string

购买的游戏币或者道具名称

600元宝(请标明充值数量)

itemid

int

游戏道具或者金币等id

1 (如果未在运营同学处配置充值档, 则不需要传该字段)

调用实例：

/**

* [charge 向平台发起充值游戏道具请求,消息体格式为{'action_yw':'pay','data':data}]

*/

function pay(){

var data={'serverid':1,'orderid':'6406548075898863641','money':6,'goodname':'600元宝','itemid':8791};

var message={'action_yw':'pay','data':data};

window.parent.postMessage(message,'*');

}

用户登录游戏区服日志记录 (可选)

参数说明：

名称

类型

说明

范例

action_yw

string

请填写log

log

data

json

用户登录数据

{'serverid':1,'username':'霸天虎','level':6}

data数据参数说明：

名称

类型

说明

范例

serverid

int

游戏区服id

1

username

string

对应游戏区服角色名称

霸天虎

level

int

用户登录时候的等级信息

6

调用实例：

/**

* [log 添加游戏登录记录,消息体格式为{'action_yw':'log','data':data}]

*

*/

function log(){

var data={'serverid':1,'username':'霸天虎','level':6};

var message={'action_yw':'log','data':data};

window.parent.postMessage(message,'*');

}

游戏内分享功能 (可选)

参数说明：

名称

类型

说明

范例

action_yw

string

请填写 share

share

data

json

分享请求数据

{action_yw: 'share','userId':6406548075898863641}

data数据参数说明：

名称

类型

说明

范例

action_yw

string

功能标识 share

share

userId

string

用户唯一ID标识(仅限数字字符串)

6406548075898863641

返回数据参数说明：

名称

类型

说明

范例

code

int

成功/失败 标识

1:成功,0:失败

action_yw

string

功能标识 share

share

userId

string

用户唯一ID标识(仅限数字字符串)

6406548075898863641

调用实例：

/**

* [share 向平台发起分享请求,消息体格式为{action_yw: 'share', data: passData};],直接调用下面方法即可

*/

function share(){

var passData = {action_yw: 'share','userId':6406548075898863641};

var data = {action_yw: 'share', data: passData};

window.parent.postMessage(data, "*");

}

/**监控来自平台侧的返回结果*/

window.addEventListener('message',function(e){

console.log(e.data)

//处理代码

});

/** 区分移动端与PC端方法,PC端目前没有创建快捷方式与分享的功能 */

function getParentUrl() {

var url = null;

if (parent !== window) {

try {

url = parent.location.href;

} catch (e) {

url = document.referrer;

}

}

return url;

}

/** 移动端域名: m-game.qidian.com，p-game.qidian.com，m-game.book.qq.com，p-game.book.qq.com */

创建桌面快捷功能 (可选)

备注：此功能只支持安卓，不支持IOS

参数说明：

名称

类型

说明

范例

action_yw

string

请填写 shortCut

shortCut

data

json

创建快捷方式请求数据

{action_yw: 'shortCut','userId':6406548075898863641}

data数据参数说明：

名称

类型

说明

范例

action_yw

string

功能标识 shortCut

shortCut

userId

string

用户唯一ID标识(仅限数字字符串)

6406548075898863641

返回数据参数说明：

名称

类型

说明

范例

code

int

成功/失败 标识

1:成功,0:失败

action_yw

string

功能标识 share

share

userId

string

用户唯一ID标识(仅限数字字符串)

6406548075898863641

调用实例：

/**

* [share 向平台发起分享请求,消息体格式为{action_yw: 'shortCut', data: passData};],直接调用下面方法即可

*/

function share(){

var passData = {action_yw: 'shortCut','userId': 6406548075898863641};

var data = {action_yw: 'shortCut', data: passData};

window.parent.postMessage(data, "*");

}

/**监控来自平台侧的返回结果*/

window.addEventListener('message',function(e){

console.log(e.data)

//处理代码

});

/** 区分移动端与PC端方法,PC端目前没有创建快捷方式与分享的功能 */

function getParentUrl() {

var url = null;

if (parent !== window) {

try {

url = parent.location.href;

} catch (e) {

url = document.referrer;

}

}

return url;

}

/** 移动端域名: m-game.qidian.com，p-game.qidian.com，m-game.book.qq.com，p-game.book.qq.com */

阅文方接口规范

用户聊天消息推送(必接)

请求方式：POST

正式：http://api2.game.qidian.com/Cp/Msg/push

参数说明:

名称类型说明范例

gameId

int

阅文平台游戏ID(请询问运营同学)

9999

serverId

int

游戏区服ID

1

serverName

string

区服名称

区服1

timestamp

int

时间戳

1539314648

sign

string

请求的签名字串：sha1(gameId+"|"+serverId+"|"+serverName+"|"+timestamp+"|"+key)

将示例所需参数，用竖线"|"拼接字串，在最后面拼接key后sha1加密，并将结果转换小写。(key询问运营同学)

cf0244de65a0db825e6a7ba98fa62517ac015e8e

data

array[json]

消息数据体说明：

fGameUserId(消息发送者gameUserId(即阅文userId))

fNickName(消息发送者昵称)

tGameUserId(消息接收者gameUserId(即阅文userId))

tNickName(消息接收者昵称)

type(1私聊，2喇叭，3邮件，4世界，5国家，6工会/帮会，7队伍，8附近，9其他)

content( 消息内容)

time(消息发送时间戳)

{

"fGameUserId": "123",

"fNickName": "this is fNickName",

"tGameUserId": "456",

"tNickName": "this is toNickName",

"type": 1,

"content": "this is content 1",

"time": 1539234456

}

以 json 格式提交，格式如下:

{

"gameId": 9999,

"serverId": "1",

"serverName": "区服1",

"data": [

{

"fGameUserId": "123",

"fNickName": "jack",

"tGameUserId": "234",

"tNickName": "tom",

"type": 1,

"content": "你好",

"time": 1539234456

}

],

"timestamp": 1539234456,

"sign": "cf0244de65a0db825e6a7ba98fa62517ac015e8e"

}返回值说明

code0成功，其他返回码失败

msg返回信息

data返回数据数组，total表示成功推送消息数

测试预览(测试地址在这里)

gameid请找阅文运营同学提供。注：阅文h5游戏为游戏内选区 不用关心测试地址的serverid参数

起点平台预览地址为：

http://m-game.qidian.com/#/fab/(这里为gameid的值)

常见问题回答(FAQ)

什么是serverid？

指选区游戏各个区服编号，只接收int类型(请自行在游戏侧做映射)

什么是itemid?

指游戏内充值选项(游戏币或者道具月卡之类的id，只接收int类型)， 如果未在运营同学处配置充值档, 则不需要传该字段

为什么接入了游戏在玩游戏页面是黑屏，白屏或灰屏？

通常是没有按照指定的json约定格式返回(请查看游戏登录接口的返回格式),需要把游戏地址加上自己的参数返回到json数组给到阅文平台，我们会内嵌到到iframe中加载出来

为什么提示游戏方充值返回参数json解析错误？

这种提示说明，没有按照约定的格式返回给我们json数据

阅文的两个平台(起点和qq阅读)只用对接一次？

是的，cp游戏方只用对接一次，登录、验证角色、充值等接口使用同一套即可

所有接口都要对接吗，这些接口使用场景是那些？

对的，都需要对接，使用场景对应如下：

查询用户接口(角色等级验证)：在以后做奖励活动，按等级发放奖励的时候，会使用到。还有平台会计划在充值的时候，去区服验证角色，角色如果不存在，不给用户充值。

游戏登录接口 (返回游戏登录链接):返回游戏登录链接，会将链接嵌套到我们平台iframe里面，展现游戏内容页面

充值游戏币接口：给用户发放游戏币或者游戏道具接口，请保持该接口的幂等性，允许平台方一个订单号可以多次重试，且结果按约定返回

js接口 发起充值游戏币或者道具请求：提供给cp方iframe跨域发起充值请求

js接口 用户登录游戏区服日志记录：因为大部分H5游戏都是游戏内部选区，所以平台统计不到用户的区服登录和充值数据，应平台运营需求，此数据不可缺少

在接入过程中提示cp方的serverid不合法、cp方的orderid不合法、cp方的money不合法、cp方的goodname不合法、cp方的itemid不合法，是什么原因导致的？

请检查是否按照接口约定数据格式传入了对应数据，亦可按照下图,在起点渠道进行调试检查传入的参数是否正确

充值时提示游戏区服未配置

游戏方没有接入或没有正确上报用户登录游戏区服日志记录需要的数据，导致调用用户登录游戏区服日志记录和发起充值游戏币或者道具请求两个接口的serverid不一致

充值时提示其他文字信息

其他文字信息一般为我方透传游戏方服务端充值游戏币接口的返回值，请游戏方自行排查提供接口的问题