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

بدءًا من الإصدار 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 أو IR أو 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
المتطلبات الأساسية لوقت التشغيل
لا ينطبق
الوصف

مواصلة تشغيل الصوت أو الفيديو في الخلفية أن تتيح وظائف تسجيل الفيديو الرقمي (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) على نظام التشغيل Android 14 أو الإصدارات الأقدم. على الأجهزة التي تعمل بهذه الإصدارات، إذا وصلت خدمة معالجة الوسائط إلى مدة المهلة، يخزّن النظام التطبيق على الفور في ذاكرة التخزين المؤقت. لهذا السبب، من المفترض ألا ينتظر تطبيقك تلقّي إشعار انتهاء المهلة. بدلاً من ذلك، يجب إنهاء الخدمة التي تعمل في المقدّمة أو تغييرها إلى خدمة تعمل في الخلفية في أقرب وقت ممكن.

عرض الوسائط

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

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

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

الوصف

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

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

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

الميكروفون

نوع الخدمة التي تعمل في المقدّمة المطلوب تقديم بيان عنه في البيان ضمن
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

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

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