يجب إدراج أنواع الخدمات التي تعمل في المقدّمة.

To help developers be more intentional with defining user-facing foreground services, Android 10 introduced the android:foregroundServiceType attribute within the <service> element.

If your app targets Android 14, it must specify appropriate foreground service types. As in previous versions of Android, multiple types can be combined. This list shows the foreground service types to choose from:

If a use case in your app isn't associated with any of these types, we strongly recommend that you migrate your logic to use WorkManager or user-initiated data transfer jobs.

The health, remoteMessaging, shortService, specialUse, and systemExempted types are new in Android 14.

The following code snippet provides an example of a foreground service type declaration in the manifest:

<manifest ...>
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
    <application ...>
      <service
          android:name=".MyMediaPlaybackService"
          android:foregroundServiceType="mediaPlayback"
          android:exported="false">
      </service>
    </application>
</manifest>

If an app that targets Android 14 doesn't define types for a given service in the manifest, then the system will raise MissingForegroundServiceTypeException upon calling startForeground() for that service.

طلب الحصول على إذن جديد لاستخدام أنواع الخدمات التي تعمل في المقدّمة

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

يتم تعريف جميع الأذونات على أنها أذونات عادية ويتم منحها بشكل افتراضي. ولا يمكن للمستخدمين إبطال هذه الأذونات.

تضمين نوع الخدمة التي تعمل في المقدّمة في وقت التشغيل

The best practice for applications starting foreground services is to use the ServiceCompat version of startForeground() (available in androidx-core 1.12 and higher) where you pass in a bitwise integer of foreground service types. You can choose to pass one or more type values.

Usually, you should declare only the types required for a particular use case. This makes it easier to meet the system's expectations for each foreground service type. In cases where a foreground service is started with multiple types, then the foreground service must adhere to the platform enforcement requirements of all types.

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

If the foreground service type is not specified in the call, the type defaults to the values defined in the manifest. If you didn't specify the service type in the manifest, the system throws MissingForegroundServiceTypeException.

If the foreground service needs new permissions after you launch it, you should call startForeground() again and add the new service types. For example, suppose a fitness app runs a running-tracker service that always needs location information, but might or might not need media permissions. You would need to declare both location and mediaPlayback in the manifest. If a user starts a run and just wants their location tracked, your app should call startForeground() and pass just the location service type. Then, if the user wants to start playing audio, call startForeground() again and pass location|mediaPlayback.

عمليات التحقّق في وقت تشغيل النظام

The system checks for proper use of foreground service types and confirms that the app has requested the proper runtime permissions or uses the required APIs. For instance, the system expects apps that use the foreground service type FOREGROUND_SERVICE_TYPE_LOCATION type to request either ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION.

This implies that apps must follow a very specific order of operations when requesting permissions from the user and starting foreground services. Permissions must be requested and granted before the app attempts to call startForeground(). Apps that request the appropriate permissions after the foreground service has been started must change this order of operations and request the permission before starting the foreground service.

The specifics of platform enforcement appear in the sections labeled "runtime requirements" in the intended use cases and enforcement for each foreground service type section on this page.

حالات الاستخدام المقصودة وإجراءات التنفيذ لكل نوع من أنواع الخدمات التي تعمل في المقدّمة

لاستخدام نوع معيّن من الخدمات التي تعمل في المقدّمة، يجب الإفصاح عن إذن معيّن في ملف البيان، كما يجب استيفاء متطلبات محدّدة لوقت التشغيل، كما يجب أن يستوفي تطبيقك إحدى مجموعات حالات الاستخدام المقصودة لهذا النوع. توضح الأقسام التالية الإذن الذي يجب تعريفه والمتطلبات الأساسية لوقت التشغيل وحالات الاستخدام المقصودة لكل نوع.

الكاميرا

نوع الخدمة التي تعمل في المقدّمة سيتم الإفصاح عنها في ملف البيان بموجب android:foregroundServiceType
camera
إذن التعريف في بيانك
FOREGROUND_SERVICE_CAMERA
تمرير مستمر إلى startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
المتطلبات الأساسية لوقت التشغيل

طلب إذن تشغيل CAMERA ومنحه

ملاحظة: يخضع إذن التشغيل "CAMERA" للقيود المفروضة أثناء الاستخدام. لهذا السبب، لا يمكنك إنشاء خدمة camera تعمل في المقدّمة أثناء تشغيل تطبيقك في الخلفية، مع بعض الاستثناءات. لمزيد من المعلومات، يمكنك الاطّلاع على مقالة القيود المفروضة على تشغيل الخدمات التي تعمل في المقدّمة والتي تحتاج إلى أذونات أثناء الاستخدام.

الوصف

مواصلة الوصول إلى الكاميرا في الخلفية، مثل تطبيقات محادثات الفيديو التي تتيح تعدُّد المهام

جهاز متّصل

نوع الخدمة التي تعمل في المقدّمة ليتم الإفصاح عنها في ملف البيان بموجب
android:foregroundServiceType
connectedDevice
إذن التعريف في بيانك
FOREGROUND_SERVICE_CONNECTED_DEVICE
تمرير مستمر إلى startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
المتطلبات الأساسية لوقت التشغيل

يجب أن يكون أحد الشروط التالية صحيحًا على الأقل:

الوصف

التفاعلات مع الأجهزة الخارجية التي تتطلب اتصال عبر البلوتوث أو تقنية NFC أو IR أو USB أو اتصال بالشبكة.

الحلول البديلة

إذا كان تطبيقك يحتاج إلى نقل البيانات باستمرار إلى جهاز خارجي، يمكنك استخدام أداة إدارة الأجهزة المصاحبة بدلاً من ذلك. استخدِم واجهة برمجة التطبيقات لتواجد الجهاز المصاحب للمساعدة في استمرار تشغيل تطبيقك عندما يكون الجهاز المصاحب داخل النطاق.

إذا كان تطبيقك يحتاج إلى البحث عن أجهزة تتضمّن بلوتوث، يمكنك استخدام واجهة برمجة التطبيقات للمسح الضوئي عبر البلوتوث بدلاً من ذلك.

مزامنة البيانات

نوع الخدمة التي تعمل في المقدّمة ليتم الإفصاح عنها في ملف البيان بموجب
android:foregroundServiceType
dataSync
إذن التعريف في بيانك
FOREGROUND_SERVICE_DATA_SYNC
تمرير مستمر إلى startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
المتطلبات الأساسية لوقت التشغيل
لا شيء
الوصف

عمليات نقل البيانات مثل ما يلي:

  • تحميل البيانات أو تنزيلها
  • عمليات النسخ الاحتياطي والاستعادة
  • عمليات الاستيراد أو التصدير
  • استرجاع البيانات
  • معالجة الملفات المحلية
  • نقل البيانات بين جهاز والسحابة الإلكترونية عبر إحدى الشبكات
الحلول البديلة

راجِع بدائل الخدمات التي تعمل في المقدّمة لمزامنة البيانات للحصول على معلومات مفصّلة.

الحالة

Foreground service type to declare in manifest under
android:foregroundServiceType
health
Permission to declare in your manifest
FOREGROUND_SERVICE_HEALTH
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
Runtime prerequisites

At least one of the following conditions must be true:

Note: The BODY_SENSORS runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a health foreground service that uses body sensors while your app is in the background, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Any long-running use cases to support apps in the fitness category such as exercise trackers.

الموقع الجغرافي

Foreground service type to declare in manifest under
android:foregroundServiceType
location
Permission to declare in your manifest
FOREGROUND_SERVICE_LOCATION
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
Runtime prerequisites

The user must have enabled location services and the app must be granted at least one of the following runtime permissions:

Note: In order to check that the user has enabled location services as well as granted access to the runtime permissions, use PermissionChecker#checkSelfPermission()

Note: The location runtime permissions are subject to while-in-use restrictions. For this reason, you cannot create a location foreground service while your app is in the background, unless you've been granted the ACCESS_BACKGROUND_LOCATION runtime permission. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Long-running use cases that require location access, such as navigation and location sharing.

Alternatives

If your app needs to be triggered when the user reaches specific locations, consider using the geofence API instead.

الوسائط

نوع الخدمة التي تعمل في المقدّمة ليتم الإفصاح عنها في ملف البيان بموجب
android:foregroundServiceType
mediaPlayback
إذن التعريف في بيانك
FOREGROUND_SERVICE_MEDIA_PLAYBACK
تمرير مستمر إلى startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
المتطلبات الأساسية لوقت التشغيل
لا شيء
الوصف
استمر في تشغيل الصوت أو الفيديو في الخلفية. إتاحة وظيفة تسجيل الفيديو الرقمي (DVR) على Android TV
الحلول البديلة
إذا كنت تعرض فيديو في وضع "نافذة ضمن النافذة"، استخدِم وضع "نافذة ضمن النافذة".

عرض الوسائط

نوع الخدمة التي تعمل في المقدّمة ليتم الإفصاح عنها في ملف البيان بموجب
android:foregroundServiceType
mediaProjection
إذن التعريف في بيانك
FOREGROUND_SERVICE_MEDIA_PROJECTION
تمرير مستمر إلى startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
المتطلبات الأساسية لوقت التشغيل

عليك استدعاء طريقة createScreenCaptureIntent() قبل بدء الخدمة التي تعمل في المقدّمة. يؤدي إجراء ذلك إلى عرض إشعار للمستخدم بالإذن؛ يجب أن يمنحه المستخدم الإذن قبل أن تتمكن من إنشاء الخدمة.

بعد إنشاء الخدمة التي تعمل في المقدّمة، يمكنك طلب الرمز MediaProjectionManager.getMediaProjection().

الوصف

عرض المحتوى على جهاز عرض غير أساسي أو جهاز خارجي باستخدام واجهات برمجة تطبيقات MediaProjection ليس من الضروري أن يكون هذا المحتوى عبارة عن محتوى وسائط حصريًا.

الحلول البديلة

لبث الوسائط إلى جهاز آخر، يمكنك استخدام Google Cast SDK.

الميكروفون

Foreground service type to declare in manifest under
android:foregroundServiceType
microphone
Permission to declare in your manifest
FOREGROUND_SERVICE_MICROPHONE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
Runtime prerequisites

Request and be granted the RECORD_AUDIO runtime permission.

Note: The RECORD_AUDIO runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a microphone foreground service while your app is in the background, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Continue microphone capture from the background, such as voice recorders or communication apps.

مكالمة هاتفية

نوع الخدمة التي تعمل في المقدّمة ليتم الإفصاح عنها في ملف البيان بموجب
android:foregroundServiceType
phoneCall
إذن التعريف في بيانك
FOREGROUND_SERVICE_PHONE_CALL
تمرير مستمر إلى startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
المتطلبات الأساسية لوقت التشغيل

يجب أن يكون أحد هذه الشروط على الأقل صحيحًا:

  • أعلن التطبيق عن إذن MANAGE_OWN_CALLS في ملف البيان الخاص به.
  • سيكون التطبيق هو تطبيق برنامج الاتصال التلقائي الذي يظهر من خلال دور ROLE_DIALER.
الوصف

متابعة مكالمة جارية باستخدام واجهات برمجة التطبيقات في ConnectionService.

الحلول البديلة

وإذا كنت بحاجة إلى إجراء مكالمات هاتفية أو مكالمات فيديو أو مكالمات عبر بروتوكول VoIP، يمكنك استخدام مكتبة android.telecom.

ننصحك باستخدام CallScreeningService لفحص المكالمات.

المراسلة عن بُعد

نوع الخدمة التي تعمل في المقدّمة ليتم الإفصاح عنها في ملف البيان بموجب
android:foregroundServiceType
remoteMessaging
إذن التعريف في بيانك
FOREGROUND_SERVICE_REMOTE_MESSAGING
تمرير مستمر إلى startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
المتطلبات الأساسية لوقت التشغيل
لا شيء
الوصف
يمكنك نقل الرسائل النصية من جهاز إلى آخر. يساعد في استمرار مهام المراسلة للمستخدم عند تبديل الأجهزة.

خدمة قصيرة

نوع الخدمة التي تعمل في المقدّمة ليتم الإفصاح عنها في ملف البيان بموجب
android:foregroundServiceType
shortService
إذن التعريف في بيانك
لا شيء
تمرير مستمر إلى startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
المتطلبات الأساسية لوقت التشغيل
لا شيء
الوصف

إنهاء العمل المهم الذي لا يمكن مقاطعته أو تأجيله بسرعة.

يتميز هذا النوع ببعض الخصائص الفريدة:

  • لا يمكن عرضها إلا لفترة زمنية قصيرة (حوالي 3 دقائق).
  • ما مِن دعم للخدمات التي تعمل في المقدّمة الثابتة.
  • يتعذّر بدء الخدمات الأخرى التي تعمل في المقدّمة.
  • ولا يتطلّب ذلك إذنًا خاصًا بالنوع، ولكنّه لا يزال يتطلب إذن FOREGROUND_SERVICE.
  • ولا يمكن تغيير "shortService" إلى نوع خدمة آخر إلا إذا كان التطبيق مؤهّلًا حاليًا لبدء خدمة جديدة تعمل في المقدّمة.
  • يمكن للخدمة التي تعمل في المقدّمة تغيير نوعها إلى shortService في أي وقت، عند بدء فترة المهلة.

تبدأ مهلة ShortService من لحظة استدعاء Service.startForeground(). ومن المتوقّع أن يطلب التطبيق الرمز Service.stopSelf() أو Service.stopForeground() قبل انتهاء المهلة. وبخلاف ذلك، سيتم تسمية Service.onTimeout() الجديد، ما يمنح التطبيقات فرصة قصيرة للاتصال بـ stopSelf() أو stopForeground() لإيقاف الخدمة.

بعد فترة قصيرة من استدعاء Service.onTimeout()، يدخل التطبيق حالة ذاكرة التخزين المؤقت ولا يتم اعتباره في المقدّمة، ما لم يتفاعل المستخدم بشكل نشط مع التطبيق. وبعد فترة قصيرة من تخزين التطبيق مؤقتًا وعدم توقف الخدمة، يتلقّى التطبيق خطأ ANR. وتشير رسالة ANR إلى FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. ولهذه الأسباب، يُعتبر تنفيذ Service.onTimeout() معاودة الاتصال بالاستناد إلى أفضل الممارسات.

لا تتوفّر ميزة معاودة الاتصال بـ "Service.onTimeout()" على نظام التشغيل Android 13 والإصدارات الأقدم. في حال تشغيل الخدمة نفسها على مثل هذه الأجهزة، لن تتلقى مهلة أو خطأ ANR. يجب التأكّد من إيقاف الخدمة فور انتهاء عملية المعالجة، حتى إذا لم تتلقَّ معاودة الاتصال بـ "Service.onTimeout()" بعد.

يُرجى العِلم أنّه في حال عدم الالتزام بانتهاء مهلة shortService، سيحدث خطأ ANR حتى في حال تشغيل خدمات أخرى صالحة تعمل في المقدّمة أو غير ذلك من عمليات مراحل نشاط التطبيق.

إذا كان التطبيق مرئيًا للمستخدم أو يستوفي أحد الاستثناءات التي تسمح ببدء الخدمات التي تعمل في المقدّمة من الخلفية، سيؤدي استدعاء Service.StartForeground() مرة أخرى باستخدام معلَمة FOREGROUND_SERVICE_TYPE_SHORT_SERVICE إلى تمديد المهلة بمقدار 3 دقائق أخرى. إذا لم يكن التطبيق مرئيًا للمستخدم ولم يستوفِ أحد الاستثناءات، ستؤدي أي محاولة لبدء خدمة أخرى تعمل في المقدّمة، بغض النظر عن نوعها، إلى حدوث ForegroundServiceStartNotAllowedException.

إذا أوقف أحد المستخدمين ميزة تحسين البطارية لتطبيقك، سيظلّ متأثّرًا بانتهاء مهلة ShortService FGS.

إذا بدأت خدمة تعمل في المقدّمة تتضمّن النوع shortService ونوعًا آخر من هذه الخدمات، يتجاهل النظام تعريف النوع shortService. ومع ذلك، يجب أن تلتزم الخدمة بالمتطلبات الأساسية للأنواع الأخرى المعلَن عنها. لمزيد من المعلومات، راجع مستندات الخدمات التي تعمل في المقدّمة.

استخدام خاص

نوع الخدمة التي تعمل في المقدّمة للإفصاح عنها في البيان ضمن
android:foregroundServiceType
specialUse
إذن بالبيان في بيان التطبيق
FOREGROUND_SERVICE_SPECIAL_USE
ثابت يتم تمريره إلى startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
المتطلّبات الأساسية لبيئة التشغيل
ما مِن قيمة محدّدة
الوصف

تشمل أي حالات استخدام صالحة للخدمة التي تعمل في المقدّمة ولا تغطيها أنواع الخدمات التي تعمل في المقدّمة.

بالإضافة إلى تقديم بيان عن FOREGROUND_SERVICE_TYPE_SPECIAL_USE نوع الخدمة التي تعمل في المقدّمة، على المطوّرين تقديم بيان عن حالات الاستخدام في ملف FOREGROUND_SERVICE_TYPE_SPECIAL_USE البيان. ولإجراء ذلك، يحددون عنصر <property> في <service>. تُعد هذه القيم وحالات الاستخدام المقابلة أن تتم مراجعتها عند إرسال تطبيقك في Google Play Console. الاستخدام الحالات التي تقدمها تكون حرة الشكل، ويجب أن تتأكد من توفير ما يكفي من للسماح للمراجع بمعرفة سبب احتياجك إلى استخدام specialUse الكتابة.

<service android:name="fooService" android:foregroundServiceType="specialUse">
  <property android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
      android:value="explanation_for_special_use"/>
</service>

تم استثناء النظام

نوع الخدمة التي تعمل في المقدّمة للإفصاح عنها في البيان ضمن
android:foregroundServiceType
systemExempted
إذن بالبيان في بيان التطبيق
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
ثابت للتمرير إلى startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
المتطلّبات الأساسية لبيئة التشغيل
ما مِن قيمة محدّدة
الوصف

محجوزة لتطبيقات النظام وعمليات تكامل النظام المحددة، مواصلة استخدام الخدمات التي تعمل في المقدّمة

ولاستخدام هذا النوع، يجب أن يستوفي التطبيق معيارًا واحدًا على الأقل من المعايير التالية:

  • الجهاز في حالة الوضع التجريبي
  • التطبيق هو مالك الجهاز
  • التطبيق مالك الملف الشخصي
  • تطبيقات الأمان التي لها دور ROLE_EMERGENCY
  • تطبيقات مشرف الجهاز
  • التطبيقات التي تحتفظ SCHEDULE_EXACT_ALARM أو إذن USE_EXACT_ALARM ويستخدم الخدمة التي تعمل في المقدّمة لمتابعة المنبّهات في الخلفية بما في ذلك المنبّهات التي تعمل باللمس فقط.

  • تطبيقات الشبكة الافتراضية الخاصة (التي تم ضبطها باستخدام الإعدادات > الشبكة والإنترنت > الشبكة الافتراضية الخاصة)

    وإلا فإن الإعلان عن هذا النوع يجعل النظام يطرح ForegroundServiceTypeNotAllowedException

فرض سياسات Google Play في ما يتعلّق باستخدام أنواع الخدمات التي تعمل في المقدّمة

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