第三方 H5 对接指南

1. 目录结构说明

交付包包含以下核心文件：

bridge.js: 核心通信库，封装了与 App 的交互，必须在所有页面引入。
api.js: 后端 API 库，封装了所有服务器请求接口。
mock_flutter.js: 调试工具，仅在本地开发使用。
demo_project/: 完整示例项目，包含首页、排行榜、报名等真实场景代码。
API.md: 详细的 App 交互接口文档 (Bridge)。
API_SERVER.md: 后端服务器接口文档 (API)。

2. 开发流程

第一步：参考 Demo

建议直接打开 demo_project/index.html (本地双击即可运行)，体验完整的交互流程。您可以参考其中的 rank.html 和 signup.html 来构建您的业务页面。

第二步：初始化 SDK

在您的 H5 项目（无论是 Vue, React 还是原生 HTML）的入口 HTML 文件中引入核心库：

<script src="./bridge.js"></script>
<script src="./api.js"></script>

第三步：开启调试模式 (Mock)

为了方便在 Chrome/Edge 浏览器中开发，请在 bridge.js 之前引入 mock_flutter.js。此外，在初始化 API 时，如果是本地环境，建议开启 Mock 模式：

// 检测是否本地开发环境
var isLocal = window.location.protocol === 'file:' || window.location.hostname === 'localhost';

API.init({
    token: '...', 
    useMock: isLocal // 本地开发自动开启 Mock，直接返回模拟数据
});

第四步：打包交付

关键步骤：在构建生产环境包（Build）之前，请移除对 mock_flutter.js 的引用。 App 环境会自动注入真实的通信通道。

3. 交付物清单

请向我们提供：

构建后的静态资源包 (dist 目录)。
部署说明（如果需要特殊的 Nginx 配置）。

4. 注意事项

OSS 图片: 后端接口返回的图片路径通常不带域名，请使用 API.getOssUrl() 获取基础域名并进行拼接。
Token: 在 App 环境中，H5 页面加载时 URL 参数中通常会携带 token。如果 URL 中没有，请使用 Bridge.getToken() 获取。

GUIDE.md 2.1 KB Geschiedenis Ruwe