مدیریت نقش‌های برنامه

ویژگی نقش‌های برنامه به سرپرست فناوری اطلاعات اجازه می‌دهد تا امتیازات ویژه‌ای به برنامه مدیریت‌شده در دستگاه Android اعطا کند. با اختصاص دادن یک نقش خاص، برنامه می‌تواند از محدودیت‌های مصرف انرژی و پس‌زمینه، تعلیق، و خواب زمستانی (در Android نسخه ۱۴ و بالاتر) معاف شود و کنترل‌های کاربر (یعنی کنش‌های کاربر مثل توقف اجباری و پاک کردن داده‌های برنامه) برای آن غیرفعال شود (در Android نسخه ۱۱ و بالاتر) تا بتواند عملکرد حیاتی خود را بدون وقفه انجام دهد. علاوه‌براین، برنامه می‌تواند از نقش‌های اختصاص‌داده‌شده به آن مطلع شود، که به آن اجازه می‌دهد بدون دخالت کاربر، خود را راه‌اندازی کند.

برای مشاهده فهرست نقش‌های موجود برنامه و امتیازات ویژه‌ای که به هر نقش اعطا شده است، به RoleType مراجعه کنید.

پیش‌نیازها

دستگاه توسط EMM مبتنی بر AMAPI مدیریت می‌شود (EMMهایی که از DPC سفارشی استفاده می‌کنند پشتیبانی نمی‌شوند).

آماده کردن برنامه برای استفاده از این ویژگی

ادغام با کیت توسعه نرم‌افزار AMAPI فقط درصورتی لازم است که برنامه بخواهد از نقش‌های اختصاص‌یافته به آن مطلع شود تا بتواند خودش را راه‌اندازی کند (یعنی راه‌اندازی خودکار بدون تعامل کاربر).

ادغام کردن با AMAPI SDK در برنامه

می‌توانید اطلاعات بیشتر درباره AMAPI SDK و نحوه افزودن آن به برنامه‌تان را در راهنمای ادغام AMAPI SDK پیدا کنید.

فراداده لازم را به مانیفست برنامه اضافه کنید

«خط‌مشی دستگاه Android» باید ComponentName کلاس شما را بداند که NotificationReceiverService را برای مطلع کردن برنامه‌تان از نقش‌های اختصاص‌داده‌شده به آن پیاده‌سازی می‌کند. باید سرویس خود را در AndroidManifest.xml به‌طور مناسب برچسب‌گذاری کنید تا بتواند به‌طور خودکار توسط ADP شناسایی شود.

  • برنامه شما باید دقیقاً یک سرویس داشته باشد که enabled است و meta-data با android:name برابر با com.google.android.managementapi.notification.NotificationReceiverService.SERVICE_APP_ROLES دارد
  • این سرویس باید android:exported را روی true تنظیم کرده باشد
  • android:value مربوط به meta-data باید روی رشته خالی تنظیم شود
<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» بتواند به‌روزرسانی‌های وضعیت فرمان محلی را به برنامه‌تان ارسال کند:

<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 شامل 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()
  }

فقط سرپرست فناوری اطلاعات می‌تواند قابلیت‌های اضافی را اعطا کند. اگر extraCapabilities را در نقشی که به EnvironmentClient منتقل می‌کنید تنظیم کنید، تماس با InvalidArgumentException ناموفق می‌شود.

آماده‌سازی دستگاه با خط‌مشی‌های نقش برنامه

توسعه‌دهندگان نرم‌افزار می‌توانند بااستفاده از EMM یا با دنبال کردن شروع سریع Android Management API، اختصاص دادن نقش‌های برنامه به برنامه‌شان را آزمایش کنند. دفترچه Colab مربوط به AMAPI به شما امکان می‌دهد شرکتی را ثبت‌نام کنید، خط‌مشی ایجاد کنید، و دستگاهی را آماده‌سازی کنید.

تنظیم خط‌مشی برای برنامه با نقش‌های برنامه

policy را با نقش‌های برنامه‌ای که برنامه شما قرار است داشته باشد بااستفاده از ApplicationPolicy.roles راه‌اندازی کنید.

مثال زیر نحوه پیکربندی نقش برای برنامه‌های 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» مطابقت داشته باشد. اگر اثر انگشت متفاوت باشد، نقش‌ها به برنامه اختصاص داده نخواهند شد و NonComplianceReason.APP_SIGNING_CERT_MISMATCH عدم‌رعایت به EMM گزارش خواهد شد.

{
  "applications": [

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

اگر برنامه‌تان پیکربندی مدیریت‌شده دارد، سرپرست فناوری اطلاعات می‌تواند پیکربندی اولیه‌ای برای 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