阅文游戏中心《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

参数说明:

以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}]}}`

游戏登录接口 （必接）

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

参数说明:

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

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

充值游戏币接口 （必接）

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

参数说明：

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

{
"ReturnCode":0,
"ReturnMessage":"成功",
"ReturnData":""
}

阅文 js 接口规范

js接口说明

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

发起充值游戏币或者道具请求 （必接）

参数说明：

data数据参数说明：

调用实例：

         /**
             * [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,'*');
            }

用户登录游戏区服日志记录 （可选）

参数说明：

data数据参数说明：

调用实例：

 /**
             * [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,'*');
            }

游戏内分享功能 （可选）

参数说明：

data数据参数说明：

返回数据参数说明：

调用实例：

         /**
             * [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

参数说明：

data数据参数说明：

返回数据参数说明：

调用实例：

         /**
             * [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

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

参数说明:

{
  "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"
}

创建角色上报（可选）

阅文游戏引导用户进入游戏后，用户在创建角色后，需要将创角数据上报给阅文。

请求方式：get

正式： https://api2-game.qidian.com/Home/Ly/roleReport?data=参数

data参数值为base64后的字符串

data编码前参数说明:

base64 编码前参数，需要将上方参数根据ASCII码从小到大排序,得到参数如下

createRoleTime=1626844407&gameId=201&roleId=201201067643989584&roleName=%25E5%25A4%2582%25E2%2580%25A6%25E2%2580%25A6%25E5%25B1%25B1&serverId=1&time=1626844407&userId=188441171&sign=d441cb43881fc645a8c8e169ebfab9f2

最终提交，格式如下:

https://api2-game.qidian.com/Home/Ly/roleReport?data=Y3JlYXRlUm9sZVRpbWU9MTYyNjg0NDQwNyZnYW1lSWQ9MjAxJnJvbGVJZD0yMDEyMDEwNjc2NDM5ODk1ODQmcm9sZU5hbWU9JTI1RTUlMjVBNCUyNTgyJTI1RTIlMjU4MCUyNUE2JTI1RTIlMjU4MCUyNUE2JTI1RTUlMjVCMSUyNUIxJnNlcnZlcklkPTEmdGltZT0xNjI2ODQ0NDA3JnVzZXJJZD0xODg0NDExNzEmc2lnbj1kNDQxY2I0Mzg4MWZjNjQ1YThjOGUxNjllYmZhYjlmMg==

实名查询（不建议接）

阅文平台实现用户实名，并且实现用户行为数据上报，合作平台不需要开启实名制，为了保证合作方平台的通用性，提供此接口提供查询。

请求方式：get

正式： https://lygame.qidian.com/Home/UserInfo/adult?userId=1&gameId=1

参数说明:

创角上报签名算法

签名算法，全参数签名。

1）参数名ASCII码从小到大排序，获得字符串，后缀加上 &key=$key

2）双层 md5 签名(结果为小写)

public function sign()
    {
    //模拟key
    $key = 'a06671bfe6cbaa7f3ce6ef207d81535a';
    //模拟订单参数
    $data = [
    'userId'=>188441171,
    'gameId'=>201,
    'serverId'=>1,
    'roleId'=>'201201067643989584',
    'roleName'=> urlencode('夂……山') ,
    'createRoleTime'=>1626844407,
    'time'=>1626844407
    ];
    //参数名ASCII码从小到大排序
    ksort($data);
    //进行参数拼接
    $signStr = http_build_query($data) . "&key=a06671bfe6cbaa7f3ce6ef207d81535a";
    //得到签名前的字符串 createRoleTime=1626844407&gameId=201&roleId=201201067643989584&roleName=%25E5%25A4%2582%25E2%2580%25A6%25E2%2580%25A6%25E5%25B1%25B1&serverId=1&time=1626844407&userId=188441171&key=a06671bfe6cbaa7f3ce6ef207d81535a
    //签名
    return md5(md5($signStr));
    }

测试预览（测试地址在这里）

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

起点平台预览地址为：

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

注：使用测试地址必须与我方关联防沉迷，否则无法进入游戏

常见问题回答（FAQ）

1. 什么是serverid？

   指选区游戏各个区服编号，只接收int类型（请自行在游戏侧做映射）请确保调用用户登录游戏区服日志记录和发起充值游戏币或者道具请求两个接口的serverid一致

2. 什么是itemid?

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

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

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

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

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

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

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

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

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

   查询用户接口（角色等级验证）：在以后做奖励活动，按等级发放奖励的时候，会使用到。还有平台会计划在充值的时候，去区服验证角色，角色如果不存在，不给用户充值。 游戏登录接口 （返回游戏登录链接）:返回游戏登录链接，会将链接嵌套到我们平台iframe里面，展现游戏内容页面 充值游戏币接口：给用户发放游戏币或者游戏道具接口，请保持该接口的幂等性，允许平台方一个订单号可以多次重试，且结果按约定返回 js接口 发起充值游戏币或者道具请求：提供给cp方iframe跨域发起充值请求 js接口 用户登录游戏区服日志记录：因为大部分H5游戏都是游戏内部选区，所以平台统计不到用户的区服登录和充值数据，应平台运营需求，此数据不可缺少

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

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

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

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

9. 充值时提示其他文字信息

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