Integrasikan aplikasi Android - Application Real-Time Monitoring Service

Real User Monitoring (RUM) menyediakan pemantauan aplikasi seluler yang komprehensif, termasuk pelacakan performa, crash, dan ketidakresponsifan secara real-time. Pelajari cara mengintegrasikan SDK RUM ke dalam aplikasi Android Anda.

Integrate the SDK

Versi yang didukung

Android 7.0 dan versi lebih baru.

Integrasi otomatis Maven (direkomendasikan)

Tambahkan dependensi online Maven dalam skrip konfigurasi build.gradle proyek Android Studio Anda untuk mengimpor versi terbaru SDK.

Catatan

Kami merekomendasikan agar Anda memperoleh versi SDK terbaru dari: Catatan rilis SDK.

Tambahkan dependensi plugin dalam skrip konfigurasi build.gradle di direktori root proyek Anda.

buildscript {
  repositories {
    mavenLocal()
    google()
    mavenCentral()
    gradlePluginPortal()
  }
  
  dependencies {
    // Impor dependensi plugin ARMS RUM untuk Alibaba Cloud
    classpath "com.aliyun.rum:alibabacloud-android-rum-plugin:2.3.2"
  }
}

Aktifkan plugin dan tambahkan dependensi SDK dalam skrip konfigurasi build.gradle untuk modul App proyek Anda.

// Aktifkan plugin ARMS RUM untuk Alibaba Cloud
apply plugin: "com.aliyun.rum"

dependencies {
  // Impor SDK ARMS RUM untuk Alibaba Cloud
  implementation("com.aliyun.rum:alibabacloud-android-rum-sdk:2.3.2")
}

Integrasi manual

Unduh dan ekstrak SDK

Unduh SDK dan ekstrak file .zip tersebut. Isi hasil ekstraksi mencakup:

Folder libs: berisi paket JAR dan library JNI yang diperlukan
Folder repo: berisi plugin yang diperlukan
Folder assets: tidak berisi file resource yang diperlukan

Konfigurasikan proyek

Salin folder repo ke direktori root proyek Anda.
Salin folder libs ke direktori Modul App.
Salin file dalam libs/assets ke direktori App/src/assets.

Buka file build.gradle (Gradle 7.0 dan sebelumnya) atau settings.gradle (Gradle 7.0 dan setelahnya) di direktori root proyek Anda, lalu tambahkan konfigurasi Maven berikut dalam blok repositories:

build.gradle

buildscript {
    repositories {
        maven {
            url uri('./repo')
        }
        //... konfigurasi lainnya
    }
}

allprojects {
    repositories {
        maven {
            url uri('./repo')
        }
        //... konfigurasi lainnya
    }
}

//... konfigurasi lainnya

settings.gradle

Tambahkan konfigurasi repositori Maven ke dalam blok pluginManagement dan dependencyResolutionManagement.

pluginManagement {
    repositories {
        maven {
            url uri('./repo')
        }
        //... konfigurasi lainnya
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven {
            url uri('./repo')
        }
        //... konfigurasi lainnya
    }
}
//... konfigurasi lainnya

Dalam file build.gradle di direktori root proyek Anda, tambahkan konfigurasi classpath:

// Terlepas dari versi Gradle, tambahkan baris berikut
buildscript {
    dependencies {
        classpath "com.aliyun.rum:alibabacloud-android-rum-plugin:2.3.2"
    }
}
//... konfigurasi lainnya

Buka file build.gradle di Modul App dan impor plugin serta dependensi AlibabaCloudRUM:

apply plugin: "com.aliyun.rum"
//... konfigurasi lainnya
android {
    //... konfigurasi lainnya
    sourceSets {
        main {
            jniLibs.srcDirs = ['libs']
        }
    }
    //... konfigurasi lainnya
}

dependencies {
    implementation files('libs/alibabacloud-android-rum-sdk.jar')
    //... konfigurasi lainnya
}

Configure plugins

Dalam file build.gradle di direktori Modul App proyek Anda, tambahkan konfigurasi plugin sesuai kebutuhan:

AlibabacloudRumExt {
    // Kecualikan paket yang tidak perlu diinstrumentasi
    excludePackages = [
        "com.example.internal",      // Kecualikan paket implementasi internal
        "com.myapp.debug",           // Kecualikan paket terkait debug
        "com.thirdparty.analytics"   // Kecualikan SDK analitik pihak ketiga
    ]
}
//... konfigurasi lainnya

Setelah memperbarui konfigurasi plugin, hapus cache historis agar perubahan berlaku. Jalankan perintah berikut untuk menghapus cache:

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

Unggah file simbol (opsional)

File simbol digunakan untuk memulihkan stack crash yang telah diobfuscate atau di-strip simbolnya. Plugin mendukung pengunggahan file berikut:

File mapping obfuscation Java/Kotlin mapping.txt
File simbol debug native yang belum di-strip (.so)

Penting

autoUploadMap dan autoUploadNativeDebugSymbol keduanya bernilai default false. Hanya dengan mengintegrasikan plugin saja tidak akan mengunggah file simbol apa pun. Plugin hanya akan mendaftarkan tugas unggah untuk file yang sesuai ketika Anda secara eksplisit mengatur item konfigurasi terkait menjadi true. Setelah tugas build assemble atau bundle dari varian yang sesuai berhasil dijalankan, plugin akan secara otomatis mengunggah file tersebut.

Tambahkan konfigurasi berikut ke file build.gradle Modul App:

AlibabacloudRumExt {
    // Informasi aplikasi RUM
    workspace = "<your workspace>"
    serviceId = "<your serviceId>"
    regionId = "cn-hangzhou"

    // Opsional: Jika Anda tidak menggunakan rantai kredensial default Alibaba Cloud,
    // konfigurasikan kredensial akses di sini.
    // accessKeyId dan accessKeySecret harus dikonfigurasi bersamaan.
    // Suntikkan melalui metode aman seperti variabel lingkungan.
    // accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
    // accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")

    // Opsional: Unggah file mapping obfuscation Java/Kotlin. Default: false
    autoUploadMap = true

    // Opsional: Unggah file simbol debug native yang belum di-strip. Default: false
    autoUploadNativeDebugSymbol = true

    // Opsional: Jika plugin tidak dapat menemukan file simbol native di direktori AGP default,
    // tentukan file atau direktori di sini.
    // nativeLibPath = "/path/to/unstripped/native/libs"
}

Anda dapat mengaktifkan hanya salah satu sakelar unggah berdasarkan kebutuhan aplikasi Anda. Setelah mengaktifkan sakelar tersebut, misalnya saat menjalankan ./gradlew :app:assembleRelease atau ./gradlew :app:bundleRelease, plugin akan menjalankan tugas uploadReleaseRumSymbols setelah proses build berhasil.

Tabel berikut menjelaskan item konfigurasi.

Item konfigurasi	Nilai default	Deskripsi
`autoUploadMap`	`false`	Menentukan apakah akan mengunggah file `mapping.txt` dari varian build saat ini. Sebelum mengaktifkan item ini, aktifkan obfuscation kode untuk varian tersebut dan pastikan file tersebut dapat dihasilkan.
`autoUploadNativeDebugSymbol`	`false`	Menentukan apakah akan mengunggah file `.so` yang belum di-strip dan berisi GNU ELF Build ID.
`workspace`	Kosong	Ruang kerja tempat aplikasi RUM berada. Wajib diisi saat unggah diaktifkan.
`serviceId`	Kosong	ID layanan aplikasi RUM. Wajib diisi saat unggah diaktifkan.
`regionId`	Kosong	Wilayah tempat aplikasi RUM berada.
`nativeLibPath`	Kosong	Jalur file atau direktori simbol native. Jika tidak dikonfigurasi, plugin akan mencari di direktori output default AGP, CMake, dan ndkBuild.
`generateSourceMapOnly`	`false`	Jika diatur ke `true`, file simbol hanya dikumpulkan ke `build/outputs/rum-symbols/<variant>` dan tidak diunggah ke server.
`accessKeyId`, `accessKeySecret`	Kosong	Kredensial akses statis opsional. Keduanya harus dikonfigurasi bersamaan. Jika tidak dikonfigurasi, rantai kredensial default Alibaba Cloud akan digunakan.

Konfigurasikan kredensial akses

Tugas unggah memerlukan kredensial akses Alibaba Cloud. Dua metode konfigurasi berikut didukung:

Gunakan rantai kredensial default Alibaba Cloud (direkomendasikan)
Anda tidak perlu mengonfigurasi accessKeyId dan accessKeySecret dalam AlibabacloudRumExt. Plugin mendukung pengambilan kredensial dari peran RAM, peran OIDC, konfigurasi CLI/Profil, atau variabel lingkungan. Contoh berikut menunjukkan cara menggunakan variabel lingkungan:
```
export ALIBABA_CLOUD_ACCESS_KEY_ID="<your accessKeyId>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<your accessKeySecret>"
```
Konfigurasikan kredensial secara eksplisit dalam AlibabacloudRumExt
Jika rantai kredensial default tidak tersedia di lingkungan build Anda, konfigurasikan accessKeyId dan accessKeySecret dalam ekstensi. Kedua parameter harus dikonfigurasi bersamaan. Kami merekomendasikan agar Anda menyuntikkannya dari variabel lingkungan atau properti 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
}
```
Jangan menuliskan pasangan AccessKey dalam teks biasa di file build.gradle atau melakukan commit ke repositori kode.

Persyaratan hak istimewa minimal

Plugin memanggil operasi GetRumSymbolFileParams Cloud Monitor untuk memperoleh parameter unggah file simbol. Identitas RAM yang digunakan untuk unggah (misalnya, Pengguna RAM tempat AccessKey tersebut berada, atau Peran RAM atau Peran OIDC yang diperoleh melalui rantai kredensial default) harus memiliki setidaknya izin berikut:

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

Sebelum mengaktifkan unggah, pastikan semua kondisi berikut terpenuhi:

Aplikasi memiliki versionName atau versionCode yang dikonfigurasi. Versi file yang diunggah harus konsisten dengan versi aplikasi dari varian build saat ini.
Lingkungan build dapat mengakses OpenAPI Cloud Monitor dan alamat unggah OSS yang dikembalikan oleh operasi tersebut.
Saat mengunggah mapping.txt, obfuscation harus diaktifkan untuk varian build saat ini. Saat mengunggah file simbol native, sediakan file .so yang belum di-strip dan berisi GNU ELF Build ID.

Konfigurasikan izin

SDK ARMS RUM untuk Alibaba Cloud memerlukan izin berikut dari aplikasi host. Pastikan izin berikut disertakan:

<!-- Wajib -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<!-- Opsional -->
<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"/>

Configure obfuscation

Jika aplikasi Anda menggunakan obfuscation ProGuard, tambahkan konfigurasi berikut:

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

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

Initialize the SDK

Tambahkan kode berikut di awal fungsi onCreate kelas Application kustom Anda.

Startup sinkron

import com.alibabacloud.rum.AlibabaCloudRum;

public class YourApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    // Versi SDK >= 2.0.0
    AlibabaCloudRum.withServiceId("") // ServiceId yang diperoleh saat membuat aplikasi RUM
          .withWorkspace("") // Workspace yang diperoleh saat membuat aplikasi RUM
          .withEndpoint("") // Endpoint yang diperoleh saat membuat aplikasi RUM
          .start(getApplicationContext());

    // Versi SDK < 2.0.0
    AlibabaCloudRum.withAppID("<your appid>") // AppID yang diperoleh saat membuat aplikasi RUM
        .withConfigAddress("<your config address>") // ConfigAddress yang diperoleh saat membuat aplikasi RUM
        .start(getApplicationContext());
  }
}

Startup asinkron

Versi SDK >= 2.2.9 mendukung startup asinkron.

Catatan

Saat menggunakan startup asinkron, proses startup SDK tidak memblokir aplikasi host. Namun, data yang dihasilkan sebelum SDK dimulai mungkin tidak terkumpul.

import com.alibabacloud.rum.AlibabaCloudRum;

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

    // Versi SDK >= 2.2.9
    AlibabaCloudRum.withServiceId("") // ServiceId yang diperoleh saat membuat aplikasi RUM
      .withWorkspace("") // Workspace yang diperoleh saat membuat aplikasi RUM
      .withEndpoint("") // Endpoint yang diperoleh saat membuat aplikasi RUM
      .start(getApplicationContext(), true);
  }
}

Verify the integration

Jalankan aplikasi APK dengan SDK yang telah diintegrasikan, lalu lihat log Logcat Android Studio. Cari kata kunci AlibabaCloudRUM (atau filter berdasarkan tag AlibabaCloudRUM). Jika log berikut muncul, SDK berhasil diintegrasikan dan pengumpulan data telah dimulai.