开发需求文档

---

1. Adjust接入

1.1 接入Adjust SDK获取归因参数

• 在项目中接入 Adjust SDK，进行初始化。
• 需在其归因数据回调中，获取并提取出以下关键传参标识：
  1. adid：Adjust 为该设备分配的归因唯一 ID。
  2. gps_adid：Google Play 服务广告 ID（即安卓的 GAID）。

1.2 组装请求URL加载业务

将获取到的相关 Adjust 数据，作为 Query URL 参数，拼接到游戏入口 URL 上进行加载。

• URL请求格式：
  https://[GAME_H5_ADDRESS]/?adid=[adid的值]&gps_adid=[gps_adid的值]&s2s=1&from=apk

---

2. WebView与JS Bridge交互要求

项目需要在 WebView 中加载指定的URL，并实现与H5通信的 JS Bridge 机制。

2.1 Webview 基础与交互配置

这部分包含了原生 WebView 的基础显示配置、网络加载控制及相关的触控体验交互。

• 基础样式与参数
  • 全屏显示，并强制锁定 竖屏（Portrait） 方向，禁止屏幕随设备旋转变更为横屏。
  • 开启 JavaScript 引擎：setJavaScriptMode(JavaScriptMode.unrestricted)。
  • 设定背景颜色：setBackgroundColor(Colors.white)，增强用户体验。
  • 支持多窗口与弹窗机制：配置 WebView 允许 JS 自动打开新窗口并支持多窗口能力（相当于开启 setSupportMultipleWindows(true) 及 javaScriptCanOpenWindowsAutomatically = true 的效果），以支持 window.open 或 <a target="_blank"> 在应用内部正确响应或新开 Web 视图处理。
• 加载控制与异常处理（网络与超时保障）
  • 加载超时机制：为 WebView 的 URL 加载增加 30秒超时 限制。如果超过30秒仍未加载完成，则视为加载失败。
  • 错误状态处理与重试：当 WebView 发生加载错误（如网络断开、加载异常、加载超时等）时：
    • 友好提示拦截：需要拦截系统默认的错误页，在 Flutter 原生界面或自定义的本地 HTML 页面向用户展示友好的错误提示信息（例如：“Load failed, please try again”）。
    • 刷新功能：在错误提示界面必须提供一个 “Refresh”或“Retry”按钮。用户点击该按钮后，调用 reload()，让 WebView 重新尝试加载当前失败的 URL。
• 手势与触控体验
  • 下拉刷新（Pull-to-Refresh）：为 WebView 增加下拉刷新交互。由于原生 WebView 控件默认没有浏览器的下拉刷新功能，必须在 Flutter 侧实现。要求在 WebView 的外层（如使用 RefreshIndicator 组件）嵌套下拉刷新控件；当用户在页面顶部下拉时，触发该控件并调用 WebView 实例的 reload() 方法重新加载当前网页。
  • 左右侧滑手势（前进/后退）：为 WebView 增加右滑返回上一页、左滑前进到下一页的交互体验。需要在 Flutter 侧通过手势监听（如 GestureDetector 或原生系统层面的滑动返回支持）来捕获用户的左滑/右滑动作：
    • 当向右滑动（常用作返回动作）且 WebView 有历史记录时，调用 goBack()。
    • 当向左滑动（常用作前进动作）且 WebView 有历史记录时，调用 goForward()。

2.2 JS Bridge Channel配置

在 WebView 初始化时，必须注册一个名为 FlutterApp 的 JavaScript 通道（JavaScript Channel）。H5页面将通过调用 window.FlutterApp.postMessage(message) 与 Flutter 端进行交互。

2.3 需要实现的JS方法（Message指令处理）

Flutter端代码需要监听并处理 FlutterApp 接收到的消息指令，执行对应的原生操作：

• open:<url> （字符串前缀匹配）
  • 作用：调用系统外部浏览器或拉起其他相关App，打开指定的外链URL。
  • 实现要求：当接收到的 message 字符串以 open: 开头时（例如 open:https://www.google.com），需截取 open: 之后的 URL 字符串，并调用类似于 url_launcher 的原生插件以 外部应用模式 (External Application) 打开该链接。
• refresh
  • 作用：重新加载/刷新当前 WebView 页面（调用 reload()）。
• back
  • 作用：返回上一页历史记录（调用 goBack()）。
• forward
  • 作用：前进到下一页历史记录（调用 goForward()）。
• alert:<message> （字符串前缀匹配）
  • 作用：在 Flutter 原生界面弹出一个提示框（Dialog 或 Toast），展示传入的 <message> 文本内容。

2.4 外部 Scheme 跳转支持

• 对于请求打开非 HTTP/HTTPS 协议的 URL（例如 whatsapp://、tg:// 等唤端协议），将 URI 使用外部应用拉起。

---

3. 联调与测试要求

测试页面链接：test_h5.html