移动客户端与 H5 对接规范

一、概述

在移动互联网技术成熟落地的今天，为满足 App 快速研发、及时更新、模块分离 等需求，在原生应用中集成 H5 页面已成为常态。制定并遵循统一的对接规范，可显著提升软件质量与研发效率。

二、集成形式及系统环境

（一）集成形式

将 H5 页面内嵌至客户端 WebView 中加载。
客户端需保证 H5 容器的稳定性与高性能，并提供以下基础能力：
- 文件上传
- 定位
- 错误处理

（二）宿主系统环境

平台	最低系统版本	浏览器内核
Android	8.0	Chrome
iOS	13	WebKit

> H5 业务系统须针对以上宿主环境做兼容性适配。

三、集成要求

（一）单点登录

App 访问 H5 业务系统时，先调用后台接口获取授权 token。随后按业务方约定携带相关参数访问 H5 链接，完成单点登录。
对无权限用户，业务系统须返回专用错误码及友好提示。
若采用 4A 统一认证，无权限账号需给予明确、友好提示。

（二）导航栏设计

场景	建议方案	补充说明
常规场景	使用App 原生导航栏	App 监听 `document.title` 变化并同步展示
受限场景	必须调用 JS 关闭原生导航栏	需保证隐藏后 UI 无遮挡
自定义导航栏	H5 自行实现	1. 适配安全区<br>2. 提供关闭当前原生页面的交互

（三）H5 与 App 交互

3.1 返回 / 关闭页面

使用原生导航栏时建议 H5 同时暴露以下两个方法，供原生调用：
- webGoBack() —— H5 自行处理返回逻辑
- nativeClosePage() —— 关闭当前 WebView 若业务评估无需暴露，则 App 按 WebView 返回栈自动处理。

3.2 当前支持的交互协议

序号	功能	交互名称	动作描述	集成建议	备注
1	返回与关闭	`webGoBack()`	H5 提供 JS 返回方法，供原生返回按钮调用	建议集成	由 H5 执行返回逻辑
		`finishPage()`	JS 调用原生关闭当前页面	建议集成	—
2	原生导航控制	`showNativeNav(show)`	JS 调用原生隐藏/显示导航栏	按需	`show=0` 隐藏，`1` 显示
3	下载文件	`downloadFile(url)`	JS 调用原生下载并自动预览	按需	url 为完整下载地址
4	扫描二维码	`startScan()`	JS 调用原生扫码	按需	—
		`setScanResult(result)`	原生将扫码结果回传 H5	按需	—
5	请求定位权限	`requestLocPerm()`	JS 调用原生申请定位权限	按需	—
		`getLocationCallback()`	原生通知权限获取成功	按需	—
6	打电话	`callPhone(tel)`	JS 调用原生拨号	按需	tel 为电话号码

> 如需新增交互，可经评审后扩展。