tencent cloud

Feedback

Integration and Initialization

Last updated: 2024-05-24 11:54:32

    Overview

    This document guides you through integrating and initializing with the Android SDK.

    Directions

    Step 1: Configure Gradle integration.

    1. Add the Maven repository source in settings.gradle.
    
    
    
    Reference code:
    pluginManagement {
    ...
    repositories {
    ...
    // Add the following content.
    maven { url 'https://qapm-maven.pkg.coding.net/repository/qapm_sdk/android_release/' }
    }
    }
    dependencyResolutionManagement {
    ...
    repositories {
    ...
    // Add the following content.
    maven { url 'https://qapm-maven.pkg.coding.net/repository/qapm_sdk/android_release/' }
    }
    }
    Note:
    If your Gradle version is below 7.0, please add the Maven repository source in the project's build.gradle as shown below:
    
    
    
    2. Add dependencies for the plugin in the project's build.gradle file.
    
    
    Reference code:
    buildscript {
    ...
    dependencies {
    ...
    // Add the following content
    classpath 'com.tencent.qapmplugin:qapm-plugin:3.1'
    ...
    }
    }
    Note:
    If your Gradle version is below 7.4, change the plugin version to 2.39.
    3. Add the following code to the app's build.gradle file:
    
    
    
    Reference code:
    plugins {
    ...
    id('qapm-plugin') // Add the plugin.
    ...
    }
    ...
    preBuild.dependsOn(UUIDGenerator) // Generate a unique identifier for subsequent stack translation.
    ...
    dependencies {
    ...
    // Add qapmsdk dependency.
    implementation 'com.tencent.qapm:qapmsdk:5.4.6-pub'
    ...
    }
    4. Please check if this step needs to be performed by the following content.
    In the class where the Application is located, enter attachBaseContext to check if there is an override method. If there is an override method, ignore this step. If not, please proceed to Next.
    
    
    
    Add the package path of the Application to the following configuration.
    Reference code:
    QAPMPluginConfig {
    // Optional, defaults to empty. In the class where Application is located, enter attachBaseContext to see if there is an override method. If there is no override method, this item needs to be configured. The following figure shows that this check is not necessary.
    // tinkerApplication = 'com/tencent/qapm/demoApplication'
    }
    5. At this point, you can try to compile. Compilation-related FAQ can be referred to for this step.
    Q1: If an error stating "feature is disabled" occurs during compilation, see below:
    
    
    
    A1: The plugin needs to dynamically insert properties into BuildConfig. Please add the following code under the app module's build.gradle file.
    
    
    
    Reference code:
    android {
    ...
    // Add the following content.
    buildFeatures {
    ...
    buildConfig true
    }
    ...
    }
    Q2: If a "Class Conflict" error occurs during compilation, as follows:
    
    
    
    A2: Qapm and your project use different Android support libraries. Please remove the qapm's android.support library when adding dependencies, as follows:
    
    
    
    Reference code:
    dependencies {
    ...
    implementation ('com.tencent.qapm:qapmsdk:5.4.6-pub') {
    // Add the following content.
    exclude group: 'com.android.support'
    }
    ...
    }
    Note:
    If the qapm-plugin plugin is not used, it will affect the monitoring of the startup and network.

    Step 2: Configure parameters.

    1. Add the following permissions in AndroidManifest.xml.
    <!--Required for information reporting-->
    <uses-permission android:name="android.permission.INTERNET" />
    <!--Required for information collection-->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    2. To avoid confusion with the SDK, add the following configuration in the app's proguard-rules.pro file:
    -keep class com.tencent.qapmsdk.**{*;}
    # If network monitoring is needed, ensure okhttp3 is not obfuscated.
    -keep class okhttp3.**{*;}

    Step 3: Initialize the SDK.

    1. Log in to TCOP console, navigate to the Mobile App Performance Monitoring page, select Application Management > Application Settings, and then obtain the Appkey (reporting ID).
    
    
    
    2. Copy the code below and modify some of the fields. The following items are mandatory interface settings; for additional interface configurations, refer to the initialization interface analysis (Initializing QAPM in Application is recommended).
    // Set the mobile phone model and device ID.
    // Device identifier required, in the form of any string. deviceId (mandatory).
    // The deviceId can be used to enable an allowlist, avoiding data sampling (Except crash and startup data, the sampling rate for other data is 0.1%).
    QAPM.setProperty(QAPM.PropertyKeyDeviceId, "Device identifier");
    // The mobile phone model is required (mandatory).
    QAPM.setProperty(QAPM.PropertyKeyModel, "Enter mobile phone model");
    
    // Set Application (mandatory).
    QAPM.setProperty(QAPM.PropertyKeyAppInstance, getApplication());
    // Set AppKey (mandatory, used to distinguish the reporting products. The value is obtained from the Product Configuration page under Mobile Performance Monitoring, refer to the previous step).
    QAPM.setProperty(QAPM.PropertyKeyAppId, "YourAppKey");
    // Set the product version, which is used for background retrieval field (mandatory).
    QAPM.setProperty(QAPM.PropertyKeyAppVersion, "YourApp Version");
    // Set the UUID to pull the obfuscated stack's mapping (mandatory. If QAPM Symbol Table Upload plugin is used, this variable can be used directly).
    // If the qapmplugin plugin is used, this variable will be generated at build time, and errors can be ignored. If not used, it needs to be manually input. Please ensure the use of UUID format and that one apk corresponds to only one uuid.
    QAPM.setProperty(QAPM.PropertyKeySymbolId, BuildConfig.QAPM_UUID);
    // Set the user ID, in the form of any string, which is used for background retrieval field (mandatory).
    // The userId can be used to enable an allowlist, avoiding data sampling (except for crash and start, the sampling rate for other data is 0.1%).
    QAPM.setProperty(QAPM.PropertyKeyUserId, "123456");
    // Set the Log level (optional). For the production environment version, set it to QAPM.LevelOff or QAPM.LevelWarn
    QAPM.setProperty(QAPM.PropertyKeyLogLevel, QAPM.LevelInfo);
    // Set the QAPM external network reporting domain (required). Chinese Mainland: https://app.rumt-zh.com; global regions (except Chinese Mainland): https://app.rumt-sg.com
    QAPM.setProperty(QAPM.PropertyKeyHost,"https://app.rumt-zh.com");
    QAPM.setProperty(QAPM.PropertyKeyHost,"https://app.rumt-sg.com");
    // Enable QAPM.
    QAPM.beginScene(QAPM.SCENE_ALL, QAPM.ModeStable);
    Note:
    The AppKey can be obtained from the Mobile App Performance Monitoring > Application Management > Application Settings page as in Step 3-Step 1.
    Crash and start data are reported in full, while other data is sampled due to its large volume, at a rate of 0.1% (one in a thousand). To report all data, an allowlist can be enabled, and the app will change the sampling rate at the next start.
    The preset userId or deviceId can be added to the allowlist through the Application Management page to enable the allowlist.
    Multiple processes need to initialize QAPM, separately.

    Step 4: Access verification.

    1. If the following log is printed, it indicates that the user has not been sampled, and the sampling rate needs to be reset:
    
    
    
    See TAG: QAPM_manager_QAPMLauncher
    2. If the following log is printed, it indicates that the initial access succeeded. You can verify data reporting and try to enable the advanced feature:
    
    
    
    See TAG: QAPM_manager_QAPMPluginManager

    Initialized Interface Analysis

    API Name
    Parameter
    Parameter Description
    Notes
    public static QAPM setProperty(int key, Stringvalue)
    Functionality: Set QAPM parameters.
    key
    Required. The Key that needs to be set.
    -
    QAPM.PropertyKeyLogLevel
    Optional. Enable log level. (It is recommended to use QAPM.LevelDebug for Debug versions and QAPM.LevelWarn for release versions).
    QAPM.PropertyNeedTranslate
    Optional. Whether stack translation is needed, which by default is required. If the apk is not obfuscated, then pass in 'false'. Otherwise the frontend may display everything as 'unTranslated'.
    public static boolean beginScene(String sceneName, int mode)
    Functionality: Enable monitoring.
    sceneName
    Required. Scene name.
    Use the OR operation to enable the performance module from Definition, such as enabling Crash and Anr: beginScene(“Crash&ANR”, QAPM.ModeCrash| QAPM.ModeANR)
    mode
    Required. The feature to be enabled.
    QAPM.ModeStable
    Optional. Enable all features (Recommended for external releases. Includes interval performance, crash, ANR, WebView page load, JsError, and network).
    QAPM.ModeWebView
    Optional. Enable WebView page load monitoring.
    QAPM.ModeJsError
    Optional. Enable WebView JS exception monitoring.
    QAPM.ModeHTTPInWeb
    Optional. Enable WebView network monitoring.
    QAPM.ModeHTTP
    Optional. Enable network monitoring.
    public static boolean endScene(String sceneName, long mode)
    Functionality: End monitoring (Only effective for frame drops and interval performance collection).
    sceneName
    Required. The name of the scene to be turned off (Required to correspond to the beginScene).
    -
    QAPM.ModeDropFrame
    Optional. Turn off frame drop monitoring.
    QAPM.ModeResource
    Optional. Turn off interval performance monitoring.

    Others

    Note:
    When compiling and packaging the app through the qapm plugin, the app needs a UUID as the Build ID. If there is a qapm.properties file in the project directory, and the value of the qapm_uuid property exists, this value will be used as the Build ID; otherwise, the plugin will randomly generate a Build ID.
    qapm-plugin Version 2.39 and earlier will report an IO Error during the app compiling process: java.io.FileNotFoundException, qapm.properties (No such file or directory).
    
    
    
    This error only occurs during compilation and does not affect the running of the app.
    
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support