文档中心

一、前言

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

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

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

    对于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
必传
完成登录后的回调地址（此地址由研发自行提供）cancalUrl
string可选点击关闭按钮时，将跳转至此URL，游戏可捕捉该UrlChange事件noQrLogin
string可选传1时关闭扫码登录stopClose
string可选传1时禁用关闭按钮langstring
可选
多语言，支持zh、zh-TW、enthemestring
可选
窗口风格参数,共有模板可选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参数，获取这几项参数。

参数
类型
必要性
说明
uidstring
必有
玩家身份唯一标识，游戏应以此匹配玩家角色
usernamestring
必有
玩家用户名，游戏可以记录，但需以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
必传
签名串，算法详见第7章签名算法描述

2.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数组包含了用户账号信息

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

参数
类型
必要性
说明
uid
int
必有
SDK用户uid
deviceId
string
必有
设备信息设备号productId
string
必有
产品idtokenIpstring必有
iptokenstring必有tokentimeleft
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

必传

游戏订单号

orderSubjectstring必传商品描述goodsNamestring
必传
商品名称goodsId
string
必传
商品id
roleNamestring必传
角色名roleLevelfloat
必传
角色等级serverIdstring
必传
区服id
serverName
string
必传
区服名称extrasParams
string
选传
透传参数，通常为研发需要的特定参数，sdk会原样回调。callbackUrl
string
选传
支付成功回调结果的地址successUrl
string
选传
支付成功的提示界面，点击回到游戏时的链接，不传则该按钮无法点击cancalUrl
string
选传
点击取消时的链接，不传则不会出现取消按钮theme
string
选传
界面样式风格，参考登录界面的theme参数

sign

string

必传

签名串，算法详见第7章签名算法描述

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加载网页期间，可设置一些过渡动画。

相关知识

游戏秘籍文档
策划入门指北01：如何编写游戏设计文档
游戏攻略word文档,游戏攻略：掌握技巧，提升游戏水平
微信小游戏开发文档
感化中心好玩吗 感化中心玩法简介
Pygame 官方文档
oppo游戏中心下载
礼包中心
拳击训练中心好玩吗 拳击训练中心玩法简介
游戏礼包领取中心

网址: 文档中心 http://www.hyxgl.com/newsview358291.html