UniApp 0.3.0 Migration Guide¶

This document applies to projects upgrading from 0.2.x to 0.3.0 or later.

First, confirm the integration method of your project and read only the corresponding section:

• uni-app Application: Built directly by HBuilderX into an App → read uni-app Application Migration.
• uni Mini Program in a Host App: Developed with uni-app, packaged as a wgt resource bundle, and run inside a host App → read uni Mini Program Migration in a Host App.

In the diff code blocks below, - indicates lines to delete, + indicates lines to add.

uni-app Application Migration¶

0.3.0 introduces the GC-UniPlugin UTS plugin to replace the original App native language plugin nativeplugins/GCUniPlugin. Two changes are required during the upgrade: replacing the plugin, and modifying the SDK API import method.

1. Replace the App Native Language Plugin¶

Delete the old local native language plugin, and install the GC-UniPlugin UTS plugin instead:

- nativeplugins/GCUniPlugin
+ uni_modules/GC-UniPlugin

Directory structure after migration:

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

Also perform the following steps:

1. Delete the configuration for the nativeplugins/GCUniPlugin local native language plugin in manifest.json.
2. Copy GC-JSPlugin and GC-UniPlugin from the same release package; do not mix different versions.
3. Use HBuilderX 4.25.0 or later.

If upgrading from 0.2.0 to 0.2.3, the original project may not contain GC-JSPlugin. During migration, install both modules simultaneously.

Do not keep both nativeplugins/GCUniPlugin and uni_modules/GC-UniPlugin at the same time, otherwise duplicate SDK, duplicate collection, or native symbol conflicts may occur.

2. Modify the SDK API Import Method¶

Remove the code that obtains the SDK object via uni.requireNativePlugin(), and import from GC-UniPlugin instead:

- const mobileAgent = uni.requireNativePlugin('GCUniPlugin-MobileAgent');
- const rum = uni.requireNativePlugin('GCUniPlugin-RUM');
- const logger = uni.requireNativePlugin('GCUniPlugin-Logger');
- const tracer = uni.requireNativePlugin('GCUniPlugin-Tracer');
+ // main.js / main.ts: load only once, and place it before the GC-JSPlugin collector calls
+ import '@/uni_modules/GC-UniPlugin/setup.js';
+ import {
+     mobileAgent,
+     rum,
+     logger,
+     tracer
+ } from '@/uni_modules/GC-UniPlugin';

3. Keep Existing Initialization Code Unchanged¶

After migrating the API import method, the existing initialization calls can continue to be used:

mobileAgent.sdkConfig(mobileConfig);
rum.setConfig(rumConfig);
logger.setConfig(loggerConfig);
tracer.setConfig(traceConfig);

Only check the relevant parameters as described below.

Sample Rate Parameter¶

If samplerate is used in the configuration, it is recommended to change it to sampleRate:

rum.setConfig({
-    samplerate: 1
+    sampleRate: 1
});

logger.setConfig({
-    samplerate: 1
+    sampleRate: 1
});

tracer.setConfig({
-    samplerate: 1
+    sampleRate: 1
});

samplerate is still supported for backward compatibility but is deprecated. When both are set, sampleRate takes precedence.

Adding HarmonyOS Application¶

Only when publishing a HarmonyOS application, add the corresponding RUM App ID:

rum.setConfig({
    androidAppId: 'YOUR_ANDROID_APP_ID',
    iOSAppId: 'YOUR_IOS_APP_ID',
+    harmonyAppId: 'YOUR_HARMONY_APP_ID',
    // ...
});

Each platform should use its own RUM App ID created in Guance.

For HarmonyOS, if automatic Action collection is required, also call the following at application startup:

gcActionTracking.startTracking();

4. Adjust JS Collector as Needed¶

Upgrading from 0.2.6 or earlier and using Vue 3¶

Vue 3 requires passing the application instance returned by createSSRApp() to gcViewTracking.startTracking():

-gcViewTracking.startTracking();

export function createApp() {
    const app = createSSRApp(App);
+    gcViewTracking.startTracking(app);
    return { app };
}

See View Auto Collection for details.

Migrating from gcRequest to gcResourceTracking¶

gcResourceTracking has been available since 0.2.7 to intercept standard uni.request. If the project still uses the deprecated gcRequest, it is recommended to migrate to gcResourceTracking; do not enable both collection methods simultaneously. See Resource Auto Collection for details.

uni Mini Program Migration in a Host App¶

In this section, "uni mini program" specifically refers to projects developed with uni-app, packaged as a wgt resource bundle, and run inside a host App.

0.3.0 adjusts the usage and release location of the App native language plugin:

  # uni mini program project
- nativeplugins/GCUniPlugin
  uni_modules/GC-JSPlugin

  # Host App
- Get host-side native dependencies from nativeplugins/GCUniPlugin
+ Get GC-UniPlugin native dependency library from dist/unimp-host-extension

The uni mini program project no longer needs the App native language plugin, nor does it install the GC-UniPlugin UTS plugin used by uni-app applications. The host App still needs to integrate the Native SDK and add the GC-UniPlugin native dependency library for the corresponding platform from dist/unimp-host-extension.

1. Adjust the uni Mini Program Project¶

1. Delete nativeplugins/GCUniPlugin and the corresponding App native language plugin configuration in manifest.json.
2. Replace the entire GC-JSPlugin directory with version 0.3.0 or later.
3. Do not install GC-UniPlugin and do not load GC-UniPlugin/setup.js.

Adjusted directory structure:

uni_modules/
└── GC-JSPlugin

Only the SDK dependency is adjusted here; no upgrade or restructuring of the uni mini program project is required. If the original code directly calls uni.requireNativePlugin() to obtain the SDK object, the next modification is also needed.

2. Modify the SDK API Import Method¶

After removing the App native language plugin, directly calling uni.requireNativePlugin() may show a "native plugin not found" prompt and return an invalid object, causing subsequent methods to fail. Instead, import the SDK API from GC-JSPlugin:

- const mobileAgent = uni.requireNativePlugin('GCUniPlugin-MobileAgent');
- const rum = uni.requireNativePlugin('GCUniPlugin-RUM');
- const logger = uni.requireNativePlugin('GCUniPlugin-Logger');
- const tracer = uni.requireNativePlugin('GCUniPlugin-Tracer');
+ import {
+     mobileAgent,
+     rum,
+     logger,
+     tracer
+ } from '@/uni_modules/GC-JSPlugin';

GC-JSPlugin checks whether the host has registered the corresponding native Module. When the Module is unavailable, subsequent API calls will degrade safely, avoiding interruption of business code. When debugging in a base that does not integrate the GC-UniPlugin native dependency library, the console may still display a generic message like "The current base does not contain the native plugin. Please configure the plugin in manifest." In this scenario, there is no need to reconfigure the App native language plugin; native capabilities should be verified in the host App that has integrated the dependencies.

3. Update Host App Dependencies¶

The host App continues to integrate the Native SDK. Replace the host-side native dependencies previously obtained from nativeplugins/GCUniPlugin with the GC-UniPlugin native dependency library for the corresponding platform from dist/unimp-host-extension:

• Android: gc-uniplugin-<version>.aar
• iOS: GC-UniPlugin-App.xcframework
• HarmonyOS: GCUniPlugin.har

The GC-UniPlugin native dependency library is used to register the SDK Module with the uni mini program runtime environment, providing the host-side native capabilities that the old App native language plugin offered.

See Host App Integration for dependencies and registration methods for each platform.

Verification After Upgrade¶

After completing the upgrade and rebuilding the custom base or installation package, check the following items:

• The Native SDK is initialized only once in the application.
• Enabled RUM, Log, and Trace data can be reported normally.
• The uni-app application has deleted the old native language plugin, and setup.js is loaded before the JS collector.
• For uni mini program host App, the Native SDK is initialized and the Module is registered before opening the wgt.
• Business callbacks for uni.request remain normal, and Trace headers can be added normally when Trace is enabled.

If you cannot call Native APIs, refer to Troubleshooting.