DocsICP FilingConsole
官方文档
首页

Application Performance Monitoring Android SDK integration

更新时间：
复制 MD 格式
产品详情
我的收藏

Prerequisites

This topic describes how to integrate the Application Performance Monitoring (APM) Android SDK. It covers two methods: Maven dependency (recommended) and local dependency.

  • You have an Android Studio project that uses Gradle to manage dependencies.

  • Your application must support Android 5.0 (API level 21) or higher.

  • You have created a project and an application. For more information, see Create a project and an application.

  • Refer to the Android SDK Release Notes for the latest version.

  • If you have integrated a version of the crash analysis, performance analysis, or remote log SDK earlier than 2.0.0, follow the Android SDK Upgrade Guide to upgrade to the APM SDK.

  • For network monitoring, the SDK supports OkHttp versions from 3.0.0 to 5.3.2, and HttpURLConnection (support added in SDK version 2.8.0).

Reference demo

For a sample integration project, see the APM Android Demo project.

Add the SDK to your application

We provide two integration methods: Maven dependency and local dependency. You can choose the method that best suits your needs.

Note

We recommend using the Maven dependency method, as it is easy to configure, less error-prone, and simplifies future updates.

Maven dependency (recommended)

1.1 Configure the Maven repository

The following sections describe how to configure the repository using the recommended dependencyResolutionManagement block for Gradle 7.0 and later, and the allprojects block for versions earlier than Gradle 7.0.

1.1.1 Using dependencyResolutionManagement

In your root-level (project-level) Gradle file (<project>/settings.gradle), add the Maven repository URL to the repositories block within dependencyResolutionManagement.

pluginManagement {
  repositories {
    // Alibaba Cloud repository. You must add the plugin repository here.
    maven {
      url 'https://maven.aliyun.com/nexus/content/repositories/releases/'
    }
  }
}

dependencyResolutionManagement {
  repositories {
    maven {
      url 'https://maven.aliyun.com/nexus/content/repositories/releases/'
    }
  }
}
1.1.2 Using allprojects

In your root-level (project-level) Gradle file (<project>/build.gradle), add the Maven repository URL to the repositories block within allprojects.

buildscript {
    repositories {
        google()
        mavenCentral()
        // Alibaba Cloud Maven repository
        maven {
          url 'https://maven.aliyun.com/nexus/content/repositories/releases/'
        }
    }
    dependencies {
        // Required for network monitoring and automatic symbol file uploads.
        classpath 'com.aliyun.ams:alicloud-apm-plugin:{pluginVersion}'
    }
}

allprojects {
  repositories {
    maven {
      url 'https://maven.aliyun.com/nexus/content/repositories/releases/'
    }
  }
}
Important

For the latest plugin version, see Android Gradle Plugin version history.

1.2 Apply the plugin

In your module (app-level) Gradle file (usually <project>/<app-module>/build.gradle), apply the plugin in the plugins block.

1.2.1 Using dependencyResolutionManagement

If you added the plugin repository as described in 1.1.1 Using dependencyResolutionManagement, apply the plugin as follows:

plugins {
  // Required for network monitoring and automatic symbol file uploads.
  id 'com.aliyun.emas.apm' version '{pluginVersion}'
}
Important

For the latest plugin version, see Android Gradle Plugin version history.

1.2.2 Using allprojects

If you added the plugin repository as described in 1.1.2 Using allprojects, apply the plugin as follows:

plugins {
  // Required for network monitoring and automatic symbol file uploads.
  id 'com.aliyun.emas.apm'
}

1.3 Add the SDK dependency

In your module (app-level) Gradle file (usually <project>/<app-module>/build.gradle), add the SDK dependency to the dependencies block.

Full integration

This integrates all Application Performance Monitoring features.

dependencies {
  implementation ("com.aliyun.ams:alicloud-apm:{apmVersion}")
}

Partial integration

To integrate only the features you need, use the exclude directive to remove unwanted components.

dependencies {
    implementation ("com.aliyun.ams:alicloud-apm:{apmVersion}") {
        exclude group: 'com.aliyun.ams', module: 'alicloud-apm-performance'     // Exclude performance analysis
        exclude group: 'com.aliyun.ams', module: 'alicloud-android-tlog'        // Exclude remote log (for versions before 2.6.0)
        exclude group: 'com.aliyun.ams', module: 'alicloud-apm-remote-log'      // Exclude remote log (for versions 2.6.0 and later)
        exclude group: 'com.aliyun.ams', module: 'alicloud-apm-crash-analysis'  // Exclude crash analysis
        exclude group: 'com.aliyun.ams', module: 'alicloud-apm-mem-monitor'     // Exclude memory analysis
    }
}
Important

  • Get the latest apmVersion from the Android SDK Release Notes.

  • Use a fixed version number for the dependency instead of dynamic versions like 1.+ or 1.0.+.

1.4 Enable AndroidX

To use the APM SDK, you must enable AndroidX in your project to avoid build failures. Add the following configuration to your <project>/gradle.properties file:

android.useAndroidX=true
android.enableJetifier=true

Local dependency

2.1 Download the SDK

From your project's page in the console, click Integrate SDK to go to the SDK List page.

On the SDK List page, select the Android platform and the Application Performance Monitoring service. Click Integration Documentation. On the resulting page, scroll to the bottom and click Download SDK.

Copy all files from the SDK package to the <project>/<app-module>/libs directory of your application module.

image

2.2 Add SDK dependencies

2.2.1 Configure the local SDK directory

In your module (app-level) Gradle file (usually <project>/<app-module>/build.gradle), add your local libs directory as a repository.

repositories {
  flatDir {
    dirs 'libs'
  }
}
2.2.2 Add SDK dependencies

In the dependencies block of your module (app-level) Gradle file (usually <project>/<app-module>/build.gradle), add the SDK dependencies.

dependencies {
  # Common SDKs
  implementation (name:'alicloud-android-ha-adapter-1.2.5.0-open', ext: 'aar')
  implementation (name:'alicloud-apm-2.0.0', ext: 'aar')
  implementation (name:'alicloud-apm-common-1.2.0', ext: 'aar')
  implementation (name:'alicloud-apm-components-1.1.0', ext: 'aar')
  implementation (name:'play-services-basement-18.3.0', ext: 'aar')
  implementation (name:'play-services-tasks-18.1.0', ext: 'aar')
  implementation (name:'alicloud-android-utdid-2.6.0', ext: 'jar')
  implementation (name:'alicloud-apm-annotations-1.0.0', ext: 'jar')
  implementation (name:'fastjson-1.1.73.android', ext: 'jar')
  implementation (name:'javax.inject-1', ext: 'jar')
  # Crash analysis SDK
  implementation (name:'alicloud-apm-crash-analysis-3.2.0', ext: 'aar')
  implementation (name:'alicloud-apm-crash-analysis-ndk-1.1.0', ext: 'aar')
  implementation (name:'firebase-encoders-json-18.0.0', ext: 'aar')
  implementation (name:'firebase-encoders-17.0.0', ext: 'jar')
  # Performance analysis SDK
  implementation (name:'alicloud-android-apm-1.1.6.0-open', ext: 'aar')
  implementation (name:'alicloud-apm-performance-2.0.0', ext: 'aar')
  # Remote log SDK
  implementation (name:'alicloud-android-tlog-1.1.8.0-open', ext: 'aar')
  implementation (name:'alicloud-apm-remote-log-2.0.0', ext: 'aar')
  implementation (name:'oss-android-sdk-2.9.15', ext: 'aar')
  implementation (name:'okhttp-3.11.0', ext: 'jar')
  implementation (name:'okio-1.14.0', ext: 'jar')
}
Important

  • Ensure the SDK version numbers in your build script match the filenames of the downloaded artifacts.

  • If you encounter a class conflict error, check whether the dependencies block already contains implementation fileTree(dir: 'libs', include: ['*.jar']).

  • In addition to the SDKs listed above, you must manually download the following AndroidX SDKs:

    • androidx.collection:collection:1.1.0

    • androidx.core:core:1.3.0

    • androidx.fragment:fragment:1.1.0

    • androidx.annotation:annotation:1.3.0

    • androidx.concurrent:concurrent-futures:1.1.0

    • com.google.guava:listenablefuture:1.0

2.3 Enable AndroidX

To use the APM SDK, you must enable AndroidX in your project to avoid build failures. Add the following configuration to your <project>/gradle.properties file:

android.useAndroidX=true
android.enableJetifier=true

Configure and use the SDK

1. Configure the APM SDK

Configuring the APM SDK only prepares it for initialization and does not start any monitoring. You should perform this configuration as early as possible in your application's lifecycle, such as in the Application.onCreate() method. You can perform this step before the user accepts your privacy policy.

import com.aliyun.emas.apm.Apm
import com.aliyun.emas.apm.ApmOptions
import com.aliyun.emas.apm.crash.ApmCrashAnalysisComponent
import com.aliyun.emas.apm.mem.monitor.ApmMemMonitorComponent
import com.aliyun.emas.apm.performance.ApmPerformanceComponent
import com.aliyun.emas.apm.remote.log.ApmRemoteLogComponent

Apm.preStart(ApmOptions.Builder() 
        // Required: Your application instance.
        .setApplication(application) 
        // Required: Your appKey from Enterprise Mobile Application Studio (EMAS).
        .setAppKey(APP_KEY) 
        // Required: Your appSecret from EMAS.
        .setAppSecret(APP_SECRET) 
        // Required if you use performance analysis or remote log. Your appRsaSecret from EMAS.
        .setAppRsaSecret(RSA_PUBLIC_KEY)
        // Enable the crash analysis feature.
        .addComponent(ApmCrashAnalysisComponent::class.java)
        // Enable the memory analysis feature.
        .addComponent(ApmMemMonitorComponent::class.java)
        // Enable the remote log feature.
        .addComponent(ApmRemoteLogComponent::class.java)
        // Enable the performance analysis feature.
        .addComponent(ApmPerformanceComponent::class.java)
        .build()
)
import com.aliyun.emas.apm.Apm;
import com.aliyun.emas.apm.ApmOptions;
import com.aliyun.emas.apm.crash.ApmCrashAnalysisComponent;
import com.aliyun.emas.apm.mem.monitor.ApmMemMonitorComponent;
import com.aliyun.emas.apm.performance.ApmPerformanceComponent;
import com.aliyun.emas.apm.remote.log.ApmRemoteLogComponent;

Apm.preStart(new ApmOptions.Builder()
        // Required: Your application instance.
        .setApplication(application)  
        // Required: Your appKey from Enterprise Mobile Application Studio (EMAS).
        .setAppKey(APP_KEY)    
        // Required: Your appSecret from EMAS.
        .setAppSecret(APP_SECRET)
        // Required if you use performance analysis or remote log. Your appRsaSecret from EMAS.
        .setAppRsaSecret(RSA_PUBLIC_KEY)
        // Enable the crash analysis feature.
        .addComponent(ApmCrashAnalysisComponent.class)
        // Enable the memory analysis feature. Added in version 2.1.0.
        .addComponent(ApmMemMonitorComponent.class) 
        // Enable the remote log feature.
        .addComponent(ApmRemoteLogComponent.class)
        // Enable the performance analysis feature.
        .addComponent(ApmPerformanceComponent.class)
        .build()
);
Note

  • Calling Apm.preStart() only configures the SDK; it does not start data collection or initialize components.

  • To obtain your appKey and other parameters, see Obtain EMAS parameters.

For detailed API information, see Basic Configuration API.

2. Start APM

import com.aliyun.emas.apm.Apm

Apm.start()
import com.aliyun.emas.apm.Apm;

Apm.start();
Important

  • Starting APM initializes the features you configured. We recommend starting APM after the user has accepted your privacy policy.

  • You must call Apm.preStart() before Apm.start() to avoid an initialization failure.

For detailed API information, see Start APM.

3. Set user information (optional)

You can set user information to associate monitoring data with specific users.

Important

You must call these methods after calling the Apm.preStart(...) method.

import com.aliyun.emas.apm.Apm

// Set user ID
Apm.setUserId(userId)
// Set user nickname
Apm.setUserNick(userNick)
import com.aliyun.emas.apm.Apm;

// Set user ID
Apm.setUserId(userId);
// Set user nickname
Apm.setUserNick(userNick);

For detailed API information, see Start APM.

4. Set channel identifier (optional)

If your application has multiple distribution channels, you can set a channel identifier.

import com.aliyun.emas.apm.ApmOptions

ApmOptions.Builder()
    // Optional: Set the application channel.
    .setChannel(APP_CHANNEL)
    .build()
import com.aliyun.emas.apm.ApmOptions;

new ApmOptions.Builder()
        // Optional: Set the application channel.
        .setChannel(APP_CHANNEL)
        .build()

For detailed API information, see setChannel.

5. Obfuscation configuration

If your project uses code obfuscation, add the following rules to your ProGuard configuration file.

# Obfuscation configuration for Application Performance Monitoring
-keep class com.aliyun.emas.apm.**{*;}
-keep class com.alibaba.sdk.android.networkmonitor.**{*;}

Verify the integration

1. Enable SDK logging

Based on 1. Configure the Mobile Monitoring SDK, add openDebug(true).

import com.aliyun.emas.apm.Apm
import com.aliyun.emas.apm.ApmOptions
import com.aliyun.emas.apm.crash.ApmCrashAnalysisComponent
import com.aliyun.emas.apm.mem.monitor.ApmMemMonitorComponent
import com.aliyun.emas.apm.performance.ApmPerformanceComponent
import com.aliyun.emas.apm.remote.log.ApmRemoteLogComponent

Apm.preStart(ApmOptions.Builder() 
        // Required: Your application instance.
        .setApplication(application) 
        // Required: Your appKey from EMAS.
        .setAppKey(APP_KEY) 
        // Required: Your appSecret from EMAS.
        .setAppSecret(APP_SECRET) 
        // Required if you use performance analysis or remote log. Your appRsaSecret from EMAS.
        .setAppRsaSecret(RSA_PUBLIC_KEY)
        // Enable the crash analysis feature.
        .addComponent(ApmCrashAnalysisComponent::class.java)
        // Enable the memory analysis feature.
        .addComponent(ApmMemMonitorComponent::class.java)
        // Enable the remote log feature.
        .addComponent(ApmRemoteLogComponent::class.java)
        // Enable the performance analysis feature.
        .addComponent(ApmPerformanceComponent::class.java)
        // Disabled by default. We recommend keeping this disabled in release builds.
        .openDebug(true)
        .build()
)

import com.aliyun.emas.apm.Apm;
import com.aliyun.emas.apm.ApmOptions;
import com.aliyun.emas.apm.crash.ApmCrashAnalysisComponent;
import com.aliyun.emas.apm.mem.monitor.ApmMemMonitorComponent;
import com.aliyun.emas.apm.performance.ApmPerformanceComponent;
import com.aliyun.emas.apm.remote.log.ApmRemoteLogComponent;

Apm.preStart(new ApmOptions.Builder()
        // Required: Your application instance.
        .setApplication(application)  
        // Required: Your appKey from EMAS.
        .setAppKey(APP_KEY)    
        // Required: Your appSecret from EMAS.
        .setAppSecret(APP_SECRET)
        // Required if you use performance analysis or remote log. Your appRsaSecret from EMAS.
        .setAppRsaSecret(RSA_PUBLIC_KEY)
        // Enable the crash analysis feature.
        .addComponent(ApmCrashAnalysisComponent.class)
        // Enable the memory analysis feature. Added in version 2.1.0.
        .addComponent(ApmMemMonitorComponent.class) 
        // Enable the remote log feature.
        .addComponent(ApmRemoteLogComponent.class)
        // Enable the performance analysis feature.
        .addComponent(ApmPerformanceComponent.class)
        // Disabled by default. We recommend keeping this disabled in release builds.
        .openDebug(true)
        .build()
);

2. Verify crash analysis integration

Filter Logcat for the tag Apm-CrashAnalysis and check the logs. The following are key log entries:

 # Start initializing crash analysis
 I  Initializing Apm Crash Analysis 1.0.0 for com.alibaba.emas.android.apm.app
 # Successfully initialized crash analysis
 I  Initializing CrashAnalysis blocked main for 20 ms

3. Verify remote log integration

Filter Logcat for the tag Apm-RemoteLog and check the logs. The following is a key log entry:

 I  Initializing RemoteLog blocked main for 1 ms

4. Verify performance analysis integration

Filter Logcat for the tag Apm-Performance and check the logs. The following is a key log entry:

 I  Initializing Performance blocked main for 1 ms

5. Verify memory analysis integration

Filter Logcat for the tag Apm-MemMonitor and check the logs. The following is a key log entry:

 I  Initializing MemMonitor blocked main for 1 ms

6. Verify network monitoring integration

Filter Logcat for the tag Apm-NetworkMonitor and check the logs. The following is a key log entry:

 I  Initializing Network monitor blocked main for 2 ms

Further reading

Previous：Android SDK release notesNext：Android SDK feature verification