UniApp Application Integration¶

Prerequisites¶

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

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

Application Integration¶

1. Go to User Access Monitoring > Create Application > Android/iOS;
2. Create two applications for UniApp Android and UniApp iOS respectively to receive RUM data from Android and iOS platforms;
3. Enter the corresponding application name and application ID for each platform's application;
4. Choose the application integration method:
   • Public DataWay: Directly receive RUM data without installing the DataKit collector.
   • Local Environment Deployment: Receive 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

Downloaded SDK package structure description

|--datakit-uniapp-native-plugin
  |-- Hbuilder_Example            // GCUniPlugin plugin example project
    |-- uni_modules           
      |-- GC-JSPlugin         // ⭐️ GC-JSPlugin JS Plugin Package ⭐️
      |   |-- js_sdk          // Folder containing js files
            |-- View/GCPageMixin.js  //view auto-capture using js, GCPageMixin.js and GCWatchRouter.js are used together
            |-- View/GCWatchRouter.js //view auto-capture using js, GCPageMixin.js and GCWatchRouter.js are used together
            |-- View/GCPageViewMixinOnly.js  // view auto-capture using js, GCPageViewMixinOnly.js is used alone
            |-- Request/GCRequest.js         // resource and trace using js, providing APM and network request monitoring capabilities
            |-- Error/GCErrorTracking.js     // error auto-capture using js, supports capturing uni.onError, console.error
      |   |-- index.js        
      |   |-- package.json    // Plugin configuration file
    |-- nativeplugins             // Example project's local plugin folder
          |-- GCUniPlugin         // ⭐️ GCUniPlugin Native Plugin Package ⭐️
          |   |-- android         // Folder containing android plugin dependencies and resource files
          |   |-- ios             // Folder containing ios plugin dependencies and resource files
          |   |-- package.json    // Plugin configuration file
  |-- UniPlugin-Android           // Plugin development Android main project 
  |-- UniPlugin-iOS               // Plugin development iOS main project 

Configure the GCUniPlugin folder to your uni_app project's "nativeplugins" directory. Also, in the manifest.json file, under "App Native Plugin Configuration," click "Select Local Plugin" and choose the GCUniPlugin plugin from the list:

Configure the GC-JSPlugin folder to your uni_app project's "uni_modules" directory.

Note: After saving, you need to submit a cloud build (creating a custom base also counts as a cloud build) for the plugin to take effect.

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

Market 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 use the local usage method to integrate GCUniPlugin.

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

Operations required by the host App:

iOS

• Add GCUniPlugin dependency library

  In the Xcode project, select the project name in the left directory, and in 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 open to add the dependency library 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 library

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

• Method 2: Use the Gradle Maven remote repository for configuration. Refer to the UniAndroid-Plugin project configuration for the configuration method.

  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();
          }
          ......
      }
  }

UniApp SDK and Native SDK Mixed Usage¶

• When performing the above operation to add the GCUniPlugin dependency library, the Native SDK has already been added to the host project, so you can directly call the Native SDK methods.

• SDK Initialization

  When using mixed mode, only initialize the Native SDK in the host App. There is no need to perform initialization configuration in the uni mini program. You can directly call the methods provided by the UniApp SDK.

  Refer to iOS SDK Initialization Configuration and Android SDK Initialization Configuration for the SDK initialization method in the host App.

  Note: Make sure the host App completes the SDK initialization 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 launch events, network request data, and Android Native related events (page jumps, click events, Native network requests, WebView data).

• Distinguish uni mini program and Native collected data:

  Supported in SDK 0.2.4 and above

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

  For example: You can filter wgt_id:wgt_id_1 to view the 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¶

Start RUM Action.

RUM will bind the Action to possible triggered Resource, Error, LongTask events. Avoid adding multiple times within 0.1 s, the same View will only associate one Action at the same time, new Actions will be discarded if the previous Action has not ended. Does not affect Actions added by the addAction method.

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

API - addAction¶

Add Action event. This type of data cannot associate Error, Resource, LongTask data, no discard logic.

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

View¶

• Auto-collection

Method 1 (Recommended):

Import and call the collection method in the project main.js, configuration code 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 in the SDK package GCUniPlugin plugin Hbuilder_Example/App.vue, Hbuilder_Example/pages/index/index.vue

// step 1. Locally add GC-JSPlugin 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 page displayed in 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, apply to each page that needs to be monitored. Refer to the example project in the SDK package GCUniPlugin plugin Hbuilder_Example/pages/rum/index.vue

// Locally add GC-JSPlugin 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¶

Create page load time record

API - startView¶

Enter page

API - stopView¶

Leave page

Error¶

• Auto-collection

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

• Manual collection

// Manually add
rum.addError({
  'message': 'Error message',
  'stack': 'Error stack',
})

API - addError¶

Add Error event

Resource¶

• Auto-collection

The SDK provides the calling method gcRequest.request, which inherits the uni.request network request method, and can replace uni.request for use.

Replacement method

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

Usage example

// Locally add GC-JSPlugin 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, refer to GCRequest.js implementation

API - startResource¶

HTTP request start

API - stopResource¶

HTTP request end

API - addResource¶

content object¶

Logger Log Printing¶

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

API - logging¶

Log Level¶

Tracer Network Trace Tracking¶

• Auto-collection

Use gc.request for request calls, will automatically add Propagation Header, 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¶

Get the request header needed for trace, add it to the HTTP request header.

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¶

Bind user information:

API - unbindRUMUserData¶

Unbind current user.

Shut Down SDK¶

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

API - shutDown¶

Shut down SDK.

Clear SDK Cache Data¶

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

API - clearAllData¶

Clear all data not yet uploaded to the server.

Active Sync Data¶

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

API - flushSyncData¶

When sdkConfig.autoSync is configured as true, no additional operation is needed, SDK will automatically sync.

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

WebView Data Monitoring¶

WebView data monitoring, need to integrate Web Monitoring SDK in the WebView access page

Android only supports offline packaging and uni mini program

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, it is recommended to use lineDataModifier.

Single Field Modification (dataModifier)

• Function: Modify a single field value in the data

• Parameter format: {key: newValue}

• Example: {'device_uuid': 'xxx'} will replace the device_uuid field value in the target data with "xxx"

Single Line Data Modification (lineDataModifier)

• Function: Modify the specified field value in a certain type of data

• Parameter format: {measurement: {key: newValue}}

• Example: {'view': {'view_url': 'xxx'}} will modify all view type data's view_url field value 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¶

Add custom global parameters. Applies to RUM, Log data

API - appendRUMGlobalContext¶

Add custom RUM global parameters. Applies to RUM data

API - appendLogGlobalContext¶

Add custom Log global parameters. Applies to 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 inject RUM and log data collected by UniApp, Native side collected data is not injected.

Purpose: Distinguish data source or mark specific scenarios.

Common Issues¶

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

SDK package structure description

|--iOSSDK   
    |-- HBuilder-Hello              // uni-app offline packaging project
    |-- HBuilder-uniPluginDemo      // uni-app plugin development main project (project needed in 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 in 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, the framework provided by uni_app supports the arm64 real machine, x86_64 simulator. So

Set Excluded Architectures to Any iOS Simulator SDK: arm64.

2.Other Linker Flags

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

3.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¶

Detailed dependency configuration, refer to Demo. More Gradle extension parameter configuration 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 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 method is the same as theGuance Android SDK integration method, using Android Studio Gradle Plugin method, cloud packaging cannot use Android Studio Gradle Plugin, so it can only implement part of the functions through the internal code of theGuance UniApp Native Plugin. Therefore, the offline packaging version has more configuration options than the cloud packaging version, the offlinePakcageparameter in the SDK configuration is to distinguish the two situations.

Others¶

• Android Privacy Review
• iOS Other Related
• Android Other Related
• Native symbol file upload
  • Android
  • iOS### Other Common Issues

Using UniApp Offline Development SDK¶

To develop plugins, you need to download the SDK package based on the version of the uni-app development tool HBuilderX. The SDK package structure is as follows:

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

Drag the SDK folder containing dependency libraries and resource files into the UniPlugin-iOS folder. The directory structure should look like this after dragging:

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

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

Project Configuration¶

1. Architectures Settings

Since the simulator provided by Xcode 12 supports the arm64 architecture, the framework provided by uni_app supports the arm64 real device and x86_64 simulator. Therefore, 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)

Plugin Development Android Main Project UniPlugin-Android Usage¶

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 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, which uses the Android Studio Gradle Plugin method. Cloud packaging cannot use the Android Studio Gradle Plugin, so it can only implement part of the functionality through the internal code of the Guance UniApp Native Plugin. Therefore, the offline packaging version has more configuration options than the cloud packaging version. The offlinePakcage parameter in the SDK configuration is used to distinguish between the two situations.

Other Common Issues¶

Android Privacy Review¶

Refer to Android Privacy Review for more details.

iOS Other Related Issues¶

Refer to iOS Other Related for more details.

Android Other Related Issues¶

Refer to Android Other Related for more details.

Native Symbol File Upload¶

• Android: Refer to Android Symbol File Upload.
• iOS: Refer to iOS Symbol File Upload.

This concludes the translation. Let me know if you need further assistance!