从应用启动前台服务需要两个步骤。首先,您必须通过调用 context.startForegroundService() 来启动服务。然后,让该服务调用 ServiceCompat.startForeground(),将自身提升为前台服务。
前提条件
根据应用所针对的 API 级别,应用何时可以启动前台服务会受到一些限制。
以 Android 12(API 级别 31)或更高版本为目标平台的应用在后台运行时,将无法启动前台服务,但少数特殊情况除外。如需了解详情以及此规则的例外情况,请参阅与从后台启动前台服务相关的限制。
以 Android 14(API 级别 34)或更高版本为目标平台的应用必须为前台服务类型请求适当的权限。当应用尝试将服务提升到前台时,系统会检查是否具有适当的权限,如果应用缺少任何权限,则会抛出
SecurityException。例如,如果您尝试启动类型为location的前台服务,系统会检查以确保您的应用已具有ACCESS_COARSE_LOCATION或ACCESS_FINE_LOCATION权限。前台服务类型文档列出了每种前台服务类型的必要前提条件。
启动服务
如需启动前台服务,您必须先将其作为普通(非前台)服务启动:
val intent = Intent(/* ... */) // Build the intent for the service. context.startForegroundService(intent)
代码要点
- 此代码段会启动一项服务。不过,该服务尚未在前台运行。在服务本身内部,您需要调用
ServiceCompat.startForeground(),将服务提升为前台服务。
将服务提升到前台
服务运行后,您需要调用 ServiceCompat.startForeground() 来请求该服务在前台运行。通常,您会在服务的 onStartCommand() 方法中调用此方法。
ServiceCompat.startForeground() 采用以下参数:
- 服务。
- 一个正整数,用于在状态栏中唯一标识服务的通知。
Notification对象本身。- 前台服务类型,用于标识服务所执行的工作
您传递给 startForeground() 的前台服务类型必须是清单中声明的类型的子集,具体取决于特定用例。然后,如果您需要添加更多服务类型,可以再次调用 startForeground()。
例如,假设某个健身应用运行一个跑步跟踪器服务,该服务始终需要 location 信息,但可能需要也可能不需要播放媒体。您需要在清单中同时声明 location 和 mediaPlayback。如果用户开始跑步,并且只想跟踪其位置信息,您的应用应调用 startForeground() 并仅传递 ACCESS_FINE_LOCATION 权限。然后,如果用户想要开始播放音频,请再次调用 startForeground(),并传递所有前台服务类型的按位组合(在本例中为 ACCESS_FINE_LOCATION|FOREGROUND_SERVICE_MEDIA_PLAYBACK)。
以下示例展示了相机服务用于将自身提升为前台服务的代码:
class MyCameraService : Service() { private fun startForeground() { // Before starting the service as foreground check that the app has the // appropriate runtime permissions. In this case, verify that the user has // granted the CAMERA permission. val cameraPermission = PermissionChecker.checkSelfPermission(this, Manifest.permission.CAMERA) if (cameraPermission != PermissionChecker.PERMISSION_GRANTED) { // Without camera permissions the service cannot run in the foreground. // Consider informing user or updating your app UI if visible. stopSelf() return } try { val notification = NotificationCompat.Builder(this, "CHANNEL_ID") // Create the notification to display while the service is running. .build() ServiceCompat.startForeground( /* service = */ this, /* id = */ 100, // Cannot be 0. /* notification = */ notification, /* foregroundServiceType = */ if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) { ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA } else { 0 }, ) } catch (e: Exception) { if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S && e is ForegroundServiceStartNotAllowedException ) { // App not in a valid state to start foreground service // (e.g. started from bg). } // ... } } }
代码要点
- 该应用已在清单中声明其需要
CAMERA权限。不过,应用还必须在运行时进行检查,以确保用户已授予该权限。如果应用实际上没有正确的权限,则应告知用户该问题。 - 不同版本 Android 平台引入的前台服务类型也不同。此代码会检查应用在哪个 Android 版本上运行,并请求适当的权限。
- 代码会检查
ForegroundServiceStartNotAllowedException,以防它尝试在不允许的情况下启动前台服务(例如,如果它尝试在应用处于后台时将服务提升到前台)。