Appearance
app嵌入 H5（webview）
方案选择
App 通过 WebView 承载直播间 H5，通过 JavaScript Bridge 提供页面返回、应用信息、分享等 Native 能力。三个技术栈使用相同的 H5 消息格式，由各自的容器适配通信通道。
| App 技术栈 | 接入方式 | 文档 |
|---|---|---|
| 纯原生 Android / iOS | Android WebView / WKWebView 注册原生消息通道 | 纯原生接入 |
| uni-app App-vue：HTML5+ | 手动创建子 WebView，通过 URL 拦截及 evalJS 双向收发 | HTML5+ WebView 接入 |
| uni-app App-vue：组件 | 页面声明 <web-view>，通过组件消息及 evalJS 双向收发 | <web-view> 组件接入 |
| Flutter | 使用 flutter_inappwebview 注册 JavaScript Handler | Flutter 接入 |
先阅读 Native 与 H5 交互协议，再按技术栈实现。各技术栈使用相同的桥接名称，名称中的 Flutter 不限制宿主的开发语言。
接入步骤
1. 获取观看地址
观看地址使用 【推荐】URL组装用户信息登录 方式生成。由客户服务端以直播间基础地址和当前 App 用户信息组装完整登录 URL，再交给 App 的 WebView 加载。
直播间基础地址示例：
text
https://live.example.com/Watch/123456上述地址用于组装登录 URL，App 应加载组装后的完整地址并保留其中的登录参数。room_webview_url 用于小程序 WebView 场景。
2. 组装登录 URL
按照 【推荐】URL组装用户信息登录，在客户服务端完成以下步骤：
- 准备直播间基础地址、AppSecret 和当前 App 用户信息。
- 按推荐文档的组装规则生成
third_login_data、third_login_time、third_login_sign。 - 将这三个参数追加到直播间基础地址，得到完整登录 URL，交给 App 的 WebView 加载。
用户信息示例：
json
{
"uuid": "user_12345",
"name": "用户昵称",
"photo": "https://example.com/avatar/default.jpg"
}| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| uuid | String | 是 | 客户系统中稳定、唯一的用户标识 | user_12345 |
| name | String | 是 | 用户昵称 | 用户昵称 |
| photo | String | 否 | 用户头像地址 | https://example.com/avatar/default.jpg |
完整参数和组装规则以推荐文档为准。third_login_time 使用 13 位毫秒时间戳，登录 URL 有效期为 60 秒，应在进入直播间时生成并立即加载；AppSecret 保留在客户服务端。
登录 URL 负责直播间账号关联；Bridge 负责页面与 App 交互。实现 getLoginState 或 getUserInfo 事件不会自动完成账号打通。第三方登录失败时仍可能以游客身份打开页面，应单独核对身份，排查时可使用 校验第三方登录 URL。
3. 配置容器与 UA
在首次请求观看地址前启用 JavaScript，并在系统默认 User-Agent 后追加应用标识。示例中的应用信息需替换为自己的配置：
UA 后缀示例：
text
channel/APPAndroid version/1.0.0 package/com.example.live wxappid/example_wechat_appid scheme/exampleliveiOS 使用 channel/APPiOS。H5 会使用 UA 中的 channel、version、package 标识判断 App 环境，因此 UA 必须在首次加载前生效。wxappid、scheme 按实际启用的微信能力及应用唤起配置填写，不使用示例值上线。
4. 安装双向 Bridge
H5 调用 postMessage(JSON字符串)，容器桥接层将 event、data 交给 App 业务层处理，再将结果送回 H5 完成 Promise。App 主动通知页面时，调用 flutterToHtmlEvent(事件对象) 并按需读取 H5 的返回值。
H5 的 postMessage 必须返回 Promise。只注册同名方法而没有结果回传，会使应用信息、用户信息等异步查询无法正常完成。首次注入和每次完整导航后的重新注入方式见各技术栈文档。
5. 按功能补齐 Native 能力
先用 getAppInfo 验证一次完整的请求与结果回传，再用扩展示例 openNativePage 验证 H5 打开 App 内订单详情页及参数传递。基础页面事件、初始化查询、可选分享能力及生命周期通知见 交互协议。
分享、支付、连麦等能力需要相应 Native SDK、权限和业务配置。示例只演示通信与基础事件，业务能力需按项目实际功能接入；未实现的事件应明确返回失败。
如需区分 App 首页、活动页等入口，可在组装登录 URL 前为观看地址添加 tpRef，详见 渠道来源追踪场景。
联调顺序
- 验证首次加载时 UA 正确，H5 能识别 App 环境。
- 验证
getAppInfo、openNativePage、并发请求、Promise 结果、可选callback和未知事件。 - 验证刷新、完整跳转、返回后 Bridge 仍然可用。
- 验证 App 账号与直播间身份一致，以及退出、切换账号后重新进入的流程。
- 验证直播、回放、声音、全屏、横竖屏及切换前后台。
- 按实际启用的功能验证分享、购买、支付及权限拒绝场景。
示例中的域名、用户信息和应用标识均为演示值，接入时请替换为自己的配置。