接入Android应用

准备阶段：创建应用

1. 登录云监控2.0控制台，选择目标工作空间，在左侧导航栏单击接入中心。

2. 在前端应用区域单击Android卡片，输入应用名称并根据需求配置其他参数，然后单击创建应用。

   说明

   应用名称唯一，不能与已创建的应用名称重复。

   创建成功后，页面下方将会生成相应的接入代码，代码中包含了AppID、ConfigAddress等关键信息。

   后续您可以在所有功能 > 用户体验监控 > 应用列表页面查看创建的应用，进入应用详情，在应用设置 > 基础信息页面可以查看应用接入代码。

集成SDK

支持版本

Android 7.0 及以上的版本

Maven自动集成（推荐）

通过在 Android Studio 工程的 build.gradle 配置脚本中添加 maven 线上依赖，并导入最新版本 SDK。

在工程根目录下的 build.gradle 配置脚本中添加插件依赖，示例如下：

buildscript {
  repositories {
    mavenLocal()
    google()
    mavenCentral()
    gradlePluginPortal()
  }
  
  dependencies {
    // 导入阿里云 ARMS RUM 插件依赖
   classpath "com.aliyun.rum:alibabacloud-android-rum-plugin:2.3.2"
  }
}

在工程 App 模块对应的 build.gradle 配置脚本中启用插件和添加SDK依赖，示例如下：

// 启用阿里云 ARMS RUM 插件
apply plugin: "com.aliyun.rum"

dependencies {
  // 导入阿里云 ARMS RUM SDK
  implementation("com.aliyun.rum:alibabacloud-android-rum-sdk:2.3.2")
}

手动集成

下载SDK并解压

下载SDK后，并解压.zip文件后得到内容如下：

• libs文件夹，包含必须的jar包和jni库

• repo文件夹，包含必须的插件

• assets文件夹，不包含必须的资源文件

工程配置

1. 复制 repo 文件夹到项目根目录

2. 复制 libs 文件夹到 App Module 目录

3. 复制libs/assets中的文件到App/src/assets目录中。如下图：

   

4. 打开项目根目录下的 build.gradle （Gradle 7.0 及以下）或 settings.gradle （Gradle 7.0 以上）文件，在 repositories 块中加入以下 maven 配置：

   build.gradle文件配置

   buildscript {
       repositories {
           maven {
               url uri('./repo')
           }
           //... 其他配置
       }
   }
   
   allprojects {
       repositories {
           maven {
               url uri('./repo')
           }
           //... 其他配置
       }
   }
   
   //... 其他配置

   settings.gradle文件配置

   pluginManagement {
       repositories {
           maven {
               url uri('./repo')
           }
           //... 其他配置
       }
   }
   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           maven {
               url uri('./repo')
           }
           //... 其他配置
       }
   }
   //... 其他配置

5. 在项目根目录下的 build.gradle 文件中，加入 classpath 配置：

   // 不区分Gradle版本，加入下面
   buildscript {
       dependencies {
           classpath "com.aliyun.rum:alibabacloud-android-rum-plugin:2.3.2"
       }
   }
   //... 其他配置

6. 打开App Module下的build.gradle文件，导入AlibabaCloudRUM插件和依赖，如下：

   apply plugin: "com.aliyun.rum"
   //... 其他配置
   android {
       //... 其他配置
       sourceSets {
           main {
               jniLibs.srcDirs = ['libs']
           }
       }
       //... 其他配置
   }
   
   dependencies {
       implementation files('libs/alibabacloud-android-rum-sdk.jar')
       //... 其他配置
   }

插件配置

在项目App Module目录下的 build.gradle 文件中，按需添加plugin配置：

AlibabacloudRumExt {
    // 排除不需要插桩的包
    excludePackages = [
        "com.example.internal",      // 排除内部实现包
        "com.myapp.debug",           // 排除调试相关包
        "com.thirdparty.analytics"   // 排除第三方分析SDK
    ]
}
//... 其他配置

plugin 配置更新后，需要删除历史缓存才会生效，删除缓存参考以下命令：

./gradlew --stop
find "$HOME/.gradle/caches" \
-type d \
\( -name "transforms" -o -name "transforms-*" \) \
-prune \
-exec rm -rf -- {} +

符号文件上传（可选）

符号文件用于还原经过混淆或符号剥离后的崩溃堆栈。插件支持上传以下文件：

• Java/Kotlin 混淆映射文件 mapping.txt

• Native 未剥离调试符号文件 .so

在 App Module 的 build.gradle 中添加以下配置：

AlibabacloudRumExt {
    // RUM 应用信息
    workspace = "<your workspace>"
    serviceId = "<your serviceId>"
    regionId = "cn-hangzhou"

    // 可选：不使用阿里云默认凭证链时，可在此配置访问凭证。
    // accessKeyId 和 accessKeySecret 必须同时配置，请通过环境变量等安全方式注入。
    // accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
    // accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")

    // 可选：上传 Java/Kotlin 混淆映射文件，默认为 false
    autoUploadMap = true

    // 可选：上传 Native 未剥离调试符号文件，默认为 false
    autoUploadNativeDebugSymbol = true

    // 可选：插件无法从 AGP 默认目录找到 Native 符号文件时，指定文件或目录
    // nativeLibPath = "/path/to/unstripped/native/libs"
}

可以根据应用实际情况只开启其中一个上传开关。开启后，例如执行 ./gradlew :app:assembleRelease 或 ./gradlew :app:bundleRelease，插件会在构建成功后执行 uploadReleaseRumSymbols 任务。

配置项说明：

访问凭证配置

上传任务需要阿里云访问凭证，支持以下两种配置方式：

1. 使用阿里云默认凭证链（推荐）

   AlibabacloudRumExt 中无需配置 accessKeyId 和 accessKeySecret。插件支持从 RAM Role、OIDC Role、CLI/Profile 配置或环境变量中获取凭证。使用环境变量的示例如下：

   export ALIBABA_CLOUD_ACCESS_KEY_ID="<your accessKeyId>"
   export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<your accessKeySecret>"

2. 在 AlibabacloudRumExt 中显式配置

   如果构建环境无法使用默认凭证链，可以在扩展中配置 accessKeyId 和 accessKeySecret。两个参数必须同时配置，建议从环境变量或 Gradle 属性注入：

   AlibabacloudRumExt {
       workspace = "<your workspace>"
       serviceId = "<your serviceId>"
       regionId = "cn-hangzhou"
   
       accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
       accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
   
       autoUploadMap = true
       autoUploadNativeDebugSymbol = true
   }

请勿将 AccessKey 明文写入 build.gradle 或提交到代码仓库。

最小权限要求

插件需要调用 CMS 的 GetRumSymbolFileParams 接口获取符号文件上传参数。用于上传的 RAM 身份（例如 AccessKey 所属的 RAM 用户，或默认凭证链获取的 RAM Role、OIDC Role）至少需要具备以下权限：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cms:GetRumSymbolFileParams",
      "Resource": "*"
    }
  ]
}

开启上传前，请同时确认：

• App 已配置 versionName 或 versionCode，上传文件的版本将与当前构建 Variant 的应用版本保持一致。

• 构建环境可以访问阿里云 CMS OpenAPI 和接口返回的 OSS 上传地址。

• 上传 mapping.txt 时，当前构建 Variant 已开启混淆；上传 Native 符号时，应提供未剥离且包含 GNU ELF Build ID 的 .so 文件。

权限配置

阿里云 ARMS RUM SDK 需要宿主App授予以下权限，确保已引入如下权限：

<!--  必须  -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<!--  可选  -->
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.READ_BASIC_PHONE_STATE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

混淆配置

若您的应用使用proguard混淆，请添加以下配置：

-keep public class com.alibabacloud.rum.** { *; }
-dontwarn com.alibabacloud.rum.**

-optimizations !code/simplification/*,!field/*,!class/merging/*,!method/propagation/*,!class/unboxing/enum,!code/allocation/variable

初始化SDK

请在自定义Application的onCreate函数首行添加以下代码，示例如下：

同步启动

import com.alibabacloud.rum.AlibabaCloudRum;

public class YourApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    // SDK版本 >= 2.0.0
    AlibabaCloudRum.withServiceId("") // ServiceId 在创建 RUM 应用时获取
          .withWorkspace("") // Workspace 在创建 RUM 应用时获取
          .withEndpoint("") // Endpoint 在创建 RUM 应用时获取
          .start(getApplicationContext());

    // SDK版本 < 2.0.0
    AlibabaCloudRum.withAppID("<your appid>") // AppID，步骤一创建RUM应用时获取。
        .withConfigAddress("<your config address>") // ConfigAddress，步骤一创建RUM应用时获取。
        .start(getApplicationContext());
  }
}

异步启动

SDK版本 >= 2.2.9 支持异步启动。

import com.alibabacloud.rum.AlibabaCloudRum;

public class YourApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();

    // SDK版本 >= 2.2.9
    AlibabaCloudRum.withServiceId("") // ServiceId 在创建 RUM 应用时获取
      .withWorkspace("") // Workspace 在创建 RUM 应用时获取
      .withEndpoint("") // Endpoint 在创建 RUM 应用时获取
      .start(getApplicationContext(), true);
  }
}

接入验证

启动已经集成了SDK的APK应用，查看Android Studio Logcat日志，搜索AlibabaCloudRUM关键字（或者过滤 AlibabaCloudRUM 标签），出现如下log则表示SDK集成成功且数据开始采集。

合规说明

应用的数据合规非常重要，您须确保按照当前法律法规或监管要求使用用户体验监控SDK服务，为避免因数据合规问题导致的应用下架，请您务必做好以下三步：

1. 请务必确保您已经将用户体验监控SDK升级到满足监管新规的最新版本。

2. 请务必在《隐私权政策》中向用户告知使用了用户体验监控SDK，参考条款如下：

   使用SDK名称：用户体验监控SDK

   服务类型：SDK服务

   使用目的：采集应用体验数据，用于应用性能问题统计与分析

   收集个人信息类型：用户信息、应用信息、设备信息、流量信息、设备状态信息、网络状态信息

   隐私权政策链接：https://terms.alicdn.com/legal-agreement/terms/privacy_policy_full/20240308104330389/20240308104330389.html

3. 请务必做延迟初始化配置，确保用户授权《隐私权政策》后再初始化用户体验监控SDK。

   请您务必按照如上提示合规使用用户体验监控SDK服务，因您未合规使用SDK服务所导致的风险由您自行承担，并承担因此对用户体验监控带来的损失。

更多说明，请参见用户体验监控SDK隐私合规书写说明。