文档中心 | 一键联接，全心服务

更新日期：2024年 05月 13日海外版服务器接入文档

<h3> 一、简要说明 </h3> 本文档的阅读对象为接入并使用SDK用户和支付系统的游戏服务器开发者。 通信时SDK均采用UTF8编码。 双发通信时，若有sign字段则一定要验证签名。 <h3> 二、接口列表 </h3> <h4> 2.1.验证用户信息接口 </h4> 2.1.1.接口目的 游戏客户端从SDK登录回调中获取到uid后，为防止用户篡改客户端而伪造用户uid标示从而登录他人账号，游戏客户端应将此信息传入给游戏服务器。游戏服务器调用此接口向SDK验证uid的真实性。若uid通过验证则允许此用户登录，若无法通过验证应拒绝此用户的登录授权。 2.1.2.接口地址 http://xxx.com/webapi/checkUserInfo    (xxx.com为域名，请联系贵方运营获取,获取之后替换即可) 2.1.3.请求方式 GET/POST 2.1.4.参数列表 <table border="1" cellpadding="0" cellspacing="0" style="width:75%;" class="" bordercolor="#000000"> <tbody> <tr> <td height="20" class="xl66" width="122"> 参数 </td> <td class="xl66" width="99"> 必要性 </td> <td class="xl66" width="183"> 说明 </td> </tr> <tr> <td height="44" class="xl65" width="122"> uid </td> <td class="xl65" width="99"> 必传 </td> <td class="xl65" width="183"> 从客户端登录回调中获取的uid </td> </tr> <tr> <td height="66" class="xl65" width="122"> token </td> <td class="xl65" width="99"> 必传 </td> <td class="xl65" width="183"> 从客户端登录回调中获取的token，请注意token的长度不要被截断 </td> </tr> </tbody> </table> 2.1.5.返回字段 接口会返回JSON格式字符串，如： 例1 {"status":false,"message":"tokenUidError"} 例2 {"status":true,"message":""} <table border="1" cellpadding="0" cellspacing="0" style="width:75%;height:30%;" class="" bordercolor="#000000"> <tbody> <tr> <td height="20" class="xl66" width="75"> 参数 </td> <td class="xl66" width="52"> 类型 </td> <td class="xl66" width="63"> 必要性 </td> <td class="xl66" width="442"> 说明 </td> </tr> <tr> <td height="22" class="xl65" width="75"> status </td> <td class="xl65" width="52"> bool </td> <td class="xl65" width="63"> 必传 </td> <td class="xl65" width="442"> 接口验证状态，若通过验证为true，否则为false </td> </tr> <tr> <td height="22" class="xl65" width="75"> message </td> <td class="xl65" width="52"> string </td> <td class="xl65" width="63"> 必传 </td> <td class="xl65" width="442"> Status为false时，message有值，为错误提示语 </td> </tr> <tr> <td height="22" class="xl65" width="75"> data </td> <td class="xl65" width="52"> array </td> <td class="xl65" width="63"> 可为空 </td> <td class="xl65" width="442"> 如果status为true时，data数组包含了用户账号绑定信息。 </td> </tr> <tr> <td> uid </td> <td> string </td> <td> 可为空 </td> <td> 如果status为true时，并且验证的用户存在，则返回用户uid </td> </tr> </tbody> </table> 2.1.6.请求示例 http://xxx.com/webapi/checkUserInfo?token=@171@174@188@127@182@163@148@179@166@168@132@179@165@222@169@116@109@166@96@212@152@156@116@121@106@139@170@154@203@134@124@118@108@164@205@126@173@151@172@169@169@140@158@215@138@153@164@136@160@162@154@197@114@212@159@143@126@125@154@179@168@151@135@155@121@148@215@146@181@100@158@219@161@112@106@184@108@189@121@129@120@158@141@186@129@177@169@140@105@136@128@176@205@124@124@166@163@179@213@151@175@124@185@140@155@124@171@160&uid=523 <h4> 2.2.发放道具接口 </h4> 2.2.1.接口目的 玩家在完成充值后,SDK会按照此接口协议向游戏提供的发货地址POST数据（简称为发送通知），游戏在收到SDK POST的数据后应验证相关信息并向玩家发送道具。 游戏应按照第三章中的算法验证签名数据，确定请求是否合法。 游戏发货的金额应当以通知中的金额为准发放道具。 游戏应判断是否重复发放道具，若已发放则不能再次发放。 处理成功后返回SUCCESS这7个字母SDK将不再通知，否则SDK将在一段内持续通知 2.2.2.接口地址 发放道具地址由游戏提供，SDK会主动向此地址发起POST请求 2.2.3.请求方式 POST 2.2.4.POST参数列表 <table border="1" cellpadding="0" cellspacing="0" style="width:75%;height:40%;" class="" bordercolor="#000000"> <tbody> <tr> <td height="20" class="xl66" width="126"> 参数 </td> <td class="xl66" width="72"> 必要性 </td> <td class="xl66" width="661"> 说明 </td> </tr> <tr> <td height="22" class="xl65" width="126"> uid </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 购买道具的用户uid </td> </tr> <tr> <td height="22" class="xl65" width="126"> username </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 购买道具的用户username </td> </tr> <tr> <td height="22" class="xl65" width="126"> cpOrderNo </td> <td class="xl65" width="72"> 可为空 </td> <td class="xl65" width="661"> 游戏下单时传递的游戏订单号，原样返回 </td> </tr> <tr> <td height="22" class="xl65" width="126"> orderNo </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> SDK唯一订单号 </td> </tr> <tr> <td height="22" class="xl65" width="126"> payTime </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 用户支付时间，如2017-02-06 14:22:32 </td> </tr> <tr> <td> payType </td> <td> 必有 </td> <td> 订单支付方式，具体值对应支付渠道详见<a href="https://www.quicksdk.com/doc-515.html" target="_blank">对照表</a> </td> </tr> <tr> <td height="22" class="xl65" width="126"> payAmount </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 用户支付金额（单位：元） 注意：如果游戏商品有多个数量，那么金额就是单价*数量 </td> </tr> <tr> <td height="22" class="xl65" width="126"> payCurrency </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 用户支付的币种，如RMB，USD等 </td> </tr> <tr> <td height="22" class="xl65" width="126"> usdAmount </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 用户支付的游戏道具以美元计价的金额（单位：元） 注意：如果游戏商品有多个数量，那么金额就是单价*数量 </td> </tr> <tr> <td height="22" class="xl65" width="126"> payStatus </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 支付状态，为0表示成功，为1时游戏不做处理 </td> </tr> <tr> <td height="22" class="xl65" width="126"> actRate </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 充值折扣，取值范围0~1(不包含0），默认为1表示不折扣；如值为0.2表示多发20%的元宝 </td> </tr> <tr> <td height="22" class="xl65" width="126"> extrasParams </td> <td class="xl65" width="72"> 可为空 </td> <td class="xl65" width="661"> 游戏下单时传递的扩展参数，将原样返回。 </td> </tr> <tr> <td> subscriptionStatus </td> <td> 非必有 </td> <td> 内购订阅型商品订单使用，如果有此字段表示订单订阅状态。cp监测到有此字段时不需要发货。字段取值为：2：订阅取消 </td> </tr> <tr> <td> subReason </td> <td> 非必有 </td> <td> 内购订阅型商品订单取消订阅原因。当有subscriptionStatus字段时此字段必有 </td> </tr> <tr> <td height="22" class="xl65" width="126"> sign </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 签名值，游戏应根据签名约定，本地计算后与此值进行比对 </td> </tr> </tbody> </table> 注：如果是官网充值方式时，CP可以获取extrasParams参数的值来定位到角色信息。这里的值CP可与第三方官网约定一个规则，让第三方官网按照规则传值。 目前规则为:区服ID|@|角色ID|@|商品ID 2.2.5.请求示例 假设游戏在SDK后台配置的发货地址为http://xxx.com/notify SDK会在玩家充值后向此地址POST如下参数： uid=543&username=554230339%40qq.com&cpOrderNo=orderNo_xxx&orderNo=0020170210162721805701&payTime=2017-02-10+16%3A27%3A55&payAmount=6.00&payStatus=0&payCurrency=RMB&usdAmount=0.99&extrasParams=&sign=22abf0b204d19316d177baeec6a90fcd CP接受到数据后应按第三章约定算法计算签名。 a)假设本地计算的签名与POST中传递的签名一致，则通过 b)若签名不一致，则返回FAILED，中断处理。 CP应判断是否已发送道具。 CP其他判断逻辑。 处理完成后。 a)希望SDK继续通知则返回任何非SUCCESS的字符。 b)处理完毕，订单结束则返回SUCCESS，SDK不会再通知。 <h4> 2.3.Facebook活动礼包发放（选接） </h4> 2.3.1.接口目的 玩家在领取礼包之后,SDK会按照此接口协议向游戏提供的发货地址POST数据，游戏在收到SDK POST的数据后应验证相关信息并向玩家发送礼包。 游戏应按照第三章中的算法验证签名数据，确定请求是否合法。 游戏应判断是否重复发放礼包，若已发放则不能再次发放。 处理成功后返回SUCCESS这7个字母表示领取成功，否则判定领取失败。 2.3.2.接口地址 礼包发放地址由游戏提供，SDK会主动向此地址发起POST请求 2.3.3.请求方式 POST 2.3.4.POST参数列表 <table border="1" cellpadding="0" cellspacing="0" style="width:75%;" class="" bordercolor="#000000"> <tbody> <tr> <td height="20" class="xl66" width="126"> 参数 </td> <td class="xl66" width="72"> 必要性 </td> <td class="xl66" width="661"> 说明 </td> </tr> <tr> <td height="22" class="xl65" width="126"> uid </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 领取礼包的用户uid </td> </tr> <tr> <td height="22" class="xl65" width="126"> giftNo </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 游戏礼包活动唯一值，表示用户要领取的哪个活动礼包 </td> </tr> <tr> <td height="22" class="xl65" width="126"> serverInfo </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 游戏跳转活动页面是传递的游戏serverId，原样返回 </td> </tr> <tr> <td height="22" class="xl65" width="126"> roleInfo </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 游戏跳转活动页面是传递的游戏roleId，原样返回 </td> </tr> <tr> <td height="22" class="xl65" width="126"> sign </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 签名值，游戏应根据签名约定，本地计算后与此值进行比对 </td> </tr> </tbody> </table> 2.3.5.请求示例 假设游戏在SDK活动配置的礼包地址为http://xxx.com/notify SDK会在玩家点击领取礼包时同步向此地址POST如下参数： uid=543&giftNo=dwqu18921hud9&sign=22abf0b204d19316d177baeec6a90fcd CP接受到数据后应按第三章约定算法计算签名。 a)假设本地计算的签名与POST中传递的签名一致，则通过 b)若签名不一致，则返回FAILED，中断处理。 CP应判断是否已发送礼包。 CP其他判断逻辑。 处理完成后，返回SUCCESS表示用户领取成功，否则为失败。 <h4> 2.4. 获取玩家游戏角色列表（选接） </h4> 2.4.1.接口目的 在网页充值平台玩家登录账号选择游戏时获取游戏角色列表。玩家选择角色后向该角色充值。 2.4.2.接口地址 地址由游戏提供，SDK会主动向此地址发起POST请求 2.4.3.请求方式 POST 2.4.4.POST参数列表 <table border="1" cellpadding="0" cellspacing="0" class="" bordercolor="#000000" style="width:1414px;"> <tbody> <tr> <td height="20" class="xl66" width="126"> 参数 </td> <td class="xl66" width="72"> 必要性 </td> <td class="xl66" width="661"> 说明 </td> </tr> <tr> <td> frType </td> <td> 非必有 </td> <td> 获取角色方式，取枚举值，如果没有此字段默认以第1种方式获取角色列表 1. 通过SDK账号UID获取，默认为此方式 2. 通过角色ID获取 </td> </tr> <tr> <td> roleId </td> <td> 非必有 </td> <td> 用户角色ID，如果frType为2时，角色ID字段必有。游戏此时应该根据角色ID查询当前游戏的角色信息 </td> </tr> <tr> <td height="22" class="xl65" width="126"> uid </td> <td class="xl65" width="72"> 非必有 </td> <td class="xl65" width="661"> 用户SDK账号uid，如果frType为1时，uid字段必有。游戏此时应该根据SDK账号ID查询当前游戏的所有角色列表 </td> </tr> <tr> <td height="22" class="xl65" width="126"> username </td> <td class="xl65" width="72"> 非必有 </td> <td class="xl65" width="661"> 用户SDK账号名，如果frType为1时，username字段必有。游戏此时应该根据SDK账号ID查询当前游戏的所有角色列表 </td> </tr> <tr> <td height="22" class="xl65" width="126"> productCode </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> SDK产品ProductCode </td> </tr> <tr> <td height="22" class="xl65" width="126"> sign </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 签名值，游戏应根据签名约定，本地计算后与此值进行比对 </td> </tr> </tbody> </table> 2.4.5.返回字段说明 游戏地址在接收到SDK请求之后返回玩家的角色信息列表，数据格式为json，返回字段如下 <table border="1" cellpadding="0" cellspacing="0" class="" bordercolor="#000000" style="width:1414px;"> <tbody> <tr> <td height="20" class="xl66" width="126"> 参数 </td> <td class="xl66" width="72"> 必要性 </td> <td class="xl66" width="661"> 说明 </td> </tr> <tr> <td height="22" class="xl65" width="126"> code </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 200：请求成功；其余值均为失败 </td> </tr> <tr> <td height="22" class="xl65" width="126"> data </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 玩家角色列表集合，每个子集包含如下字段： serverId：区服ID serverName：区服名 roleId：角色ID roleName：角色名 roleLevel：角色等级 sdkUid：当获取方式frType=2时，游戏应必须返回SDK的uid，否则可能会无法调起支付 </td> </tr> </tbody> </table> <h4> 2.5. 消息推送（选接） </h4> 2.5.1.接口目的 开发者可通过该接口对玩家进行消息推送。接收推送的设备为玩家最后登录设备。 a.SDK海外后台->平台管理->开放平台生成开发者秘钥，获取openId和openKey。 b.其中openKey为用于生成签名KEY。 c.玩家设备可能是Android或IOS，开发者需在SDK后台推送配置配置 FireBase(Android) 和推送证书(IOS)。 d.接口最终使用的推送参数，取决于玩家最后登录设备对应平台以及产品的配置，同一玩家也可能每次使用不同设备登录不同游戏！ 2.5.2.接口地址 http://xxx.com/pushApi/send   (xxx.com为域名，请联系贵方运营获取,获取之后替换即可) 2.5.3.请求方式 POST 2.5.4.POST参数列表 <table border="1" cellpadding="0" cellspacing="0" class="" bordercolor="#000000" style="width:1414px;"> <tbody> <tr> <td height="20" class="xl66" width="126"> 参数 </td> <td class="xl66" width="72"> 必要性 </td> <td class="xl66" width="661"> 说明 </td> </tr> <tr> <td height="22" class="xl65" width="126"> openid </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> SDK后台获取 </td> </tr> <tr> <td height="22" class="xl65" width="126"> users </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 玩家ID集合，JSON串，如 ["123","124"] </td> </tr> <tr> <td height="22" class="xl65" width="126"> title </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 消息标题 </td> </tr> <tr> <td height="22" class="xl65" width="126"> message </td> <td class="xl65" width="72"> 必有 </td> <td class="xl65" width="661"> 消息内容 </td> </tr> <tr> <td> andDebug </td> <td> 可选 </td> <td> Google推送环境，可选值：1沙盒模式，0正式环境；默认0，请注意对应环境参数。 </td> </tr> <tr> <td> iosDebug </td> <td> 可选 </td> <td> Apple推送环境，可选值：1沙盒模式，0正式环境；默认0，请注意对应环境参数。 </td> </tr> <tr> <td> sign </td> <td> 必有 </td> <td> 参数签名，参考本接口所述签名算法 </td> </tr> </tbody> </table> 2.5.5.请求示例 POST openId=0lEAhY&title=New%20message&message=The%20test%20message&users=%5B%22123%22%2C%22124%22%5D&sign=a2fd31d0d525857fb386298a509a3755 2.5.6.接口响应 失败 <pre class="brush:js;toolbar:false">{ "status": false, "data": [], "message": "SIGN ERROR" }</pre> 成功，返回推送成功数。 <pre class="brush:js;toolbar:false">{ "data": { "success": 2 }, "status": true, "message": "" }</pre> 2.5.7.签名算法 请求参数中除sign外的所有参数(可选参数可不传)，按键首字母升序排序，键值对按照 key=val 封装，并使用 & 进行拼接，最后再拼接上openKey(注意openKey 前面也应该有个 &)得到待签名串。 待签名串示例： <pre class="brush:js;toolbar:false">message=The test message&openId=0lEAhY&title=You have a new message&users=["57524269","57524270"]&bkajTWxAT2TyU5vXuStD59smApTrMGso</pre> 将上一步得到的待签名串进行MD5，即得到32位签名sign。 <h3> 三、签名算法描述 </h3> 通信时，发起方会在请求中附带sign字段。 接收方收到消息后将收到的键值对POST参数，移除sign后，按首字母升序排序。 将所有键值对按 key1=val1&key2=val2&key3=val3& 格式进行拼接。 在第3步拼接的字符后拼接SDK约定的callbackKey则此时格式为：key1=val1&key2=val2&key3=val3&callbackKey 将第4步处理的字符串进行md5编码，得到32位md5值。 将第5步获取的md5值与第1步中发起方传递的sign值进行对比，一致则通过。 代码片段参见第四章。 <h3> 四、代码片段 </h3> <pre class="brush:js;toolbar:false">/** * 本地计算MD5签名PHP示例代码 * @params $callbackey SDK后台分配的通信密钥 * @return本地计算的md5签名值 */ public function getMd5Sign($callbackkey){ $params = $_POST; unset($params['sign']); ksort($params);$signKey = ''; foreach($params as $key => $val){ $signKey .= $key.'='.$val.'&'; } $signKey .= $callbackkey; return md5($signKey); }</pre>