如何集成移动监控Android SDK_移动研发平台(EMAS)-阿里云帮助中心

一、前提条件

本章节介绍移动监控Android SDK的接入方法，主要包含Maven依赖方式（推荐）和本地依赖方式。

推荐使用Gradle管理依赖的Android Studio项目。
支持Android 5.0-Android 16。
已创建项目和应用。具体操作请参见创建项目和应用。
已阅读Android SDK发布说明，获取最新版本。
如已接入2.0.0以下版本的崩溃分析、性能分析和远程日志一个或者多个SDK的应用，可以按照文档SDK升级指南完成移动监控SDK的升级工作。
网络监控，根据AGP版本提供了不同的apm gradle插件。
- 版本后缀是agp8，支持AGP8以上的版本，网络库支持okhttp 3.0.0-okhttp 5.1.0
- 版本后缀是agp3，支持[AGP3-AGP8)的版本，网络库支持okhttp 2.0.0-okhttp 5.1.0

二、将SDK添加到您的应用

我们提供了Maven依赖和本地依赖两种集成方式，方便您根据需要将SDK添加到您的应用中。

说明

建议开发者采用Maven依赖方式进行集成，配置简单，不容易出问题，后续更新方便。

1 Maven依赖方式（推荐）

1.1 配置Maven仓库

下面分别介绍Gradle 7.0及以上推荐的dependencyResolutionManagement配置方式和Gradle 7.0之下推荐的allprojects配置方式。

1.1.1 dependencyResolutionManagement方式

在您的根级（项目级）Gradle 文件（<project>/settings.gradle）中，在dependencyResolutionManagement的repositories中添加Maven仓库地址。

pluginManagement {
  repositories {
    //阿里云仓库，如果您使用了性能分析，需要在这里添加插件仓库
    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 allprojects方式

在您的根级（项目级）Gradle 文件（<project>/build.gradle）中，在allprojects的repositories中添加Maven仓库地址。

buildscript {
    repositories {
        google()
        mavenCentral()
        //阿里云maven仓库
        maven {
          url 'https://maven.aliyun.com/nexus/content/repositories/releases/'
        }
    }
    dependencies {
        //如果您使用了性能分析，需要添加这个插件，否则网络监控不能正常采集数据
        classpath 'com.aliyun.ams:alicloud-apm-plugin:2.4.0-agp8'
    }
}

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

重要

由于Google在AGP8调整了API，所以根据AGP版本提供了不同的apm gradle插件。

如果您项目的AGP版本不低于8.0，请使用后缀agp8，比如com.aliyun.ams:alicloud-apm-plugin:2.4.0-agp8
如果您项目的AGP版本低于8.0，请使用后缀agp3，最低支持到AGP3.0，比如com.aliyun.ams:alicloud-apm-plugin:2.5.0-agp3

插件版本号请查看Android Gradle Plugin版本记录。

1.2 应用插件

在您的模块（应用级）Gradle 文件（通常是<project>/<app-module>/build.gradle）中，在plugins中应用插件。

1.2.1 dependencyResolutionManagement方式

如果您的插件仓库是通过1.1.1 dependencyResolutionManagement方式添加的，应用插件方式如下。

plugins {
  //如果您使用了性能分析，需要在此处应用插件，否则网络监控不能正常采集数据
  id 'com.aliyun.emas.apm' version '2.4.0-agp8'
}

重要

由于Google在AGP8调整了API，所以根据AGP版本提供了不同的apm gradle插件。

如果您项目的AGP版本不低于8.0，请使用后缀agp8，比如com.aliyun.ams:alicloud-apm-plugin:2.4.0-agp8
如果您项目的AGP版本低于8.0，请使用后缀agp3，最低支持到AGP3.0，比如com.aliyun.ams:alicloud-apm-plugin:2.5.0-agp3

插件版本号请查看Android Gradle Plugin版本记录。

1.2.2 allprojects方式

如果您的插件仓库是通过1.1.2 allprojects方式添加的，应用插件方式如下。

plugins {
  //如果您使用了性能分析，需要在此处应用插件，否则网络监控不能正常采集数据
  id 'com.aliyun.emas.apm'
}

1.3 添加SDK依赖

在您的模块（应用级）Gradle 文件（通常是<project>/<app-module>/build.gradle）中，在dependencies中添加SDK依赖。

整体接入

整体接入是指接入移动监控全部产品功能。

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

部分接入

部分接入是指按需要接入移动监控的部分产品功能，需要在整体接入的基础上exclude掉不需要的产品组件。

dependencies {
    implementation ("com.aliyun.ams:alicloud-apm:{apmVersion}") {
        exclude group: 'com.aliyun.ams', module: 'alicloud-apm-performance'     //不接入性能分析
        exclude group: 'com.aliyun.ams', module: 'alicloud-apm-remote-log'      //不接入远程日志
        exclude group: 'com.aliyun.ams', module: 'alicloud-apm-crash-analysis'  //不接入崩溃分析
        exclude group: 'com.aliyun.ams', module: 'alicloud-apm-mem-monitor'     //不接入内存分析
    }
}

重要

apmVersion请从Android SDK发布说明中获取。
请使用固定版本号集成，不要使用动态版本号。错误示例：1.+或者1.0.+。

1.4 启用AndroidX

使用移动监控，需要启动AndroidX，不然编译会失败。请在<project>/gradle.properties中添加如下配置：

android.useAndroidX=true
android.enableJetifier=true

2 本地依赖方式

2.1 下载SDK

在项目空间中，点击接入SDK按钮进入SDK列表页面。

在SDK列表页，选择Android平台的移动监控服务，点击接入文档按钮，在文档最下方点击下载SDK按钮。

将SDK包内所有文件拷贝至您的模块（应用级）的<project>/<app-module>/libs目录下。

2.2 添加SDK依赖

2.2.1 配置本地SDK目录

在您的模块（应用级）Gradle 文件（通常是<project>/<app-module>/build.gradle）中，添加本地SDK文件目录地址。

repositories {
  flatDir {
    dirs 'libs'
  }
}

2.2.2 添加SDK依赖

在您的模块（应用级）Gradle 文件（通常是<project>/<app-module>/build.gradle）中的dependencies中添加SDK依赖。

dependencies {
  # 通用SDK
  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')
  # 崩溃分析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')
  # 性能分析SDK
  implementation (name:'alicloud-android-apm-1.1.6.0-open', ext: 'aar')
  implementation (name:'alicloud-apm-performance-2.0.0', ext: 'aar')
  # 远程日志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')
}

重要

示例依赖中的SDK版本号请根据下载产物的文件名中的版本号为准。
如果编译报类冲突错误，请确认dependencies下是否已经有implementation fileTree(dir: 'libs', include: ['*.jar'])
除了上述SDK，还有部分AndroidX SDK需要您自行下载。
- 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 启用AndroidX

使用移动监控，需要启动AndroidX，不然编译会失败。请在<project>/gradle.properties中添加如下配置：

android.useAndroidX=true
android.enableJetifier=true

三、配置使用SDK

1 配置移动监控SDK

配置移动监控SDK，不会真正的去初始化移动监控，需要尽早进行配置，可以在同意隐私协议前进行配置，建议在Application.onCreate()中完成配置。

Kotlin

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

ApmOptions.Builder() 
        //必须配置application
        .setApplication(application) 
        //必须配置EMAS的appKey
        .setAppKey(APP_KEY) 
        //必须配置EMAS的appSecret
        .setAppSecret(APP_SECRET) 
        //使用性能分析或者远程日志，必须配置EMAS的appRsaSecret
        .setAppRsaSecret(RSA_PUBLIC_KEY)
        //配置使用崩溃分析功能
        .addComponent(ApmCrashAnalysisComponent::class.java)
        //配置使用内存分析功能, 2.1.0版本新增
        .addComponent(ApmMemMonitorComponent::class.java)
        //配置使用远程日志功能
        .addComponent(ApmRemoteLogComponent::class.java)
        //配置使用性能分析功能
        .addComponent(ApmPerformanceComponent::class.java)
        .build()
)

Java

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()
        //必须配置application
        .setApplication(application)  
        //必须配置EMAS的appKey
        .setAppKey(APP_KEY)    
        //必须配置EMAS的appSecret
        .setAppSecret(APP_SECRET)
        //使用性能分析或者远程日志，必须配置EMAS的appRsaSecret
        .setAppRsaSecret(RSA_PUBLIC_KEY)
        //配置使用崩溃分析功能
        .addComponent(ApmCrashAnalysisComponent.class)
        //配置使用内存分析功能, 2.1.0版本新增
        .addComponent(ApmMemMonitorComponent.class) 
        //配置使用远程日志功能
        .addComponent(ApmRemoteLogComponent.class)
        //配置使用性能分析功能
        .addComponent(ApmPerformanceComponent.class)
        .build()
);

说明

配置移动监控SDK，仅完成参数配置，不会真正地去初始化。
获取appKey等参数请参考获取EMAS相关参数。

详细API请查看基础配置接口。

2 开启移动监控

Kotlin

import com.aliyun.emas.apm.Apm

Apm.start()

Java

import com.aliyun.emas.apm.Apm;

Apm.start();

重要

开启移动监控后，会根据您配置使用的功能去进行初始化，建议在同意隐私协议后开启移动监控。
Apm.start()前必须执行了Apm.preStart()，否则会导致初始化失败。

详细API请查看开启移动监控。

3 设置用户信息（可选）

移动监控SDK提供了设置用户信息的API，以将移动监控日志关联到用户，请根据需要使用。

重要

设置用户信息需要在调用Apm.preStart(...)方法后才能调用。

Kotlin

import com.aliyun.emas.apm.Apm

//设置用户Id
Apm.setUserId(userId)
//设置用户昵称
Apm.setUserNick(userNick)

Java

import com.aliyun.emas.apm.Apm;

//设置用户Id
Apm.setUserId(userId);
//设置用户昵称
Apm.setUserNick(userNick);

详细API请查看开启移动监控。

4 设置渠道标识（可选）

如果您的App有多渠道包，可以设置渠道信息。

Kotlin

import com.aliyun.emas.apm.ApmOptions

ApmOptions.Builder()
    //可选配置，设置App渠道
    .setChannel(APP_CHANNEL)
    .build()

Java

import com.aliyun.emas.apm.ApmOptions;

new ApmOptions.Builder()
        //可选配置，设置App渠道
        .setChannel(APP_CHANNEL)
        .build()

详细API请查看setChannel。

5 混淆配置

如果您的项目做了代码混淆，请保留以下混淆配置。

# 崩溃分析的混淆配置
-keep class com.aliyun.emas.apm.**{*;}
# 远程日志的混淆配置
-keep class com.taobao.tao.log.**{*;}
-keep public class * extends com.taobao.android.tlog.protocol.model.request.base.FileInfo{*;}
-keep class com.alibaba.sdk.android.oss.** { *; }
# 性能分析的混淆配置
-keep class com.taobao.monitor.impl.**{*;}
-keep class com.taobao.monitor.adapter.**{*;}
-keep class com.taobao.application.common.**{*;}
-keep class com.facebook.drawee.generic.RootDrawable{*;}
-keep class com.facebook.drawee.drawable.FadeDrawable{*;}
-keep class androidx.fragment.app.Fragment{*;}

四、接入验证

1 打开SDK日志

在1 配置移动监控SDK的基础上，添加openDebug(true)。

Kotlin

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

ApmOptions.Builder() 
        //必须配置application
        .setApplication(application) 
        //必须配置EMAS的appKey
        .setAppKey(APP_KEY) 
        //必须配置EMAS的appSecret
        .setAppSecret(APP_SECRET) 
        //使用性能分析或者远程日志，必须配置EMAS的appRsaSecret
        .setAppRsaSecret(RSA_PUBLIC_KEY)
        //配置使用崩溃分析功能
        .addComponent(ApmCrashAnalysisComponent::class.java)
        //配置使用内存分析功能
        .addComponent(ApmMemMonitorComponent::class.java)
        //配置使用远程日志功能
        .addComponent(ApmRemoteLogComponent::class.java)
        //配置使用性能分析功能
        .addComponent(ApmPerformanceComponent::class.java)
        //默认关，建议release版本关掉
        .openDebug(true)
        .build()
)

Java

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()
        //必须配置application
        .setApplication(application)  
        //必须配置EMAS的appKey
        .setAppKey(APP_KEY)    
        //必须配置EMAS的appSecret
        .setAppSecret(APP_SECRET)
        //使用性能分析或者远程日志，必须配置EMAS的appRsaSecret
        .setAppRsaSecret(RSA_PUBLIC_KEY)
        //配置使用崩溃分析功能
        .addComponent(ApmCrashAnalysisComponent.class)
        //配置使用内存分析功能
        .addComponent(ApmMemMonitorComponent.class) //2.1.0版本新增
        //配置使用远程日志功能
        .addComponent(ApmRemoteLogComponent.class)
        //配置使用性能分析功能
        .addComponent(ApmPerformanceComponent.class)
        //默认关，建议release版本关掉
        .openDebug(true)
        .build()
);

2 验证崩溃分析接入

过滤tag:Apm-CrashAnalysis，分析日志，下面列出关键日志。

 # 开始初始化崩溃分析
 I  Initializing Apm Crash Analysis 1.0.0 for com.alibaba.emas.android.apm.app
 # 成功初始化崩溃分析
 I  Initializing CrashAnalysis blocked main for 20 ms

3 验证远程日志接入

过滤tag:AliHaCore分析日志，下面列出关键日志。

 D  start init plugin tlog
 D  end init plugin tlog 0ms

4 验证性能分析接入

过滤tag:AliHaCore分析日志，下面列出关键日志。

 D  start init plugin apm
 D  end init plugin apm 17ms

5 验证内存分析接入

过滤tag:Apm-MemMonitor，下面列出关键日志。

 I  Initializing MemMonitor blocked main for 1 ms

五、扩展资料

按照功能验证，验证各个功能是否正常。
查看Android SDK API。