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 entries, advanced scenario entries, and FAQ.

If you need parameter tables, API descriptions, manual collection examples, and runtime capabilities, please read the following topic pages.

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 link tracing are needed, continue reading Log Configuration and Trace Configuration.
  5. If tags, data masking, or WebView collection are needed, then 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 application integration.

Application Integration

  1. Go to RUM > Create > Android/iOS.
  2. Create two applications, one for UniApp Android and one for UniApp iOS, to receive RUM data from the Android and iOS platforms respectively.
  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-capture, needs to be used with GCWatchRouter.js
      |   |   |-- View/GCWatchRouter.js      // Used for view auto-capture, 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   // 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 a cloud build. Creating a custom playground also counts as a cloud build; the plugin will only take effect after completion.

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

Marketplace Plugin Method

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

uni Mini Program SDK Installation

Development Debugging and wgt Release Usage

  • During the development and debugging phase of the uni mini program SDK, you need to integrate GCUniPlugin using 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 setting 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, and gc-uniplugin-[last-version].aar from GCUniPlugin/android/ to the project's libs directory, and add dependencies in build.gradle.
  • Method 2: Configure via the 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 already imported, so Native SDK methods can be called directly.
  • When using them together, 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 the methods provided by the UniApp SDK.
  • The host App initialization method can refer to iOS SDK Initialization Configuration and Android SDK Initialization Configuration.
  • Be sure to complete the SDK initialization in the host App before loading the uni mini program to ensure the SDK is ready when subsequent methods are called.

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 add additional context to the data collected on the uni mini program side via BridgeContext for filtering or associating specific scenarios.

For example, you can filter data for the 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 Entries

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 link tracing.

Advanced Scenarios

FAQ

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 developing the plugin.

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 support for the arm64 simulator, while the framework provided by uni-app supports arm64 real devices and x86_64 simulators, you need to set arm64 for Any iOS Simulator SDK in Excluded Architectures.

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

Android Cloud Build vs Offline Build Differences

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

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

Others

Feedback

Is this page helpful? ×