انواع سرویس پیش‌زمینه‌ای

از Android نسخه ۱۴ (سطح API‏ ۳۴) به بعد، باید نوع سرویس مناسبی را برای هر سرویس پیش‌زمینه‌ای اعلام کنید. یعنی باید نوع سرویس را در مانیفست برنامه‌تان تعریف کنید و همچنین اجازه سرویس پیش‌زمینه‌ای مناسب را برای آن نوع درخواست کنید (علاوه‌بر درخواست اجازه 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 یا اتصال شبکه نیاز دارند.

جایگزین ها

اگر برنامه شما نیاز به انتقال مداوم داده به یک دستگاه خارجی دارد، به جای آن از مدیر دستگاه همراه استفاده کنید. از API حضور دستگاه همراه استفاده کنید تا به برنامه شما کمک کند تا زمانی که دستگاه همراه در محدوده است در حال اجرا بماند.

اگر برنامه شما نیاز به اسکن دستگاه‌های بلوتوث دارد، به جای آن از API اسکن بلوتوث استفاده کنید.

همگام‌سازی داده‌ها

نوع سرویس پیش‌زمینه‌ای برای اعلام در مانیفست تحت
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) در اندروید 14 یا پایین‌تر در دسترس نیست. در دستگاه‌هایی که این نسخه‌ها را اجرا می‌کنند، اگر یک سرویس پردازش رسانه به دوره زمانی پایان برسد، سیستم بلافاصله برنامه را در حافظه پنهان ذخیره می‌کند. به همین دلیل، برنامه شما نباید منتظر دریافت اعلان مهلت باشد. در عوض، باید سرویس پیش زمینه را خاتمه دهد یا در اسرع وقت آن را به سرویس پس زمینه تغییر دهد.

نمایش جریانی رسانه

نوع سرویس پیش‌زمینه‌ای برای اعلام در مانیفست تحت
android:foregroundServiceType
mediaProjection
اجازه برای اعلام در مانیفست
FOREGROUND_SERVICE_MEDIA_PROJECTION
ثابت برای ارسال به startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
پیش‌نیازهای زمان اجرا

پیش‌از شروع سرویس پیش‌زمینه‌ای، روش createScreenCaptureIntent() را فراخوانی کنید. با انجام این کار، اعلان اجازه به کاربر نشان داده می‌شود؛ کاربر باید اجازه را اعطا کند تا بتوانید سرویس را ایجاد کنید.

پس‌از ایجاد سرویس پیش‌زمینه‌ای، می‌توانید MediaProjectionManager.getMediaProjection() را فراخوانی کنید.

شرح

محتوا را بااستفاده از میاناهای برنامه‌سازی کاربردی MediaProjection به نمایشگر غیر اصلی یا دستگاه خارجی فرافکنی کنید. این محتوا لزوماً نباید محتوای رسانه‌ای انحصاری باشد.

موارد جایگزین

برای جاری‌سازی رسانه در دستگاهی دیگر، از کیت توسعه نرم‌افزار 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() بهترین روش در نظر گرفته می شود.

فراخوانی Service.onTimeout() در اندروید 13 و پایین‌تر وجود ندارد. اگر همان سرویس در چنین دستگاه‌هایی اجرا شود، نه مهلت زمانی دریافت می‌کند و نه ANR. مطمئن شوید که سرویس شما به محض اتمام کار پردازش متوقف می شود، حتی اگر هنوز فراخوانی Service.onTimeout() دریافت نکرده باشد.

توجه به این نکته مهم است که اگر مهلت زمانی shortService رعایت نشود، برنامه ANR می‌کند حتی اگر سایر خدمات پیش‌زمینه معتبر یا سایر فرآیندهای چرخه عمر برنامه در حال اجرا باشد.

اگر برنامه‌ای برای کاربر قابل مشاهده است یا یکی از معافیت‌هایی را برآورده می‌کند که اجازه می‌دهد خدمات پیش‌زمینه از پس‌زمینه شروع شود، با فراخوانی مجدد Service.StartForeground() با پارامتر FOREGROUND_SERVICE_TYPE_SHORT_SERVICE ، مدت زمان 3 دقیقه دیگر تمدید می‌شود. اگر برنامه برای کاربر قابل مشاهده نباشد و یکی از معافیت ها را برآورده نکند، هرگونه تلاش برای راه اندازی یک سرویس پیش زمینه دیگر، صرف نظر از نوع، باعث ایجاد یک ForegroundServiceStartNotAllowedException می شود.

اگر کاربری بهینه سازی باتری را برای برنامه شما غیرفعال کند، باز هم تحت تأثیر مهلت زمانی کوتاه سرویس 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 ارسال می کنید، این مقادیر و موارد استفاده مربوطه بررسی می شوند. موارد استفاده ای که ارائه می کنید به صورت رایگان هستند و باید مطمئن شوید که اطلاعات کافی را ارائه می دهید تا به بازبین اجازه دهید ببیند چرا باید از نوع 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

  • برنامه های VPN (پیکربندی شده با استفاده از تنظیمات > شبکه و اینترنت > VPN )

    در غیر این صورت، اعلان این نوع باعث می شود که سیستم یک ForegroundServiceTypeNotAllowedException پرتاب کند.

اجرای خط‌مشی Google Play برای استفاده از انواع سرویس‌های پیش‌زمینه‌ای

اگر برنامه شما Android 14 یا بالاتر را هدف قرار می دهد، باید انواع خدمات پیش زمینه برنامه خود را در صفحه محتوای برنامه کنسول Play ( خط مشی > محتوای برنامه ) اعلام کنید. برای اطلاعات بیشتر در مورد نحوه اعلام انواع سرویس های پیش زمینه خود در Play Console، به درک خدمات پیش زمینه و الزامات هدف تمام صفحه مراجعه کنید.