# PC SDK接入说明文档
### 文档历史
| **修订日期** | **修订内容** | **修订版本** | **修订人** |
| ------------ | ------------ | ------------ | ---------- |
| 2020-11-05 | 说明文档初版 | V1.0 | 福小月 |
**文档阅读提示：**勾选视图中的**导航窗格**，可以让您快速阅读和定位。
## 接入PC SDK联系人
| **业务项** | **对接人** | **说明** |
| ---------------------- | ---------- | --------- |
| PCSDK产品 | 别如雨 | PCSDK产品 |
| 接入需求对接人 | 梨可可 | PCSDK运营 |
| 打包工具&SDK独立端问题 | 张三丰 | PCSDK前端 |
| 管理后台&接口服务问题 | 其昂 | PCSDK后端 |
| 如何进行测试问题 | 蟹王堡 | PCSDK测试 |
### 外链地址汇总
| [SDK接入游戏运营准备项（接入信息、素材&配置参考）](https://youzu.feishu.cn/sheets/shtcniEIocGFlIAmpdy1jazrPJb?sheet=876463) |
| ------------------------------------------------------------ |
| [Sdk独立端&渠道接口文档V2.0](https://youzu.feishu.cn/docs/doccnMXKD1O11AHViai494pGhxe) |
| [exe游戏&SDK端通信协议文档说明](http://showdoc.gtarcade.com/index.php?s=/page/1182) （页游无需关注） |
## 一、游戏接入说明
### 1.PC SDK接入流程线
(1) 游戏方与微端项目组沟通确定明确接入需求、接入类型及大致时间节点。按照文档 [SDK接入游戏运营准备项（接入信息、素材&配置参考）](https://youzu.feishu.cn/sheets/shtcniEIocGFlIAmpdy1jazrPJb?sheet=876463) 填写游戏和渠道信息、发送需求邮件。
(2) 游戏方和渠道方准备（具体参考本文档第三、第四部分详细说明）：
- 素材、自定义配置、打包环境、签名证书
- 接入开发事项（协议参考技术文档说明：[Sdk独立端&渠道接口文档V2.0](https://youzu.feishu.cn/docs/doccnMXKD1O11AHViai494pGhxe) ）：
如是SDK内登录选服：渠道需按照协议制作登录页选服页
如是浏览器唤起SDK端直接进游戏：渠道需按照协议实现唤起SDK及用户态免登功能
(3) 创建游戏沟通群（一个游戏一个渠道一个群，信息清晰明确），微端项目组给游戏方提供授权账号，打包工具
(4) 游戏方在SDK管理后台配置游戏发行渠道信息
(5) 游戏方在SDK管理后台下载授权文件，使用打包工具打出游戏成包
(6) 游戏方进行游戏成包测试验收
(7) 游戏方测试通过后，使用打包工具上传成包至后台，在SDK管理后台发布上线，获取成包下载地址。
**游戏接入SDK微端需求邮件模板 【一个游戏一个渠道一封邮件,**信息**清晰明确】**
**标题：**XXX游戏发行XX渠道接入PC SDK需求
**发送：别如雨（biehf@yoozoo.com）；梨可可(li_mm@yoozoo.com) ; 华天(dongzh@youzu.com) ；****渺渺朱(cynthia朱渺)**(zhumm@yoozoo.com)**; 张三丰(liwanxi@yoozoo.com)****;大璐（****zhanglu@yoozoo.com****）；**
**抄送：波仔(hbzhang@youzu.com)；**
**内容：**
[SDK接入游戏运营准备项（接入信息、素材&配置参考）](https://youzu.feishu.cn/sheets/shtcniEIocGFlIAmpdy1jazrPJb?sheet=876463) 在该表格中填好，截图放邮件内容里。
**如接入途中，游戏的渠道需变更接入模式。游戏运营需修改在线表格中的接入模式，并回复之前的接入需求邮件，截图以及说明变更信息。**
### 2. PC SDK支持如下两种接入模式
(1) SDK端上登录、选服、进游戏模式：
***此模式，渠道方需提供给PC SDK端登录页、选服页，具体制作要求见第三部分的渠道准备项**
SDK端Demo包地址：[Demo包参考文件](https://oss.youzu.com/test%2Fmicrosdk%2F46573540-593d-4f6f-bb69-ae3568f85474.exe?Expires=1638945971&OSSAccessKeyId=LTAIxkKeVZyhIF2V&Signature=UDNBrvhdW830BDGKqtzR%2FlTYwDU%3D&response-content-disposition=attachment%3Bfilename%3D"36jweb.exe")
Demo参考地址：http://micro-web.youzu.com/browser.html
渠道登录页和选服页具体需实现的功能，请参考第三部分说明。
登录页Demo参考：https://micro-web.youzu.com/en/home?gameId=193&opId=1&appId=36.youzu.com
选服页Demo参考：https://micro-web.youzu.com/en/home?gameId=193&opId=1&appId=36.youzu.com
(2) 浏览器渠道网页登录、选服，后调起SDK端进游戏模式：
选用这个模式，需要把自定义配置中，小号多开关掉，登录页地址配置去掉！！
*此模式，渠道方需做如下技术开发处理：
- 提示引导玩家下载安装PC SDK。
- 玩家本地已安装PC SDK，浏览器页面可以在用户完成登录选服后，调用协议启动PC SDK端进游戏(具体参考调用协议中的外部浏览器启动协议[Sdk独立端&渠道接口文档V2.0](https://youzu.feishu.cn/docs/doccnMXKD1O11AHViai494pGhxe#) )
- 渠道需实现用户态免登逻辑，以支持在浏览器中用户已经登录的用户态，在SDK端上进游戏时能获取用户态。（可参考我们Demo的内部逻辑实现方式）
Demo参考地址：http://micro-web.youzu.com/browser.html
测试登录账号，使用游族官网的账号登录。区服填区服ID，如2466310853
### 3.PC SDK支持如下两种游戏类型
(1) **游戏网页版接入**游戏
*SDK内置的chrome浏览器中运行
(2) 游戏exe包端的方式接入
*游戏exe包独立可执行，由SDK程序触发控制运行的方式
游戏方需提供游戏母包，exe文件。
游戏方需按照 [exe游戏&SDK端通信协议文档说明](http://showdoc.gtarcade.com/index.php?s=/page/1182)，接入通信协议。
*注：已经接入GTarcade微端平台的exe游戏，不需要重复接入。仅需联调。*
## 二、PC SDK说明
### 1.PC SDK简述
游族PC SDK是将页游、端游母包打包成桌面原生应用的解决方案，支持游戏发行不同渠道。
页游无游戏母包，仅添加配置文件即可。
PC SDK参考UI效果图：
PC SDK功能：
(1) SDK端安装、更新、卸载
安装：安装在系统剩余空间最大的磁盘里，文件夹名称是游戏配置文件中的安装名称。
更新：启动游戏时，会检测游戏包更新。（使用SDK管理后台发布游戏包，并且游戏包内部版本号有递增，才会有更新功能）
卸载程序：双击运行uninstall.exe即可卸载
(2) SDK端主窗口
内嵌渠道登录页、选服页
(3) SDK端游戏窗口
页游：SDK窗口内嵌chrome浏览器，渲染游戏画面
端游：游戏exe程序
(4) SDK端任务托盘
- 小号多开：可在自定义配置文件，配置是否显示，以及支持数量，支持编辑昵称备注小号。 渠道唤起微端，要在配置文件中关掉小号多开功能。
- 开机自启动：可在自定义配置文件，配置是否显示
- 联系客服：配置文件中配置了客服地址，则显示联系客服功能
- 游戏修复：强制更新游戏成包exe到最新版本
- 创建桌面快捷方式：配置文件中配置了桌面快捷方式名称，则支持创建桌面快捷方式
- 切换多语言：
- 退出：退出SDK端功能
(5) SDK日志路径：C:/Users/%USERNAME%/AppData/Roaming/YOOZOO/app/log
### 2.打包工具
[打包工具-QA.zip](https://youzu.feishu.cn/file/boxcnQt7J4TwbG3HgcaFwFZ9Tq5)
（打出的包，上传包时会传到SDK管理后台的QA环境）
[打包工具-线上.zip](https://youzu.feishu.cn/file/boxcn4zJ179GlW3LSZRV4ge9rjb)
（打出的包，上传包时会传到SDK管理后台的线上环境）
#### 打包工具打包流程
通过打包工具将游戏和自定义配置打包成一个可独立安装启动运行的游戏成包。
***使用打包工具 需先从管理后台下载导出签名授权文件 放到打包工具的指定目录下。 并且本地需安装VS环境。**
1. 准备各类文件，放至对应目录下
签名授权文件，从后台下载签名授权文件，放到打包工具的data目录下。(sign.txt)。
游戏自定义的配置文件，放到data目录下。（template.xml） 。
选择template.xml文件打包之前，请先确认文件xml格式没有被改坏。比如浏览器上可以正常解析、正常访问。
图片素材压缩包文件，放到打包工具目录下。（img.zip）。
2. 本地安装VS环境
下载VS程序[vs_community__1382699039.1584356171.exe](https://youzu.feishu.cn/file/boxcnPQRyfw8qHY8mxmTqtbmC0c)
安装VS程序（安装时如图所示需勾选使用C++的桌面开发，选中VS 2015C++生成工具）
3. 进行打包。双击运行打包工具exe。（IntegratedUIBox.exe）
4. 选择SDK版本（通常选择最新的，有问题可以问SDK技术）
5. 选择游戏发行渠道、游戏、游戏分支（页游默认选中）、
6. 内部版本号（自动生成，游戏包更新功能依赖内部版本号）、填写外部版本号（如1.0.0）、
7. 选择配置文件地址（游戏自定义配置，template.xml）、
8. 选择资源包路径（图片素材地址，img.zip）、
9. 选择成包目录（游戏成包存放文件夹）、
10. 选择MSBuild.exe文件（Visual Studio的安装目录下选中MSBuild.exe，默认是C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/MSBuild/Current/Bin目录下）
11. 选择自动签名（签名代表这个程序 是XX制作 或者XX发行的 这种签名证书。 这个证书是经过微软认证的。 如果打出来的exe包不带签名。就可能会被杀毒软件拦截，和微软就会弹出安全提示拦截程序运行,如下图：
**公司内的游族渠道和gtarcade渠道找樱木要 签名证书（不可外传，仅供内部使用，如果有什么特别需求。一定得和樱木申请和沟通确认）。 其他的外部渠道，尽量让外部渠道提供数字证书（如果实在没有，需要用我们公司的，一定得和樱木申请和沟通确认）。**
签名工具：[签名工具&说明.zip](https://youzu.feishu.cn/file/boxcn04IxbWUUacVBB0t8EclQbf) 拿到数字签名证书后，下载签名工具。按照使用手册安装和配置签名工具。
先安装signtools-setuo.exe程序。安装完成后。按照数字签名工具使用手册（**参考数字签名工具使用手册.pdf文件**），运行DSignTool.exe程序，配置导入证书，添加签名规则。签名规格填写gtarcade
安装和配置好签名工具后。 拿到安装的目录。 在打包工具中选中CSignTool.exe文件。打包工具签名规则填写gtarcade
4. 开始打包
点击开始打包，程序开始制作成包，此时不要强制关闭打包界面和自动编译的窗口。
打包完成后，会有游戏成包文件。 其他文件为编译器生成的临时文件（无需过多关注）。生成的游戏成包不要修改exe文件名称（上传成包时，只选exe文件，会根据文件自动读取信息）。
#### 打包工具上传流程
通过打包工具将成包上传至管理后台，在后台发布后，用户将可下载更新
注：游戏和渠道也可以把打包好的exe游戏成包，直接放到游戏的渠道页面上。
可以不使用SDK管理后台去管理成包版本，但这样就无法做到exe包自动升级更新，如果游戏升级更换了新exe包，用户需要重新下载安装。
打包工具出包成功后，会有弹窗提示，点击确认，会切换到打包工具上传界面。
选择好打包工具打出的成包，游戏成包信息会自动读取，正常情况无需再修改编辑。
确认内部版本号有递增，填写好版本更新描述就可以开始上传了。
上传至后台。默认是未发布状态，需要去管理后台点击发布。（传到线上，包测试没问题后，要点击发布，这样用户本地装好的包才能更新到最新。）
#### 打包工具界面效果图
### 3.SDK管理后台
后台地址：https://developers.gtarcade.com/sdk/games-client
登录账号：由微端平台创建账号/授权账号
#### 导出签名授权文件
用于授权使用打包工具，导出的文件，放在打包工具文件夹data文件目录下。
#### SDK版本管理
包含SDK版本和SDK支持的游戏，由微端平台操作、配置和发布。
#### 游戏配置
渠道管理：选择游戏，选择渠道，渠道描述，以及游戏在该渠道的发行状态。
#### 分支管理：支持一个游戏配置多个版本
页游，无需配置分支管理。
端游，通常游戏只需使用默认分支，如端游一个游戏不同区服为不同游戏版本（比如GOT-PC，永测服和正式服在某个渠道同时发行的情况），需增加配置游戏分支。
#### 游戏包版本管理
管理用户使用的游戏独立端。
使用打包工具上传测试通过的游戏成包。上传后，默认是未发布状态。后台可编辑成发布状态。
游戏包版本的资源地址，可以下载游戏成包。
## 三、渠道准备
1. 签名证书
给游戏包打包时的数字签名证书，代表这个程序是正规公司发行的应用， 签名证书是经过微软认证的。 如果打出来的exe包不带签名。就可能会被杀毒软件拦截，和微软就会弹出安全提示拦截程序运行, 具体签名说明及没有签名效果，见打包工具的打包流程中的数字签名说明。
2. 渠道登录页
*在浏览器上 渠道网页中登录：可以不用制作登录页
1. (1) 登录页-未登录状态
界面参考（红框内区域）：游戏图、账号密码输入框、登录按钮、自动登录选项、注册账号入口、游戏官网/游戏充值/客服中心入口 ...
功能参考：实现登录功能（登录成功后，回调通知SDK独立端）
自动登录功能（勾选自动登录，用户态有效时间内，下次运行SDK独立端可免除输账号密码登录，直接能获取用户登录态进入选服页/游戏内）
渠道方技术实现功能时、注意参考协议文档：[Sdk独立端&渠道接口文档V2.0](https://youzu.feishu.cn/docs/doccnMXKD1O11AHViai494pGhxe#PGkbiE)
1. (2) 登录页-已登录状态
*有选服页游戏无需制作，无选服页如GOT-PC游戏，需让渠道方制作此红框内已登录状态页面
界面（红框内区域）：当前已登录账号，切换其他账号按钮，开始游戏按钮，游戏官网/游戏充值/客服中心入口 ...
功能：实现切换账号功能（登出当前账号，回调通知独立端，清除本地cookie）
开始游戏功能(回调通知独立端；独立端收到后，调用进游戏sdk接口启动游戏)
*渠道方根据发行需要，自行考虑页面内的文案，自行考虑是否制作登录页面内的文案的本地化。页面内自己实现。sdk端可以切换语言（可以配置是否允许切换语言），页面内可以调用sdk的协议获取当前SDK端的语言。文案参考示例*[PC SDK多语言参考](https://youzu.feishu.cn/sheets/shtcnSAx7jEbf2Q6chI2TQ3qBne?sheet=c0Km67)
#### 渠道选服页
*在浏览器上 渠道网页中选服或者没有选服的游戏：可以不用制作选服页
界面参考（红框内区域）：我的服务器列表，推荐服务器列表，全部服务器列表，切换账号按钮，游戏官网/游戏充值/客服中心入口 ...
功能参考： 实现切换账号功能（登出当前账号，回调通知SDK独立端，清除本地cookie）
实现进游戏功能(点击某个区服后，回调通知SDK独立端，SDK独立端收到后，调用进游戏接口/地址进入游戏)
**渠道方技术实现功能时、注意参考协议文档：[Sdk独立端&渠道接口文档V2.0](https://youzu.feishu.cn/docs/doccnMXKD1O11AHViai494pGhxe#PGkbiE)**
*渠道方根据发行需要，自行考虑页面内的文案，自行考虑是否制作选服页面内的文案的本地化。页面内自己实现。sdk端可以切换语言（可以配置是否允许切换语言），页面内可以调用sdk的协议获取当前SDK端的语言。文案参考示例*[PC SDK多语言参考](https://youzu.feishu.cn/sheets/shtcnSAx7jEbf2Q6chI2TQ3qBne?sheet=c0Km67)
#### 渠道进游戏地址
*页游进游戏地址，exe端游戏按照通信协议文档实现进游戏
功能：sdk端调用进游戏地址，可以正常进入游戏
进游戏地址，由选服页选服成功后传递给SDK端，SDK端透传给游戏。比如：http://game.youzu.com/play?type=web&gameId='+gameId+'&serverId='+server_id+'&opId=' + opId+'&manual: '+manual
PC SDK端游戏窗口效果图如下：
#### 渠道充值页
充值页可以选购游戏商品，能正常支付，成功支付后游戏能正常发货到账。
#### 游戏客服页
*非必要项，可以没有
客服页面
#### 游戏官网页
*非必要项，可以没有
游戏官网页面
## 四、游戏准备
### 1.游戏自定义配置
自定义配置为xml文件，可在[SDK接入游戏运营准备项（接入信息、素材&配置参考）](https://youzu.feishu.cn/sheets/shtcniEIocGFlIAmpdy1jazrPJb?sheet=dIle51) 文档中参考配置说明，下载参考模板。
游戏每个渠道准备一份渠道对应的游戏自定义配置。
编辑后的template.xml建议使用浏览器打开检查格式是否符合规范。
正常的格式应该显示类似下图：
下表是可配置项说明：
[SDK接入游戏运营准备项（接入信息、素材&配置参考）](https://youzu.feishu.cn/sheets/shtcniEIocGFlIAmpdy1jazrPJb?sheet=dIle51)
### 2.游戏SDK微端包素材
SDK端使用的图片素材参考文件（游戏方看需要更换游戏自己的图片，文件名称严格参照文件夹中的图片名称来，图片素材文件夹目录也不要做更改调整）：
如果游戏采用的是浏览器唤起SDK端的模式，不使用SDK登录和选服。图片素材更换icon、更新窗口底图（尺寸不变）就行，任务托盘素材更换是可选的。
**PC-独立端素材说明如图：**
[SDK接入游戏运营准备项（接入信息、素材&配置参考）](https://youzu.feishu.cn/sheets/shtcniEIocGFlIAmpdy1jazrPJb?sheet=2zHqhL)
### 3. 游戏包制作
*不必要，网页运行的页游无需准备游戏包
exe端运行的游戏。 游戏需提供自测通过、可独立运行的游戏exe包
## 五、常见FAQ
| Q1：PC SDK支持渠道方登录、选服后唤起SDK端进游戏吗？ |
| ------------------------------------------------------------ |
| 答：支持 |
| Q2：PC SDK端支持自定义配置吗？ |
| 答：支持，游戏可按照素材建议制作，也可自行设计，SDK端大小可配置 |
| Q3：PC SDK登录页中的按钮跳转地址在哪里配置？ |
| 答：渠道登录页中写死的。游戏有特殊需求可跟渠道方沟通，渠道自定义 |
| Q4: PC SDK端充值可以在SDK端内打开充值页吗？ |
| 答：可以，配置就行 |
| Q5：渠道登录页可以增加点击按钮，增加第三方登录吗？ |
| 答：可以，登录页的点击功能渠道方自己实现/写死地址就行。第三方登录渠道方实现功能，在登录成功后把用户登录态根据协议标准告知给SDK端就行 |
| Q6：PC SDK端图片素材、SDK端配置文件由谁制作提供？ |
| 答：游戏方制作或者游戏的渠道方制作都行，游戏运营自己沟通协商确认 |
| Q7：打包工具由谁使用出包？ |
| 答：游戏研发或者游戏的渠道方研发来使用打包工具出包都行，游戏运营自己协商确认 |
| Q8：如何计算 login_web_rect ？ |
| 答： 1.从游戏UI设计稿通过UI标注得出Web页面距离外边框的横向纵向坐标，如下图分别为280,169 2.从web页面地址在浏览器中得出实际的Dom元素的宽高，如下图分别为717,381 3.最终 login_web_rect 的值为 （web页坐标顶点横轴起点，纵轴起点，横轴起点+web页面宽,纵轴起点+web页面高） 如下示例，等于 280,169,997,556 如果计算的位置，在SDK窗口上显示了横向纵向滚动条。顶点位置不变，后面的宽高调大。 如果计算的位置，在SDK窗口上显示了黑边。顶点不变，宽高调小 |
|  |
|  |