Tracking API

1. How to view an instrumentation plan

Before you track events, you must determine what to track and where. This process requires a clear instrumentation plan. The QuickTracking platform refers to this as an instrumentation plan and provides a standard template.

An instrumentation plan specifies the following content to track:

1. Event entity: The "who" that triggered the event. This can be a device ID or an account ID. Each reported event must have at least one of these identifiers.

• Device ID: For Android and iOS devices, the default device ID is unique at the application level and is automatically generated by QuickTracking:

  • For devices running Android 9 and earlier: The software development kit (SDK) automatically collects the International Mobile Equipment Identity (IMEI), Wi-Fi MAC address, Android ID, and serial number (SN) to generate a device ID. The device ID is then stored locally. It is regenerated only if the application is uninstalled or its data is deleted.

  • For devices running Android 10 and later: The SDK automatically collects the Open Anonymous Device Identifier (OAID), Google Advertising ID (GAID), Android ID, and SN to generate a device ID. The device ID is then stored locally. It is regenerated only if the application is uninstalled or its data is deleted.

  • For iOS devices: The SDK automatically collects the OpenUDID to generate a device ID. The device ID is then stored in the keychain. It is regenerated only if the device is reset to factory settings or the application data is deleted.

  • The QuickTracking SDK collects the Identifier for Advertisers (IDFA) and OAID only after the end user of the application provides consent. Only the QuickTracking app SDK can collect OAID, GAID, IMEI, Wi-Fi MAC, Android ID, SN, IDFA, and Identifier for Vendors (IDFV).

• Account ID: The identifier for a user after they log on to the client. When a user logs on from different devices, the device ID changes, but the account ID remains the same. For example, a user might log on from both a phone and a tablet.

2. User properties: Properties associated with an account ID. For example, for the account ID "testdemo@111", the "birthday" could be "1999-02-13" and the "membership level" could be "Platinum". "Birthday" and "membership level" are user properties.

3. Channel properties: Properties related to ad delivery, such as the ad channel, delivery method, and content.

4. Global properties: Properties that are set once globally and are included with every subsequent event.

5. Page view event: A page view event is reported when a page loads. In the instrumentation plan, this is an event where the page code and event code are the same. This event is also marked in blue.

6. Click, impression, and custom events: Events reported when a user interacts with the client.

2. Set device ID & account ID

2.1 Set a device ID

The SDK provides a default device identifier collection utility class, `DefaultDeviceInfo`, in the `com.quick.qt.commonsdk` package path. This default implementation collects the following identifiers.

To control the collection of specific device identifiers, such as not collecting the IMEI and Serial fields and implementing your own method for collecting the OAID, you can create a child class of `DefaultDeviceInfo` and override the `getImei`, `getSerial`, and `getOaid` methods. The following example shows how to do this:

import com.quick.qt.commonsdk.DefaultDeviceInfo;

public class CustomDeviceInfo extends DefaultDeviceInfo {

	@Override
	public String getImei(Context context) {
		return null;
	}

	@Override
	public String getSerial() {
		return null;
	}

	@Override
	public String getOaid(Context context) {
		String oaid = "";
        // oaid = getOaidMethod(); // Your method to get the OAID
        return oaid;
	}

}

Note: If you do not override these methods, the QuickTracking SDK collects the identifiers by default. You should carefully consider whether to implement your own methods. If you provide your own collection method, you are fully responsible for collecting that identifier. The SDK will no longer attempt to collect it. The fewer device identifiers the SDK can collect, the greater the negative impact on the accuracy and stability of your statistics.

Register the custom utility class:

import com.quick.qt.commonsdk.QtConfigure;

// Before setting the data collection domain name and calling the SDK pre-initializer function, call the collection utility class registration function.
// If you do not need to control the device identifier collection behavior, you do not need to implement and register a custom utility class.
QtConfigure.setDeviceInfo(new CustomDeviceInfo());
QtConfigure.setCustomDomain("Your data collection service domain name", null);

The SDK supports custom device IDs. To use a custom device ID, you can call the `setCustomDeviceId` interface with a valid (non-empty) value before initialization (before calling `init`).

public static void setCustomDeviceId(Context var0, String var1)

Example:

import com.quick.qt.commonsdk.QtConfigure;

QtConfigure.setCustomDeviceId(this, "xxxxxx");

Note: This feature takes effect only if a device ID has not yet been retrieved. If a device ID already exists in local storage, setting a custom ID has no effect. To verify this feature when a local device ID exists, you must uninstall and reinstall the application.

2.2 Get a device ID

You can use the following methods to obtain it:

import com.quick.qt.commonsdk.QtConfigure;

QtConfigure.getUMIDString(this)

2.3 Set an account ID

1. By default, user statistics are based on the device. To collect statistics based on your application's accounts, you can use the following interface:

public static void onProfileSignIn(String ID);

Note: After an account ID is set, it is saved to local storage. The account ID remains valid and is included with every event until the app is uninstalled, the application data is cleared, or the logout interface described below is called.

2. When a user logs out, you can call this interface. After this interface is called, account-related information is no longer sent.

public static void onProfileSignOff();

Example:

import com.quick.qt.analytics.QtTrackAgent;

// When a user logs on with their own account, you can collect statistics as follows:
QtTrackAgent.onProfileSignIn("userID");

// Log out
QtTrackAgent.onProfileSignOff();

import com.quick.qt.analytics.QtTrackAgent;
import java.util.HashMap;
import java.util.Map;

Map<String, Object> user = new HashMap<String, Object>();
user.put("sex", "girl");// Gender
user.put("age", "8"); // Age
QtTrackAgent.onEventObject(mContext, "$$_user_profile", user);

4. Channel properties

4.1 Launch an app from an H5 link

Channel properties do not require instrumentation. However, the URL used to launch the miniapp or app must carry these channel properties, and the property keys must start with `utm_`. The SDK recognizes `utm_` as the keyword. For example:

<URL scheme>?utm_channel=gzh

Note: If your channel properties are already integrated with third-party ad delivery companies and cannot start with `utm_`, you can use the global properties API to track and report them. The property keys must still start with `utm_`.

4.2 Open the app marketplace from an H5 link, download, and launch the app

In this scenario, simply including `utm_` parameters in the H5 link is not enough to ensure that the `utm_` parameters are carried by the app launch event after the download. This requires a fuzzy match between the H5 launch event and the app activation event based on the IP address and browser User-Agent.

1. When a user clicks the Launch/Download App button on the H5 page, you can report an app link event (`$$_app_link`). This event must include the AppKey of the app to be launched and the channel properties.

// Example
aplus_queue.push({
  action:'aplus.recordAppLink',
  arguments:[{
    targetAppKey: 'The AppKey of the app to launch',  // Required. The AppKey of the app to launch.
    custom1: 'custom1', // Optional. Custom parameter.
    ...
  }]
})

2. The app activation event (`$$_app_install`), which occurs the first time the app is launched after being downloaded, is automatically collected and reported by the QT App SDK.

3. The QuickTracking system performs a fuzzy match between the app link event (`$$_app_link`) and the app activation event (`$$_app_install`) based on the IP address and browser User-Agent. When you use this feature, you can directly analyze the channel properties of the App Activation (Preset) event in your application.

4.3 Collect statistics on active app users from different marketplaces

The third input parameter, `Channel`, in the initializer function is used to set the app marketplace for the application. For example: QtConfigure.preInit(this,"Your AppKey","Channel-Huawei");, QtConfigure.init(this,"Your AppKey","Channel-Huawei",QtConfigure.DEVICE_TYPE_PHONE, "");

5. Global properties

After you register global properties, all subsequent events automatically include them. These properties and their values are stored in memory and are cleared when the app exits. You can view and filter data based on these properties during analysis.

5.1 Register a global property

public static void registerGlobalProperties(Context var0, Map<String, Object> var1);

Numeric type description:

Note:

1. Property names and string-type property values can contain only uppercase letters, lowercase letters, numbers, and underscores.

2. The property value can be one of the following Java types: String, Long, Integer, Float, Double, or Short.

3. If the key of a new global property is the same as an existing one, the existing value is updated. If the key is different from all existing global property keys, the new global property is added.

   Example:

   import com.quick.qt.analytics.QtTrackAgent;
   import java.util.HashMap;
   import java.util.Map;
   
   Map firstMap = new HashMap<String, Object>();
   firstMap.put("a", "1");
   firstMap.put("b", "2");
   QtTrackAgent.registerGlobalProperties(mContext, firstMap);// The current global properties are a:1 and b:2.
   
   Map secondMap = new HashMap<String, Object>();
   secondMap.put("b", "3");
   secondMap.put("c", "4");
   QtTrackAgent.registerGlobalProperties(mContext, secondMap);// The current global properties are a:1, b:3, and c:4.

5.2 Delete a global property

public static void unregisterGlobalProperty(Context context, String propertyName);

Example:

You can delete a specific global property. After deletion, subsequent events will no longer carry this property.

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.unregisterGlobalProperty(mContext, "lnch_Source");

5.3 Get a single global property by key

public static Object getGlobalProperty(Context context, String propertyName);

Example:

import com.quick.qt.analytics.QtTrackAgent;

String userId = QtTrackAgent.getGlobalProperty(mContext, "lnch_Source");

5.4 Get all global properties

public static String getGlobalProperties(Context context);

Example:

import com.quick.qt.analytics.QtTrackAgent;

String allSuperProp = QtTrackAgent.getGlobalProperties(mContext);

5.5 Purge all global properties

public static void clearGlobalProperties(Context context);

Example:

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.clearGlobalProperties(mContext);

6 Page View Event API

6.1 Manual page collection

If you want to collect and analyze the page paths and page durations for Activities, Fragments, CustomViews, and other custom pages, you can perform manual instrumentation by calling the `QtTrackAgent.onPageStart`/`QtTrackAgent.onPageEnd` pair of APIs.

public static void onPageStart(String viewName);
public static void onPageEnd(String viewName);

Example code for manually tracking Fragment page paths:

import com.quick.qt.analytics.QtTrackAgent;

// A matched pair of onPageStart -> onPageEnd calls tracks the lifecycle of a non-Activity page, such as a Fragment.

// Override the onResume method of the Fragment.
public void onResume() {
    super.onResume();
    QtTrackAgent.onPageStart("MainScreen"); // Track the page. "MainScreen" is the page name and can be customized.
}

// Override the onPause method of the Fragment.
public void onPause() {
    super.onPause();
    QtTrackAgent.onPageEnd("MainScreen");
}

Note:

The `onPageStart` method records page entry information but does not report an event. A page view event is reported only when the `onPageEnd` method is called.

`onPageStart` and `onPageEnd` must be called in pairs, and the `page_name` value passed to them must be identical. If the `onPageEnd` call is missing, or if its `page_name` value does not match the value from `onPageStart`, the information recorded by `onPageStart` will not take effect.

6.1.1 Upload page properties

You can use the `QtTrackAgent.setPageProperty()` method to attach custom properties to the current page.

API: QtTrackAgent.setPageProperty

Parameters:

Sample code:

The following example shows how to set the properties of an Activity when it is displayed:

import com.quick.qt.analytics.QtTrackAgent;

private static final String PAGE_NAME = "page_home"; // Page name
 
 @Override
 public void onResume() {
    super.onResume();
   
    QtTrackAgent.onPageStart(PAGE_NAME); // Track the start of the page display.
    Map<String, Object> params = new HashMap<>();
    params.put("home_param_1", "value11"); // Set properties for the current page.
    QtTrackAgent.setPageProperty(mContext, PAGE_NAME, params);
 }

Note: Page property settings only support manual page instrumentation.

6.1.2 Pass-through page properties

The QuickTracking SDK also provides the `SpmAgent.updateNextPageProperties` interface. This interface lets you attach custom properties to the next page.

API: SpmAgent.updateNextPageProperties

Parameters:

Supported types:

/**
* 
* This function is called when navigating to the next target page.
*/
public static void updateNextPageProperties(Map<String, Object> params)

Value passing example:

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.spm.SpmAgent;

public class MainActivity extends AppCompatActivity {
    private static final String PAGE_NAME = "page_home"; // Page name
    private Button mGoNewsWithHole;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        setTitle("QuickTracking Statistics Home Page");
        setContentView(R.layout.activity_u4a_home);

        binding.btnGoToDetail.setOnClickListener(v -> {
            // Add custom properties to the next page.
            Map<String, Object> params = new HashMap<>();
            params.put("my_transfer_arg1", "The value of the pass-through property from MainActivity");
            SpmAgent.updateNextPageProperties(params); //
            startActivity(new Intent(this, DetailActivity.class));
        });
    }
 }

Example:

import com.quick.qt.spm.SpmAgent;

String transferValue = SpmAgent.getPageProperty(PAGE_NAME, "my_transfer_arg1", SpmAgent.transProperties);

Note: Pass-through page properties are only supported for manual page instrumentation.

6.2 Automatic Activity page collection (full instrumentation)

Automatic page collection is enabled by default for Activity pages. You do not need to integrate the Gradle plugin for full instrumentation. By default, when the SDK collects session data, it automatically collects and reports the path and access duration for each Activity page. If you also call the manual page path collection APIs, `QtTrackAgent.onPageStart`/`onPageEnd`, this will cause duplicate data reporting and generate redundant page path data. You can call the QtTrackAgent.disableActivityPageCollection() function immediately after calling the `QtConfigure.preInit` pre-initializer function to disable automatic collection of Activity page path data by the SDK.

public static void disableActivityPageCollection();

To disable the automatic data collection and reporting API for only a specific activity, you can call this function in the `onCreate` function of the activity:

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.skipMe(this, null); 

6.3 Automatic data collection for Fragment pages (Full instrumentation)

Automatic data collection is disabled by default for Fragment pages. To enable it, you must integrate the full instrumentation plugin and enable the automatic collection switch. For more information, see

8.1 Adding the automatic instrumentation Gradle plugin and Enabling automatic instrumentation for Fragment PV data.

7. Event Instrumentation

You can use custom events to track user behavior and record specific details about the behavior.

7.1 Event instrumentation

You can use the onEventObject interface to track events. The parameter value can be one of the following types: String, Long, Integer, Float, Double, or Short.

API:

public static void onEventObject(Context context, String eventID, Map<String, Object> map)

public static void onEventObject(Context context, String eventID, Map<String, Object> map, String pageName)

Event upload limit:

• Maximum length of a custom property key string: 1024

• Maximum length of a custom property value string: 1024 × 4

• Maximum number of key-value pairs in a custom property map: 100

• Maximum number of elements in an array value of a custom property: 100

Numeric type description:

Example:

import com.quick.qt.analytics.QtTrackAgent;

Map<String, Object> music = new HashMap<String, Object>();
music.put("music_type", "popular");// Custom parameter: music type, value: popular
music.put("singer", "JJ"); // Singer: (JJ Lin)JJ
music.put("song_name","A_Thousand_Years_Later"); // Song name: A Thousand Years Later
music.put("song_price",100); // Price: 100 CNY
QtTrackAgent.onEventObject(this, "play_music", music, "home_page");

Note:

• The configuration for pulling the event sample rate depends on the automatic collection switch. When you use the SDK, you can call the `setAutoEventEnabled()` method.

  Example:

  public class MyApplication extends Application {
  
      @Override
      public void onCreate() {
          super.onCreate();
  	QtConfigure.setCustomDomain("your_data_collection_service_domain", null);
          // Enable the debug log.
          QtConfigure.setLogEnabled(true);
          // Pulling the sample rate depends on the automatic instrumentation switch setting. If you need the event sample rate control feature, call this API as needed.
          QtTrackAgent.setAutoEventEnabled(false);        
          //...
      }
      //... 
  }

• Multi-parameter events can be used for the same analysis scenarios as compute events and count events.

• For compute-optimized events, different parameter types use different calculation methods. They are divided into two main categories: numeric and character.

  • Numeric: Supports calculations for sum, maximum, minimum, average value, and unique count.

  • Character: Supports unique count calculations.

7.2 Child Process Instrumentation

The SDK supports instrumentation for only custom events in child processes. Data collection for other types, such as pages, is not currently supported. To instrument child processes, you can call the `QtConfigure.setProcessEvent` function after the SDK initialization is complete.

Example:

public class MyApplication extends Application{
    @Override
    public void onCreate(){
        super.onCreate();
        // Initialize the SDK.
        QtConfigure.preInit(this, "Your AppKey", "App Marketplace");
        
        // Enable tracking of custom events in child processes.
        QtConfigure.setProcessEvent(true);
        // ...

Note:

• To track custom events in a child process, you must initialize the SDK in that child process.

7.3 Duration-type events

SDK version 1.9.1.PX+ introduces a duration event. This event lets you manually control the lifecycle of a timer (start, pause, resume, and end). This enables the SDK to automatically exclude paused time, calculate the effective playback duration, and support custom property reporting.

API:

 /**
   * Starts an event timer.
   *
   * @param context The current context.
   * @param eventID The event ID.
   * @return The unique ID of the timer, which is used for subsequent control.
 */
public static String eventTimerStart(Context context, String eventID)

/**
   * Ends the specified event timer and reports the statistics.
   *
   * @param timerID The timer ID.
   */
public static void eventTimerEnd( String timerID)

 /**
   * Pauses the specified event timer.
   *
   * @param timerID The timer ID.
   */
public static void eventTimerPause(String timerID) 

 /**
   * Resumes the specified event timer.
   *
   * @param timerID The timer ID.
   */
public static void eventTimerResume(String timerID) 

/**
 * Sets properties for the specified event timer.
 *
 * @param timerID    The timer ID.
 * @param properties A collection of event properties.
 */
public static void setTimerProperties(String timerID, Map<String, Object> properties) 

7.3.1 Start timing (eventTimerStart)

This method is called when the event starts. It generates a unique ID and starts a background task for periodic saving.

Example:

String playId = QtTrackAgent.eventTimerStart(this,"video_play");

7.3.2 Setting properties (setTimerProperties)

This is the metadata for the associated event, such as the title, URL, and type. You can invoke this method at any time after the event starts and before it ends.

Event upload quantity limit:

• Maximum length of a custom property key: 1024 characters

• Maximum length of a custom property value: 4096 characters

• Maximum number of custom properties: 100

• Maximum number of elements in an array value: 100

Description of numeric types:

Example:

Map<String, String> props = new HashMap<>();
props.put("video_id", "10086");
props.put("video_title", "Test Video");
props.put("category", "movie");
QtTrackAgent.setTimerProperties(playId, props);

7.3.3 Pausing the timer (eventTimerPause)

This function is called when the user pauses the video or when the video buffers. If this function is called multiple times, only the first call is recognized. Subsequent calls do not cause the pause time to accumulate.

Example:

QtTrackAgent.eventTimerPause(videoUuid);

7.3.4 Resume timer (eventTimerResume)

This method is called when the user resumes playback or when buffering is complete. If this method is called multiple times, only the first call takes effect.

Example:

QtTrackAgent.eventTimerResume(videoUuid);

7.3.5 End and Report (eventTimerEnd)

This method is invoked when video playback ends, the user closes the page, or the user switches videos.
This method will:

1. Calculate the final effective playback duration in milliseconds.

2. Build the JSON-formatted data for reporting.

3. Trigger the reporting callback, which you must integrate with your own instrumentation solution.

4. Purge the task from local storage and memory.

QtTrackAgent.eventTimerEnd(videoUuid);

7.3.6 Automatic event persistence interval settings (setEventTimeInterval)

You can configure the automatic data persistence interval. The default interval is 15 s, and the valid range is 1 s to 300 s.

Interface:

public static void setEventTimeInterval(int interval);

Example:

QtConfigure.setEventTimeInterval(3 * 1000);

8 Full instrumentation (automatic instrumentation)

8.1 Adding the automatic instrumentation Gradle plugin

buildscript {
    repositories {
        maven { url 'https://repo1.maven.org/maven2/' } // QuickTracking repository
        jcenter()
            google()
        }
    
    dependencies {
        classpath 'com.android.tools.build:gradle:3.5.4'
            
            // Add the QuickTracking android-gradle-plugin dependency
            // For Gradle versions earlier than 7.1.2
            //classpath 'com.umeng.umsdk:android-gradle-plugin:1.0.0' 
            // For Gradle versions from 7.1.2 to 7.5
            classpath 'com.lydaas.qtsdk:quick-gradle-plugin2:1.0.2'
            // For Gradle versions from 7.5 to 8+
            // classpath 'com.lydaas.qtsdk:quick-gradle-plugin2:2.0.0'
            // For Gradle versions 9+
            // classpath 'com.lydaas.qtsdk:quick-gradle-plugin2:2.0.1'
        }
}

allprojects {
    repositories {
        maven { url 'https://repo1.maven.org/maven2/' } // QuickTracking repository
        jcenter()
            google()
        }
}

pluginManagement {
    repositories {
        google {
            content {
                includeGroupByRegex("com\\.android.*")
                includeGroupByRegex("com\\.google.*")
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
        maven { url 'https://repo1.maven.org/maven2/' }// QuickTracking repository
    }

}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url 'https://repo1.maven.org/maven2/' }// QuickTracking repository
    }
}

buildscript {
    dependencies {
        classpath 'com.lydaas.qtsdk:quick-gradle-plugin2:2.0.1'
    }
}

8.2 Using the Gradle compile plugin for dependencies

In the `build.gradle` configuration of the main module, you can apply the full instrumentation plugin:

apply plugin: 'com.android.application'
//apply plugin: 'com.qt.analytics.plugin' // P version plugin (for auto-instrumentation scenarios)
apply plugin: 'com.quick.analytics.plugin' // PX version plugin (for auto-instrumentation scenarios)

dependencies {
   // Add the Quick Tracking analytics SDK. The SDK version must match the Gradle plugin version specified above.
   //implementation 'com.umeng.umsdk:qt-common:1.4.4.P' // P version (SDK version format: x.x.x.P)
   implementation 'com.lydaas.qtsdk:qt-px-common:1.8.6.PX'  // PX version (SDK version format: x.x.x.PX)
}

8.3 Automatic Tracking API

8.3.1 Auto-instrumentation switch

Enable automatic Fragment PV instrumentation

You can use the enableFragmentPageCollection() method to enable automatic collection of all Fragment page view events.

/**
* Switch for automatic data collection from Fragment pages. This feature is disabled by default in the SDK.
* @param enable true to enable, or false to disable.
*/
public static void enableFragmentPageCollection(boolean enable);

Sample code:

import com.quick.qt.commonsdk.QtConfigure;
import com.quick.qt.analytics.QtTrackAgent;

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
	QtConfigure.setCustomDomain("your_data_collection_service_domain", null);
        // Enable the debug log.
        QtConfigure.setLogEnabled(true);
        // Enable automatic collection of all Fragment page view events.
        QtTrackAgent.enableFragmentPageCollection(true);
        //...
    }
    //... 
}

Enable the Activity PV data switch

Automatic collection of Activity page data is enabled by default. The SDK automatically collects and reports the path and access duration of each Activity page when it collects session data. If you also call the `QtTrackAgent.onPageStart`/`onPageEnd` APIs to manually collect page path data, this results in duplicate data reporting and generates redundant page path data. To prevent this, you can call the QtTrackAgent.disableActivityPageCollection() function immediately after the `QtConfigure.preInit` pre-initializer function to disable the SDK's automatic collection of Activity page path data.

public static void disableActivityPageCollection();

To disable automatic data collection and reporting for only a specific activity page, you can call this function in the onCreate function of the activity:

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.skipMe(this, null); 

Disable automatic data collection for a page

To disable automatic data collection and reporting for only a specific activity page, you must call this function in the onCreate function of the activity:

import com.quick.qt.analytics.QtTrackAgent;

QtTrackAgent.skipMe(this, null); 

Enable automatic instrumentation for control clicks

/**
 * Enables or disables the automatic collection of control click events.
 * This feature is disabled by default.
 * @param enable Set to `true` to enable automatic collection, or `false` to disable it.
 */
public static void setAutoEventEnabled(boolean enable);

Sample code:

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.commonsdk.QtConfigure;

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
	QtConfigure.setCustomDomain("Your data collection service domain name", null);
        // Enable the debug log
        QtConfigure.setLogEnabled(true);
        QtTrackAgent.enableFragmentPageCollection(true);
        // Enable the automatic collection of control click events.
        QtTrackAgent.setAutoEventEnabled(true);
        //...
    }
    //...
    
}

List of control types that support automatic monitoring:

8.3.2 Setting custom properties for automatic Activity/Fragment PV

By implementing the com.umeng.analytics.autotrack.PageAutoTracker interface for a specific Activity or Fragment, you can customize the properties, page name, or source page name for the page that is automatically tracked.

public interface PageAutoTracker {
    /**
     * Returns the current page name.
     * @return Returns null or an empty string if a custom page name is not required.
     */
    String getPageName();

    /**
     * Returns the source page name.
     * @return Returns null or an empty string if a custom source page name is not required.
     */
    String getRefPageName();

    /**
     * Returns custom attribute key-value pairs. Both the key and the value must be strings. Return null if there are no custom attributes.
     *
     * @return Returns null if there are no custom attributes.
     */
    Map<String, String> getTrackProperties();
}

Sample code:

import com.quick.qt.analytics.QtTrackAgent;

/**
 * Specify a custom page name and custom page properties for FragmentContacts.
 */
public static class FragmentContacts extends Fragment implements PageAutoTracker {
        private final String mPageName = "FragmentContacts";

        static FragmentSimple newInstance(int num) {
            FragmentSimple f = new FragmentSimple();

            // Supply num input as an argument.
            Bundle args = new Bundle();
            args.putInt("num", num);
            f.setArguments(args);

            return f;
        }

        /**
         * The Fragment's UI is just background simple text view showing its instance
         * number.
         */
        @Override
        public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {

            FrameLayout fl = new FrameLayout(getActivity());
            fl.setLayoutParams(new FrameLayout.LayoutParams(FrameLayout.LayoutParams.MATCH_PARENT,
                    FrameLayout.LayoutParams.MATCH_PARENT));
            fl.setBackgroundColor(Color.LTGRAY);
            TextView tv = new TextView(getActivity());
            tv.setText("Fragment Contacts");
            tv.setTextColor(Color.BLACK);
            tv.setOnClickListener(new View.OnClickListener() {
                @Override
                public void onClick(View v) {
                    QtTrackAgent.ignoreView(v); // Disable automatic data collection and reporting for the TextView control.
                    Toast.makeText(getActivity(), "The TextView was clicked.", Toast.LENGTH_LONG).show();
                }
            });
            fl.addView(tv);
            return fl;
        }

        // Custom page name for FragmentContacts
        @Override
        public String getPageName() {
            return "FragmentContacts";
        }

    	// Return null because a custom source page name is not required for FragmentContacts.
        @Override
        public String getRefPageName() {
            return null;
        }

    	// Custom properties for the FragmentContacts page
        @Override
        public Map<String, String> getTrackProperties() {
            Map<String, String> properties = new HashMap<>();
            properties.put("fragment_arg1", "fragment_value111");
            properties.put("fragment_arg2", "fragment_value222");
            return properties;
        }
    }

8.3.3 Setting custom properties for a control's click event

You can use the setViewProperties() method to set custom properties on a specific control. These properties are provided as key-value pairs, and both the key and value must be strings. The custom properties and their values are then included in the data of the full instrumentation click event for that control.

/**
* Sets the custom properties for a control. The properties are specified as multiple key-value pairs, where both the keys and values must be strings.
* @param view The control object.
* @param properties The custom properties.
*/
public static void setViewProperties(View view, JSONObject properties);

Sample code:

import com.quick.qt.analytics.QtTrackAgent;

@QtDataTrackViewOnClick
public void onClick(View v) {
    int id = v.getId();
    Intent in = null;
    if (id == R.id.normal) {
        // Set a custom event ID "ekv_normal" for the button control whose resource ID is "normal".
        // After this is set, the SDK reports the event ID as "ekv_normal" when this control is clicked.
        QtTrackAgent.setViewEventID(v, "ekv_normal");
        // Set custom property values for the click event of the "normal" button, which is the "ekv_normal" event.
        // The properties and their values in customArgs will be included in the "ekv_normal" event data and reported.
        JSONObject customArgs = new JSONObject();
        try {
            customArgs.put("customArg1", "value1111");
            customArgs.put("customArg2", "value2222");
        } catch (JSONException e) {
        
        }
        QtTrackAgent.setViewProperties(v, customArgs);
      }
   }

8.3.4 Setting a custom event encoding for a control's click event

You can use the setViewEventID() method to set a custom event code for the click event of a specific control.

/**
* Sets a custom event code for an automatically collected control click event.
* @param view The View object.
* @param eventcode The custom event code.
*/
public void setViewEventID(View view, String eventcode);

Example:

import com.quick.qt.analytics.QtTrackAgent;

@QtDataTrackViewOnClick
public void onButtonClick(View v) {
    int id = v.getId();
    Intent in = null;
    if (id == R.id.normal) {
       // Set the custom event ID to "ekv_normal" for the Button control with the Resource ID normal.
       // After this is set, when this control is clicked, the event ID in the data reported by the SDK is "ekv_normal".
       QtTrackAgent.setViewEventID(v, "ekv_normal");
       //...
    }
}

8.3.5 Handling click events set by the onClick attribute

A click callback method that is configured using the `android:onClick` attribute in a layout file does not automatically trigger a control click event when the method is executed. In this case, you can add the `@QtDataTrackViewOnClick` annotation to the method that corresponds to the `android:onClick` attribute. This allows the SDK to automatically trigger the control click event when the method is executed. For example:

Layout file:

<Button
    android:id="@+id/normal"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_marginTop="24dp"
    android:onClick="onButtonClick"
    android:text="@string/ana_name"/>

Custom onClick event handler function:

import com.quick.qt.analytics.autotrack.QtDataTrackViewOnClick;

@QtDataTrackViewOnClick
public void onButtonClick(View v) {
    //...
}

8.3.6 Ignoring automatic collection of click events for specific types of controls

You can call the ignoreViewType() method to ignore the autotracking of click events on specific types of controls.

/**
* Ignores the automatic collection of click events for controls of a specific type.
* You can call this method multiple times to add more control types to the ignore list.
* @param viewType The class of the control type to ignore.
*/
public static void ignoreViewType(Class viewType);

Example:

import com.quick.qt.analytics.QtTrackAgent;

// Ignore click events for Button controls.
QtTrackAgent.ignoreViewType(Button.class);

8.3.7 Ignoring automatic collection of specific control click events

You can use the ignoreView() method to ignore the automatic collection of click events for specific controls.

/**
* Ignores the automatic tracking of click events for a specific View object.
*
* @param view The View object.
*/
public static void ignoreView(View view);

Sample code:

import com.quick.qt.analytics.QtTrackAgent;

Button myButton = (Button)findViewById(R.id.testButton);
// Ignore the myButton click event.
QtTrackAgent.ignoreView(myButton);

8.4 Impression Instrumentation

To use the automatic impression instrumentation feature, you must manually enable the automatic impression feature in the configuration item.

import com.quick.qt.analytics.QtTrackAgent;

// Enable exposure collection
QtTrackAgent.enableExposureCollection();

You can also disable the auto exposure feature.

// Disable exposure collection
QtTrackAgent.disableExposureCollection();

8.4.1 Exposing configuration items

import com.quick.qt.analytics.exposure.QTExposureConfig;
import com.quick.qt.analytics.QtTrackAgent;

// General exposure settings
QTExposureConfig config = new QTExposureConfig.Builder()
                .setMinDuration(300) // Minimum exposure duration (in milliseconds)
                .setMinVisibleRatio(0.5f) /// Minimum visible ratio
                .setRepeated(true) // Enable repeated exposures
                .setCallback(new QTExposureConfig.ExposureCallback() { // Exposure callback
                    @Override
                    public void onExposure(View view) {
                        Toast.makeText(mContext, "Exposure successful", Toast.LENGTH_SHORT).show();
                    }
                })
                .build();
        
QtTrackAgent.setExposureConfig(config);

QTExposureConfig is the property for impression configuration. Its parameters are described as follows:

8.4.2 Configure global exposure settings

You can call the QtTrackAgent.setExposureConfig(config) method to set global exposure properties. This method must be called before SDK initialization.

import com.quick.qt.analytics.exposure.QTExposureConfig;
import com.quick.qt.analytics.QtTrackAgent;

// General exposure settings
QTExposureConfig config = new QTExposureConfig.Builder()
                .setMinDuration(300) // Minimum exposure duration (in milliseconds)
                .setMinVisibleRatio(0.5f) /// Minimum visible ratio
                .setRepeated(true) // Specifies whether to report repeated exposures.
                .setCallback(new QTExposureConfig.ExposureCallback() { // Exposure callback
                    @Override
                    public void onExposure(View view) {
                        Toast.makeText(mContext, "Exposure successful", Toast.LENGTH_SHORT).show();
                    }
                })
                .build();
        
QtTrackAgent.setExposureConfig(config);

8.4.3 Mark exposure elements

To use the impression feature, you need to manually attach the impression element by calling the `QtTrackAgent.addExposureView()` method.

import com.quick.qt.analytics.QtTrackAgent;

  /**
   * Marks an element for exposure tracking.
   *
   * @param view          The view object to track for exposure.
   * @param data          The object that contains the exposure data parameters.
   * @return              No return value.
   */
public static void addExposureView(View view, QTExposureData data) {
    QtTrackAgent.addExposureView(view, data);
}

Parameter descriptions:

QTExposureData API:

// Import the package.
import com.quick.qt.analytics.exposure.QTExposureData;

/**
 * Initializes the exposure data with the specified event name.
 *
 * @param event The name of the event.
 */
public QTExposureData(String event) 

/**
 * Initializes the exposure data with the specified event name and custom properties.
 *
 * @param event      The name of the event.
 * @param properties The custom event properties.
 */
public QTExposureData(String event, Map<String, Object> properties) 

/**
 * Initializes the exposure data with the specified event name, custom properties, and exposure configuration.
 *
 * @param event          The name of the event.
 * @param properties     The custom event properties.
 * @param exposureConfig The exposure configuration.
 */
public QTExposureData(String event,  Map<String, Object>  properties, QTExposureConfig exposureConfig) 

Parameter descriptions:

Note:

1. Property names and property values of the String type can only contain letters, numbers, and underscores.

2. A property value can be one of the following Java types: String, Long, Integer, Float, Double, or Short.

3. If a key matches an existing global property, its value is updated. Otherwise, a new global property is inserted.

   Example:

   import com.quick.qt.analytics.exposure.QTExposureData;
   
   Map<String, Object> properties = new HashMap<>();
   properties.put("param1", item.text); // Custom parameter 1
   properties.put("param2", position); // Custom parameter 2
   
   QTExposureData exposureData = new QTExposureData("Event encoding", properties))

Standard element mark

Example:

import com.quick.qt.analytics.exposure.QTExposureData;
import com.quick.qt.analytics.QtTrackAgent;

// Create the exposure data
QTExposureData exposureData = new QTExposureData("exposure_view_click");
QtTrackAgent.addExposureView(imageView, exposureData);

Marking list class elements

Mark all elements

import com.quick.qt.analytics.exposure.QTExposureConfig;
import com.quick.qt.analytics.exposure.QTExposureData;
import com.quick.qt.analytics.QtTrackAgent;

// Construct exposure data
public void onBindViewHolder(@NonNull ViewHolder holder, final int position) {
    View view = holder.xxxx; 
    Map<String, Object> properties = new HashMap<>();
    properties.put("param1", item.text); // Custom parameter 1
    properties.put("param2", position); // Custom parameter 2
    QtTrackAgent.addExposureView(convertView, new QTExposureData(item.text, properties));
}

Marking a single element:

import com.quick.qt.analytics.exposure.QTExposureConfig;
import com.quick.qt.analytics.exposure.QTExposureData;
import com.quick.qt.analytics.QtTrackAgent;

// Construct exposure data.
public void onBindViewHolder(@NonNull ViewHolder holder, final int position) {
     View view = holder.xxxx; 
     if(item.text.contains("New")){
          Map<String, Object> properties = new HashMap<>();
          properties.put("$$item_reused_id","custom_id"); // Mark the element with a custom ID to avoid duplicates.
          properties.put("text", item.text); // Custom parameter 1.
          properties.put("position", position); // Custom parameter 1.
          QtTrackAgent.addExposureView(convertView, new QTExposureData(item.text, properties));
     }
}

8.4.4 Removing exposure elements

Removing an element also removes its corresponding instrumentation monitoring, such as when you delete a list.

You can use `QtTrackAgent.removeExposureView()` to remove elements that you do not want to track for impressions.

import com.quick.qt.analytics.QtTrackAgent;

/**
 * Initializes exposure data with the specified event name and custom properties.
 *
 * @param view        The annotated element.
 * @param item_reused_id Custom ID (pass the ID if a custom element ID exists).
 */
QtTrackAgent.removeExposureView(view,"custom_id");

9 Viral Sharing

Viral sharing is a key concept in growth hacking strategies, relying on social connections between users to spread information and promote new user acquisition.

After you integrate the SDK feature set for viral sharing, you can use the Quick Tracking platform to share trend models and measure the user acquisition effectiveness of marketing campaigns based on sharing and referral traffic metrics.

1. View performance metrics for top sharing users and at different referral levels.

2. You can flexibly configure combinations of referral metrics. You can also view top users with the strongest capabilities for viral acquisition and referral conversion. You can track viral sharing paths and referral relationships to quickly locate Key Opinion Consumers (KOCs).

9.1 Obtaining source sharing parameters

import com.quick.qt.analytics.QtTrackAgent;
/**
 * API for retrieving referral share parameters.
 * @param context The ApplicationContext object of the host app. This parameter is required.
 * */
public static Map<String, String> getRefShareParams(Context context);

Version

Android SDK v1.6.0.PX or later

Features

This API is used to retrieve the source share ID and source share URL before you request the share parameters.

Request parameters

Return Parameters

Call Example

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.analytics.share.ShareResultHandler;

public class DemoActivity {
    ...
    public void onShare() {
        Context context = DemoActivity.this;
        Map<String, String> refShareParams = QtTrackAgent.getRefShareParams(context);
        String $$_ref_share_id = refShareParams.get("$$_ref_share_id");
        
        Map<String, String> shareParams = new HashMap<String, String>();
        shareParams.put("shareId", $$_ref_share_id);
        shareParams.put("title", "Share Campaign A");
        shareParams.put("campaign", "Share Campaign A");
        QtTrackAgent.requestShareParams(context, "https://www.taobao.com/productId", shareParams, 0, new ShareResultHandler() {
            @Override
            public void onShareResultSuccess(final JSONObject result) {
                try {
                    Log.i("Test", "shareParams = " + result.toString());
                    String $sid = result.getString("shareId");
                    Map<String, Object> properties = new HashMap<String, Object>();
                    properties.put("$$_share_id", $sid);
                    properties.put("$$_share_url", "https://www.taobao.com/productId"); 
                    properties.put("$$_share_title","Share Campaign A"); 
                    properties.put("$$_share_campaign_id", "This is a custom share campaign");
                      // 
                    properties.put("$$_share_type", "User-defined share destination platform");
                    QtTrackAgent.onEventObject(this, "$$_share", properties);
                    // Assume that this is an operation in a background thread.
                    new Thread(new Runnable() {
                        @Override
                        public void run() {
                            // Execute some background tasks...

                            // Switch back to the main thread to update the UI.
                            runOnUiThread(new Runnable() {
                                @Override
                                public void run() {
                                    // Display a dialog box on the main thread.
                                    AlertDialog.Builder builder = new AlertDialog.Builder(context);
                                    builder.setTitle("Share Parameters");
                                    builder.setMessage(result.toString());
                                    builder.show();
                                }
                            });
                        }
                    }).start();
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }

            @Override
            public void onShareResultFail(Throwable t) {
                Log.i("Test", "fail = " + t.getMessage());
            }
        });
    }
    ...
}

9.2 Share request parameters

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.analytics.share.ShareResultHandler;

/**
 * API for retrieving share parameters.
 * @param context The ApplicationContext object of the host app. This parameter is required.
 * @param url The URL of the page. This parameter is required.
 * @param params The parameters for sharing. This parameter can be null.
 *    {
 *      title: The title for sharing. Can be null. Maximum length: 4*1024.
 *    campaign: The sharing campaign. Can be null. Maximum length: 4*1024.
 *    shareId: The source share ID. Can be null.
 *      ... More parameters may be added.
 *  }
 * @param timeout The request timeout period in seconds. The valid range is 0 to 10, inclusive. If you pass 0, the default SDK value of 3 seconds is used.
 * @param callback The result callback object. This parameter is required and cannot be null.
 * */
public static void requestShareParams(Context context, String url, Map<String, String> params, int timeout,final ShareResultHandler callback)

Version

Android SDK v1.6.0.PX or later

Features

This API requests the share ID required to create a share link.

Request parameters

The ShareResultHandler callback interface is defined as follows:

public interface ShareResultHandler {
    // This method is called back when the share operation is successful.
    void onShareResultSuccess(JSONObject result);
    // This method is called back when the share operation fails. You can obtain the failure reason by calling t.getMessage().
    void onShareResultFail(Throwable t);
}

Return Parameters

Invocation Example

import com.quick.qt.analytics.QtTrackAgent;
import com.quick.qt.analytics.share.ShareResultHandler;

public class DemoActivity {
    ...
    public void onShare() {
        Context context = DemoActivity.this;
        Map<String, String> shareParams = new HashMap<String, String>();
        shareParams.put("shareId", "");
        shareParams.put("title", "Share Campaign A");
        shareParams.put("campaign", "Share Campaign A");
        QtTrackAgent.requestShareParams(context, "https://www.taobao.com/productId", shareParams, 0, new ShareResultHandler() {
            @Override
            public void onShareResultSuccess(final JSONObject result) {
                try {
                    Log.i("Test", "shareParams = " + result.toString());
                    String $sid = result.getString("shareId");

                    Map<String, Object> properties = new HashMap<String, Object>();
                    properties.put("$$_share_id", $sid);
                    properties.put("$$_share_url", "https://www.taobao.com/productId"); 
                    properties.put("$$_share_title","Share Campaign A"); 
                    properties.put("$$_share_campaign_id", "This is a custom sharing campaign");
                    properties.put("$$_share_type", "User-defined sharing platform");
                    QtTrackAgent.onEventObject(this, "$$_share", properties);
                    
                    // Assume that this is an operation in a background thread.
                    new Thread(new Runnable() {
                        @Override
                        public void run() {
                            // Execute some background tasks...

                            // To update the UI, switch back to the main thread.
                            runOnUiThread(new Runnable() {
                                @Override
                                public void run() {
                                    // Display a dialog box on the main thread.
                                    AlertDialog.Builder builder = new AlertDialog.Builder(context);
                                    builder.setTitle("Share Parameters");
                                    builder.setMessage(result.toString());
                                    builder.show();
                                }
                            });
                        }
                    }).start();
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }

            @Override
            public void onShareResultFail(Throwable t) {
                Log.i("Test", "fail = " + t.getMessage());
            }
        });
    }
}

9.3 Reporting share events

You can use the preset event code $$_share to report a share event.

Example

import com.quick.qt.analytics.QtTrackAgent;

Map<String, Object> properties = new HashMap<String, Object>();
properties.put("$$_share_id", "The share ID obtained by calling the share parameter API");
properties.put("$$_share_url", "https://www.taobao.com/productId"); 
properties.put("$$_share_title","Share Campaign A"); 
properties.put("$$_share_campaign_id", "This is a custom share campaign");
properties.put("$$_share_type", "User-defined sharing platform");
QtTrackAgent.onEventObject(this, "$$_share", properties);

Note: The link that is opened must include a parameter where the key is `$sid` and the value is the share ID. For example: `https://example.aliyun.com/path/to/content?$sid=123456`