閱文游戲中心《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×tamp=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={游戲服標識}×tamp={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={充值金額}×tamp = 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不一致
充值時提示其他文字信息
其他文字信息一般為我方透傳游戲方服務端充值游戲幣接口的返回值，請游戲方自行排查提供接口的問題
