Basic Integration

1 Path configuration

Check whether you are already using the Umeng+ SDK. If so, update the SDK file path as follows:

• If you have already integrated the Umeng+ SDK and now need to integrate the QT SDK: Add the following line before all code for both QT and Umeng+ (at least before setting the data collection domain): [QTConfigure resetStorePath]

• If you have already integrated the QT SDK and now need to integrate the Umeng+ SDK: Add the following line before all code for both QT and Umeng+ (at least before setting the data collection domain): [UMConfigure resetStorePath]

Note: If you reset the QT SDK path, the keys used to store user account, app version, and other feature information you explicitly set will change. If your business logic depends on these fields, reconfigure them. We strongly recommend configuring this during initial integration to avoid data loss.

2 Domain configuration

API:

/** Set the primary and alternative domain names for reporting statistical logs. Call this function before initializing the SDK.

 @param primaryDomain Primary domain for log collection. This parameter must not be null or an empty string. Example: https://www.xxx.com
 @param standbyDomain Alternative domain for log collection. This parameter can be null or an empty string. If empty, the SDK automatically uses the primary domain as the fallback.
*/
+ (void)setCustomDomain:(NSString *)primaryDomain standbyDomain:(NSString *)standbyDomain;

Parameters:

Tip

Call this method before the initialization method.

Example code:

[QTConfigure setCustomDomain:@"your_data_collection_domain" standbyDomain:nil];

3 Compliance initialization

3.1 Initialization API

1. Compliance notice

You must inform users that your app uses the Quick Tracking SDK. Add the following clause to your Privacy Policy:

“Our product integrates the Quick Tracking SDK. The Quick Tracking SDK collects your OAID/GAID/MAC/IMEI/Android ID/IDFA/IDFV/OPENUDID/GUID/SIM card IMSI/hardware serial number/MCC (Mobile Country Code) and MNC (Mobile Network Code) to provide statistical analysis services.”

2. Compliance initialization

Initialization enables statistical tracking. To comply with Chinese regulatory requirements after integrating the Quick Tracking SDK, ensure that you call the official initialization function only after the user has read your Privacy Policy and granted consent during the app’s first cold launch. Only then will the SDK collect device information and report data. If the user does not consent, do not call the initialization function.

/** Initialize all Quick Tracking components.
 @param appKey The AppKey you obtained from the Quick Tracking console.
 @param channel Channel identifier. Set to nil to indicate "App Store".
 */
+ (void)initWithAppkey:(NSString *)appKey channel:(NSString *)channel;

If you also use the Performance Experience SDK and need to set a separate data collection domain for it, use the following initialization method (supported in v1.5.6.PX and later):

/** Initialize all QT SDK components.
 @param appKey The AppKey you obtained from the Quick Tracking console.
 @param channel Channel identifier. Set to nil to indicate "App Store".
 @param pluginsTrackDomainIndepent Whether to independently configure the data collection domain for the Performance Experience SDK.
 */
+ (void)initWithAppkey:(NSString *)appKey channel:(NSString *)channel shouldPluginsTrackDomainIndepent:(BOOL)pluginsTrackDomainIndepent;

After obtaining user consent for the Privacy Policy, ensure the initialization function is called on every subsequent cold launch.

3.2 Obtain AppKey

The AppKey parameter is required during SDK initialization. AppKey is a unique identifier for your app in Quick Tracking, generated when you create the app. For instructions on how to obtain or view it, see Application Management.

4 Log printing

In iOS, the logging module is a separate plug-in. You must integrate it to use logging features.

4.1 Import the log plug-in

If you manually integrated the SDK, import the log plug-in package into your project.

1. Select the SDK component and download it. Unzip the .zip file to get the component package (for example: UMCommonLog.framework, UMCommonLog.bundle).

2. In Xcode, choose File → Add Files to "Your Project". In the dialog that appears, select the downloaded component package and click Add. (Note: Select “Copy items if needed.”)

4.2 Initialize the log plug-in

1. Description and purpose

2. API function

API:

+(void) setUpUMCommonLogManager;

Example code:

#import <UMCommonLog/UMCommonLogManager.h>
  
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    // Explicitly call this function to enable the logging system.
    [UMCommonLogManager setUpUMCommonLogManager];
}

4.3 Enable logging

Use the UMConfigure.h header file in QTCommon.framework to enable logging.

API:

/** Enable or disable SDK log output in the console.
 @param bFlag Default is NO (logs disabled). Set to YES to output debug logs. Always set to NO before publishing your app.
 */
+ (void)setLogEnabled:(BOOL)bFlag;

To view logs during SDK initialization, enable logging before calling the domain configuration and initialization APIs.

Example:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    // Explicitly call this function to enable the logging system.
    [UMCommonLogManager setUpUMCommonLogManager];
    [QTConfigure setLogEnabled:YES]; // Enable logging
    [QTConfigure setCustomDomain:@"your_data_collection_domain" standbyDomain:nil]; // Set domain
    [QTConfigure initWithAppkey:@"your_appkey" channel:@"App Store"];
    
     /**
     * To set a separate APM data collection domain, use the following initialization method:
     * [QTConfigure initWithAppkey:@"your_appkey" channel:@"App Store" shouldPluginsTrackDomainIndepent:YES]; // Supported in v1.5.6.PX and later
     */
}

Log format:

Example: If the AppKey passed by the user is empty, the log appears as shown below:

5 Custom data encryption

Custom encoding and decoding API:

The SDK does not implement your custom encryption algorithm. Instead, it provides the QTCryptoProviderDelegate protocol. You must implement the following two methods in your code.

@protocol QTCryptoProviderDelegate <NSObject>

- (NSData *)encode:(NSMutableDictionary<NSString *,NSString *> *)header input:(NSData *)input;

- (NSData *)decode:(NSDictionary<NSString *,NSString *> *)header input:(NSData *)input;

@end

Register the custom encoding and decoding delegate:

[QTConfigure registerCryptoProvider:self];

Example code:

#import <QTCommon/UMCommon.h>

@interface AppDelegate ()<QTCryptoProviderDelegate>

@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [QTConfigure setCustomDomain:@"your_data_collection_domain" standbyDomain:nil];
		[QTConfigure registerCryptoProvider:self];
    [QTConfigure initWithAppkey:@"your_appkey" channel:@"your_channel"];
    
	....
	
    return YES;
}

- (NSData *)encode:(NSMutableDictionary<NSString *,NSString *> *)header input:(NSData *)input{
    // Example
    [header setObject:@"value1" forKey:@"arg1"];
    [header setObject:@"value2" forKey:@"arg2"];
    return [self customEncode:input key:CryptoKey];
}

- (NSData *)decode:(NSDictionary<NSString *,NSString *> *)header input:(NSData *)input{
    // Example
    NSLog(@"decode header:%@",header);
    return [self customDecode:input key:CryptoKey];
}

// Custom encryption
- (NSData *)customEncode:(NSData *)data key:(NSString *)key
{
    // Implement custom encryption
}

// Custom decryption
- (NSData *)customDecode:(NSData *)data key:(NSString *)key
{
    // Implement custom decryption
}

6 Data collection toggle

The SDK enables data collection by default. You can control data collection timing using the enable/disable APIs. (Supported in v1.5.2.PX and later.)

6.1 Enable data collection

enableSDK

Example:

[QTConfigure enableSDK];

6.2 Disable data collection

disableSDK

Example:

[QTConfigure disableSDK];

Note:

1. Because privacy policy workflows are managed by your app, the SDK does not cache the enable/disable state. If you disable the SDK during a cold launch and want it disabled on all future cold launches, your app must explicitly call disableSDK each time.

2. After calling disableSDK, QT SDK does not generate a device ID. Since the APM SDK reads its device ID from QT SDK, set a custom device ID to ensure APM works correctly. For instructions, see 2.1 Device ID configuration.