管理應用程式角色

IT 管理員可透過應用程式角色功能,將特殊權限授予 Android 裝置上的受管理應用程式。指派特定角色後,應用程式可免受電源和背景限制、暫停、休眠 (Android 14 以上版本) 的影響,並停用使用者控制項 (即強制停止和清除應用程式資料等使用者動作) (Android 11 以上版本),以便不中斷地執行重要功能。此外,應用程式可以收到指派角色的通知,以便在不需使用者介入的情況下自行啟動。

如需可用應用程式角色和各角色授予的特殊權限清單,請參閱 RoleType。

必要條件

裝置由以 AMAPI 為基礎的 EMM 管理 (不支援使用自訂 DPC 的 EMM)。

準備應用程式以使用這項功能

只有在應用程式需要接收指派角色的通知,以便自行啟動 (即在沒有使用者互動的情況下自動啟動) 時,才需要整合 AMAPI SDK。

在應用程式中整合 AMAPI SDK

如要進一步瞭解 AMAPI SDK,以及如何將其新增至應用程式,請參閱 AMAPI SDK 整合指南。

在應用程式資訊清單中新增必要的中繼資料

Android Device Policy (ADP) 需要知道實作 NotificationReceiverService 的類別 ComponentName,才能通知應用程式其指派的角色。您必須在 AndroidManifest.xml 中適當標記服務,以便 ADP 自動探索。

  • 應用程式必須只有一項服務,即 enabled,且 meta-data 的 android:name 等於 com.google.android.managementapi.notification.NotificationReceiverService.SERVICE_APP_ROLES
  • 這項服務必須將 android:exported 設為 true
  • meta-data 的 android:value 必須設為空白字串
<service
 android:name=".MyNotificationReceiverService"
 android:exported="true">
    <meta-data android:name="com.google.android.managementapi.notification.NotificationReceiverService.SERVICE_APP_ROLES" android:value="" />
</service>

如果您要測試 COMPANION_APP 角色,也應在服務中新增下列 meta-data,以便 Android Device Policy 將本機指令狀態更新傳送至應用程式:

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

建立擴充 NotificationReceiverService 的服務 (或更新現有服務)

建立或更新現有的 NotificationReceiverService,並實作 AppRolesListener,監聽指派給應用程式的角色。如要監聽指派給應用程式的角色,只需 getAppRolesListener() 即可。如果應用程式獲派 COMPANION_APP 角色,您也應實作 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"
  }
}

如果應用程式的角色多次變更,可能會多次收到通知。如果所有角色都遭到移除,應用程式仍會收到空白角色清單的通知。這項通知會讓應用程式脫離停止狀態,並授予應用程式豁免權,讓應用程式在沒有任何使用者互動的情況下自行啟動。有了應用程式角色通知和豁免,應用程式就能監聽 ACTION_BOOT_COMPLETED 廣播。如果應用程式需要受管理的設定才能啟動,請參閱「設定受管理的設定」,瞭解如何讀取及監聽變更。

從 AMAPI SDK 1.9.0 開始,AppRolesSetRequest 中的每個角色也包含 IT 管理員在政策中授予的 Role.ExtraCapabilities。舉例來說,隨附應用程式可以檢查是否允許發出本機抹除指令:

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()
  }

只有 IT 管理員可以授予額外功能。如果您在傳遞至 EnvironmentClient 的角色上設定 extraCapabilities,呼叫會失敗並傳回 InvalidArgumentException。

使用應用程式角色政策佈建裝置

應用程式開發人員可以使用 EMM,或按照 Android Management API 快速入門導覽課程,測試為應用程式指派應用程式角色。AMAPI Colab 筆記本可讓您註冊企業、建立政策及佈建裝置。

使用應用程式角色設定應用程式政策

使用 ApplicationPolicy.roles,設定 policy,並加入應用程式應具備的角色。

以下範例說明如何設定 MTD 應用程式的角色:

{
  "applications": [

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

只有 COMPANION_APP 角色支援 extraCapabilities。如要允許隨附應用程式在本機抹除裝置或工作資料夾,請將該角色的 extraCapabilities.localDeviceWipeCommand 設為 LOCAL_DEVICE_WIPE_COMMAND_ALLOWED。

系統會先確認裝置上的應用程式簽署金鑰憑證指紋與 Play 商店中的指紋相符,再按照政策指定的方式指派角色。如果指紋不同,系統就不會將角色指派給應用程式,並向 EMM 回報 NonComplianceReason.APP_SIGNING_CERT_MISMATCH 不符合規定。

{
  "applications": [

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

如果應用程式有受管理的設定,IT 管理員可以在應用程式政策中,為相關的 restriction 設定初始設定:

{
  "applications": [

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

確認電池豁免狀態

具備行動威脅防禦 (MTD) 角色的應用程式,會自動豁免標準背景用電限制。不過,這項豁免是由應用程式待命值區實施,而非系統的電源許可清單。

如要確認應用程式豁免是否有效,請按照下列步驟操作:

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