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

更新日期：2025年 03月 24日H5游戏接入文档（微端和网页）

<h1> 背景说明： </h1> 1.H5游戏通过js API接入QuickSDK后，可直接用于上架H5、Android、iOS全平台渠道。需要注意的是，接完QuickSDKH5文档后的母链地址不能直接进行测试，需要配置好渠道，用渠道提供的链接或者包来测试。H5渠道最终是使用渠道给出的URL地址进行测试；Android、iOS渠道则需使用QuickSDK提供的打包工具打出apk或ipa渠道包进行测试 2.上架H5渠道需要将游戏地址配置到QuickSDK后台渠道参数列表上方的"H5游戏地址"里，其后QuickSDK将附带一些参数生成一个新的游戏地址(此地址可通过QuickSDK后台"渠道回调地址"栏目查看)，运营需将此地址配置到渠道后台，然后使用渠道给出的地址测试。渠道给出的游戏地址会以iFrame加载游戏真实地址，若加载游戏地址后，游戏地址发生跳转或重定向，则新地址需原样保存被iframe加载的游戏地址上渠道所附加的URL参数 3.Android、iOS渠道需将游戏地址配置到QuickSDK后台对应渠道参数"H5GameUrl"里，启用打包工具，工具识别到游戏平台为H5时不需要提供母包，直接出包即可，然后用打出的渠道包进行测试 注意：开发者应仔细阅读以上3点内容，若游戏不按照此步骤配置测试，在调用SDK时将出现跨域错误 <h3> 流程描述: </h3> 1.游戏开发者在游戏主页引入QuickSDK js类库 2.引入类库后调用类库中的初始化方法 3.在初始化完成的回调中,调用登录方法,从登录方法的回调中获取用户uid和token 4.将js端取到的uid和token传回游戏服务器,游戏服务器调用QuickSDK用户验证的服务器API,验证用户 5.验证结果返回1，标示信息通过，游戏使用此uid完成登录。验证结果为0，则标示信息有误，游戏应给出登录失败的提示 <h3> 接入流程 </h3> <h4> 1.引用JS类库 </h4> https://qkh5api.quickapi.net/static/lib/libQuickSDK_v2.js 注意: 游戏应原样引入此JS，不能随意变更协议为http或在后面附加时间戳（如是要转出安卓或越狱渠道的包，则js必须在html的script里进行引用，不能动态加载） <h4 style="margin:3.75pt 0cm;"> 2.初始化QuickSDK </h4> <o:p></o:p> 游戏应调用QuickSDK的init接口,同时传入QuickSDK后台分配给游戏的参数.<o:p></o:p> <pre class="brush:js;toolbar:false">var productCode = '05425578266356246482673853629430'; //QuickSDK后台自动分配 var productKey = '98253036'; //QuickSDK后台自动分配 QuickSDK.init(productCode,productKey,true,function(){ console.log("init success"); //初始成功之后可以调用登录接口 }) </pre> 注意如果是要转出安卓渠道的包，游戏需要按如下方式进行初始化： <pre class="brush:js;toolbar:false">//申请权限第3个参数传true QuickSDK.init(productCode,productKey,true,function(){ console.log("init success"); //初始成功之后可以调用登录接口 }) //不申请权限第3个参数传false QuickSDK.init(productCode,productKey,false,function(){ console.log("init success"); //初始成功之后可以调用登录接口 })</pre> <o:p></o:p> <h4 style="margin:3.75pt 0cm;"> 3.调用QuickSDK的login方法示例如下： </h4> <h1> 通常登录方法需要在初始化回调中调用 </h1> <pre class="brush:js;toolbar:false">QuickSDK.login(function(callbackData){ var message; if(callbackData.status){ console.log('GameDemo:QuickSDK登录成功: uid=>' + callbackData.data.uid); }else{ console.log('GameDemo:QuickSDK登录失败:' + callbackData.message); } }) </pre> <o:p></o:p> 从回调函数中可获取用户关键信息 注意:若游戏收到失败回调,判断message为cancel时,应再次调用登录接口. 回调范例: <table style="width:100%;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 字段 </td> <td> 类型 </td> <td> 说明 </td> </tr> <tr> <td> status </td> <td> bool </td> <td> 是否登录成功,true成功,false失败 </td> </tr> <tr> <td rowspan="6"> data </td> <td> uid </td> <td> 渠道uid </td> </tr> <tr> <td> username </td> <td> 渠道username </td> </tr> <tr> <td> token </td> <td> token 游戏服务器需通过v2/checkUserInfo接口(参见服务器接口文档)验证token和UID的正确性 </td> </tr> <tr> <td> isLogin </td> <td> 是否游客,登录后此值为true </td> </tr> <tr> <td> channelId </td> <td> 渠道ID </td> </tr> <tr> <td> message </td> <td> status为false时,此字段为Failed表示登录失败,为cancel表示玩家取消登录 </td> </tr> </tbody> </table> JSON范例 <pre class="brush:js;toolbar:false">{“status”:true,”data”:{“uid”:”123”,”username”:”quicksdk”,”token”:””,”isLogin”:true},”message”:””}</pre> 获取回调信息中的uid和token发回游戏服务器，游戏服务器按《<a href="https://www.quicksdk.com/doc-15.html" target="_blank">服务器接入文档</a>》调用用户验证接口 除主动调用登录后，游戏同时需处理切换帐号的回调通知。注册切换帐号的回调方法如下: <div> 一些渠道（如：百度 天宇游等）在悬浮框有切换账号的功能，此回调即切换成功后的回调。游戏应清除当前的游戏角色信息。在切换账号成功后回到选择服务器界面，用回调结果里面的新的UID 和Token 进入游戏。注意：在此回调内无需调用登录接口 </div> <pre class="brush:js;toolbar:false">QuickSDK.setSwitchAccountNotification(function(callbackData){ });</pre> 注意：一般Android、iOS渠道会收到此回调，H5渠道绝大部分渠道没有此回调 <h4> 4.调用支付接口 </h4> 当用户点击购买时，游戏可调用pay方法传入orderInfo对象调起各渠道的支付页面。调用示例如下: <pre class="brush:js;toolbar:false">orderInfo = new Object(); orderInfo.productCode = “05425578266356246482673853629430”; orderInfo.uid = 'uid'; orderInfo.username = 'username'; orderInfo.userRoleId = 'roleId1'; orderInfo.userRoleName = '小朋友'; orderInfo.serverId= 1; orderInfo.userServer = '内测1区'; orderInfo.userLevel = 1; orderInfo.cpOrderNo = 'cpOrderNo000001'; orderInfo.amount = '0.01'; orderInfo.subject = '大袋钻石'; orderInfo.desc = '一大袋钻石60个'; orderInfo.callbackUrl = ''; orderInfo.extrasParams = ''; orderInfo.goodsId = 'goods'; orderInfo.count = 60; orderInfo.quantifier = '个'; var orderInfoJson = JSON.stringify(orderInfo); QuickSDK.pay(orderInfoJson,function(payStatusObject){ console.log('GameDemo:下单通知' + JSON.stringify(payStatusObject)); //H5渠道基本没有此回调返回，游戏发货要以服务器通知为准 })</pre> 注：UID为渠道的UID 支付后，部分渠道可触发回调函数，函数中可获取是否支付成功，但需要注意，此结果仅仅作为UI展示(或完全不用)，发货应以服务器通知为准 orderInfo对象如下: <table style="width:100%;" cellpadding="2" cellspacing="0" border="1" bordercolor="#000000"> <tbody> <tr> <td> 字段 </td> <td> 类型 </td> <td> 说明 </td> </tr> <tr> <td> productCode </td> <td> 必传 </td> <td> QuickSDK后台自动分配的参数 </td> </tr> <tr> <td> uid </td> <td> 必传 </td> <td> 渠道UID </td> </tr> <tr> <td> username </td> <td> 必传 </td> <td> 渠道username </td> </tr> <tr> <td> userRoleId </td> <td> 必传 </td> <td> 游戏内角色ID </td> </tr> <tr> <td> userRoleName </td> <td> 必传 </td> <td> 游戏角色 </td> </tr> <tr> <td> serverId </td> <td> 必传 </td> <td> 角色所在区服ID </td> </tr> <tr> <td> userServer </td> <td> 必传 </td> <td> 角色所在区服 </td> </tr> <tr> <td> userLevel </td> <td> 必传 </td> <td> 角色等级 </td> </tr> <tr> <td> cpOrderNo </td> <td> 必传 </td> <td> 游戏内的订单,服务器通知中会回传 </td> </tr> <tr> <td> amount </td> <td> 必传 </td> <td> 购买金额（元） </td> </tr> <tr> <td> count </td> <td> 必传 </td> <td> 购买商品个数 </td> </tr> <tr> <td> quantifier </td> <td> 必传 </td> <td> 购买商品单位，如，个 </td> </tr> <tr> <td> subject </td> <td> 必传 </td> <td> 道具名称 </td> </tr> <tr> <td> desc </td> <td> 必传 </td> <td> 道具描述 </td> </tr> <tr> <td> callbackUrl </td> <td> 选传 </td> <td> 服务器通知地址 </td> </tr> <tr> <td> extrasParams </td> <td> 选传 </td> <td> 透传参数,服务器通知中原样回传 </td> </tr> <tr> <td> goodsId </td> <td> 必传 </td> <td> 商品ID </td> </tr> </tbody> </table> 注：选传的字段值可以为空，但是对象必须包含此属性 回调函数payStatusObject对象中status为true时为支付成功 服务器通知接口参见《<a href="https://www.quicksdk.com/doc-15.html" target="_blank">QuickSDK服务器对接文档</a>》 <h4> 5.上传角色信息接口 </h4> 游戏需要在玩家登录或角色发生变化调用此接口. 调用示例如下: <pre class="brush:js;toolbar:false">var roleInfo = new Object(); roleInfo.isCreateRole = true; roleInfo.roleCreateTime = 1490598150; roleInfo.uid = 12; roleInfo.username = 'username'; roleInfo.serverId = 1; roleInfo.serverName = '内测1区'; roleInfo.userRoleName = '小朋友'; roleInfo.userRoleId = 'roleId1'; roleInfo.userRoleBalance = 1000; roleInfo.vipLevel = 1; roleInfo.userRoleLevel = 1; roleInfo.partyId = 1; roleInfo.partyName = '行会名称'; roleInfo.gameRoleGender = '男'; roleInfo.gameRolePower = 100; roleInfo.partyRoleId = 1; roleInfo.partyRoleName = '会长'; roleInfo.professionId = '1'; roleInfo.profession = '武士'; roleInfo.friendlist =''; var roleInfoJson = JSON.stringify(roleInfo); QuickSDK.uploadGameRoleInfo(roleInfoJson,function(response){ }); }</pre> roleInfo对象字段如下 <table style="width:100%;" cellpadding="2" cellspacing="2" border="1" bordercolor="#000000"> <tbody> <tr> <td> 字段 </td> <td> 类型 </td> <td> 说明 </td> </tr> <tr> <td> isCreateRole </td> <td> 必传 </td> <td> 仅创建角色时传true,更新信息时传false </td> </tr> <tr> <td> roleCreateTime </td> <td> 必传 </td> <td> 角色创建时间 </td> </tr> <tr> <td> uid </td> <td> 必传 </td> <td> 渠道UID </td> </tr> <tr> <td> username </td> <td> 必传 </td> <td> 渠道username </td> </tr> <tr> <td> serverId </td> <td> 必传 </td> <td> 区服ID </td> </tr> <tr> <td> serverName </td> <td> 必传 </td> <td> 区服名称 </td> </tr> <tr> <td> userRoleId </td> <td> 必传 </td> <td> 游戏内角色ID </td> </tr> <tr> <td> userRoleName </td> <td> 必传 </td> <td> 游戏角色 </td> </tr> <tr> <td> userRoleBalance </td> <td> 必传 </td> <td> 角色游戏内货币余额 </td> </tr> <tr> <td> vipLevel </td> <td> 必传 </td> <td> 角色VIP等级 </td> </tr> <tr> <td> userRoleLevel </td> <td> 必传 </td> <td> 角色等级 </td> </tr> <tr> <td> partyId </td> <td> 必传 </td> <td> 公会/社团ID </td> </tr> <tr> <td> partyName </td> <td> 必传 </td> <td> 公会/社团名称 </td> </tr> <tr> <td> gameRoleGender </td> <td> 选传 </td> <td> 角色性别 </td> </tr> <tr> <td> gameRolePower </td> <td> 选传 </td> <td> 角色战力 </td> </tr> <tr> <td> partyRoleId </td> <td> 选传 </td> <td> 角色在帮派中的ID </td> </tr> <tr> <td> partyRoleName </td> <td> 选传 </td> <td> 角色在帮派中的名称 </td> </tr> <tr> <td> professionId </td> <td> 选传 </td> <td> 角色职业ID </td> </tr> <tr> <td> profession </td> <td> 选传 </td> <td> 角色职业名称 </td> </tr> <tr> <td> friendlist </td> <td> 选传 </td> <td> 角色好友列表 </td> </tr> </tbody> </table> 注：选传的字段值可以为空，但是对象必须包含此属性 <h4> 6.调用注销接口以及注销回调 </h4> 6.1 注销接口调用示范（一般不需要调用此接口，当游戏自己需要做注销账号功能时才调用） <pre class="brush:js;toolbar:false">QuickSDK.logout(function(logoutObject){ console.log('Game:成功退出游戏'); }) </pre> 6.2 注销回调调用示例（注销回调必须接入） <pre class="brush:js;toolbar:false">QuickSDK.setLogoutNotification(function(logoutObject){ console.log('Game:玩家点击注销帐号'); }) </pre> 注意：一般Android、iOS渠道会返回此回调，H5绝大部分渠道没有此回调（一些渠道切换账号返回的是注销成功的回调而不是切换账号的回调，所以游戏一定要接好此回调，在收到注销成功回调后，需要清除当前的角色信息，然后重新进行初始化登录，或者直接reload） <h4> 7.调用实名认证接口（目前渠道基本都做了实名跟防沉迷，游戏无需再调此接口来获取实名信息做防沉迷限制） </h4> H5渠道有返回实名认证信息的，将通过这个接口返回给游戏 params是自定义参数，游戏可以随便传递，后面是回调函数，数据会在回调里进行返回 注：realName表示是否实名，值为1或者0；age表示是否已经成年，10为未成年，18为成年人；extra为扩展字段 <pre class="brush:js;toolbar:false" style="font-size:14px;">QuickSDK.getExtendsVal(params, function(data){})</pre> <h4> 8.Android/iOS其他接口支持 </h4> 8.1 QuickSDK.getChannelType();    获取渠道ID 8.2 QuickSDK.getExtrasConfig(key);    获取后台配置的产品自定义参数 8.3 QuickSDK.setOnResumeNotification(callback) ; 注册恢复home键时通知 8.4 QuickSDK.setOnStopNotification(callback); 注册按下home键时通知 8.5 QuickSDK.getExtendsVal("getScreenType",function(data){  })；  获取当前屏幕类型，data为JSON格式数据，true表示为刘海屏或者水滴屏，反之则不是。(此方法H5转安卓微端支持；为了适配刘海屏，苹果对HTML的viewport meta标签做了扩展处理，转iOS渠道的包游戏可参看此文档进行处理<a href="https://www.jianshu.com/p/bc87d1e25702" target="_blank">https://www.jianshu.com/p/bc87d1e25702</a>) 8.6 QuickSDK.getExtendsVal("getRealNameMsg",function(data){  })；  获取当前渠道实名信息&防沉迷信息，data为JSON格式数据，如：  {"uid":"jc453530202","resumeGame":true,"realName":false,"other":"","age":-1}   (此方法仅H5转安卓微端支持，但目前渠道基本都做了实名跟防沉迷，游戏无需再调此接口来获取实名信息做防沉迷限制)  8.7 QuickSDK.getExtendsVal("getDeviceId",function(data){  })；  获取QuickSDK生成的设备ID，data为JSON格式数据，如：  {"status":"yes","data":{"deviceId":"ADE41EC04DA7C54A074242EEB78509D9"}}  8.8 QuickSDK.callExtFunction("exit",{})  ；退出游戏接口  8.9 打开游戏传入的url QuickSDK.callUrl(url) ; 使用浏览器打开url QuickSDK.openUrlInApp(url) ; 在游戏内打开url 注意：iOS需要更新打包工具到3.1.4或者以上版本，才可以实现打开游戏传入的url <h4> 9.Android deeplink </h4> 先在QuickSDK后台，添加自定义参数为：deeplinkCode，值配置为对应渠道的code，然后浏览器打开超链接  举例吊起渠道号为134的H5转安卓包： 9.1 先在后台点击自定义Meta参数，添加deeplinkCode 9.2 在渠道参数配置页面，将添加的deeplinkCode参数值配置为134 9.3 重新出渠道包 <pre class="brush:js;toolbar:false"><a href="h5gameapp://quicksdkchannel/ChannelCode"></a><a href="h5gameapp://quicksdkchannel/134">打开134号渠道包</a></pre> 10.接入代码demo地址 https://gameyt.quicksdk.net/demo.php 再次提醒，接完此文档后的游戏地址不能直接用于测试，一定要配置好渠道，用渠道方提供的链接或者打出的渠道包进行测试！！！ 另附: H5游戏上架H5渠道后台配置流程：<a href="https://www.quicksdk.com/doc-214.html" target="_blank">https://www.quicksdk.com/doc-214.html</a> H5游戏上架Android或越狱渠道后台配置流程：<a href="https://www.quicksdk.com/doc-213.html" target="_blank">https://www.quicksdk.com/doc-213.html</a>