إدارة أدوار التطبيقات

تسمح ميزة "أدوار التطبيقات" لمشرف تكنولوجيا المعلومات بمنح امتيازات خاصة لتطبيق مُدار على جهاز يعمل بنظام التشغيل Android. من خلال منح دور معيّن، يمكن إعفاء التطبيق من قيود استهلاك الطاقة والقيود المفروضة على التشغيل في الخلفية، والإيقاف المؤقت، والوضع "السبات" (على Android 14 والإصدارات الأحدث)، وإيقاف عناصر التحكّم الخاصة بالمستخدم (أي إجراءات المستخدم، مثل الإيقاف الإجباري ومحو بيانات التطبيق) (على Android 11 والإصدارات الأحدث)، ما يسمح له بتنفيذ وظيفته الأساسية بدون انقطاع. بالإضافة إلى ذلك، يمكن إشعار التطبيق بأدواره الممنوحة، ما يسمح له بتهيئة نفسه بدون تدخّل من المستخدم.

للاطّلاع على قائمة بأدوار التطبيقات المتاحة والامتيازات الخاصة الممنوحة لكل دور، يُرجى الرجوع إلى RoleType.

المتطلبات الأساسية

يتم إدارة الجهاز من خلال نظام إدارة الخدمات الجوّالة للمؤسسات (EMM) المستند إلى واجهة برمجة التطبيقات AMAPI (لا يتم دعم أنظمة إدارة الخدمات الجوّالة للمؤسسات التي تستخدم وحدة التحكّم بسياسة الجهاز المخصّصة).

إعداد تطبيقك لاستخدام الميزة

لا يكون التكامل مع حزمة تطوير البرامج (SDK) لواجهة برمجة التطبيقات AMAPI مطلوبًا إلا إذا كان التطبيق يريد تلقّي إشعارات بأدواره الممنوحة، ما يسمح له بتهيئة نفسه (أي التشغيل التلقائي بدون تفاعل المستخدم).

دمج حزمة تطوير البرامج (SDK) لواجهة برمجة التطبيقات AMAPI في تطبيقك

يمكنك العثور على مزيد من المعلومات حول حزمة تطوير البرامج (SDK) لواجهة برمجة التطبيقات AMAPI وكيفية إضافتها إلى تطبيقك في دليل تكامل حزمة تطوير البرامج (SDK) لواجهة برمجة التطبيقات AMAPI.

إضافة البيانات الوصفية المطلوبة إلى ملف بيان التطبيق

يحتاج تطبيق Android Device Policy إلى معرفة الـ ComponentName لفئتك التي تنفّذ NotificationReceiverService لإشعار تطبيقك بأدواره الممنوحة. عليك وضع علامة مناسبة على خدمتك في AndroidManifest.xml حتى يتمكّن تطبيق Android Device Policy من اكتشافها تلقائيًا.

• يجب أن يتضمّن تطبيقك خدمة واحدة فقط 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 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 عمليات البث. إذا كان تطبيقك يعتمد على إعداداته المُدارة لتهيئة نفسه، يُرجى الاطّلاع على إعداد الإعدادات المُدارة لمعرفة كيفية قراءة التغييرات والاستماع إليها.

تزويد الجهاز بسياسات أدوار التطبيقات

يمكن لمطوّري التطبيقات اختبار منح أدوار التطبيقات لتطبيقاتهم باستخدام نظام إدارة الخدمات الجوّالة للمؤسسات أو اتّباع دليل البدء السريع لواجهة برمجة التطبيقات Android Management API. تتيح لك ورقة ملاحظات Colab لواجهة برمجة التطبيقات AMAPI تسجيل مؤسسة وإنشاء سياسة وتزويد جهاز.

ضبط السياسة لتطبيقك باستخدام أدوار التطبيقات

يمكنك إعداد policy باستخدام أدوار التطبيقات التي من المفترض أن يحصل عليها تطبيقك باستخدام الـ ApplicationPolicy.roles.

يوضّح المثال التالي كيفية ضبط الدور لتطبيقات Mobile Threat Defense (MTD):

{
  "applications": [

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

قبل منح الأدوار كما هو محدّد في السياسة، سيتحقّق النظام من تطابق الملف المرجعي لشهادة مفتاح توقيع التطبيق على الجهاز مع الملف المرجعي من "متجر Play". إذا كان الملف المرجعي مختلفًا، لن يتم منح الأدوار للتطبيق وسيتم إبلاغ نظام إدارة الخدمات الجوّالة للمؤسسات بعدم الامتثال.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" }
      ]
    }
  ]
}

إذا كان تطبيقك يتضمّن إعدادات مُدارة، يمكن لمشرف تكنولوجيا المعلومات إعداد إعدادات أولية لـ restriction ذات الصلة في سياسة التطبيق:

{
  "applications": [

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

التحقّق من حالة الإعفاء من قيود استهلاك البطارية

يتم تلقائيًا إعفاء التطبيقات التي لها دور Mobile Threat Defense (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