如何集成崩溃分析Android SDK_移动研发平台(EMAS)-阿里云帮助中心

前言

本章节介绍崩溃分析Android SDK的接入方法。

推荐使用Gradle管理依赖的Android Studio项目。
支持Android 5.0及以上版本。
ANR采集支持Android11及以上版本。

准备工作

已创建项目和应用。具体操作请参见创建项目和应用。
已阅读Android SDK发布说明，获取最新版本。

第一步：将SDK添加到您的应用

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

说明

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

1 Maven依赖方式

2 本地依赖方式

1.1 配置Maven仓库

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

1.1.1 dependencyResolutionManagement方式

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

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

1.1.2 allprojects方式

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

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

1.2 添加SDK依赖

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

dependencies {
  api 'com.aliyun.ams:alicloud-apm-crash-analysis:{crashVersion}'
}

重要

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

2.1 下载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 {
  implementation (name:'alicloud-apm-crash-analysis-x.x.x', ext: 'aar')
  implementation (name:'alicloud-apm-crash-common-x.x.x', ext: 'aar')
  implementation (name:'alicloud-apm-crash-components-x.x.x', ext: 'aar')
  implementation (name:'alicloud-apm-annotations-x.x.x', ext: 'jar')
  implementation (name:'alicloud-apm-crash-analysis-x.x.x', ext: 'aar')
  implementation (name:'alicloud-apm-crash-analysis-ndk-x.x.x', ext: 'aar')
  implementation (name:'alicloud-android-utdid-x.x.x', ext: 'jar')
}

重要

示例依赖中的SDK版本号请根据下载产物的文件名中的版本号为准。
如果编译报类冲突错误，请确认dependencies下是否已经有implementation fileTree(dir: 'libs', include: ['*.jar'])

第二步：配置使用SDK

1 配置崩溃分析SDK

配置崩溃分析SDK，不会去初始化崩溃分析，需要尽早进行初始化，可以在同意隐私协议前进行配置，建议在Application.onCreate()中完成配置。

import com.aliyun.emas.apm.Apm;
import com.aliyun.emas.apm.ApmOptions;
import com.aliyun.emas.apm.crash.ApmCrashAnalysisComponent;

Apm.preStart(new ApmOptions.Builder()
        //必须配置application
        .setApplication(application)  
        //必须配置EMAS的appKey
        .setAppKey(appKey)    
        //必须配置EMAS的appSecret
        .setAppSecret(appSecret)
        //必须配置，否则不会打开崩溃分析功能
        .addComponent(ApmCrashAnalysisComponent.class)
        .build()
);

说明

配置崩溃分析SDK，仅完成参数配置，不会初始化崩溃分析。

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

2 开启崩溃分析

Apm.start();

重要

开启崩溃分析后，会初始化崩溃分析，建议在同意隐私协议后开启崩溃分析。

详细API请查看开启崩溃分析。

3 自定义异常

崩溃分析SDK提供了自定义异常的API，方便您添加自定义异常。

ApmCrashAnalysis.getInstance().recordException(new RuntimeException("This is an non-fatal"));

详细API请查看自定义异常。

4 设置用户信息（可选）

崩溃分析SDK提供了设置用户信息的API，以将崩溃日志关联到用户，请根据需要使用。

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

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

5 添加自定义维度数据（可选）

崩溃分析SDK提供了一系列设置键/值对的API，方便给崩溃日志添加更多额外信息，请根据需要使用。

ApmCrashAnalysis.getInstance().setCustomKey(key, value);

详细API请查看添加自定义维度。

6 设置日志信息（可选）

崩溃分析SDK提供了设置日志信息的API，方便给崩溃日志添加运行日志数据，请根据需要使用。

ApmCrashAnalysis.getInstance().log(message);

详细API请查看添加日志信息。

7 设置渠道标识（可选）

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

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

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

8 混淆配置

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

-keep class com.aliyun.emas.apm.**{*;}

注意事项：老版本升级指南

如果您集成的是低于3.0.0版本的崩溃分析，需要按以下步骤删掉旧版本SDK，避免带来额外的问题。

重要

如果您没有集成低于3.0.0版本的崩溃分析SDK，可以跳过这一步。

低于3.0.0版本的崩溃分析SDK的Maven artifactId是alicloud-android-ha-crashreporter。

1 删掉老版本依赖

在您的模块（应用级）Gradle 文件（通常是<project>/<app-module>/build.gradle）中，在dependencies中删除旧版本崩溃分析SDK的依赖。

dependencies {
  //删除掉这个sdk的依赖
  implementation('com.aliyun.ams:alicloud-android-ha-crashreporter:x.x.x')
}

2 删除初始化代码

需要删除旧版本崩溃分析SDK的初始化代码。

//删除下面的代码
AliHaAdapter.getInstance().addPlugin(Plugin.crashreporter);

第三步：接入验证

过滤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

第四步：崩溃监控功能验证

1 打开SDK日志

在1 配置崩溃分析SDK的基础上，添加openDebug(true)。

Apm.preStart(new ApmOptions.Builder()
        //必须配置application
        .setApplication(application)  
        //必须配置EMAS的appKey
        .setAppKey(appKey)    
        //必须配置EMAS的appSecret
        .setAppSecret(appSecret)
        //必须配置，否则不会打开崩溃分析功能
        .addComponent(ApmCrashAnalysisComponent.class)
        //可选配置，设置App渠道
        .setChannel(channel)
        //默认关，建议release版本关掉
        .openDebug(true)
        .build()
);

2 强制造成一次测试崩溃

如需在 EMAS 控制台查看崩溃数据，您需要强制造成一次测试崩溃。

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    
    Button crashButton = new Button(this);
    crashButton.setText("Test Crash");
    crashButton.setOnClickListener(new View.OnClickListener() {
       public void onClick(View view) {
           throw new RuntimeException("Test Crash"); //触发崩溃
       }
    });
    
    addContentView(crashButton, new ViewGroup.LayoutParams(
           ViewGroup.LayoutParams.MATCH_PARENT,
           ViewGroup.LayoutParams.WRAP_CONTENT));
}

构建运行App后，点击Test Crash按钮触发崩溃。

3 查看日志

过滤tag:Apm-CrashAnalysis，查看崩溃数据是否上报，下面列出关键日志。

 # 开始上报崩溃数据
 D  Sending report : 67AC2CAD026A00016CB8DE472237D11C
 # 成功上报崩溃数据
 D  Crashlytics report successfully enqueued to DataTransport: 67AC2CAD026A00016CB8DE472237D11C

4 控制台查看数据

进入控制台，选择您的项目。根据下图步骤查看崩溃日志。