Skip to content

UniApp Application Integration

Document Overview

This document serves as the entry page for the UniApp RUM SDK, containing the essential information needed for first-time integration, installation methods, reading path, detailed configuration entries, advanced scenario entries, and FAQ.

If you need parameter tables, API descriptions, manual data collection examples, and runtime capabilities, please refer to the dedicated topic pages below.

Reading Path

We recommend reading in the following order:

  1. If upgrading from 0.2.x, first read the UniApp 0.3.0 Migration Guide.
  2. For first-time integration, first read Quick Start.
  3. Complete the installation according to your actual integration method.
  4. After SDK initialization, continue reading SDK Initialization and RUM Configuration.
  5. If you need log collection and distributed tracing, continue reading Log Configuration and Trace Configuration.
  6. If you need tags, data masking, or WebView collection, continue reading the corresponding advanced topics.

Prerequisites

Note: If you have already activated the RUM Headless service, the prerequisites are automatically configured and you can proceed directly with the application integration.

App Integration

  1. Go to Real User Monitoring (RUM) > Create Application;
  2. Create separate Android, iOS, and HarmonyOS applications based on the actual publishing platforms;
  3. Save the RUM App ID for each platform, and pass androidAppId, iOSAppId, and harmonyAppId respectively when initializing RUM;
  4. Choose the data reporting method:
  5. Public DataWay: prepare datawayUrl and clientToken;
  6. On-premises deployment: prepare datakitUrl.

Installation

Local Use

Source Code Repository: TrueWatchTech/datakit-uniapp-native-plugin

The downloaded SDK package structure is as follows:

|-- datakit-uniapp-native-plugin
  |-- Hbuilder_Example                         // HBuilderX example project and directly usable uni_modules
    |-- uni_modules
      |-- GC-JSPlugin                         // JS automatic collection
        |-- js_sdk
          |-- Action/GCActionTracking.js      // Automatic collection of Actions on the HarmonyOS side
          |-- Error/GCErrorTracking.js        // Automatic collection of Errors
          |-- Request/GCResourceTracking.js   // Automatic collection of uni.request Resources and Trace
          |-- View/GCViewTracking.js          // Recommended global automatic View collector
        |-- index.js
        |-- package.json
      |-- GC-UniPlugin                        // Android, iOS, HarmonyOS UTS main plugin
        |-- utssdk
        |-- setup.js                          // Bridges JS collector with UTS SDK
        |-- package.json
      |-- GC-UniSessionReplay                 // Optional Android, iOS Session Replay plugin
  |-- native-projects                         // Native build, packaging, and integration verification projects
  |-- dist                                    // Release artifacts
    |-- native-sdk-hybrid                     // Offline packaging artifacts for uni-app applications
    |-- unimp-host-extension                  // Native dependency library for the host App

Copy the following directories from the Hbuilder_Example/uni_modules directory of the corresponding SDK source code version to the uni_modules directory of your project:

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

If you need Session Replay, also install the optional GC-UniSessionReplay. Session Replay currently only supports Android and iOS.

All installed modules should use the same release version. When upgrading, replace them together; do not mix JS, UTS, or Session Replay modules from different versions.

GC-UniPlugin was introduced in 0.3.0 to replace the old nativeplugins/GCUniPlugin native plugin. It is a UTS module and does not need to be copied to nativeplugins, nor does it need to be registered in manifest.json as a local native plugin. GC-JSPlugin continues to provide public JS APIs and collectors.

Loading the UTS Bridge

Load setup.js at the very beginning of the application entry:

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

Import SDK APIs from GC-UniPlugin to get type checking and parameter hints from HBuilderX based on the UTS interface; import JS collectors from GC-JSPlugin:

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

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

Market Plugin Method

This method is currently not available. Please use Local Use for integration.

Uni Mini Program SDK Installation

In this section, "Uni Mini Program" specifically refers to projects developed with uni-app, packaged as wgt resource packages via HBuilderX, and running in a host App. It does not refer to mini programs on platforms like WeChat or Alipay.

The Uni Mini Program SDK installation consists of two parts: the Uni Mini Program project and the Host App.

Integration Location Content to Install Main Responsibilities
Uni Mini Program project GC-JSPlugin Provides public JS APIs, collects View, Error, Resource, and Action
Host App Native SDK + Uni Mini Program host extension Initializes the SDK, collects native data, and provides native Modules to the Uni Mini Program

Development, Debugging, and wgt Release Usage

During development, debugging, and when creating wgt resource packages, the Uni Mini Program project only installs GC-JSPlugin:

uni_modules/
└── GC-JSPlugin

GC-JSPlugin is delivered as a complete directory. The source directory in the SDK repository is Hbuilder_Example/uni_modules/GC-JSPlugin/. Copy this directory to the uni_modules/ directory of the Uni Mini Program project, resulting in the path uni_modules/GC-JSPlugin/.

Do not install or import GC-UniPlugin in the Uni Mini Program project, and do not load GC-UniPlugin/setup.js, otherwise the UTS code will be included in the project compilation dependencies.

Import SDK objects and JS collectors uniformly from GC-JSPlugin:

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

Starting from 0.3.0, the host App is responsible for initializing the SDK, RUM, Log, and Trace for new integrations. The Uni Mini Program should not call mobileAgent.sdkConfig(), rum.setConfig(), logger.setConfig(), or tracer.setConfig() again. Only call the following runtime APIs:

  • bindRUMUserData(), unbindRUMUserData();
  • appendGlobalContext(), appendRUMGlobalContext(), appendLogGlobalContext(), appendBridgeContext();
  • Manual data collection and header retrieval APIs provided by rum, logger, and tracer.

When upgrading existing 0.2.x Uni Mini Program projects, you can retain the original initialization method and continue to obtain Modules via uni.requireNativePlugin(), without modifying business code immediately:

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

For new projects, it is recommended to import uniformly from GC-JSPlugin. For specific migration methods from older versions, see Upgrading from 0.2.x.

Host App Integration

The host App needs to integrate the corresponding platform's Native SDK and the Uni Mini Program host extension of version 0.3.0 or later:

Host Platform Extension Form Release Artifact Release Path in SDK Repository
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 native extension GCUniPlugin.har dist/unimp-host-extension/harmony/

The actual artifact names depend on the release package you are using.

The host extension needs to register the following module IDs with the Uni Mini Program runtime environment, so that the Uni Mini Program can call native capabilities via the public JS API or uni.requireNativePlugin():

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

The host App must complete the following dependency integration and Module registration operations per platform:

iOS

  1. Add the dependency library.

    The host App must integrate the Native SDK following the iOS Native SDK Installation Guide. It is recommended to use Swift Package Manager and add the TrueWatchSDK Package Product to the host App target. The Native SDK version must match the UniApp SDK release version; see the changelog for the specific version.

    Add GC-UniPlugin-App.xcframework from the release package to the host App target: In Xcode, go to TARGETS -> Build Phases -> Link Binary With Libraries, click "+", select Add Other -> Add Files..., and choose the file. This XCFramework is a static library; in TARGETS -> General -> Frameworks, Libraries, and Embedded Content, keep it as Do Not Embed.

  2. Register the GCUniPlugin Module at application startup:

    - (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

  1. Add the dependency library:

    Copy gc-uniplugin-<version>.aar from the release package to the libs directory of the host project. Follow the Android Native SDK Gradle Configuration to add the Maven repository, and add the following dependencies in build.gradle:

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

    The Native SDK version must match the UniApp SDK release version; see the changelog for the specific version.

  2. Register the GCUniPlugin Module in Application.onCreate():

    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

Place GCUniPlugin.har in the libs directory of the host project, and add the UniMP runtime and local extension dependency in oh-package.json5:

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

After adding the dependency, run ohpm install in the project directory.

The host extension provides initializeNativeSDK() and registerNativeModules(). The host must first initialize the SDK in UIAbility.onCreate(); then, after init() completes the Uni Mini Program runtime initialization and before opening the first Uni Mini Program, register the modules:

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { init } from '@dcloudio/uni-app-runtime';
import {
    initializeNativeSDK,
    registerNativeModules
} from '@truewatchtech/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);

        // Then open the Uni Mini Program.
    }
}

SDK_STARTUP_CONFIG is provided by the host App and contains the initialization configuration for Mobile, RUM, Log, and Trace. The Uni Mini Program does not call the corresponding initialization APIs again.

Initialization and Debugging

The host App must complete Native SDK initialization and Module registration before opening the Uni Mini Program, and ensure that only one instance of the Native SDK and one set of SDK singletons exist in the final application. The Uni Mini Program does not need to initialize the SDK again.

For Android and iOS hosts, refer to Android SDK Initialization and iOS SDK Initialization respectively; for HarmonyOS hosts, use the initializeNativeSDK() method described above.

When the Uni Mini Program project runs in a standard debugging base without the host extension integrated, GC-JSPlugin will downgrade missing native calls to no-ops, preventing page loading from being blocked by uni.requireNativePlugin() returning null. This mode is only for debugging JS pages and collection logic; it cannot verify native data reporting. Full end-to-end testing must be performed in the actual host App.

Upgrading from 0.2.x

0.3.0 uses different migration approaches for regular uni-app and Uni Mini Programs: regular uni-app replaces the old native plugin with GC-UniPlugin; Uni Mini Program projects continue to integrate only GC-JSPlugin, while the host App upgrades the Native SDK and host extension.

For the complete dependency structure, API imports, initialization location, compatibility, and before/after code comparison, see the UniApp 0.3.0 Migration Guide.

Detailed Configuration Entries

Configuration Guides

  • Quick Start: Shortest path for first-time integration.
  • SDK Initialization: Basic configuration, user binding, disabling the SDK, clearing cache, manual sync.
  • RUM Configuration: RUM initialization configuration, Action/View/Error/Resource collection capabilities.
  • Log Configuration: Log initialization configuration and log printing.
  • Trace Configuration: Trace initialization configuration and distributed tracing.

Advanced Scenarios

FAQ

Difference between Android Cloud Packaging and Offline Packaging

Android cloud packaging and offline packaging use two different sets of integration logic. The offline packaging method is consistent with the Android Native SDK integration method, allowing the use of the Android Gradle Plugin in the host project; cloud packaging cannot apply this plugin, so some capabilities are implemented internally by the UniApp plugin.

Therefore, offline packaging typically provides more complete native automatic collection capabilities. The sdkConfig parameter offlinePackage distinguishes between the two packaging methods:

  • Android cloud packaging: keep the default value false;
  • Android offline packaging: set to true;
  • Existing 0.2.x Uni Mini Program projects that still call sdkConfig() on the JS side: set to true;
  • New Uni Mini Program integrations in 0.3.0 and later: the host App initializes the SDK, so this parameter is not involved; the Uni Mini Program does not call sdkConfig() again.

To collect App launch, native page, click, network request, and WebView data in offline packaging or Uni Mini Program host apps, you also need to configure the Android Gradle Plugin in the host project.

Others