shudao-main/移动客户端与H5对接规范.md

移动客户端与H5对接规范

一、概述

在移动互联网技术发展成熟的今天，为了更好的满足app快速研发、及时更新、模块分离等需要；在原生应用中集成H5页面也越来越重要和常见。因此需要制定良好的规范以提高软件整体质量及研发效率。

二、集成形式及系统环境

（一） 集成形式

简单来说，就是把H5放到客户端中加载。为了更好的提升体验，客户端要保证H5容器的稳定和性能，

客户端需要为H5提供加载容器及基本的能力支持，如：上传文件、定位、错误处理。

（二） 宿主系统环境

Android：最低支持Android 8.0 系统，浏览器内核为Chrome；

iOS：最低支持iOS 13系统，浏览器内核为WebKit。

针对上述宿主环境，H5业务系统需要做兼容性适配。

三、集成要求

（一） 单点登录

1. app访问H5业务系统时，首先调用该系统接口获取授权token，然后按照该业务系统要求携带相关参数访问业务系统h5链接，实现单点登录。

2. 针对业务系统无权限用户，需要返回给app单独的错误码和错误提示信息。

3. 如使用4a作为认证，在访问业务系统时，无权限账户要进行友好提示。

（二） 导航栏设计

1. 建议使用app原生导航栏，app会监听h5页面标题的变化并进行展示。

2. 如受到业务系统限制不能使用app原生导航栏，需要调用交互关闭导航栏。

3. H5页面自定义导航栏的情况下，需要适配安全区并且需要增加关闭原生页面的交互。

（三） H5与app交互

为了保证业务系统功能完善、性能优良，对接时往往需要支持多种交互。

3.1 返回上一级与关闭页面

在使用app原生导航栏的情况下，建议同时添加“返回webGoBack()”和“关闭页面（nativeClosePage()）”这两个交互来实现返回上一级、关闭页面的功能；如业务系统评估不需要增加，则app根据webview返回栈调用返回和关闭。

3.2 当前支持的交互

当前支持的交互内容如下表所列，H5业务系统可以按照需要使用；如需要增加新的交互，可协商添加。

序号	功能	交互名称	动作（需求）表述	交互集成建议	备注
1	返回与关闭	webGoBack()	H5提供JS返回方法，供原生调用	建议集成	点击原生返回按钮时调用，由h5执行返回逻辑
		finishPage()	JS调用原生交互关闭当前页面	建议集成
2	原生导航控制	showNativeNav(show)	JS调用原生方法关闭/显示导航栏	按需	参数show：0隐藏，1显示
3	下载文件	downloadFile(url)	JS调用原生方法下载文件；下载后自动预览	按需	对于H5不支持查看（或需要下载）的文件，需要通知原生进行下载查看。参数url：下载地址的全路径。
4	扫描二维码	startScan()	JS调用原生方法扫描二维码	按需
5		setScanResult(String result)	原生将扫码结果传递给h5	按需
6	请求定位权限	requestLocPerm()	JS调用原生方法请求获取定位权限	按需
		getLocationCallback()	原生通知定位权限获取成功	按需
7	打电话	callPhone(tel)	JS调用原生方法拨打电话	按需