Basic integration

1. Configure domain names

Before pre-initialization, call the QtConfigure.setCustomDomain() method to set the data collection domain name for your private environment. This call must precede any other SDK method calls.

/**
 * Sets the primary and standby domain names for uploading analytics logs. Call this method before the SDK pre-initialization or initialization methods.
 * The SDK first attempts to report statistical data to the primary domain. If the attempt fails, it retries by sending the data to the standby domain.
 * If primaryDomain is null or an empty string, the pre-initialization method throws an SdkDomainUndefined runtime exception.
 * @param standbyDomain If standbyDomain is null or empty, the SDK uses the primaryDomain as the standby, retrying the upload to it if the initial attempt fails.
 * The domain name parameters must include the "https://" prefix.
*/
public static void setCustomDomain(String primaryDomain, String standbyDomain)

Domain name method for the APM stability library:

public static void setCustomDomainCrash(String url)

Domain name method for the APM performance library:

public static void setCustomDomainEfs(String url)

Example:

public class MainApplication extends Application {
  
 @Override
 public void onCreate() {
 super.onCreate();

 // Enter your own data collection domain name
 QtConfigure.setCustomDomain("xxxxxx", null); 
 // Enter the data collection domain name for your APM performance library
 UMEfs.setCustomDomainEfs("xxxxxx");
 // Enter the data collection domain name for your APM stability library
 UMCrash.setCustomDomainCrash("xxxxxx");
 
 // Enable debug logs (disable them in the production environment)
 QtConfigure.setLogEnabled(true);
 QtConfigure.preInit(this,"YOUR_APPKEY","YOUR_CHANNEL");
 QtTrackAgent.disableActivityPageCollection();

If you use the same data collection domain name for both data analytics and performance monitoring, you only need to call QtConfigure.setCustomDomain().

2. Set a device ID (optional)

The APM SDK uses the device ID from the QTCommon SDK. APM strictly validates this ID. If you provide a custom device ID (for instructions, see 2.1 Device ID settings), it must meet these requirements:

• Length: 16 to 34 characters

• Type: Alphanumeric characters (case-sensitive)

3. Set a user ID (optional)

This is an optional feature that uses the same set of methods as the analytics module. After you set a user ID, the corresponding user account is displayed in the management console.

1. By default, users are tracked by device. To track users by their user account in your app, use the following methods:

public static void onProfileSignIn(String ID);
public static void onProfileSignIn(String Provider, String ID);

2. Call this method when a user signs out. After this call, the SDK stops sending account-related information.

public static void onProfileSignOff();

4. Compliant initialization

4.1 Initialization methods

Initialization enables analytics tracking. "Delayed initialization" is essentially a way to control when this tracking starts. To comply with regulatory requirements, your app must not collect any personal information until the user agrees to your privacy policy. Therefore, the initialization process involves two steps:

1. Pre-initialization

Call the pre-initialization method for the basic component library in the onCreate method of your host app's Application class.

// The SDK pre-initialization method does not collect device information or report data.
// The preInit method consumes minimal resources and does not affect the user experience during a cold start.
QtConfigure.preInit(this,"YOUR_APPKEY","Channel");

2. Official initialization

Initialize the SDK only after the user agrees to your privacy policy.

// Completes the SDK initialization. This call is required.
QtConfigure.init(this,"YOUR_APPKEY",QtConfigure.DEVICE_TYPE_PHONE, "");

4.2 Get an AppKey

Go to app management in the management console to find and copy the AppKey for your application.

5. Configure log printing

Use the QtConfigure.setLogEnabled(boolean) method to control log output.

Note:

• Before you release your app, disable the SDK's debug logs to prevent unnecessary log output.

Log switch

Use the following method to enable or disable the SDK's debug logs. By default, debug logging is disabled and must be enabled manually.

/**
* Toggles the log switch for the component.
* @param boolean The default value is false. Set it to true to view logs.
*/
QtConfigure.setLogEnabled(true);

Note:

• To view logs from the initialization process, you must enable the log switch before you call an initialization method.

Log level

• Logs are categorized into four levels for easier debugging:

• Error: Errors related to SDK integration or runtime.

• Warn: SDK warning messages.

• Info: Informative messages from the SDK.

• Debug: Detailed debugging information from the SDK.