UniApp Application Access¶

Prerequisites¶

Note: If you have activated the RUM Headless service, the prerequisites have been automatically configured for you. You can directly proceed with application access.

• Install DataKit;
• Configure the RUM Collector;
• Configure DataKit to be accessible via the public network and install the IP Geolocation database.

Application Access¶

1. Go to RUM > Create Application > Android/iOS;
2. Create two separate applications for UniApp Android and UniApp iOS to receive RUM data from the Android and iOS platforms respectively;
3. Enter the corresponding Application Name and Application ID for each platform's application;
4. Choose the application access method:
   • Public DataWay: Directly receives RUM data without installing the DataKit collector.
   • Local Environment Deployment: Receives RUM data after meeting the prerequisites.

Installation¶

Local Usage¶

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

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

Structure of the downloaded SDK package:

|--datakit-uniapp-native-plugin
  |-- Hbuilder_Example                 // Example project for the GCUniPlugin plugin
    |-- uni_modules
      |-- GC-JSPlugin                  // ⭐️ GC-JSPlugin JS Plugin Package ⭐️
      |   |-- js_sdk                   // Folder containing js files
            |-- View/GCPageMixin.js    // js for view auto-capture, used together with GCWatchRouter.js
            |-- View/GCWatchRouter.js  // js for view auto-capture, used together with GCPageMixin.js
            |-- View/GCPageViewMixinOnly.js  // js for view auto-capture, GCPageViewMixinOnly.js used alone
            |-- Request/GCRequest.js         // js for resource and trace, provides APM and network request monitoring capabilities
            |-- Error/GCErrorTracking.js     // js for error auto-capture, supports collecting uni.onError, console.error
      |   |-- index.js
      |   |-- package.json             // Plugin configuration file
    |-- nativeplugins                   // Local plugins folder for the example project
          |-- GCUniPlugin              // ⭐️ GCUniPlugin Native Plugin Package ⭐️
          |   |-- android              // Contains dependency libraries and resource files for the android plugin
          |   |-- ios                  // Contains dependency libraries and resource files for the ios plugin
          |   |-- package.json         // Plugin configuration file
  |-- UniPlugin-Android                // Main Android project for plugin development
  |-- UniPlugin-iOS                    // Main iOS project for plugin development

Configure the GCUniPlugin folder into the "nativeplugins" directory of your uni_app project. You also need to go to the "App Native Plugin Configuration" section in the manifest.json file, click "Select Local Plugin", and choose the GCUniPlugin plugin from the list:

Configure the GC-JSPlugin folder into the "uni_modules" directory of your uni_app project.

Note: After saving, you need to submit for cloud packaging (making a custom debugger also counts as cloud packaging) for the plugin to take effect.

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

Marketplace Plugin Method¶

(Not provided)

Uni Mini Program SDK Installation¶

Development Debugging and wgt Release Usage¶

• When developing and debugging the uni mini program SDK, you need to integrate GCUniPlugin using the Local Usage method.

• When the uni mini program SDK is packaged into a wgt package for use by a host App, the host App needs to import the dependency libraries of GCUniPlugin (including the Native SDK libraries) and register the GCUniPlugin Module.

Operations required for the host App:

iOS

• Add GCUniPlugin dependency libraries

  In the Xcode project, select the project name in the left directory, go to TARGETS -> Build Phases -> Link Binary With Libaries, click the "+" button, in the pop-up window click Add Other -> Add Files..., then open the GCUniPlugin/ios/ dependency library directory, select FTMobileSDK.xcframework and GC_UniPlugin_App.xcframework in the directory, and click the open button to add the dependency libraries to the project.

  When SDK Version < 0.2.0: In TARGETS -> General -> Frameworks,Libaries,and Embedded Content, find FTMobileSDK.xcframework and change the Embed method to Embed & sign.

• Register GCUniPlugin Module:

    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    ....
      //  Register GCUniPlugin module
    [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 GCUniPlugin dependency libraries

• Method 1: Add ft-native-[version].aar, ft-sdk-[version].aar, and gc-uniplugin-[last-version].aar from the GCUniPlugin/android/ folder to the libs folder of your project, and modify the build.gradle file to add dependencies.

• Method 2: Use the Gradle Maven remote repository for configuration. The configuration method can refer to the UniAndroid-Plugin 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 GCUniPlugin Module:

  public class App extends Application {
      @Override
      public void onCreate() {
          super.onCreate();
          try {
            //  Register GCUniPlugin module
              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 performing the above operation to add GCUniPlugin dependency libraries, the Native SDK has already been added to the host project, so you can directly call Native SDK methods.

• SDK Initialization

  For mixed usage, you only need to initialize the Native SDK within the host App. No initialization configuration is needed within the uni mini program; you can directly call the methods provided by the UniApp SDK.

  The SDK initialization method within the host App please refer to iOS SDK Initialization Configuration, Android SDK Initialization Configuration.

  Note: Please ensure the SDK initialization is completed within the host App before loading the uni mini program to ensure the SDK is fully ready before calling any other SDK methods.

• Additional Configuration for Android Integration:

  Configure the Gradle Plugin ft-plugin to collect App startup events, network request data, and Android Native related events (page navigation, click events, Native network requests, WebView data).

• Distinguishing data collected by uni mini program and Native:

  Supported in SDK 0.2.4 and above

  You can add BridgeContext in the uni mini program to filter or correlate data for specific scenarios based on the set key-value pairs.

  For example: You can filter by wgt_id:wgt_id_1 to view data collected by the uni mini program.

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

SDK Initialization¶

Basic Configuration¶

// Configure in App.vue
<script>
    var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");
    export default {
        onLaunch: function() {
            ftModule.sdkConfig({
                'datakitUrl': 'your datakitUrl',
                'debug': true,
                'env': 'common',
                'globalContext': {
                    'custom_key': 'custom value'
                }
            })
        }
    }
</script>
<style>
</style>

RUM Configuration¶

var rum = uni.requireNativePlugin("GCUniPlugin-RUM");
rum.setConfig({
  'androidAppId':'YOUR_ANDROID_APP_ID',
  'iOSAppId':'YOUR_IOS_APP_ID',
  'errorMonitorType':'all', // or 'errorMonitorType':['battery','memory']
  'deviceMonitorType':['cpu','memory']// or  'deviceMonitorType':'all'
})

Log Configuration¶

var logger = uni.requireNativePlugin("GCUniPlugin-Logger");
logger.setConfig({
  'enableLinkRumData':true,
  'enableCustomLog':true,
  'discardStrategy':'discardOldest'
})

Trace Configuration¶

var tracer = uni.requireNativePlugin("GCUniPlugin-Tracer");
tracer.setConfig({
  'traceType': 'ddTrace'
})

RUM User Data Tracking¶

var rum = uni.requireNativePlugin("GCUniPlugin-RUM");

Action¶

API - startAction¶

Starts a RUM Action.

RUM will bind Resource, Error, LongTask events that this Action might trigger. Avoid adding multiple times within 0.1s. Only one Action can be associated with a View at the same time. If a previous Action hasn't ended, a new one will be discarded. Does not interfere with Actions added by the addAction method.

rum.startAction({
  'actionName': 'action name',
  'actionType': 'action type'
})

API - addAction¶

Adds an Action event. This type of data cannot associate Error, Resource, LongTask data and has no discard logic.

rum.addAction({
  'actionName': 'action name',
  'actionType': 'action type'
})

View¶

• Automatic Collection

Method 1 (Recommended):

Import and call the collection method in the project's main.js. Configuration code is as follows:

import {
  gcViewTracking
} from '@/uni_modules/GC-JSPlugin'
// Enable View auto-collection
gcViewTracking.startTracking();

Method 2: App.vue + first page combination configuration. Refer to the example project Hbuilder_Example/App.vue, Hbuilder_Example/pages/index/index.vue in the SDK package's GCUniPlugin plugin.

// step 1. Add GC-JSPlugin locally to your project's uni_modules directory.
// step 2. Add Router monitoring in App.vue, as follows:
<script>
  import {gcWatchRouter} from '@/uni_modules/GC-JSPlugin';
  export default {
    mixins:[gcWatchRouter], //<--- Notice
  }
</script>
// step 3. Add pageMixin to the first displayed page of the application, as follows:
<script>
  import {gcPageMixin} from '@/uni_modules/GC-JSPlugin';
  export default {
    data() {
      return {}
    },
    mixins:[gcPageMixin], //<--- Notice
  }
</script>

Method 3: Only monitor specific pages, applied to each page that needs monitoring. Refer to the example project Hbuilder_Example/pages/rum/index.vue in the SDK package's GCUniPlugin plugin.

// Add GC-JSPlugin locally to your project's uni_modules directory.
<script>
import  {gcPageViewMixinOnly} from '@/uni_modules/GC-JSPlugin';
export default {
    data() {
        return {
        }
    },
    mixins:[gcPageViewMixinOnly], //<--- Notice
    methods: {}
}
</script>

• Manual Collection

// Manually collect View lifecycle
// step 1 (optional)
rum.onCreateView({
  'viewName': 'Current Page Name',
  'loadTime': 100000000,
})
// step 2
rum.startView('Current Page Name')
// step 3
rum.stopView()

API - onCreateView¶

Creates a page load time record.

API - startView¶

Enters a page.

API - stopView¶

Leaves a page.

Error¶

• Automatic Collection

// Add GC-JSPlugin locally to your project's uni_modules directory.
import { gcErrorTracking } from '@/uni_modules/GC-JSPlugin'
gcErrorTracking.startTracking()

• Manual Collection

// Add manually
rum.addError({
  'message': 'Error message',
  'stack': 'Error stack',
})

API - addError¶

Adds an Error event.

Resource¶

• Automatic Collection

The SDK provides the calling method gcRequest.request, which inherits the network request method of uni.request and can be used as a replacement for uni.request.

Replacement Method

+ import {gcRequest} from '@/uni_modules/GC-JSPlugin';
- uni.request({
+ gcRequest.request({
  //...
});

Usage Example

// Add GC-JSPlugin locally to your project's uni_modules directory.
 import {gcRequest} from '@/uni_modules/GC-JSPlugin';
gcRequest.request({
  url: requestUrl,
  method: method,
  header: header,
  filterPlatform:["ios"],
  timeout:30000,
  success(res)  {
    console.log('success:' + JSON.stringify(res))
  },
  fail(err) {
    console.log('fail:' + JSON.stringify(err))
  },
  complete() {
    console.log('complete:' + JSON.stringify(err))
  }
});

• Manual Collection

Manually call startResource, stopResource, addResource to implement. You can refer to the implementation of GCRequest.js.

API - startResource¶

HTTP request starts.

API - stopResource¶

HTTP request ends.

API - addResource¶

content object¶

Logger Log Printing¶

var logger = uni.requireNativePlugin("GCUniPlugin-Logger");
logger.logging({
  'content':`Log content`,
  'status':status
})

API - logging¶

Log Levels¶

Tracer Network Trace¶

• Automatic Collection

Using the gc.request method for requests will automatically add Propagation Headers. Refer to Resource.

• Manual Collection

//Example using uni.request for network requests
var tracer = uni.requireNativePlugin("GCUniPlugin-Tracer");
let key = Utils.getUUID();//Refer to Hbuilder_Example/utils.js
var header = tracer.getTraceHeader({
      'key': key,
      'url': requestUrl,
})
uni.request({
        url: requestUrl,
        header: header,
        success() {

        },
        complete() {

        }
});

API - getTraceHeader¶

Gets the request headers needed for trace, which should be added to the HTTP request headers.

Return type: object

User Information Binding and Unbinding¶

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");
ftModule.bindRUMUserData({
  'userId':'Test userId',
  'userName':'Test name',
  'userEmail':'test@123.com',
  'extra':{
    'age':'20'
  }
})

ftModule.unbindRUMUserData()

API - bindRUMUserData¶

Binds user information:

API - unbindRUMUserData¶

Unbinds the current user.

Shut Down SDK¶

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");
ftModule.shutDown()

API - shutDown¶

Shuts down the SDK.

Clear SDK Cache Data¶

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");
ftModule.clearAllData()

API - clearAllData¶

Clears all data that has not yet been uploaded to the server.

Active Data Synchronization¶

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");
ftModule.flushSyncData()

API - flushSyncData¶

When sdkConfig.autoSync is configured as true, no additional operation is needed; the SDK will perform automatic synchronization.

When sdkConfig.autoSync is configured as false, you need to actively trigger the data synchronization method to synchronize data.

WebView Data Monitoring¶

WebView data monitoring requires integrating the Web Monitoring SDK into the WebView access page.

Android only supports offline packaging and uni mini programs.

Data Masking¶

If you want to fully mask a field, it is recommended to use dataModifier, which performs better. If you need detailed rule replacement, lineDataModifier is recommended.

Single Field Modification (dataModifier)

• Function: Modifies the value of a single field in the data.
• Parameter format: {key: newValue}
• Example: {'device_uuid': 'xxx'} will replace the device_uuid field value of the target data with "xxx".

Single Data Line Modification (lineDataModifier)

• Function: Modifies the specified field value in a certain type of data.
• Parameter format: {measurement: {key: newValue}}
• Example: {'view': {'view_url': 'xxx'}} will modify the view_url field value of all view type data to "xxx".
• measurement data type list:
• RUM data: view, resource, action, long_task, error
• Log data: log

 var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");
  ftModule.sdkConfig({
                 datakitUrl: 'your datakitUrl',
                 debug: true,
         dataModifier: { 'device_uuid':'xxx'},
         lineDataModifier:{ 'resource' :{'response_header':'xxx'},
                            'view' :{'view_url':'xxx'},
    }
    })

Add Custom Tags¶

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");
ftModule.appendGlobalContext({
          'ft_global_key':'ft_global_value'
})
ftModule.appendRUMGlobalContext({
          'ft_global_rum_key':'ft_global_rum_value'
})
ftModule.appendLogGlobalContext({
          'ft_global_log_key':'ft_global_log_value'
})

API - appendGlobalContext¶

Adds custom global parameters. Affects RUM and Log data.

API - appendRUMGlobalContext¶

Adds custom RUM global parameters. Affects RUM data.

API - appendLogGlobalContext¶

Adds custom Log global parameters. Affects Log data.

Add BridgeContext¶

Supported in SDK 0.2.4 and above.

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

API - appendBridgeContext¶

Only injects into RUM and log data collected by UniApp. Data collected by the Native end is not injected.

Purpose: Distinguish data sources or mark specific scenarios.

FAQ¶

Using the Plugin Development iOS Main Project UniPlugin-iOS¶

Download the 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.

SDK package structure description:

|--iOSSDK
    |-- HBuilder-Hello                // uni-app offline packaging project
    |-- HBuilder-uniPluginDemo        // uni-app plugin development main project (project needed for this document)
    |-- SDK                          // Dependency libraries and resource files

Drag the dependency libraries and resource files SDK folder into the UniPlugin-iOS folder. The directory structure after dragging should be as follows.

|-- UniPlugin-iOS
    |-- HBuilder-uniPluginDemo        // uni-app plugin development main project (project needed for this document)
    |-- SDK                          // Dependency libraries and resource files

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

Project Configuration¶

1. Architectures Settings

Because the simulator provided by Xcode 12 supports the arm64 architecture, and the framework provided by uni_app supports the arm64 real device and x86_64 simulator. So,

Set Excluded Architectures to Any iOS Simulator SDK: arm64.

1. 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)

Using the Plugin Development Android Main Project UniPlugin-Android¶

Project Configuration¶

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

|-- UniPlugin-Android
    |-- app
        |--build.gradle
        // ---> Configure ft-plugin
        // apply:'ft-plugin'

    |-- uniplugin_module
        |-- src
            |-- main
                |-- java
                    |-- com.ft.sdk.uniapp
        |-- build.gradle
        //---> Configure dependencies
        //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
        //---> Configure repo
        //    maven {
        //          url 'https://mvnrepo.jiagouyun.com/repository/maven-releases'
        //    }
        //
        //--> Configure buildScrpit
        //    classpath 'com.cloudcare.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. Offline packaging integration is the same as the Guance Android SDK integration method, using the Android Studio Gradle Plugin method. Cloud packaging cannot use the Android Studio Gradle Plugin, so it can only implement some functions through the internal code of the Guance UniApp Native Plugin. Therefore, the offline packaging version has more configurable options than the cloud packaging version. The offlinePakcage parameter in the SDK configuration is used to distinguish these two situations.

Others¶

• Android Privacy Review
• iOS Other Related
• Android Other Related
• Native Symbol File Upload
  • Android
  • iOS* Data Security
• Terms of Service
• Privacy Policy
• Help Center
• Contact Us

Version History¶

Related Links¶

• Official Website
• Documentation
• API Reference
• Community Forum
• GitHub Repository

Support¶

If you encounter any issues or have questions, please: 1. Check our FAQ section 2. Search our Knowledge Base 3. Submit a support ticket 4. Join our community Discord

Contributing¶

We welcome contributions! Please see our: * Contributing Guidelines * Code of Conduct * Development Setup

License¶

This project is licensed under the MIT License.

Acknowledgments¶

• Thanks to all our contributors
• Built with Awesome Tool
• Inspired by Great Project

Additional Resources¶

• Tutorial Videos
• Webinars
• Case Studies
• White Papers

Stay Updated¶

• Blog
• Newsletter
• Twitter
• LinkedIn

Enterprise Support¶

For enterprise customers: * Enterprise Features * SLAs * Custom Development * Dedicated Support

Training¶

• Certification Program
• Workshops
• Online Courses
• Training Materials

Partners¶

• Partner Program
• Integration Partners
• Reseller Program
• Technology Alliances