Skip to content

UniApp Application Integration

Document Introduction

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

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

Reading Path

It is recommended to read in the following order:

  1. For first-time integration, please read Quick Start first.
  2. Complete the Installation according to the actual integration method.
  3. After completing SDK initialization, continue reading SDK Initialization and RUM Configuration.
  4. If log collection and distributed tracing are needed, continue reading Log Configuration and Trace Configuration.
  5. If tagging, data masking, or WebView collection are needed, then proceed to 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 to application integration.

Application Integration

  1. Navigate to RUM > Create Application > Android/iOS.
  2. Create two applications for UniApp Android and UniApp iOS respectively, to receive RUM data for the Android and iOS platforms separately.
  3. Fill in the corresponding application name and application ID for each platform.
  4. Choose the application integration method:
  5. Public DataWay: Directly receives RUM data without installing DataKit.
  6. Local environment deployment: After meeting the prerequisites, the local DataKit receives RUM data.

Installation

Local Usage

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

Demo Address: https://github.com/GuanceCloud/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/GCPageMixin.js        // Used for view auto-collection, needs to be used with GCWatchRouter.js
      |   |   |-- View/GCWatchRouter.js      // Used for view auto-collection, needs to be used with GCPageMixin.js
      |   |   |-- View/GCPageViewMixinOnly.js // Used alone when only collecting specified pages
      |   |   |-- Request/GCRequest.js       // Used for resource and trace, provides APM and network request monitoring capabilities
      |   |   |-- Error/GCErrorTracking.js   // Used for error auto-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 your project's nativeplugins directory. Then, in the "App Native Plugin Configuration" section of manifest.json, click "Select Local Plugin" and choose GCUniPlugin:

img

Copy the GC-JSPlugin directory to the project's uni_modules directory.

Note: After saving, you must perform cloud packaging. Creating a custom debug loader also counts as cloud packaging; the plugin will only take effect after completion.

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

Marketplace Plugin Method

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

uni Mini Program SDK Installation

Development Debugging and wgt Release Usage

  • For uni mini program SDK during the development debugging phase, integrate GCUniPlugin according to the Local Usage method.

  • When the uni mini program SDK is packaged as a wgt for use by a 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's TARGETS -> Build Phases -> Link Binary With Libraries, click "+", select Add Other -> Add Files..., open the GCUniPlugin/ios/ directory, and add FTMobileSDK.xcframework and GC_UniPlugin_App.xcframework.
  • When SDK Version < 0.2.0, you need to change the Embed method of FTMobileSDK.xcframework to Embed & Sign in TARGETS -> General -> Frameworks, Libraries, and Embedded Content.
  • 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's 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();
        }
    }
}

UniApp SDK and Native SDK Mixed Usage

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

Android Additional 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), please configure the Gradle Plugin ft-plugin in the host project.

Distinguishing uni Mini Program and Native Data

Supported in SDK 0.2.4 and above

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

For example, you can filter data for a corresponding uni mini program using wgt_id:wgt_id_1:

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

Detailed Configuration Entry Points

Configuration Instructions

  • Quick Start: The shortest path for first-time integration.
  • SDK Initialization: Basic configuration, user binding, disabling 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

Frequently Asked Questions

Plugin Development iOS Main Project UniPlugin-iOS Usage

Download UniApp Offline Development SDK

According to the version number 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 library and resource file 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 Settings Because Xcode 12 provides arm64 simulator support, while the framework provided by uni-app supports arm64 real devices and x86_64 simulators, you need to set Excluded Architectures for Any iOS Simulator SDK to arm64.

  2. Other Linker Flags

$(inherited) -ObjC -framework "FTMobileSDK" -framework "GC_UniPlugin_App"
  1. 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)

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.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.guance.com/repository/maven-releases' }
        // classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin:xxxx'

Android Cloud Packaging vs Offline Packaging Differences

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

Therefore, the configuration items available for the offline packaging version are usually more than those for the cloud packaging version. The offlinePakcage parameter in sdkConfig is used to distinguish these two situations. For details, see SDK Initialization.

Others

Feedback

Is this page helpful? ×