uniapp plugin integration-Quick Tracking(Quick Tracking)-阿里云帮助中心

Integrate the QuickTracking SDK in your uni-app project to track events and report analytics data.

Warning

The uniapp plugin is deprecated and no longer maintained. New users must integrate the UTS plugin instead. For more information, see UTS SDK.

1. Download the plugin

QuickTracking uniapp plugin download

Platform compatibility

Android	iOS
Supported versions: 4.4 - 13.0	Supported versions: 9 - 15

Usage:

1.1 Purchase for cloud packaging

1.2 Select the project

1.3 Enter the package name

Note: The package name must match the one used for cloud packaging in HBuilderX.

2. Native plugin configuration

2.1 In your HBuilderX project, open manifest.json and select the plugin under App native plugin configuration.

3. Tracking API

3.1 Initialize the SDK

Initialize the SDK to enable event tracking.

App.vue

<script>
  // #ifdef APP-PLUS
  const QtAnalytics = uni.requireNativePlugin('qt-analytics-plugin');
  // #endif
  export default {
    onLaunch: function() {
      // #ifdef APP-PLUS
      QtAnalytics.setCustomDomain('your_custom_domain');
      if (uni.getSystemInfoSync().platform === 'ios') {
        /**
        * @description QtAnalytics.initWithAppkey(String appkey, String channel, int deviceType, String pushSecret)
        * @param {string} appkey The unique appkey issued by QuickTracking.
        * @param {string} channel The channel where the app is distributed.
        * @param {int} deviceType The device type. 1 for phone, 2 for box.
        * @param {string} pushSecret Reserved. Pass an empty string.
        * */
        QtAnalytics.initWithAppkey('your_ios_appkey', 'your_channel', 1, '');
      } else {       
        /**
        * @description QtAnalytics.preInit(String appkey, String channel, int deviceType, String pushSecret)
        * @param {string} appkey The unique appkey issued by QuickTracking.
        * @param {string} channel The channel where the app is distributed. 
        * @param {int} deviceType The device type. 1 for phone, 2 for box.
        * @param {string} pushSecret Reserved. Pass an empty string.  
        * */
        QtAnalytics.preInit('your_android_appkey', 'your_channel', 1, '');
        // For Android, call QtAnalytics.init after the user grants privacy consent.
        QtAnalytics.init('your_android_appkey', 'your_channel', 1, '');
      }
      // #endif
    },
    onShow: function() {
      console.log('App Show')
    },
    onHide: function() {
      console.log('App Hide')
    }
  }
</script>

For H5 integration, see the Web SDK documentation.

For Mini Program integration, see the Mini Program SDK documentation.

3.2 Set global properties

1. Register global properties

/**
 * @description QtAnalytics.registerGlobalProperties(String params)
 * @param {string} params A flat JSON object of key-value pairs for global properties. Nested objects are not supported. On iOS, keys with null or empty string values are not supported.
 * @return {void}
 */
registerGlobalProperties(string params)

Example:

QtAnalytics.registerGlobalProperties(JSON.stringify({
  "param_1":"value_1",
  "param_2":"value_2",
  "param_3":"value_3",
  "param_4":"undefined"
}));

2. Unregister a global property

/**
 * @description Unregisters a specific global property.
 * @param {string} key The name of the global property.
 * @return {void}
 */
unregisterGlobalProperty(String key)

Example:

 QtAnalytics.unregisterGlobalProperty('a');

3. Get all global properties

/**
 * @description Returns all registered global properties.
 * @return {Object} All currently registered global properties.
 */
getGlobalProperties

Example:

const gp = QtAnalytics.getGlobalProperties();

4. Clear all global properties

/**
 * @description Clears all global properties.
 * @return {void}
 */ 
clearGlobalProperties

Example:

QtAnalytics.clearGlobalProperties();

3.3 Page view event

/**
 * Tracks the duration of a page view.
 * Usage: To track duration, you must call onPageStart and onPageEnd in pairs. Calling only one of them will not generate valid data.
 * Call onPageStart when the page is displayed and onPageEnd when the page is hidden.
 * @param {string} viewName The name of the page to track.
 */
onPageStart(String viewName) // Page start
onPageEnd(String viewName) // Page end

Note: You must call onPageStart() and onPageEnd() in pairs. Mismatched calls will not generate valid data.

Example:

//page.vue
const QtAnalytics = uni.requireNativePlugin('qt-analytics-plugin')

export default {
   onShow() {
     ...
     QtAnalytics.onPageStart('current_page_code');
     ...
   }, 
   onHide() {
     ...
     QtAnalytics.onPageEnd('current_page_code');
     ...
   },
}

Update page properties

Call setPageProperty() to attach custom properties to the current page.

/**
 * @param {string} pageName The page name. Must match the current page name, otherwise the call is ignored.
 * @param {Object} pageProperty The key-value pairs to associate with the page. Values must be of type string or number. Nested objects are not supported.
 *
 * @warning You must call this method before onHide.
 */
setPageProperty(String pageName, Object pageProperty)

Note: Call this method after onPageStart().

Example:

//page.vue
const QtAnalytics = uni.requireNativePlugin('qt-analytics-plugin')

export default {
   onShow() {
     ...
     QtAnalytics.onPageStart('current_page_code');
     QtAnalytics.setPageProperty('current_page_code', {
      "pageparam_1":"value_1",
      "pageparam_2":"value_2",
      "pageparam_3":"value_3"
     })
     ...
   }, 
   onHide() {
     ...
     QtAnalytics.onPageEnd('current_page_code');
     ...
   },
}

3.4 Custom event

/**
 * @description QtAnalytics.onEventObject(String eventId, String params)
 * @param {string} eventId The name of the custom event.
 * @param {string} params A flat JSON object of key-value pairs for custom properties. Nested objects are not supported.
 */
onEventObject(String eventId, String params)

Example:

QtAnalytics.onEventObject(
  'test_clk', 
  JSON.stringify({
      "product":"Water bottle",
      "productColor":"Yellow",
      "productId":"003"
  })
);

3.5 User sign-in

onProfileSignIn(String puid, String provider = ''). The second parameter defaults to an empty string.

QtAnalytics.onProfileSignIn('testUserId', 'testOrganization')

User sign-off

QtAnalytics.onProfileSignOff()

Set user profile

Call onProfileSignIn to set a user ID before setting a user profile. This is a custom event with the event ID hardcoded as $$_user_profile.

Example:

/**
 * @description QtAnalytics.onEventObject(String eventId, String params)
 * @param {string} eventId Must be the string literal `$$_user_profile`.
 * @param {string} params A flat JSON object of key-value pairs for custom properties. Nested objects are not supported. 
 */

QtAnalytics.onEventObject(
  '$$_user_profile', 
  JSON.stringify({
    "gender":"male",
    "_user_nick":"a_nick",
    "province":"Beijing"
  })
);

4. Run the application

Package a custom runtime, select the plugin, and run the app on it to test the log output.
After development, perform the final cloud packaging.

Paid native plugins do not currently support offline packaging.

Android Offline Packaging Native Plugin Documentation

iOS Offline Packaging Native Plugin Documentation

If you bind multiple package names to the same plugin and app ID, a package name mismatch error may occur during cloud packaging. To resolve this, open manifest.json, go to "App Native Plugin Configuration" > "Cloud Plugins", and re-add the plugin.

5. Privacy and permissions

1. Required system permissions

Android

android.permission.ACCESS_NETWORK_STATE
android.permission.ACCESS_WIFI_STATE
android.permission.INTERNET

iOS

The QuickTracking SDK collects the IDFA by default to improve data analysis accuracy. If your app does not serve ads, configure your App Store submission as shown below to avoid being rejected for "the app does not include advertising features but collects the advertising identifier (IDFA)."
The QuickTracking SDK does not proactively request IDFA permission. If your app does not request IDFA permission, QuickTracking will not trigger the client-side permission prompt.

2. Data collection, server addresses, and data usage

Android

The QuickTracking Android SDK collects unique device identifiers (such as Android ID, Serial, IMEI, IMSI, OAID, GAID, MAC address, MCC, and MNC) to uniquely identify users for analytics, such as new user tracking. When a standard device identifier is unavailable (for example, on tablets or TV boxes), the MAC address is used instead to ensure continuous analysis.

iOS

The QuickTracking iOS SDK collects unique device identifiers (such as IDFA, IDFV, MCC, MNC, IP address, and UTDID) to uniquely identify users for analytics, such as tracking new users.

For private deployments, specify a custom domain for data reporting. Obtain the required parameters as follows:

appkey: Obtain from the App List in the admin console.

custom domain: Obtain from the "Collection Information" module in the admin console.

SDK link: Obtain from the "Collection Information" module in the admin console.

6. Tracking verification

Android

In the manifest.json file, open "App Common Other Settings", find "Android Settings", and add atm.your_android_app_key to "UrlSchemes". This allows the specified URL scheme to launch the app.

iOS

In the manifest.json file, open "App Common Other Settings", find "iOS Settings", and add atm.your_ios_app_key to "UrlSchemes". This allows the specified URL scheme to launch the app.

For tracking verification in Mini Programs and web apps, see the Tracking Verification documentation.

7. Codeless tracking features

Platform	Feature
Android	App launch (`$$_app_start`) App exit (`$$_app_end`) App activation (`$$_app_install`)
iOS	App launch (`$$_app_start`) App exit (`$$_app_end`) App activation (`$$_app_install`)
Web/H5	Page view (`$$_page_start`) Page leave (`$$_page_leave`) Heatmap click (`$$_hotpoint`) Auto-click and auto exposure Auto-capture clicks on any control
WeChat Mini Program	App launch (`$$_app_start`) App exit (`$$_app_end`) Page view (`$$_page_end`) Reach bottom (`$$_reach_bottom`) Pull-to-refresh (`$$_pull_down_refresh`) Share (`$$_share`) Auto-click Auto exposure
Alipay Mini Program	App launch (`$$_app_start`) App exit (`$$_app_end`) Page view (`$$_page_end`) Reach bottom (`$$_reach_bottom`) Pull-to-refresh (`$$_pull_down_refresh`) Share (`$$_share`) Auto-click Auto exposure
Bytedance Mini Program	App launch (`$$_app_start`) App exit (`$$_app_end`) Page view (`$$_page_end`) Reach bottom (`$$_reach_bottom`) Pull-to-refresh (`$$_pull_down_refresh`) Share (`$$_share`) Auto-click Auto exposure
Baidu Mini Program	App launch (`$$_app_start`) App exit (`$$_app_end`) Page view (`$$_page_end`) Reach bottom (`$$_reach_bottom`) Pull-to-refresh (`$$_pull_down_refresh`) Share (`$$_share`) Auto-click Auto exposure