WebView 数据监测¶

UniApp 中的 WebView 数据监测，需要在 WebView 所访问的页面中集成 Web 监测 SDK。

Android 仅支持离线打包与 uni 小程序场景。

配置¶

普通 uni-app 在 RUM 初始化时配置：

import { rum } from '@/uni_modules/GC-UniPlugin';

rum.setConfig({
    enableTraceWebView: true,
    allowWebViewHost: [
        'example.com'
    ]
});

enableTraceWebView：是否开启 WebView RUM 桥接，默认 true；
allowWebViewHost：允许追踪的 WebView Host 列表；不设置时采集全部 Host。

普通 uni-app 应先完成 Mobile SDK 与 RUM 初始化，再加载 WebView。uni 小程序由宿主 App 完成 SDK 和 RUM 初始化，不重复初始化。

平台说明¶

Android、iOS 使用标准 <web-view>，实际能力取决于 Native SDK 与打包方式；
HarmonyOS 根据业务侧是否持有 WebviewController 选择对应接入方式，详见HarmonyOS 接入；
uni 小程序的 WebView 采集能力由宿主 App 集成的 Native SDK 提供；Android 宿主还需安装并应用 ft-plugin。

HarmonyOS 接入¶

HarmonyOS 的 WebView Bridge 必须在目标页面加载前安装。请根据业务侧是否持有 WebviewController，选择以下其中一种方式；不要在同一个 WebView 上同时使用两种方式。

业务侧不持有 WebviewController¶

普通 uni-app 页面不直接管理 WebviewController 时，在 HarmonyOS 平台使用插件提供的原生嵌入组件 gcwebview。该组件会在控制器可用时自动安装 Bridge，并在组件销毁时自动释放。

<!-- #ifdef APP-HARMONY -->
<embed
  class="harmony-webview"
  tag="gcwebview"
  :options="{
    src: webviewUrl,
    viewName: 'order-detail'
  }"
></embed>
<!-- #endif -->

<!-- #ifndef APP-HARMONY -->
<web-view :src="webviewUrl" />
<!-- #endif -->

src：要加载的 Web 页面地址；
viewName：可选的 Native RUM View 名称。建议为每个业务 WebView 设置有意义且稳定的名称；未设置时默认使用 webview；
使用 gcwebview 时无需调用 rum.attachWebView() 或 rum.detachWebView()。

业务侧持有 WebviewController¶

在 HarmonyOS 原生页面、UTS 原生 WebView 或 uni 小程序宿主 App 中，如果业务代码自行持有 WebviewController，请在控制器的 onControllerAttached 回调中调用 rum.attachWebView()，并确保此时尚未加载目标页面：

Web({ src: webviewUrl, controller })
  .onControllerAttached(() => {
    rum.attachWebView(controller, 'order-detail');
  });

WebView 销毁时释放对应 Bridge：

rum.detachWebView(controller);

rum.attachWebView() 仅在 RUM 已完成初始化且 enableTraceWebView 为 true 时生效。因此，应先执行 rum.setConfig()，再创建 WebView 或绑定控制器；在页面加载完成后再绑定，会错过首个文档的 Web RUM Bridge。

uni 小程序宿主 App 使用此方式前，还应在首次打开 uni 小程序前完成宿主扩展的 registerNativeModules(context) 注册。

使用建议¶

在 Web 页面中接入 Web 监测 SDK；
在 Native SDK/RUM 初始化完成后再加载 WebView；
使用 allowWebViewHost 限制允许桥接的业务域名；
HarmonyOS 的 gcwebview 与手动 attachWebView() 方式二选一；
在 Android、iOS、HarmonyOS 真机环境分别验证 WebView 数据与当前 RUM View 的关联。