Appearance
一、概述
在财运通应用场景之中，终端用户需要从应用侧发起咨询或报障，这些应用的底层技术架构各异、开发商有别。本文档用于说明不同应用如何依据同一规则，以较低成本集成“财运通”，从而为任何平台赋予财运通的问题搜索、反馈以及解答功能。
二、集成机制和流程
“财运通”应用的集成采用SDK的方式进行集成，被集成应用需要在应用页面初始化时加载ZKHelp.js资源，加载完成后可使用ZKHelp类进行实例化，实例化的时机应为用户登录完成后，需要在实例化时提供应用和用户信息，实例化完成后会在当前页面的右下角出现一个问题反馈的图标。设置完成后通过点击图标即可弹框方式呼起财运通提交咨询保障的相关功能界面，用户提交咨询内容后数据进入财运通平台，后续由客服人员针对咨询单进行回复完成业务闭环。
具体的对接流程如下：
- 引入js包：平台、应用的前端项目中，在资源加载阶段，引入ZKHelp.js资源包。
- 应用id获取：为了简化用户需反馈的信息，使得财运通能够快捷地区分反馈的内容来自哪个应用，因此采用预置的方式，由各应用在集成时根据被分配的应用id（应用接入前由财运通平台具体提供），配置对应参数。
- 初始化信息：集成的应用页面中，在用户登录完成后，需要基于ZKHelp进行实例化，实例化中配置应用id参数和当前登录用户id参数（统一使用已登录账号的浙政钉uid值）。
点击图标呼起财运通弹框页面前会进行当前所在应用页面信息的采集，相关内容会随咨询内容一并发送到“财运通”应用中，具体包括：
- 对当前应用的显示内容进行自动截图（如页面还包含其他iframe则iframe内部内容不会被包含在截图内），用户也可基于截图进行二次截图标注，如添加标注或隐藏一些敏感信息。
- 同时附带用户的浏览器userAgent及网页相关的信息，用于后续的问题排查分析。
三、集成方案说明
- 在需要集成的应用html页面中引入加载ZKHelp.js。
<script src="ZKHelp.js"></script>
- 在应用页面中用户登录完成后，实例化ZKHelp并设置应用id和用户id
let helper = new ZKHelp({
appId: 123456, // 注册成功后提供的应用id
userId: 888888 // 用户的浙政钉id号码
})
具体使用时可根据条件判断是否进行实例化，以达到“满足条件的用户才可见”的目的。集成完成后进行测试，打开页面右下角出现“财运通”应用的图标，点击图标弹出反馈页面框。该弹框页面采用iframe方式，基于浙政钉id单点登录逻辑进行免登验证，若该id在“财运通”项目下有账号，则可以顺利登录并查看“财运通”页面。
四、约束和前提条件
- 浏览器兼容性
本方案采用前端集成的形式，仅支持B/S架构应用，要求接入应用系统采用HTML形式进行构建，支持H5、Vue、React、Angular等前端框架，其中使用的截图功能基于html2canvas进行实现，因此支持的浏览器为：
IE9+
Opera 12+
Safari 6+
Firefox 3.5+
Google Chrome
Edge
- 代理
因财运通平台与各应用部署环境是各自独立的，因此存在跨域请求问题。为规避各浏览器对安全要求的差异性，因此推荐采用本地代理方式。即应用侧服务器需通过nginx等web中间件，配置本地代理/cyt-api指向财运通服务地址 http://10.249.43.237/cyt-api （政务外网）
五、常见问题
- 点击图标后出现页面无内容或为登录页
需检查用户登录完成后其用户id（浙政钉id）是否被正确初始化；截图保存接口是否顺利传入该用户id并返回token及id，新开页面的iframe的url中get参数是否正确包含token和id，且其值不为undefined。若这些内容均正常，则可能是“财运通”平台的单点登录问题，可尝试再次点击或联系“财运通”服务人员协助排查解决。
- 如何控制图标在页面中的显隐
zkhelper对象提供一个方法控制其显示隐藏，可使用window.zkhelper.toogle(true)或window.zkhelper.toogle(false)来控制其是否显示，前者为显示，后者为隐藏。
- 截图功能异常
需检查浏览器是否支持canvas截图，页面内容中是否存在复杂内容（如占用空间较大的图片、视频）等，截图功能无法保留iframe中的内容或屏幕范围以外的内容，主要用于问题反馈的依据进行使用，不能保证与原页面的1：1还原。