UniApp 应用接入¶

文档简介¶

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

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

阅读路径¶

建议按照以下顺序阅读：

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

前置条件¶

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

应用接入¶

进入 用户访问监测 > 新建应用 > Android/iOS。
分别为 UniApp Android 和 UniApp iOS 创建两个应用，以便分别接收 Android 和 iOS 平台的 RUM 数据。
为每个平台填写对应的应用名称和应用 ID。
选择应用接入方式：
公网 DataWay：直接接收 RUM 数据，无需安装 DataKit。
本地环境部署：满足前置条件后，由本地 DataKit 接收 RUM 数据。

安装¶

本地使用¶

源码地址：https://github.com/GuanceCloud/datakit-uniapp-native-plugin

Demo 地址：https://github.com/GuanceCloud/datakit-uniapp-native-plugin/Hbuilder_Example

下载后的 SDK 包结构如下：

|--datakit-uniapp-native-plugin
  |-- Hbuilder_Example
    |-- uni_modules
      |-- GC-JSPlugin
      |   |-- js_sdk
      |   |   |-- View/GCPageMixin.js        // view 自动抓取使用，需与 GCWatchRouter.js 配合使用
      |   |   |-- View/GCWatchRouter.js      // view 自动抓取使用，需与 GCPageMixin.js 配合使用
      |   |   |-- View/GCPageViewMixinOnly.js // 仅采集指定页面时单独使用
      |   |   |-- Request/GCRequest.js       // resource 与 trace 使用，提供 APM 与网络请求监测能力
      |   |   |-- Error/GCErrorTracking.js   // error 自动采集，支持 uni.onError、console.error
      |   |-- index.js
      |   |-- package.json
    |-- nativeplugins
      |-- GCUniPlugin
      |   |-- android
      |   |-- ios
      |   |-- package.json
  |-- UniPlugin-Android
  |-- UniPlugin-iOS

将 GCUniPlugin 目录复制到您项目的 nativeplugins 目录下，并在 manifest.json 的“App 原生插件配置”中点击“选择本地插件”，选择 GCUniPlugin：

将 GC-JSPlugin 目录复制到项目的 uni_modules 目录下。

注意：保存后必须执行云端打包；制作自定义基座也属于云端打包，完成后插件才会生效。

更多详情可参考：HBuilderX 中使用本地插件、自定义基座

市场插件方式¶

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

uni 小程序 SDK 安装¶

开发调试与 wgt 发布使用¶

uni 小程序 SDK 在开发调试阶段，需要按本地使用方式集成 GCUniPlugin。
uni 小程序 SDK 打包为 wgt 供宿主 App 使用时，宿主 App 需要导入 GCUniPlugin 依赖库，并注册 GCUniPlugin Module。

宿主 App 需要补充以下操作：

iOS

添加 GCUniPlugin 依赖库。在 Xcode 的 TARGETS -> Build Phases -> Link Binary With Libraries 中点击“+”，选择 Add Other -> Add Files...，打开 GCUniPlugin/ios/ 目录，添加 FTMobileSDK.xcframework 和 GC_UniPlugin_App.xcframework。
当 SDK Version < 0.2.0 时，需要在 TARGETS -> General -> Frameworks, Libraries, and Embedded Content 中将 FTMobileSDK.xcframework 的 Embed 方式改为 Embed & Sign。
注册 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

添加 GCUniPlugin 依赖库：
方式一：将 GCUniPlugin/android/ 中的 ft-native-[version].aar、ft-sdk-[version].aar、gc-uniplugin-[last-version].aar 复制到项目 libs 目录，并在 build.gradle 中添加依赖。
方式二：通过 Gradle Maven 远程仓库配置，参考 UniPlugin-Android 工程配置。

dependencies {
    implementation files('libs/ft-native-[version].aar')
    implementation files('libs/ft-sdk-[version].aar')
    implementation files('libs/gc-uniplugin-[last-version].aar')
    implementation 'com.google.code.gson:gson:2.8.5'
}

注册 GCUniPlugin Module：

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

UniApp SDK 与 Native SDK 混合使用¶

在宿主 App 集成 GCUniPlugin 时，Native SDK 已一并导入，因此可直接调用 Native SDK 方法。
混合使用时，仅需在宿主 App 内初始化 Native SDK；uni 小程序侧无需再次初始化，可直接调用 UniApp SDK 提供的方法。
宿主 App 初始化方式可参考 iOS SDK 初始化配置和 Android SDK 初始化配置。
请务必在加载 uni 小程序之前完成宿主 App 中的 SDK 初始化，确保后续方法调用时 SDK 已经准备就绪。

Android 额外配置

如需采集 App 启动事件、网络请求以及 Android Native 相关事件（页面跳转、点击事件、Native 网络请求、WebView 数据），请在宿主工程中配置 Gradle Plugin ft-plugin。

区分 uni 小程序与 Native 数据

SDK 0.2.4 以上支持

可通过 BridgeContext 为 uni 小程序侧采集数据添加额外上下文，用于筛选或关联特定场景。

例如，可通过 wgt_id:wgt_id_1 筛选对应 uni 小程序数据：

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");
ftModule.appendBridgeContext({
    'wgt_id': 'wgt_id_1'
});

详细配置入口¶

配置说明¶

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

高级场景¶

常见问题¶

插件开发 iOS 主工程 UniPlugin-iOS 使用¶

下载 UniApp 离线开发 SDK¶

根据 uni-app 开发工具 HBuilderX 的版本号，下载开发插件需要的 SDK 包。

SDK 包结构如下：

|--iOSSDK
    |-- HBuilder-Hello
    |-- HBuilder-uniPluginDemo
    |-- SDK

将依赖库和资源文件 SDK 目录拖入 UniPlugin-iOS 中，最终目录结构如下：

|-- UniPlugin-iOS
    |-- HBuilder-uniPluginDemo
    |-- SDK

更多详情可参考 iOS 插件开发环境配置。

工程配置¶

Architectures 设置
因 Xcode 12 提供 arm64 模拟器支持，而 uni-app 提供的 framework 支持的是 arm64 真机和 x86_64 模拟器，因此需要将 Excluded Architectures 中 Any iOS Simulator SDK 设置为 arm64。
Other Linker Flags

$(inherited) -ObjC -framework "FTMobileSDK" -framework "GC_UniPlugin_App"

Framework Search Paths

$(inherited)
"${PODS_CONFIGURATION_BUILD_DIR}/FTMobileSDK"
"${PODS_CONFIGURATION_BUILD_DIR}/GC-UniPlugin-App"
$(DEVELOPER_FRAMEWORKS_DIR)
$(PROJECT_DIR)/../SDK/libs
$(PROJECT_DIR)

插件开发 Android 主工程 UniPlugin-Android 使用¶

工程配置¶

详细依赖配置可参考 Demo。更多 Gradle 扩展参数可参考 Android SDK。

|-- UniPlugin-Android
    |-- app
        |-- build.gradle
        // apply:'ft-plugin'
    |-- uniplugin_module
        |-- src
            |-- main
                |-- java
                    |-- com.ft.sdk.uniapp
        |-- build.gradle
// implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:xxxx'
// implementation 'com.google.code.gson:gson:xxxx'
// implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-native:xxxx'
|-- build.gradle
// maven { url 'https://mvnrepo.jiagouyun.com/repository/maven-releases' }
        // classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin:xxxx'

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

Android 云打包与离线打包使用了两套不同的集成逻辑。离线打包方式与观测云 Android SDK 的集成方式一致，可使用 Android Studio Gradle Plugin；云打包无法使用该插件，因此部分能力由观测云 UniApp Native Plugin 内部实现。

因此，离线打包版本可使用的配置项通常多于云打包版本。sdkConfig 中的 offlinePakcage 参数就是用来区分这两种情况，详见 SDK 初始化。

UniApp 应用接入¶

文档简介¶

阅读路径¶

前置条件¶

应用接入¶

安装¶

本地使用¶

市场插件方式¶

uni 小程序 SDK 安装¶

开发调试与 wgt 发布使用¶

UniApp SDK 与 Native SDK 混合使用¶

详细配置入口¶

配置说明¶

高级场景¶

常见问题¶

插件开发 iOS 主工程 UniPlugin-iOS 使用¶

下载 UniApp 离线开发 SDK¶

工程配置¶

插件开发 Android 主工程 UniPlugin-Android 使用¶

工程配置¶

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

其他¶

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