UniApp 应用接入¶

文档简介¶

本文作为 UniApp RUM SDK 的入口页，保留首次接入的必要信息、安装方式、阅读路径、详细配置入口、高级场景入口和 FAQ。

如果您需要参数表、API 说明、手动采集示例和运行时能力，请进入下方专题页阅读。

阅读路径¶

建议按照以下顺序阅读：

从 0.2.x 升级，请先阅读 UniApp 0.3.0 迁移指南。
首次接入请先阅读快速开始。
按实际接入方式完成安装。
完成 SDK 初始化后，继续阅读 SDK 初始化和 RUM 配置。
如需日志采集与链路追踪，继续阅读 Log 配置和 Trace 配置。
如需标签、脱敏或 WebView 采集，再继续阅读对应高级专题。

前置条件¶

注意：若您已开通 RUM Headless 服务，前置条件已自动配置完成，可直接开始应用接入。

安装 DataKit；
配置 RUM 采集器；
DataKit 配置为公网可访问，并且安装 IP 地理信息库；
uni-app 应用接入 GC-UniPlugin 0.3.0 及以上版本时，使用 HBuilderX 4.25.0 或更高版本。

应用接入¶

进入 用户访问监测 > 新建应用；
按实际发布平台分别创建 Android、iOS、HarmonyOS 应用；
保存每个平台对应的 RUM App ID，初始化 RUM 时分别传入 androidAppId、iOSAppId、harmonyAppId；
选择数据上报方式：
公网 DataWay：准备 datawayUrl 和 clientToken；
本地环境部署：准备 datakitUrl。

安装¶

本地使用¶

源码地址：GuanceCloud/datakit-uniapp-native-plugin

下载后的 SDK 包结构如下：

|-- datakit-uniapp-native-plugin
  |-- Hbuilder_Example                         // HBuilderX 示例工程及可直接使用的 uni_modules
    |-- uni_modules
      |-- GC-JSPlugin                         // JS 自动采集
        |-- js_sdk
          |-- Action/GCActionTracking.js      // HarmonyOS 侧 Action 自动采集
          |-- Error/GCErrorTracking.js        // Error 自动采集
          |-- Request/GCResourceTracking.js   // uni.request Resource 与 Trace 自动采集
          |-- View/GCViewTracking.js          // 推荐的 View 全局自动采集器
        |-- index.js
        |-- package.json
      |-- GC-UniPlugin                        // Android、iOS、HarmonyOS UTS 主插件
        |-- utssdk
        |-- setup.js                          // 建立 JS 采集器与 UTS SDK 的桥接
        |-- package.json
      |-- GC-UniSessionReplay                 // 可选的 Android、iOS Session Replay 插件
  |-- native-projects                         // 原生构建、打包及集成验证工程
  |-- dist                                    // 对外发布产物
    |-- native-sdk-hybrid                     // uni-app 应用离线打包产物
    |-- unimp-host-extension                  // 宿主 App 使用的 GC-UniPlugin 原生依赖库

从 SDK 源码仓库对应版本的 Hbuilder_Example/uni_modules 中复制以下目录到业务工程的 uni_modules：

uni_modules/
├── GC-JSPlugin
└── GC-UniPlugin

如需 Session Replay，再安装可选的 GC-UniSessionReplay。Session Replay 当前仅支持 Android 和 iOS。

所有已安装模块应使用同一发布版本。升级时请一并替换，不要混用不同版本的 JS、UTS 或 Session Replay 模块。

GC-UniPlugin 自 0.3.0 起新增，用于替换旧版 nativeplugins/GCUniPlugin 原生插件。它是 UTS 模块，不需要复制到 nativeplugins，也不需要在 manifest.json 中注册旧的本地原生插件。GC-JSPlugin 继续提供公共 JS API 和采集器。

加载 UTS Bridge¶

在应用入口最先加载一次 setup.js：

import '@/uni_modules/GC-UniPlugin/setup.js';

SDK API 从 GC-UniPlugin 导入，以获得 HBuilderX 基于 UTS interface 提供的类型检查和参数提示；JS 采集器从 GC-JSPlugin 导入：

import {
    mobileAgent,
    rum,
    logger,
    tracer
} from '@/uni_modules/GC-UniPlugin';

import {
    gcErrorTracking,
    gcViewTracking,
    gcResourceTracking,
    gcActionTracking
} from '@/uni_modules/GC-JSPlugin';

市场插件方式¶

当前未提供市场插件方式，请使用本地使用完成接入。

uni 小程序 SDK 安装¶

本节中的“uni 小程序”特指使用 uni-app 开发、通过 HBuilderX 制作为 wgt 资源包，并运行在宿主 App 中的项目，不泛指微信、支付宝等平台小程序。

uni 小程序 SDK 安装由 uni 小程序项目 和 宿主 App 两部分组成：

接入位置	安装内容	主要职责
uni 小程序项目	`GC-JSPlugin`	提供公共 JS API，采集 View、Error、Resource 和 Action
宿主 App	Native SDK + uni 小程序宿主扩展	初始化 SDK、采集原生数据，并向 uni 小程序提供原生 Module

开发调试与 wgt 发布使用¶

开发调试与制作 wgt 资源包时，uni 小程序项目只安装 GC-JSPlugin：

uni_modules/
└── GC-JSPlugin

GC-JSPlugin 以完整目录交付，SDK 仓库中的源目录为 Hbuilder_Example/uni_modules/GC-JSPlugin/。将该目录复制到 uni 小程序项目的 uni_modules/ 下，最终路径应为 uni_modules/GC-JSPlugin/。

uni 小程序项目中不要安装或导入 GC-UniPlugin，也不要加载 GC-UniPlugin/setup.js，否则 UTS 代码会进入项目编译依赖。

SDK 对象与 JS 采集器统一从 GC-JSPlugin 导入：

import {
    mobileAgent,
    rum,
    logger,
    tracer,
    gcErrorTracking,
    gcViewTracking,
    gcResourceTracking,
    gcActionTracking
} from '@/uni_modules/GC-JSPlugin';

自 0.3.0 起，新接入项目由宿主 App 完成 SDK 以及 RUM、Log、Trace 初始化。uni 小程序不重复调用 mobileAgent.sdkConfig()、rum.setConfig()、logger.setConfig() 或 tracer.setConfig()，只调用以下运行时 API：

bindRUMUserData()、unbindRUMUserData()；
appendGlobalContext()、appendRUMGlobalContext()、appendLogGlobalContext()、appendBridgeContext()；
rum、logger、tracer 提供的手动数据采集与 Header 获取 API。

现有 0.2.x uni 小程序项目升级时，可以保留原有初始化方式，并继续通过 uni.requireNativePlugin() 获取 Module，无需立即改写业务代码：

const mobileAgent = uni.requireNativePlugin('GCUniPlugin-MobileAgent');
const rum = uni.requireNativePlugin('GCUniPlugin-RUM');
const logger = uni.requireNativePlugin('GCUniPlugin-Logger');
const tracer = uni.requireNativePlugin('GCUniPlugin-Tracer');

新项目推荐统一从 GC-JSPlugin 导入。旧版本的具体迁移方式见从 0.2.x 升级。

宿主 App 集成¶

宿主 App 需要集成对应平台的 Native SDK 和 0.3.0 及以上版本的 uni 小程序宿主扩展：

宿主平台	宿主扩展形态	发布产物	SDK 仓库中的发布路径
Android	Android UniModule	`gc-uniplugin-<version>.aar`	`dist/unimp-host-extension/android/`
iOS	`DCUniModule`	`GC-UniPlugin-App.xcframework`	`dist/unimp-host-extension/ios/`
HarmonyOS	ETS 原生扩展	`GCUniPlugin.har`	`dist/unimp-host-extension/harmony/`

发布产物名称以所用版本发布包中的实际文件名为准。

宿主扩展需要向 uni 小程序运行环境注册以下模块 ID，以便 uni 小程序通过公共 JS API 或 uni.requireNativePlugin() 调用原生能力：

GCUniPlugin-MobileAgent
GCUniPlugin-RUM
GCUniPlugin-Logger
GCUniPlugin-Tracer

宿主 App 需要按平台完成以下依赖集成与 Module 注册操作：

iOS¶

添加依赖库。

宿主 App 需按照 iOS Native SDK 安装说明集成 Native SDK。推荐使用 Swift Package Manager，并将 GuanceSDK Package Product 添加到宿主 App Target。Native SDK 版本需要与 UniApp SDK 发布版本匹配，具体版本见对应版本的更新日志。

将发布包中的 GC-UniPlugin-App.xcframework 添加到宿主 App Target：在 Xcode 的 TARGETS -> Build Phases -> Link Binary With Libraries 中点击“+”，选择 Add Other -> Add Files... 并选中该文件。该 XCFramework 为静态库，在 TARGETS -> General -> Frameworks, Libraries, and Embedded Content 中保持 Do Not Embed。

在应用启动时注册 GCUniPlugin Module：

- (BOOL)application:(UIApplication *)application
        didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [WXSDKEngine registerModule:@"GCUniPlugin-MobileAgent"
                       withClass:NSClassFromString(@"FTMobileUniModule")];
    [WXSDKEngine registerModule:@"GCUniPlugin-RUM"
                       withClass:NSClassFromString(@"FTRUMModule")];
    [WXSDKEngine registerModule:@"GCUniPlugin-Logger"
                       withClass:NSClassFromString(@"FTLogModule")];
    [WXSDKEngine registerModule:@"GCUniPlugin-Tracer"
                       withClass:NSClassFromString(@"FTTracerModule")];
    return YES;
}

Android¶

添加依赖库：

将发布包中的 gc-uniplugin-<version>.aar 复制到宿主工程的 libs 目录。按照 Android Native SDK Gradle 配置添加 Maven 仓库，并在 build.gradle 中添加以下依赖：

dependencies {
    implementation files('libs/gc-uniplugin-<version>.aar')
    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:<version>'
    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-native:<version>'
    implementation 'com.alibaba:fastjson:1.2.83'
    implementation 'com.google.code.gson:gson:2.8.5'
}

Native SDK 版本需要与 UniApp SDK 发布版本匹配，具体版本见对应版本的更新日志。

在 Application.onCreate() 中注册 GCUniPlugin Module：

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        try {
            WXSDKEngine.registerModule("GCUniPlugin-MobileAgent", FTSDKUniModule.class);
            WXSDKEngine.registerModule("GCUniPlugin-RUM", FTRUMModule.class);
            WXSDKEngine.registerModule("GCUniPlugin-Logger", FTLogModule.class);
            WXSDKEngine.registerModule("GCUniPlugin-Tracer", FTTracerModule.class);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

HarmonyOS¶

将 GCUniPlugin.har 放入宿主工程 libs，并在 oh-package.json5 中添加 UniMP 运行时与本地扩展依赖：

{
    "dependencies": {
        "@dcloudio/uni-app-runtime": "5.2.32026080401",
        "@guancecloud/gc-uniplugin": "file:./libs/GCUniPlugin.har"
    }
}

添加依赖后，在工程目录执行 ohpm install。

宿主扩展提供 initializeNativeSDK() 和 registerNativeModules()。宿主需要先在 UIAbility.onCreate() 中初始化 SDK；随后在 init() 完成 uni 小程序运行环境初始化后、首次打开 uni 小程序前注册模块：

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { init } from '@dcloudio/uni-app-runtime';
import {
    initializeNativeSDK,
    registerNativeModules
} from '@guancecloud/gc-uniplugin';
import { SDK_STARTUP_CONFIG } from '../config/SDKStartupConfig';

export default class EntryAbility extends UIAbility {
    onCreate(): void {
        initializeNativeSDK(this.context, SDK_STARTUP_CONFIG);
    }

    onWindowStageCreate(windowStage: window.WindowStage): void {
        init(this, windowStage, { debug: true });
        registerNativeModules(this.context);

        // 此后再打开 uni 小程序。
    }
}

SDK_STARTUP_CONFIG 由宿主 App 提供，包含 Mobile、RUM、Log 和 Trace 的初始化配置。uni 小程序不重复调用对应的初始化 API。

初始化与调试¶

宿主 App 必须在打开 uni 小程序前完成 Native SDK 初始化和 Module 注册，并确保最终应用中只存在一份 Native SDK 和一组 SDK 单例。uni 小程序不需要再次初始化 SDK。

Android 和 iOS 宿主的 Native SDK 初始化方式分别见 Android SDK 初始化和 iOS SDK 初始化；HarmonyOS 宿主使用上文的 initializeNativeSDK() 完成初始化。

当 uni 小程序项目在未集成宿主扩展的普通调试基座中运行时，GC-JSPlugin 会将缺失的原生调用降级为空操作，不会因 uni.requireNativePlugin() 返回 null 而阻断页面加载。此模式只用于 JS 页面与采集逻辑调试，不能验证原生数据上报；完整联调必须在真实宿主 App 中进行。

从 0.2.x 升级¶

0.3.0 对普通 uni-app 与 uni 小程序采用不同的迁移方式：普通 uni-app 使用 GC-UniPlugin 替换旧原生插件；uni 小程序项目继续只集成 GC-JSPlugin，由宿主 App 升级 Native SDK 与宿主扩展。

完整的依赖结构、API 导入、初始化位置、兼容方式和迁移前后代码对比，请查看 UniApp 0.3.0 迁移指南。

详细配置入口¶

配置说明¶

快速开始：首次接入最短路径。
SDK 初始化：基础配置、用户绑定、关闭 SDK、清理缓存、主动同步。
RUM 配置：RUM 初始化配置、Action/View/Error/Resource 采集能力。
Log 配置：Log 初始化配置与日志打印。
Trace 配置：Trace 初始化配置与链路追踪。

高级场景¶

常见问题¶

Android 云打包与离线打包区别¶

Android 云打包与离线打包使用两套不同的集成逻辑。离线打包方式与 Android Native SDK 的集成方式一致，可以在宿主工程中应用 Android Gradle Plugin；云打包无法应用该插件，因此部分能力由 UniApp 插件内部实现。

因此，离线打包通常可以使用更完整的 Native 自动采集能力。sdkConfig 中通过 offlinePackage 区分两种打包方式：

Android 云打包：保持默认值 false；
Android 离线打包：设置为 true；
现有 0.2.x uni 小程序项目如仍在 JS 侧调用 sdkConfig()：设置为 true；
0.3.0 及以上版本的新 uni 小程序接入由宿主 App 初始化 SDK，不涉及该参数，uni 小程序不重复调用 sdkConfig()。

如需在离线打包或 uni 小程序宿主 App 中采集 App 启动、Native 页面、点击、网络请求及 WebView 数据，还需要在宿主工程中配置 Android Gradle Plugin。

UniApp 应用接入¶

文档简介¶

阅读路径¶

前置条件¶

应用接入¶

安装¶

本地使用¶

加载 UTS Bridge¶

市场插件方式¶

uni 小程序 SDK 安装¶

开发调试与 wgt 发布使用¶

宿主 App 集成¶

iOS¶

Android¶

HarmonyOS¶

初始化与调试¶

从 0.2.x 升级¶

详细配置入口¶

配置说明¶

高级场景¶

常见问题¶

Android 云打包与离线打包区别¶

其他¶

文档内容是否对您有帮助？

UniApp 应用接入¶

文档简介¶

阅读路径¶

前置条件¶

应用接入¶

安装¶

本地使用¶

加载 UTS Bridge¶

市场插件方式¶

uni 小程序 SDK 安装¶

开发调试与 wgt 发布使用¶

宿主 App 集成¶

iOS¶

Android¶

HarmonyOS¶

初始化与调试¶

从 0.2.x 升级¶

详细配置入口¶

配置说明¶

高级场景¶

常见问题¶

Android 云打包与离线打包区别¶

其他¶

文档内容是否对您有帮助？ ×

文档内容是否对您有帮助？