Skip to content

UniApp Application Access

Document Overview

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

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

Reading Path

It is recommended to read in the following order:

  1. For first-time access, start with Quick Start.
  2. Complete the Installation based on your actual access method.
  3. After completing SDK initialization, continue with SDK Initialization and RUM Configuration.
  4. If you need log collection and distributed tracing, continue with Log Configuration and Trace Configuration.
  5. If you need tags, data masking, or WebView collection, continue with the corresponding advanced topics.

Prerequisites

Note: If you have already enabled the RUM Headless service, the prerequisites are automatically configured, and you can start application access directly.

Application Access

  1. Go to RUM > Create Application > Android/iOS.
  2. Create two applications for UniApp Android and UniApp iOS respectively, to receive RUM data from the Android and iOS platforms.
  3. Fill in the corresponding application name and application ID for each platform.
  4. Select the application access method:
  5. Public DataWay: directly receives RUM data without installing DataKit.
  6. Local Deployment: after meeting the prerequisites, the local DataKit receives RUM data.

Installation

Local Usage

Source Code: https://github.com/TrueWatchTech/datakit-uniapp-native-plugin

Demo: https://github.com/TrueWatchTech/datakit-uniapp-native-plugin/Hbuilder_Example

The downloaded SDK package structure is as follows:

|--datakit-uniapp-native-plugin
  |-- Hbuilder_Example
    |-- uni_modules
      |-- GC-JSPlugin
      |   |-- js_sdk
      |   |   |-- View/GCViewTracking.js      // Recommended View global automatic collector
      |   |   |-- View/GCPageMixin.js         // Compatible with View collection, must be used with GCWatchRouter.js
      |   |   |-- View/GCWatchRouter.js       // Compatible with View collection, must be used with GCPageMixin.js
      |   |   |-- View/GCPageViewMixinOnly.js // Use alone when only collecting specified pages
      |   |   |-- Request/GCResourceTracking.js // Standard uni.request Resource and Trace automatic collector
      |   |   |-- Request/GCRequest.js        // Deprecated Resource compatibility API
      |   |   |-- Error/GCErrorTracking.js   // Error automatic collection, supports uni.onError, console.error
      |   |-- index.js
      |   |-- package.json
    |-- nativeplugins
      |-- GCUniPlugin
      |   |-- android
      |   |-- ios
      |   |-- package.json
  |-- UniPlugin-Android
  |-- UniPlugin-iOS

Copy the GCUniPlugin directory to the nativeplugins directory of your project, and in manifest.json, under "App Native Plugin Configuration", click "Select Local Plugin" and choose GCUniPlugin:

img

Copy the GC-JSPlugin directory to the uni_modules directory of your project.

Note: After saving, you must perform cloud packaging; creating a custom base is also considered cloud packaging, and the plugin will only take effect after completion.

For more details, refer to: Using Local Plugins in HBuilderX, Custom Base

Marketplace Plugin

Currently, the marketplace plugin is not available. Please use Local Usage to complete the integration.

uni Mini Program SDK Installation

Development Debugging and wgt Release Usage

  • During development and debugging, the uni mini program SDK needs to integrate GCUniPlugin via Local Usage.

  • When the uni mini program SDK is packaged as wgt for use by the host app, the host app needs to import the GCUniPlugin dependency library and register the GCUniPlugin Module.

The host app needs to perform the following additional operations:

iOS

  • Add the GCUniPlugin dependency library. In Xcode, go to TARGETS -> Build Phases -> Link Binary With Libraries, click "+", select Add Other -> Add Files..., and open the GCUniPlugin/ios/ directory. For SDK 0.2.7 and above, add GuanceSDK.xcframework and GC_UniPlugin_App.xcframework; for SDK 0.2.6 and below, add FTMobileSDK.xcframework and GC_UniPlugin_App.xcframework.
  • When SDK version is < 0.2.0, in TARGETS -> General -> Frameworks, Libraries, and Embedded Content, change the Embed method of FTMobileSDK.xcframework to Embed & Sign.
  • Register the 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

  • Add the GCUniPlugin dependency library:
  • Method 1: Copy ft-native-[version].aar, ft-sdk-[version].aar, gc-uniplugin-[last-version].aar from GCUniPlugin/android/ to the project libs directory, and add dependencies in build.gradle.
  • Method 2: Configure via Gradle Maven remote repository, refer to UniPlugin-Android Project Configuration.
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'
}
  • Register the 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();
        }
    }
}

Mixed Usage of UniApp SDK and Native SDK

  • When integrating GCUniPlugin in the host app, the Native SDK is also imported, so Native SDK methods can be called directly.
  • When using mixed mode, only initialize the Native SDK in the host app; the uni mini program side does not need to initialize again and can directly call the methods provided by the UniApp SDK.
  • For the host app initialization method, refer to iOS SDK Initialization Configuration and Android SDK Initialization Configuration.
  • Ensure that the SDK initialization in the host app is completed before loading the uni mini program, so that the SDK is ready when subsequent methods are called.

Additional Android Configuration

If you need to collect app launch events, network requests, and Android Native related events (page navigation, click events, Native network requests, WebView data), configure the Gradle Plugin ft-plugin in the host project.

Differentiating uni Mini Program and Native Data

Supported from SDK 0.2.4 onwards

You can use BridgeContext to add additional context to data collected from the uni mini program side, for filtering or associating specific scenarios.

For example, you can filter corresponding uni mini program data by wgt_id:wgt_id_1:

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

Detailed Configuration Entry Points

Configuration Description

  • Quick Start: Shortest path for first-time access.
  • SDK Initialization: Basic configuration, user binding, shutting down the SDK, clearing cache, active synchronization.
  • 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

Plugin Development – iOS Main Project UniPlugin-iOS Usage

Download the UniApp Offline Development SDK

According to the version of the uni-app development tool HBuilderX, download the SDK package required for plugin development.

The SDK package structure is as follows:

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

Drag the dependency libraries and resource files SDK directory into UniPlugin-iOS, the final directory structure is as follows:

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

For more details, refer to iOS Plugin Development Environment Configuration.

Project Configuration

  1. Architectures Setting
    Because Xcode 12 provides arm64 simulator support, while the framework provided by uni-app supports arm64 physical devices and x86_64 simulators, you need to set Any iOS Simulator SDK in Excluded Architectures to arm64.

  2. Other Linker Flags

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

For SDK 0.2.6 and below, still use the FTMobileSDK framework name.

  1. Framework Search Paths
$(inherited)
"${PODS_CONFIGURATION_BUILD_DIR}/GuanceSDK"
"${PODS_CONFIGURATION_BUILD_DIR}/GC-UniPlugin-App"
$(DEVELOPER_FRAMEWORKS_DIR)
$(PROJECT_DIR)/../SDK/libs
$(PROJECT_DIR)

For SDK 0.2.6 and below, replace the GuanceSDK path with FTMobileSDK.

Plugin Development – Android Main Project UniPlugin-Android Usage

Project Configuration

For detailed dependency configuration, refer to the Demo. For more Gradle extension parameters, refer to Android SDK.

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

Difference Between Android Cloud Packaging and Offline Packaging

Android cloud packaging and offline packaging use two different integration logics. The offline packaging method is consistent with the integration method of TrueWatch Android SDK, and can use Android Studio Gradle Plugin; cloud packaging cannot use this plugin, so some capabilities are implemented internally by the TrueWatch UniApp Native Plugin.

Therefore, the offline packaging version can use more configuration items than the cloud packaging version. The offlinePackage parameter in sdkConfig is used to distinguish between these two cases. See SDK Initialization for details.

Other