Mengelola peran aplikasi

Fitur peran aplikasi memungkinkan admin IT memberikan hak istimewa khusus kepada aplikasi terkelola di perangkat yang didukung Android. Dengan menetapkan peran tertentu, aplikasi dapat dikecualikan dari pembatasan daya dan latar belakang, penangguhan, hibernasi (di Android 14+) dan menonaktifkan kontrol pengguna (yaitu mencakup tindakan pengguna seperti menghentikan paksa dan menghapus data aplikasi) (di Android 11+), sehingga aplikasi dapat menjalankan fungsi pentingnya tanpa gangguan. Selain itu, aplikasi dapat diberi tahu tentang peran yang ditetapkan, sehingga dapat melakukan bootstrap sendiri tanpa intervensi pengguna.

Catatan: Fitur peran aplikasi menggantikan kolom extensionConfig di ApplicationPolicy.

Untuk mengetahui daftar peran aplikasi yang tersedia dan hak istimewa khusus yang diberikan ke setiap peran, lihat RoleType.

Prasyarat

Perangkat dikelola oleh EMM berbasis AMAPI (EMM yang menggunakan DPC kustom tidak didukung).

Menyiapkan aplikasi untuk menggunakan fitur

Integrasi dengan AMAPI SDK hanya diperlukan jika aplikasi ingin diberi tahu tentang peran yang ditetapkan, yang memungkinkannya melakukan bootstrap sendiri (yaitu, peluncuran otomatis tanpa interaksi pengguna).

Mengintegrasikan dengan AMAPI SDK di aplikasi Anda

Anda dapat menemukan informasi selengkapnya tentang AMAPI SDK dan cara menambahkannya ke aplikasi di panduan integrasi AMAPI SDK.

Menambahkan metadata yang diperlukan ke manifes aplikasi

Android Device Policy (ADP) perlu mengetahui ComponentName class Anda yang mengimplementasikan NotificationReceiverService untuk memberi tahu aplikasi Anda tentang peran yang ditetapkan. Anda harus memberi tag pada layanan di AndroidManifest.xml dengan tepat agar dapat ditemukan secara otomatis oleh ADP.

• Aplikasi Anda harus memiliki tepat satu layanan yang merupakan enabled dan memiliki meta-data dengan android:name sama dengan com.google.android.managementapi.notification.NotificationReceiverService.SERVICE_APP_ROLES
• Layanan ini harus memiliki android:exported yang ditetapkan ke true
• android:value dari meta-data harus ditetapkan ke string kosong

<service
 android:name=".MyNotificationReceiverService"
 android:exported="true">
    <meta-data android:name="com.google.android.managementapi.notification.NotificationReceiverService.SERVICE_APP_ROLES" android:value="" />
</service>

Catatan: Class dasar NotificationReceiverService otomatis menangani perlindungan keamanan. Hal ini memastikan bahwa hanya aplikasi Kebijakan Perangkat Android (ADP) yang dapat berkomunikasi dengan aman dengan layanan ini. Anda tidak perlu mendeklarasikan izin BIND kustom atau memverifikasi paket panggilan secara manual.

Jika Anda menguji peran COMPANION_APP, Anda juga harus menambahkan meta-data berikut ke layanan Anda agar kebijakan perangkat Android dapat mengirim update status perintah lokal ke aplikasi Anda:

<meta-data android:name="com.google.android.managementapi.notification.NotificationReceiverService.SERVICE_COMMAND_STATUS" android:value="" />

Buat layanan yang memperluas NotificationReceiverService (atau perbarui yang sudah ada)

Buat atau perbarui NotificationReceiverService yang ada dan terapkan AppRolesListener untuk memproses peran yang ditetapkan ke aplikasi Anda. Hanya getAppRolesListener() yang diperlukan untuk memproses peran yang ditetapkan ke aplikasi Anda. Jika aplikasi Anda diberi peran COMPANION_APP, Anda juga harus menerapkan getCommandListener():

import android.util.Log
import com.google.android.managementapi.approles.AppRolesListener
import com.google.android.managementapi.approles.model.AppRolesSetRequest
import com.google.android.managementapi.approles.model.AppRolesSetResponse
import com.google.android.managementapi.commands.CommandListener
import com.google.android.managementapi.commands.model.Command
import com.google.android.managementapi.notification.NotificationReceiverService

class MyNotificationReceiverService : NotificationReceiverService() {

  // If your app wants to listen for roles assigned
  override fun getAppRolesListener(): AppRolesListener =
    object : AppRolesListener {
      override fun onAppRolesSet(request: AppRolesSetRequest): AppRolesSetResponse {
        val roleTypes = request.roles.map { role -> role.roleType }
        Log.i(TAG, "onAppRolesSet: $roleTypes")

        return AppRolesSetResponse.getDefaultInstance()
      }
    }

 // If your app wants to listen for local command status updates
 // Only relevant for COMPANION_APP role
 override fun getCommandListener(): CommandListener {
    return object : CommandListener {
      override fun onCommandStatusChanged(command: Command) {
         Log.i(TAG, "onCommandStatusChanged")
      }
    }
  }

  private companion object {
    const val TAG = "MyNotificationReceiverService"
  }
}

Catatan: Aplikasi Anda akan diberi tahu tentang peran yang ditetapkan hanya jika ada perubahan dalam perannya atau kemampuan tambahannya.

Aplikasi Anda dapat diberi tahu beberapa kali jika perannya berubah beberapa kali. Jika semua peran dihapus, aplikasi Anda akan tetap diberi tahu dengan daftar peran yang kosong. Notifikasi ini akan mengeluarkan aplikasi Anda dari status dihentikan dan bersama dengan pengecualian yang diberikan untuk aplikasi Anda, aplikasi Anda dapat melakukan bootstrap sendiri tanpa interaksi pengguna. Berkat notifikasi dan pengecualian peran aplikasi, aplikasi Anda dapat memproses siaran ACTION_BOOT_COMPLETED. Jika aplikasi Anda bergantung pada konfigurasi terkelolanya untuk melakukan bootstrap, lihat Menyiapkan konfigurasi terkelola tentang cara membaca dan memproses perubahan.

Mulai AMAPI SDK 1.9.0, setiap peran dalam AppRolesSetRequest juga menyertakan Role.ExtraCapabilities yang diberikan admin IT dalam kebijakan. Misalnya, aplikasi pendamping dapat memeriksa apakah aplikasi tersebut diizinkan untuk mengeluarkan perintah penghapusan total lokal:

import com.google.android.managementapi.approles.model.AppRolesSetRequest
import com.google.android.managementapi.approles.model.AppRolesSetResponse
import com.google.android.managementapi.common.model.Role
...

  override fun onAppRolesSet(request: AppRolesSetRequest): AppRolesSetResponse {
    val canWipeLocally =
      request.roles.any { role ->
        role.roleType == Role.RoleType.COMPANION_APP &&
          role.extraCapabilities.localDeviceWipeCommand ==
            Role.ExtraCapabilities.LocalDeviceWipeCommand.LOCAL_DEVICE_WIPE_COMMAND_ALLOWED
      }
    Log.i(TAG, "onAppRolesSet: canWipeLocally=$canWipeLocally")

    return AppRolesSetResponse.getDefaultInstance()
  }

Hanya admin IT yang dapat memberikan kemampuan tambahan. Jika Anda menetapkan extraCapabilities pada peran yang Anda teruskan ke EnvironmentClient, panggilan akan gagal dengan InvalidArgumentException.

Menyediakan perangkat dengan kebijakan peran aplikasi

Developer aplikasi dapat menguji penetapan peran aplikasi ke aplikasi mereka menggunakan EMM atau mengikuti panduan memulai Android Management API. Notebook Colab AMAPI memungkinkan Anda mendaftarkan perusahaan, membuat kebijakan,dan menyediakan perangkat.

Menetapkan kebijakan untuk aplikasi Anda dengan peran aplikasi

Siapkan policy dengan peran aplikasi yang dimaksudkan untuk aplikasi Anda menggunakan ApplicationPolicy.roles.

Contoh berikut menunjukkan cara mengonfigurasi peran untuk aplikasi MTD:

{
  "applications": [

    {
      "packageName": "com.example.mtd",
      "installType": "FORCE_INSTALLED",
      "roles": [
        { "roleType": "MOBILE_THREAT_DEFENSE_ENDPOINT_DETECTION_RESPONSE" }
      ]
    }
  ]
}

Poin Penting: Aplikasi dapat memiliki beberapa peran, tetapi peran apa pun hanya dapat ditetapkan ke satu aplikasi. Lihat RoleType untuk mengetahui daftar semua peran aplikasi yang tersedia.

Hanya peran COMPANION_APP yang mendukung extraCapabilities. Untuk mengizinkan aplikasi pendamping menghapus total perangkat atau profil kerja secara lokal, tetapkan extraCapabilities.localDeviceWipeCommand ke LOCAL_DEVICE_WIPE_COMMAND_ALLOWED untuk peran tersebut.

Sebelum menetapkan peran seperti yang ditentukan dalam kebijakan, sistem akan memeriksa apakah sidik jari sertifikat kunci penandatanganan aplikasi di perangkat cocok dengan yang ada di Google Play Store. Jika sidik jari berbeda, peran tidak akan ditetapkan ke aplikasi dan ketidakpatuhan NonComplianceReason.APP_SIGNING_CERT_MISMATCH akan dilaporkan ke EMM.

Catatan: Anda dapat menguji berbagai build aplikasi, yang ditandatangani dengan sertifikat yang berbeda, dengan memberikan sidik jari sertifikat kunci penandatanganan tambahan (nilai hash SHA-256 yang dienkode base64 dari sertifikat kunci penandatanganan aplikasi) untuk dibandingkan sebagai berikut:

{
  "applications": [

    {
      "packageName": "com.example.mtd",
      "installType": "FORCE_INSTALLED",
      "signingKeyCerts": [
         { "signingKeyCertFingerprintSha256": "base64-encoded-sha256" }
       ],
      "roles": [
        { "roleType": "MOBILE_THREAT_DEFENSE_ENDPOINT_DETECTION_RESPONSE" }
      ]
    }
  ]
}

Jika aplikasi Anda memiliki konfigurasi terkelola, admin IT dapat menyiapkan konfigurasi awal untuk restriction yang relevan dalam kebijakan aplikasi:

{
  "applications": [

    {
      "packageName": "com.example.mtd",
      "installType": "FORCE_INSTALLED",
      "roles": [
        { "roleType": "MOBILE_THREAT_DEFENSE_ENDPOINT_DETECTION_RESPONSE" }
      ],
      "managedConfiguration": {
        "<key>": "<value>"
      }
    }
  ]
}

Memverifikasi Status Pengecualian Baterai

Aplikasi dengan peran Mobile Threat Defense (MTD) otomatis dikecualikan dari pembatasan daya latar belakang standar. Namun, pengecualian ini diterapkan oleh Bucket Aplikasi Standby, bukan Daftar yang Diizinkan untuk Penggunaan Daya sistem.

Penting: Jika Anda perlu memverifikasi pengecualian terkait MTD, jangan gunakan PowerManager.isIgnoringBatteryOptimizations() karena akan ditampilkan sebagai false. API ini memeriksa Daftar yang Diizinkan untuk Penggunaan Daya, yang akan salah menunjukkan bahwa aplikasi dibatasi.

Untuk memverifikasi apakah pengecualian aplikasi aktif:

import android.app.usage.UsageStatsManager
import android.content.Context

// UsageStatsManager.STANDBY_BUCKET_EXEMPTED is annotated as a @SystemApi. We can redefine it for clarity.
// Define this at the top level of your file, or inside a companion object
private const val STANDBY_BUCKET_EXEMPTED = 5

private fun isAppExemptedFromAppStandbyBucket(): Boolean =
    (getSystemService(Context.USAGE_STATS_SERVICE) as? UsageStatsManager)
        ?.appStandbyBucket == STANDBY_BUCKET_EXEMPTED