أنواع الخدمات التي تعمل في المقدّمة

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

الكاميرا

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

طلب إذن وقت التشغيل CAMERA والحصول عليه

الوصف

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

جهاز متّصل

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

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

الوصف

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

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

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

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

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

要在清单中声明的前台服务类型，位于
android:foregroundServiceType
dataSync
要在清单中声明的权限
FOREGROUND_SERVICE_DATA_SYNC
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_DATA_SYNC
运行时前提条件
无
说明

数据传输操作，例如：

  • 数据上传或下载
  • 备份和恢复操作
  • 导入或导出操作
  • 获取数据
  • 本地文件处理
  • 通过网络在设备和云端之间传输数据
替代方案

如需了解详情，请参阅数据同步前台服务的替代方案。

الصحة

نوع الخدمة التي تعمل في المقدّمة المطلوب تقديم بيان عنه في البيان ضمن
android:foregroundServiceType
health
الإذن المطلوب تضمينه في بيان التطبيق
FOREGROUND_SERVICE_HEALTH
ثابت يتم تمريره إلى startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
المتطلبات الأساسية لوقت التشغيل

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

الوصف

أيّ حالات استخدام طويلة الأمد لتفعيل التطبيقات في فئة اللياقة البدنية، مثل أجهزة تتبُّع التمارين الرياضية

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

نوع الخدمة التي تعمل في المقدّمة المطلوب تقديم بيان عنها في البيان ضمن
android:foregroundServiceType
location
الإذن المطلوب تضمينه في بيان التطبيق
FOREGROUND_SERVICE_LOCATION
ثابت يتم تمريره إلى startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
المتطلبات الأساسية لوقت التشغيل

يجب أن يكون المستخدم قد فعّل خدمات الموقع الجغرافي وأن يتم منح التطبيق إذن تشغيل واحدًا على الأقل من الأذونات التالية:

الوصف

حالات الاستخدام التي تستغرق وقتًا طويلاً وتتطلّب الوصول إلى الموقع الجغرافي، مثل التنقّل ومشاركة الموقع الجغرافي

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

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

الوسائط

要在清单中声明的前台服务类型，位于
android:foregroundServiceType
mediaPlayback
要在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PLAYBACK
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
运行时前提条件
无
说明

在后台继续播放音频或视频。在 Android TV 上支持数字视频录制 (DVR) 功能。

替代方案

如果您要显示画中画视频，请使用画中画模式。

جارٍ معالجة الوسائط

Foreground service type to declare in manifest under
android:foregroundServiceType
mediaProcessing
Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PROCESSING
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
Runtime prerequisites
None
Description

Service for performing time-consuming operations on media assets, like converting media to different formats. The system allows this service a limited time to run; under normal circumstances, this time limit would be 6 hours out of every 24. (This limit is shared by all of an app's mediaProcessing foreground services.)

Your app should manually stop the media processing service in the following scenario:

If the timeout period is reached, the system calls the service's Service.onTimeout(int, int) method. At this time, the service has a few seconds to call Service.stopSelf(). If the service does not call Service.stopSelf(), an ANR will occur with this error message: "A foreground service of <fgs_type> did not stop within its timeout: <component_name>".

Note: Service.onTimeout(int, int) is not available on Android 14 or lower. On devices running those versions, if a media processing service reaches the timeout period, the system immediately caches the app. For this reason, your app shouldn't wait to get a timeout notification. Instead, it should terminate the foreground service or change it to a background service as soon as appropriate.

عرض الوسائط

要在清单中声明的前台服务类型，位于
android:foregroundServiceType
mediaProjection
要在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PROJECTION
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
运行时前提条件

在启动前台服务之前，调用 createScreenCaptureIntent() 方法。这样做会向用户显示权限通知；用户必须授予权限，您才能创建服务。

创建前台服务后，您可以调用 MediaProjectionManager.getMediaProjection()。

说明

使用 MediaProjection API 将内容投影到非主要显示屏或外部设备。这些内容不必全都为媒体内容。

替代方案

如需将媒体内容流式传输到其他设备，请使用 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.

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() callback من أفضل الممارسات.

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

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

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

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

إذا بدأت خدمة تعمل في المقدّمة تتضمّن نوع 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
运行时前提条件
无
说明

为系统应用和特定系统集成预留，以便继续使用前台服务。

如需使用此类型，应用必须至少满足以下条件之一：

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

如果您的应用以 Android 14 或更高版本为目标平台，您需要在 Play 管理中心的“应用内容”页面（政策 > 应用内容）中声明应用的前台服务类型。如需详细了解如何在 Play 管理中心内声明前台服务类型，请参阅了解前台服务和全屏 intent 要求。