انتهاء مهلة الخدمة التي تعمل في المقدّمة

إذا كان التطبيق يستهدف الإصدار 15 من نظام التشغيل Android أو إصدارًا أحدث، يفرض النظام قيودًا على المدة التي يُسمح خلالها بتشغيل خدمات معيّنة تعمل في المقدّمة بينما يكون تطبيقك في الخلفية. لا ينطبق هذا التقييد حاليًا إلا على خدمات foreground dataSync و mediaProcessing نوع الخدمة التي تعمل في المقدّمة. هناك حدود أكثر تقييدًا على shortService نوع الخدمة التي تعمل في المقدّمة والتي تتم مناقشتها في مستندات نوع الخدمة هذا.

سلوك المهلة

يسمح النظام بتشغيل الخدمات التي تعمل في المقدّمة dataSync وmediaProcessing لمدة إجمالية تبلغ 6 ساعات في فترة 24 ساعة، وبعد ذلك يستدعي النظام Service.onTimeout(int, int) method (تم تقديمه في Android 15) للخدمة التي تعمل في المقدّمة. (تمّت إضافة نوع الخدمةmediaProcessing التي تعمل في المقدّمة في الإصدار Android 15). يتم تتبُّع المهلة الزمنية التي تبلغ ست ساعات بشكل منفصل لكل من خدمات dataSync وmediaProcessing. على سبيل المثال، إذا تم تشغيل خدمة dataSync لمدة ساعة واحدة فقط، سيتوفّر للتطبيق خمس ساعات فقط لخدمات mediaProcessing التي تعمل في المقدّمة، ولكن سيكون لديه ساعتان كاملتان لخدمات dataSync.

ملاحظة: تفرض shortService خدمات المقدّمة مدة زمنية أكثر تقييدًا. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات الخدمة في Shorts.

عندما تصل الخدمة التي تعمل في المقدّمة إلى الحدّ الأقصى البالغ ست ساعات، يكون أمامها بضع ثواني للاتصال بخدمة Service.stopSelf(). عندما يُطلِق النظام علامة Service.onTimeout()، تصبح الخدمة غير خدمة تعمل في المقدّمة. إذا لم تطلب الخدمة Service.stopSelf()، يُرسِل النظام استثناءً داخليًا. يتم تسجيل الاستثناء في Logcat مع الرسالة التالية:

Fatal Exception: android.app.RemoteServiceException: "A foreground service of
type [service type] did not stop within its timeout: [component name]"

ملاحظة: تتم مشاركة الحدّ الزمني البالغ 6 ساعات مع جميع خدمات التطبيق التي تعمل في المقدّمة والتي تنتمي إلى النوع المحدّد. على سبيل المثال، إذا كان التطبيق يشغِّل خدمة dataSync لمدة أربعة ساعات، ثم بدأ خدمة dataSync مختلفة، لن يُسمح بتشغيل هذه الخدمة الثانية سوى لمدة ساعتَين. ومع ذلك، إذا نقل المستخدم التطبيق إلى المقدّمة، تتم إعادة ضبط الموقّت ويصبح لدى التطبيق 6 ساعات.

لتجنُّب حدوث مشاكل بسبب هذا التغيير في السلوك، يمكنك تنفيذ إجراء واحد أو أكثر مما يلي:

1. اطلب من مقدّم الخدمة تنفيذ طريقة Service.onTimeout(int, int) الجديدة. عندما يتلقّى تطبيقك المكالمة المُعاد توجيهها، احرص على الاتصال بالرقم stopSelf() في غضون بضع ثوانٍ. (إذا لم توقف التطبيق على الفور، سيُنشئ النظام حالة تعطُّل.)
2. تأكَّد من عدم تشغيل خدمتَي dataSync وmediaProcessing في تطبيقك مدّة تزيد عن 6 ساعات في أي فترة مدتها 24 ساعة (ما لم يتفاعل المستخدم مع التطبيق، فهذا يؤدي إلى إعادة ضبط الموقّت).
3. لا تبدأ خدمات dataSync أو mediaProcessing التي تعمل في المقدّمة إلا نتيجة تفاعل المستخدم المباشر، لأنّ تطبيقك يكون في المقدّمة عند بدء الخدمة، وبالتالي تتوفر لخدمتك ست ساعات كاملة بعد انتقال التطبيق إلى الخلفية.
4. بدلاً من استخدام هذه الخدمات التي تعمل في المقدّمة، استخدِم واجهة برمجة تطبيقات بديلة، مثل WorkManager. على وجه الخصوص، بدلاً من استخدام dataSync خدمة تعمل في المقدّمة، ننصحك باستخدام واجهة برمجة تطبيقات بديلة.

إذا استمر تشغيل خدمات dataSync التي تعمل في المقدّمة في تطبيقك لمدة 6 ساعات في آخر 24 ساعة، لا يمكنك بدء خدمة أخرى تعمل في المقدّمة dataSync ما لم ينقل المستخدم تطبيقك إلى المقدّمة (ما يؤدي إلى إعادة ضبط الموقّت). إذا حاولت بدء dataSync خدمة أخرى تعمل في المقدّمة، يُرسِل النظام ForegroundServiceStartNotAllowedException رسالة خطأ مثل "انتهت المهلة الزمنية للخدمة التي تعمل في المقدّمة من النوع dataSync".

الاختبار

لاختبار سلوك تطبيقك، يمكنك تفعيل مهلات مزامنة البيانات حتى إذا كان تطبيقك لا يستهدف الإصدار 15 من نظام التشغيل Android (ما دام التطبيق يعمل على جهاز يعمل بالإصدار 15 من نظام التشغيل Android). لتفعيل مهلات الانتظار، شغِّل الأمر adb التالي:

adb shell am compat enable FGS_INTRODUCE_TIME_LIMITS your-package-name

يمكنك أيضًا تعديل فترة المهلة لتسهيل اختبار سلوك تطبيقك عند بلوغ الحدّ الأقصى. لضبط فترة مهلة جديدة لخدمات dataSync التي تعمل في المقدّمة، شغِّل الأمر adb التالي:

adb shell device_config put activity_manager data_sync_fgs_timeout_duration duration-in-milliseconds

لضبط فترة مهلة جديدة لخدمات mediaProcessing التي تعمل في المقدّمة، يمكنك تنفيذ الأمر التالي:

adb shell device_config put activity_manager media_processing_fgs_timeout_duration duration-in-milliseconds