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

اعتبارًا من الإصدار 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

المتطلبات الأساسية لوقت التشغيل

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

• يجب الإفصاح عن أحد الأذونات التالية على الأقل في البيان:

  • CHANGE_NETWORK_STATE
  • CHANGE_WIFI_STATE
  • CHANGE_WIFI_MULTICAST_STATE
  • NFC
  • TRANSMIT_IR

• طلب الحصول على واحد على الأقل من أذونات وقت التشغيل التالية والحصول عليه:

  • BLUETOOTH_CONNECT
  • BLUETOOTH_ADVERTISE
  • BLUETOOTH_SCAN
  • UWB_RANGING

• اتصل على UsbManager.requestPermission().

الوصف

التفاعلات مع الأجهزة الخارجية التي تتطلّب اتصالاً عبر البلوتوث أو تقنية 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

المتطلبات الأساسية لوقت التشغيل

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

• أدخِل الإذن HIGH_SAMPLING_RATE_SENSORS في ملف البيان.

• طلب الحصول على إذن واحد على الأقل من أذونات وقت التشغيل التالية والحصول عليه:

  • ‫BODY_SENSORS على الإصدار 35 من واجهة برمجة التطبيقات والإصدارات الأقدم
  • READ_HEART_RATE
  • READ_SKIN_TEMPERATURE
  • READ_OXYGEN_SATURATION
  • ACTIVITY_RECOGNITION

الوصف

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

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

نوع الخدمة التي تعمل في المقدّمة المطلوب تقديم بيان عنها في البيان ضمن

android:foregroundServiceType

location

الإذن المطلوب تضمينه في بيان التطبيق

FOREGROUND_SERVICE_LOCATION

ثابت يتم تمريره إلى startForeground()

FOREGROUND_SERVICE_TYPE_LOCATION

المتطلبات الأساسية لوقت التشغيل

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

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION

الوصف

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

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

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

الوسائط

نوع الخدمة التي تعمل في المقدّمة التي يجب تقديم بيان عنها في ملف البيان ضمن

android:foregroundServiceType

mediaPlayback

الأذونات المطلوب تضمينها في بيان التطبيق

FOREGROUND_SERVICE_MEDIA_PLAYBACK

الثابت الذي سيتم تمريره إلى startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK

المتطلبات الأساسية لبيئة التشغيل

لا شيء

الوصف

مواصلة تشغيل الصوت أو الفيديو في الخلفية إتاحة وظائف تسجيل الفيديو الرقمي (DVR) على Android TV

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

إذا كنت تعرض فيديو في وضع "نافذة ضمن النافذة"، استخدِم وضع "نافذة ضمن النافذة".

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

نوع الخدمة التي تعمل في المقدّمة المطلوب تقديم بيان عنها في البيان ضمن

android:foregroundServiceType

mediaProcessing

الإذن المطلوب تضمينه في بيان التطبيق

FOREGROUND_SERVICE_MEDIA_PROCESSING

ثابت يتم تمريره إلى startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING

المتطلبات الأساسية لوقت التشغيل

بدون

الوصف

خدمة لتنفيذ عمليات تستغرق وقتًا طويلاً على مواد عرض الوسائط، مثل تحويل الوسائط إلى تنسيقات مختلفة يسمح النظام لهذه الخدمة بوقت محدود للعمل. وفي الظروف العادية، يكون هذا الحدّ الزمني 6 ساعات من كل 24 ساعة. (تتم مشاركة هذا الحدّ بين جميع خدمات mediaProcessing التي تعمل في المقدّمة في التطبيق).

يجب أن يوقف تطبيقك يدويًا خدمة معالجة الوسائط في السيناريو التالي:

• عند اكتمال عملية تحويل الترميز أو وصولها إلى حالة تعذُّر، اطلب من العميل الاتصال بخدمة Service.stopForeground() وService.stopSelf() لإيقاف الخدمة بالكامل.

في حال بلوغ فترة المهلة، يستدعي النظام طريقة Service.onTimeout(int, int) في الخدمة. في هذه اللحظة، تتوفّر للخدمة بضع ثواني للاتصال بالرقم Service.stopSelf(). إذا لم تطلب الخدمة Service.stopSelf()، سيحدث خطأ ANR مع ظهور رسالة الخطأ التالية: "لم يتم إيقاف الخدمة التي تعمل في المقدّمة من النوع <fgs_type> خلال مهلة الانتظار: <component_name>".

ملاحظة: لا تتوفّر Service.onTimeout(int, int) على الإصدار 14 من نظام التشغيل Android أو الإصدارات الأقدم. على الأجهزة التي تعمل بالإصدارات السابقة، إذا انتهت مهلة خدمة معالجة الوسائط، يُخزِّن النظام التطبيق في ذاكرة التخزين المؤقت على الفور. لهذا السبب، يجب ألا ينتظر تطبيقك تلقّي إشعار بانتهاء المهلة. بدلاً من ذلك، يجب إنهاء الخدمة التي تعمل في المقدّمة أو تغييرها إلى خدمة تعمل في الخلفية في أقرب وقت ممكن.

عرض الوسائط

نوع الخدمة التي تعمل في المقدّمة التي يجب تقديم بيان عنها في ملف البيان ضمن

android:foregroundServiceType

mediaProjection

الأذونات المطلوب تضمينها في بيان التطبيق

FOREGROUND_SERVICE_MEDIA_PROJECTION

الثابت الذي سيتم تمريره إلى startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION

المتطلبات الأساسية لبيئة التشغيل

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

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

الوصف

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

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

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

الميكروفون

نوع الخدمة التي تعمل في المقدّمة التي يجب تقديم بيان عنها في ملف البيان ضمن

android:foregroundServiceType

microphone

الأذونات المطلوب تضمينها في بيان التطبيق

FOREGROUND_SERVICE_MICROPHONE

الثابت الذي سيتم تمريره إلى startForeground()

FOREGROUND_SERVICE_TYPE_MICROPHONE

المتطلبات الأساسية لبيئة التشغيل

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

الوصف

مواصلة تسجيل الصوت باستخدام الميكروفون في الخلفية، مثل تطبيقات تسجيل الصوت أو تطبيقات التواصل

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

نوع الخدمة التي تعمل في المقدّمة التي يجب تقديم بيان عنها في ملف البيان ضمن

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

المتطلبات الأساسية لوقت التشغيل

لا شيء

الوصف

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

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

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

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

  وإلا، سيؤدي تعريف هذا النوع إلى عرض النظام للسمة ForegroundServiceTypeNotAllowedException.

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

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