接入Android應用 - Application Real-Time Monitoring Service

使用者體驗監控提供了非常全面的移動端應用監控能力，支援對應用效能、崩潰、卡頓等關鍵計量的進行即時監控與分析。本文介紹如何接入Android應用。

整合SDK

支援版本

Android 7.0 及以上的版本

Maven自動整合（推薦）

通過在 Android Studio 工程的 build.gradle 配置指令碼中添加 maven 線上依賴，並匯入最新版本 SDK。

說明

建議從以下連結擷取最新版本SDK：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檔案夾，不包含必須的資源檔

工程配置

複製 repo 檔案夾到專案根目錄
複製 libs 檔案夾到 App Module 目錄
複製libs/assets中的檔案到App/src/assets目錄中。如下圖：

開啟專案根目錄下的 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')
        }
        //... 其他配置
    }
}
//... 其他配置

在專案根目錄下的 build.gradle 檔案中，加入 classpath 配置：

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

開啟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

重要

autoUploadMap 和 autoUploadNativeDebugSymbol 預設均為 false，僅接入外掛程式不會上傳任何符號檔案。只有顯式將對應配置設定為 true，外掛程式才會為相應檔案註冊上傳任務；成功執行對應 Variant 的 assemble 或 bundle 構建任務後，外掛程式會自動上傳檔案。

在 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 任務。

配置項說明：

配置項	預設值	說明
`autoUploadMap`	`false`	是否上傳當前構建 Variant 的 `mapping.txt`。開啟前需為該 Variant 啟用代碼混淆並確保能夠產生該檔案。
`autoUploadNativeDebugSymbol`	`false`	是否上傳包含 GNU ELF Build ID 的未剝離 `.so` 檔案。
`workspace`	空	RUM 應用所屬工作空間。開啟上傳時必須配置。
`serviceId`	空	RUM 應用的 Service ID。開啟上傳時必須配置。
`regionId`	空	RUM 應用所屬地區。
`nativeLibPath`	空	Native 符號檔案或目錄路徑。未配置時，外掛程式會從 AGP/CMake/ndkBuild 的預設輸出目錄中尋找。
`generateSourceMapOnly`	`false`	設定為 `true` 時只將符號檔案收集到 `build/outputs/rum-symbols/<variant>`，不會上傳到服務端。
`accessKeyId`、`accessKeySecret`	空	可選的靜態訪問憑證，必須同時配置。未配置時使用阿里雲預設憑證鏈。

訪問憑證配置

上傳任務需要阿里雲訪問憑證，支援以下兩種配置方式：

使用阿里雲預設憑證鏈（推薦）
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>"
```

在 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 支援非同步啟動。

說明

使用非同步啟動的方式SDK啟動流程不阻塞宿主APP，但SDK啟動前產生的資料會有採集不到的風險。

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整合成功且資料開始採集。