一、前言

    本文档用于引导技术人员进行PC游戏接入，阅读者需具备一定web基础。

    通信时SDK均采用UTF8编码，若游戏使用其他编码，在处理中文时需转为UTF8。

    调用接口的凭证为openId和openKey，由SDK后台分配，需自行前往创建，功能位于”系统设置/开放API“

    对于PC游戏，SDK提供了多种集成方式，具体可见文档：PC游戏接入方式说明

    本文档讲解上述第1种接入方式，即使用SDK提供的web界面基于OAuth协议进行授权认证

二、流程说明

1. 登录流程

    1.获取openId及openKey，获取方式可联系运营人员或自行通过SDK后台添加。

    2.按第三章第1点“构造登录链接”接口所需要的参数构造登录URL，并传入成功后的回调URL successUrl参数。

    3.游戏以webview打开构造好的登录界面，并监听UrlChange事件（这个 步骤各个开发语言略有不同，Demo是基于QT的可以参考）

    4.当监听到webview的URL跳转至successUrl时，游戏应关闭webview界面，从URL中解析GET参数，获取uid、authToken、username参数

    5.游戏客户端获取到uid和username后，不能直接使用，需传回游戏服务器，通过游戏服务器调用SDK验证接口验证authToken有效性，验证uid是否匹配

    6.游戏服务器调用authToken验证接口通过后，方可使用该uid匹配游戏角色并进入游戏。

    7.游戏客户端进入游戏后，需判断timeleft的值，若为-1时则无需计时，若大于0则代表玩家需进行防沉迷保护，游戏客户端需设置计时器开始倒计时，倒计时为0时应提示未成年玩家下线。

2. 支付流程

    1.玩家在游戏内点击道具购买后，游戏应调用第三章“支付下单接口”传入商品信息等参数，此接口会返回支付链接。

    2.以webview或使用默认浏览器打开该支付链接。

    3.玩家支付成功后，SDK将向游戏服务器发送成功通知（支付回调地址callbackUrl）。

三、接口列表

1. 构造登录链接

1.1  接口目的

    构造登录链接，以便在PC平台中使用webview加载登录界面。

    若游戏使用专属登陆器，可尝试从进程启动参数中获取authToken，若取到authToken，可略过此步骤，直接前往本章2接口验证authToken并免登录进入游戏。

1.2 接口地址

   https://qkgamesdk.quickapi.net/open/oauth

1.3 请求方式

   GET

1.4 参数列表

参数	类型	必要性	说明
openId	string	必传	开放平台开发者身份id，由SDK分配，可通过后台获取
productCode	string	必传	产品标识，由SDK分配，可通过后台获取
channelCode	string	选传	分包标识，可选。用于识别玩家来源
successUrl	string	必传	完成登录后的回调地址（此地址由研发自行提供）
cancelUrl	string	可选	点击关闭按钮时，将跳转至此URL，游戏可捕捉该UrlChange事件
noQrLogin	string	可选	传1时关闭扫码登录
stopClose	string	可选	传1时禁用关闭按钮
lang	string	可选	多语言，支持zh、zh-TW、en
theme	string	可选	窗口风格参数,共有模板可选web,gameLauncher,android,dark

   注：登录页通常会100%铺满webview的尺寸，故游戏的webview多大，授权网页将等同其大小。

   游戏可自定义webview尺寸。

   作为建议，我们建议不同theme的尺寸如下：

   web风格：470x475 (默认使用web风格)

   androrid风格：470x535

   gameLaucher风格：510x460

   dark风格：470x510 （注意，若使用dark风格，建议将webview设为透明状态以提高显示效果）

1.5 返回字段

   当玩家登录完成，SDK会跳转时传入的successUrl链接。同时附带uid、username、authToken参数。

   游戏客户端应监听URLChange并关闭webview同时解析GET参数，获取这几项参数。

参数	类型	必要性	说明
uid	string	必有	玩家身份唯一标识，游戏应以此匹配玩家角色
username	string	必有	玩家用户名，游戏可以记录，但需以uid作为唯一标识
authToken	string	必有	授权令牌，游戏服务器应调用授权验证接口，验证authToken和uid是否匹配

2. 验证uid及authToken

2.1 接口目的

   验证客户端获取的uid和authToken是否匹配，防止篡改。

2.2 接口地址

   https://qkgamesdk.quickapi.net/webOpen/checkToken

2.3 请求方式

   POST

2.4 参数列表

参数	类型	必要性	说明
openId	string	必传	开放平台开发者身份id，由Quick官方SDK分配
productCode	string	必传	产品CODE，在Quick官方SDK后台获取
channelCode	string	选传	cps分包标识，选传，不传系统默认website，如果是用登录器登录的，可以通过启动参数获取
authToken	string	必传	登录成功回传的authToken
sign	string	必传	签名串，算法详见第4章签名算法描述

2.5 返回字段

    接口会返回JSON格式字符串，如：

    例1 {"status":false,"message":"tokenUidError",”data”:[]}

    例2 {"status":true,"message":"","data":[]}

    注：以下参数只有当status为true且data不为空才有

参数	类型	必要性	说明
uid	int	必有	SDK用户uid
deviceId	string	必有	设备信息设备号
productId	string	必有	产品id
tokenIp	string	必有	ip
token	string	必有	token
timeleft	int	必有	防沉迷标识，-1时无需处理，大于0时应启动倒计时定时器，在到期后提示未成年玩家下线，单位为秒

3. 创建订单并构造支付链接

3.1 接口目的

   通过此接口传入下单数据，下单成功后可返回进入支付的连接。

3.2 接口地址

   https://qkgamesdk.quickapi.net/webOpen/getPayUrl

3.3 请求方式

   POST

3.4 参数列表

参数	类型	必要性	说明
openId	string	必传	开放平台开发者身份id，由Quick官方SDK分配
productCode	string	必传	产品CODE，在Quick官方SDK后台获取
channelCode	string	选传	cps分包标识，选传，不传系统默认website，如果是用登录器登录的，可以通过启动参数获取
amount	float	必传	将要下单的金额，单位元
userId	string	必传	sdk登录成功返回的uid
cpOrderNo	string	必传	游戏订单号
orderSubject	string	必传	商品描述
goodsName	string	必传	商品名称
goodsId	string	必传	商品id
roleName	string	必传	角色名
roleLevel	float	必传	角色等级
serverId	string	必传	区服id
serverName	string	必传	区服名称
extrasParams	string	选传	透传参数，通常为研发需要的特定参数，sdk会原样回调。
callbackUrl	string	选传	支付成功回调结果的地址
successUrl	string	选传	支付成功的提示界面，点击回到游戏时的链接，不传则该按钮无法点击
cancelUrl	string	选传	点击取消时的链接，不传则不会出现取消按钮
theme	string	选传	界面样式风格，参考登录界面的theme参数
sign	string	必传	签名串，算法详见第4章签名算法描述

3.5 返回字段

    接口会返回JSON格式字符串，如：

    例1 {"status":false,"message":"tokenUidError",”data”:[]}

    例2 {"status":true,"message":"","data":[]}

参数	类型	必要性	说明
status	bool	必有	接口验证状态，若通过验证为true，否则为false
message	string	必有	Status为false时，message有值，为错误提示语
data	array	可为空	如果status为true时，data数组包含了订单详细信息

    接口会返回JSON格式字串，形如：

{"status":true,"data":{"payUrl":"https://qkgamesdk.quickapi.net/payH5/payCenter?clientLang=zh-cn&data=zzk4puUOWCH13TXOOb6AuOhAiGb/slIUrw2+EURpRinTg1ubbYeMjLBb+Z3cVnn0AulLuWVOud86+EudHyYqX3oililkAcDT5G2+E9Og4U8=&sign=ce30d0a71aa2584bb8ee91921f4dca57"},"message":"请求成功"} 说明：返回的JSON结构体里，data.payUrl即为当前接口返回的完整支付页面url

4. 构造并打开个人中心

4.1 接口目的

    用户构造用户中心地址，以便在游戏中打开用户中心，方便玩家进行修改密码等操作。

4.2 接口地址

    https://qkgamesdk.quickapi.net/openCenter/index

4.3 请求方式

GET

4.4 参数列表

参数	类型	必要性	说明
appProduct	string	必传	产品CODE，在Quick官方SDK后台获取
channelCode	string	选传	cps分包标识，选传，不传系统默认website
authToken	string	必传	登录成功回传的authToken

4.5 返回字段

  该接口无返回，以webview或默认浏览器加载构造的URL即可

5. 上传角色信息

5.1 接口目的

   通过此接口上报游戏的角色信息

5.2 接口地址

    https://qkgamesdk.quickapi.net/webOpen/setGameRoleInfo

5.3 请求方式

   POST

5.4 参数列表

参数	类型	必要性	说明
openId	string	必传	开放平台开发者身份id，由Quick官方SDK分配
productCode	string	必传	产品CODE，在Quick官方SDK后台获取
channelCode	string	选传	cps分包标识，选传，不传系统默认website，如果是用登录器登录的，可以通过启动参数获取
userId	string	必传	sdk登录成功返回的uid
vipLevel	string	必传	vip等级
deviceId	string	必传	设备信息设备号
partyId	string	选传	帮派id
partyName	string	选传	公会社团名称
userRoleName	string	必传	角色名称
userRoleLevel	string	必传	角色等级
userRoleBalance	string	必传	角色用户余额
userRoleId	string	选传	角色ID
serverId	string	选传	区服ID
serverName	string	必传	区服名称
sign	string	必传	签名串，算法详见第4章签名方法描述

5.6 返回字段

  

    接口会返回JSON格式字符串，如：

    例1 {"status":false,"message":"tokenUidError",”data”:[]}

    例2 {"status":true,"message":"","data":[]}

参数	类型	必要性	说明
status	bool	必有	接口验证状态，若通过验证为true，否则为false
message	string	必有	Status为false时，message有值，为错误提示语
data	array	可为空	如果status为true时，data数组包含了角色详细信息

    接口会返回JSON格式字串，形如：

{"status":false,"data":[],"message":"Mandatory param missing:sign"}

四、签名方法

  第一步：对所有参与请求的参数（排除sign本身）进行字典升序排序，首字母相同则按第二位升序，类推。

  第二步：使用上述参数构造签名串比如key1=val1&key2=val2&key3=val3依次类推，假如得到签名串StringA，注意key与val都是urldecode之后的值。

  第三步：拼接最终的签名串StringB = StringA + "&" + openKey(通过开发者平台获取)。

  第四步：使用md5计算第三步签名串哈希值即为：sign=md5(StringB)。

五、其他注意事项

   当登录系统包含第三方授权登录时，游戏的webview应支持新窗口打开方法。各程序语法有差异，大体思路为继承webview控件重新实现onCreateWindow之类的方法。

   新标签也应监听urlChange事件，当跳转至successUrl时应关闭webview并解析参数。

   为获得较好的视觉效果，如圆角等，可将webview控件设为透明模式。等待webview加载网页期间，可设置一些过渡动画。