انواع خدمات پیش زمینه

از اندروید ۱۴ (سطح 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
运行时前提条件
无
说明

在后台继续播放音频或视频。在 Android TV 上支持数字视频录制 (DVR) 功能。

替代方案

如果您要显示画中画视频，请使用画中画模式。

پردازش رسانه

要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
mediaProcessing
在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PROCESSING
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
运行时前提条件
无
说明

用于对媒体资源执行耗时的操作（例如将媒体转换为其他格式）的服务。系统允许此服务运行的时间有限；在正常情况下，此时限为每天 24 小时中的 6 小时。（此限制由应用的所有 mediaProcessing 前台服务共享。）

在以下情况下，您的应用应手动停止媒体处理服务：

如果超时期限已到，系统会调用服务的 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() را فراخوانی کنید.

توضیحات

با استفاده از APIهای 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
运行时前提条件

必须满足以下至少一个条件：

  • 应用是默认拨号器应用（通过 ROLE_DIALER 角色）。
说明

使用 ConnectionService API 继续当前通话。

替代方案

如果您需要拨打电话、视频通话或 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 前台服务类型之外，开发者还应在清单中声明用例。为此，他们会在 <service> 元素内指定 <property> 元素。这些值和相应的应用场景 。用途 您提供的案例均为自由形式，因此，您应确保提供足够的 相关信息，让审核人员了解您为何需要使用 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، به درک خدمات پیش زمینه و الزامات هدف تمام صفحه مراجعه کنید.