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业务系统可以按照需要使用；如需要增加新的交互，可协商添加。 移动端集成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调用原生方法拨打电话 按需