# 移动客户端与 H5 对接规范

## 一、概述

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

---

## 二、集成形式及系统环境

### （一）集成形式

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

### （二）宿主系统环境

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

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

---

## 三、集成要求

### （一）单点登录

1. App 访问 H5 业务系统时，先调用后台接口获取授权 `token`。随后按业务方约定携带相关参数访问 H5 链接，完成单点登录。
2. 对无权限用户，业务系统须返回**专用错误码**及**友好提示**。
3. 若采用 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 为电话号码              |

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

---