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

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

سلوك المهلة

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

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

عندما تصل الخدمة التي تعمل في المقدّمة إلى الحدّ الأقصى البالغ ست ساعات، يكون أمامها بضع ثوانٍ لاستدعاء 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".

الاختبار

لاختبار سلوك تطبيقك، يمكنك تفعيل مهلة مزامنة البيانات حتى إذا لم يكن تطبيقك يستهدف Android 15 (طالما أنّ التطبيق يعمل على جهاز Android 15). لتفعيل المهلة، نفِّذ الأمر التالي في 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