Android SDK Access

Prerequisites

• Before using the SDK, you need to register a HUAWEI ID and create an Android app on the App Monitoring page.

Transport Protocol

HTTPS

Version Updates

• For details about how the SDK processes personal information, see Privacy Statement of APM Data Collection SDKs.
• You must meet personal information protection requirements when integrating and using the SDK. For details, see Developer Compliance Guide for APM Data Collection SDKs.

Procedure

1. Integrate the access SDK.
   1. Method 1: Integrate the SDK from the Maven repository.
      • Add dependencies to build.gradle.

        buildscript {
            dependencies {
                ...
                classpath 'io.github.apm-sdk:apm-sdk-plugin:2.0.16'
                ...
            }
        }
        plugins {
            ...
            id 'org.jetbrains.kotlin.android' version 'KOTLIN_VERSION' apply false  // Add kotlin 1.6.20 or later.
            ...
        }

      • Add dependencies to app/build.gradle.

        plugins {
            ...
            id 'org.jetbrains.kotlin.android'
            id 'kotlin-kapt'
            id 'com.cloud.apm.plugin'  // Add dependency plug-ins.
            ...
        }
        dependencies {
            ...
            implementation 'io.github.apm-sdk:apm-sdk-android:2.0.16' // Add APM SDK dependencies.
            ...
        }

      • Add the Maven repository to settings.gradle.

        pluginManagement{
            ...
            repositories {
                ...
                // Add the following content:
                mavenCentral()
           }
        }
        dependencyResolutionManagement {
            ...
            repositories {
                ...
                // Add the following content:
                mavenCentral()
           }
        }

   2. Method 2: Manual integration
      • Download the SDK and plug-in packages.
      • Add the .jar plug-in package to your project.
      • Add dependencies to build.gradle.

        buildscript {
            dependencies {
                classpath fileTree(dir: $dir, include: '*.jar') // Enter the folder where the .jar package is located, for example, libs.
            }
        }

      • Add the .aar SDK package to your project.
      • Add dependencies to app/build.gradle.

        dependencies {
            ...
            implementation fileTree(dir: $dir, include: ['*.aar']) // Enter the folder where the .aar package is located, for example, libs.
            implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.0'
            implementation 'androidx.core:core-ktx:1.6.0'
            implementation 'com.google.code.gson:gson:2.8.9'
            kapt 'androidx.room:room-compiler:2.4.0'
            api 'androidx.room:room-runtime:2.4.0'
            api 'androidx.room:room-common:2.4.0'
            ...
        }

      • Add the Maven repository to settings.gradle.

        pluginManagement{
            ...
            repositories {
                ...
                // Add the following content:
                google()
                mavenCentral()
           }
        }
        dependencyResolutionManagement {
            ...
            repositories {
                ...
                // Add the following content:
                google()
                mavenCentral()
           }
        }

        If your Gradle version is earlier than 7.0, add the Maven repository to the build.gradle file.

2. Add a configuration file.

   Add the Android app on the console, download the apm-sdk-config.json configuration file, and drag it to the root directory of the app, as shown in the following figure.

   

   Table 2 Configuration parameters

   Parameter	Mandatory	Default Value	Description
   appId	Yes	-	Mobile app ID.
   authorization	Yes	-	Used for app authentication.
   region	Yes	-	Region where APM is deployed. Currently, cn-north-4 is supported.
   uid	No	-	Custom ID.
   tag	No	-	Custom tag. Use commas (,) to separate multiple tags.
   url	No	-	Public domain name for reporting data to APM.
   networkWhiteList	No	-	Network monitoring whitelist.
   cacheThreshold	No	200	When the number of logs stored in the local database reaches this threshold, an alarm is reported. Value range: 30 to 1,000.
   timeInterval	No	60s	Interval for triggering reporting. Value range: 60 to 1,800, in seconds.
   reportBackground	No	true	Whether to report logs upon app backend switching.
   reportLaunch	No	false	Whether to report logs upon app startups. To enable this function, start the SDK in the onCreate method of the application.
   enableNetwork	No	false	Whether to enable network collection.
   enableCrash	No	false	Whether to enable crash collection.
   enableLaunch	No	false	Whether to enable startup collection.
   enableANR	No	false	Whether to enable ANR collection.
   enableError	No	false	Whether to enable error collection.
   enableDevice	No	false	Whether to enable device collection.
   enableEvent	No	false	Whether to enable custom statistics reporting.
   traceType	No	apm	Whether to enable open tracing. If this function is enabled, OpenTelemetry will be used. If this function is disabled, APM tracing will be used.
   logLevel	No	off	Debug log level. Options: debug, info, warn, error, and off.
   samplingRate	No	1.0	Sampling rate. Range: 0–1.0.

3. Start the SDK.
   • Kotlin code example

     import com.cloud.apm.APMSDK
      
     // Start the SDK based on the apm-sdk-config.json configuration file.
     APMSDK.start(this)
     
     // (Optional) Set a custom ID.
     APMSDK.setUid ("Custom ID")
     
     // (Optional) Set custom tags.
     APMSDK.addTag ("Custom tag 1, Custom tag 2, Custom tag 3")

   • Java code example:

     import com.cloud.apm.APMSDK
     
     // Start the SDK based on the apm-sdk-config.json configuration file.
     APMSDK.start(); 
     
     // (Optional) Set a custom ID.
     APMSDK.setUid ("Custom ID");  
     
     // (Optional) Set custom tags.
     APMSDK.addTag ("Custom tag 1, Custom tag 2, Custom tag 3");

4. (Optional) Configure custom statistics reporting.

   Method	Description
   fun <T> event(key: String, event: HashMap<String, T>); fun <T> event(key: String, event: Array<T>) fun event(key: String, event: Number) fun event(key: String, event: String)	key: event name (string). Max.: 2,048 characters. value: event content. Valid JSON objects such as String, Array, HashMap, and Number are supported. Max.: 30,720 characters.

   Kotlin code example

   // Example of event statistics
   APMSDK.event("User Information", hashMapOf(Pair("name","zhang san"))
   APMSDK.event("Call Stack", listOf("0x0000000101ee9c6c","0x0000600000e61d80").toTypedArray())
   APMSDK.event("Error Description", "The request timed out.")
   
   // Example of numeric statistics
   APMSDK.event("Purchase Statistic", 1653)
   APMSDK.event("Custom Load Time", 1.653)

   Java code example:

   // Example of event statistics
   HashMap<String, String> user = new HashMap(){{
       put("name","zhang san");
   }};
   APMSDK.event("User Information", user);
   String[] stacks = {"0x0000000101ee9c6c", "0x0000600000e61d80"};
   APMSDK.event("Call Stack", stacks);
   APMSDK.event("Error Description", "The request timed out.");
   
   // Example of numeric statistics
   APMSDK.event("Purchase Statistic", 1653);
   APMSDK.event("Custom Load Time", 1.653);

Data Reporting Policy

The SDK supports the following log reporting policies: threshold-based reporting, scheduled reporting, reporting when the app is switched to the backend, and reporting upon startup. Set parameters such as cacheThreshold, timeInterval, reportBackground, and reportLaunch based on the scenario.

Obfuscation Configuration

To achieve code obfuscation, add the following code segment to the obfuscation configuration file:

-keep class com.cloud.apm.**{*;} 
# If Gradle 8.x is used, use the following configuration:
-keep classeswithmembers class okhttp3.**{*;} # Use okhttp3&okhttp4.
-dontwarn okhttp3.** # okhttp3&okhttp4 is not used.
-keep classeswithmembers class com.squareup.okhttp.**{*;} # Use okhttp2.
-dontwarn com.squareup.okhttp.** # okhttp2 is not used.

Setting Permissions

The APMSDK requires the network and network status permissions. The permissions have been configured in the Manifest.xml file of the SDK.

Enabling Log Debugging

Enable debugging if needed. Then you can monitor SDK running in real time based on logs, and make adjustments accordingly. The debug level can be debug, info, warn, error, or off (disabled).

Example: Set the debug level in the apm-sdk-config.json configuration file.