前台服务

前台服务用于执行可被用户注意到的操作。

前台服务会显示状态栏通知,让用户知道您的应用正在前台执行任务并消耗系统资源。

使用前台服务的应用示例包括:

  • 一款音乐播放器应用,用于在前台服务中播放音乐。通知可能会显示当前播放的歌曲。
  • 一款健身应用,会在收到用户的权限后,在前台服务中记录用户跑步数据。该通知可能会显示用户在当前健身课程期间的运动距离。

仅当您的应用需要执行可被用户注意到的任务(即使用户并未直接与应用互动)时,才使用前台服务。如果该操作的重要性足够低,以至于您想要使用优先级最低的通知,请改为创建后台任务

本文档介绍了使用前台服务所需的权限,以及如何启动前台服务并将其从后台移除。此外,还介绍了如何将某些用例与前台服务类型相关联,以及从在后台运行的应用启动前台服务时生效的访问限制。

用户可以默认关闭通知

从 Android 13(API 级别 33)开始,默认情况下,用户可以关闭与前台服务关联的通知。为此,用户可以在通知上执行滑动手势。按照传统,除非前台服务停止或从前台移除,否则通知不会关闭。

如果您希望用户无法关闭该通知,请在使用 Notification.Builder 创建通知时将 true 传入 setOngoing() 方法。

立即显示通知的服务

如果某项前台服务至少具有以下特征之一,系统会在服务启动后立即显示关联的通知,即使在搭载 Android 12 或更高版本的设备上也是如此:

在 Android 13(API 级别 33)或更高版本中,如果用户拒绝授予通知权限,他们仍会在任务管理器中看到与前台服务相关的通知,但不会在抽屉式通知栏中看到这些通知。

在清单中声明前台服务

在应用清单中,使用 <service> 元素声明应用的各项前台服务。对于每项服务,请使用 android:foregroundServiceType 属性声明服务要执行的工作类型。

例如,如果您的应用创建了用于播放音乐的前台服务,您可以按如下方式声明该服务:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>

    <service
        android:name=".MyMediaPlaybackService"
        android:foregroundServiceType="mediaPlayback"
        android:exported="false">
    </service>
</manifest>

如果您的服务有多个类型,请使用 | 运算符将其分隔开。例如,使用摄像头和麦克风的服务可按如下方式声明该功能:

android:foregroundServiceType="camera|microphone"

请求前台服务权限

如果应用以 Android 9(API 级别 28)或更高版本为目标平台并使用前台服务,则需要在应用清单中请求 FOREGROUND_SERVICE,如以下代码段所示。这是普通权限,因此,系统会自动为请求权限的应用授予此权限。

此外,如果应用以 API 级别 34 或更高级别为目标平台,则必须针对前台服务将要执行的工作类型请求适当的权限类型。每种前台服务类型都有对应的权限类型。例如,如果应用启动使用相机的前台服务,您必须同时请求 FOREGROUND_SERVICEFOREGROUND_SERVICE_CAMERA 权限。这些都是普通权限,因此,如果这些权限在清单中列出,系统会自动授予它们。

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>

    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA"/>

    <application ...>
        ...
    </application>
</manifest>

前台服务前提条件

从 Android 14(API 级别 34)开始,当您启动前台服务时,系统会根据服务类型检查是否满足特定的前提条件。例如,如果您尝试启动 location 类型的前台服务,系统会进行检查,确保您的应用已具有 ACCESS_COARSE_LOCATIONACCESS_FINE_LOCATION 权限。否则,系统会抛出 SecurityException

因此,您必须在启动前台服务之前确认已满足必要的前提条件。前台服务类型文档列出了每种前台服务类型所需的前提条件。

启动前台服务

在请求系统将某项服务作为前台服务来运行之前,请先启动该服务本身:

Kotlin

val intent = Intent(...) // Build the intent for the service
context.startForegroundService(intent)

Java

Context context = getApplicationContext();
Intent intent = new Intent(...); // Build the intent for the service
context.startForegroundService(intent);

在该服务内(通常在 onStartCommand() 中),您可以请求在前台运行您的服务。为此,请调用 ServiceCompat.startForeground()(在 androidx-core 1.12 及更高版本中可用)。此方法采用以下参数:

这些类型可能是清单中声明的类型的子集,具体取决于特定用例。然后,如果您需要添加更多服务类型,可以再次调用 startForeground()

例如,假设健身应用运行一项跑步跟踪器服务,该服务始终需要 location 信息,但不一定需要播放媒体内容。您需要在清单中同时声明 locationmediaPlayback。如果用户开始跑步并且只想跟踪其位置,您的应用应调用 startForeground() 并仅传递 ACCESS_FINE_LOCATION 权限。然后,如果用户想要开始播放音频,请再次调用 startForeground() 并传递所有前台服务类型的按位组合(在本例中为 ACCESS_FINE_LOCATION|FOREGROUND_SERVICE_MEDIA_PLAYBACK)。

以下是启动相机前台服务的示例:

Kotlin

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 =
            ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA)
    if (cameraPermission == PackageManager.PERMISSION_DENIED) {
        // 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)
        }
        // ...
    }
  }
}

Java

public class MyCameraService extends Service {

    private void 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.
        int cameraPermission =
            ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA);
        if (cameraPermission == PackageManager.PERMISSION_DENIED) {
            // Without camera permissions the service cannot run in the
            // foreground. Consider informing user or updating your app UI if
            // visible.
            stopSelf();
            return;
        }

        try {
            Notification notification =
                new NotificationCompat.Builder(this, "CHANNEL_ID")
                    // Create the notification to display while the service
                    // is running
                    .build();
            int type = 0;
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                type = ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA;
            }
            ServiceCompat.startForeground(
                    /* service = */ this,
                    /* id = */ 100, // Cannot be 0
                    /* notification = */ notification,
                    /* foregroundServiceType = */ type
            );
        } catch (Exception e) {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S &&
                    e instanceof ForegroundServiceStartNotAllowedException
            ) {
                // App not in a valid state to start foreground service
                // (e.g started from bg)
            }
            // ...
        }
    }

    //...
}

从前台移除服务

如需从前台移除服务,请调用 stopForeground()。此方法采用一个布尔值,指示是否也移除状态栏通知。请注意,服务会继续运行。

如果您在前台运行时停止该服务,则系统会移除该服务的通知。

处理用户发起的停止运行前台服务的应用的操作

抽屉式通知栏底部有一个按钮,用于指示当前在后台运行的应用的数量。按下此按钮时,系统会显示一个对话框,其中列出了不同应用的名称。每个应用的右侧都有“停止”按钮
图 1. 搭载 Android 13 或更高版本的设备上的任务管理器工作流。

从 Android 13(API 级别 33)开始,无论应用的目标 SDK 版本是什么,用户都可以从抽屉式通知栏中完成工作流,以停止具有持续前台服务的应用。此功能称为任务管理器,可显示当前正在运行前台服务的应用列表。

此列表的标签为使用中的应用。每个应用旁边都有一个 Stop 按钮。图 1 说明了搭载 Android 13 的设备上的任务管理器工作流。

当用户在任务管理器中按下应用旁边的 Stop 按钮时,会发生以下操作:

  • 系统会从内存中移除您的应用。因此,您的整个应用都会停止,而不仅仅是正在运行的前台服务。
  • 系统会移除应用的 activity 返回堆栈。
  • 所有媒体播放都会停止。
  • 与前台服务关联的通知会被移除。
  • 您的应用会保留在历史记录中。
  • 预定的作业会在其安排的时间执行。
  • 闹钟会在预定的时间或时间范围响起。

如需测试应用在用户停止应用期间和之后的行为是否符合预期,请在终端窗口中运行以下 ADB 命令:

adb shell cmd activity stop-app PACKAGE_NAME

豁免

系统会针对特定类型的应用提供几种级别的豁免,下面几部分将介绍这些豁免。

豁免针对的是应用而不是进程。如果系统豁免了应用中的一个进程,则该应用中的所有其他进程也会被豁免。

完全不会显示在任务管理器中

以下应用可以运行前台服务,而根本不会显示在任务管理器中:

免于被用户停止

当以下类型的应用运行前台服务时,它们会显示在任务管理器中,但应用名称旁边没有可供用户点按的 Stop 按钮:

使用专为特定用途构建的 API,而不是前台服务

对于许多用例,您可以使用平台或 Jetpack API 执行原本需要使用前台服务的工作。如果有合适的专用 API,您几乎总是应该使用它,而不是使用前台服务。用途特定的 API 通常可提供特定于用例的额外功能,否则您必须自行构建这些功能。例如, Bubbles API 可为需要实现聊天气泡功能的即时通讯应用处理复杂的界面逻辑。

前台服务类型文档列出了可用于替代前台服务的良好替代方案。

针对从后台启动前台服务的限制

以 Android 12 或更高版本为目标平台的应用在后台运行时无法启动前台服务,少数特殊情况除外。如果应用在后台运行时尝试启动前台服务,并且前台服务不符合任何特殊情况,系统就会抛出 ForegroundServiceStartNotAllowedException

此外,如果应用想要启动需要“在使用时”权限(例如身体传感器、摄像头、麦克风或位置信息权限)的前台服务,则当它在后台运行时,它就无法创建该服务,即使该应用属于可免于执行后台启动限制的其中一项。如需了解原因,请参阅与启动需要正在使用中权限的前台服务相关的限制部分。

不受后台启动限制的约束

在以下情况下,即使应用在后台运行,也可以启动前台服务:

针对启动需要运行时权限的前台服务的限制

在 Android 14(API 级别 34)或更高版本中,如果您启动的前台服务需要在使用时获得权限,则存在一些特殊情况需要注意。

如果您的应用以 Android 14 或更高版本为目标平台,操作系统会在您创建前台服务时进行检查,以确保您的应用具有该服务类型的所有适当权限。例如,当您创建麦克风类型的前台服务时,操作系统会验证您的应用当前是否具有 RECORD_AUDIO 权限。如果您没有该权限,系统会抛出 SecurityException

对于在使用时的权限,这会引发潜在问题。如果您的应用具有仅在使用时获得的权限,那么只有在前台运行时才具有该权限。这意味着,如果您的应用在后台运行,并且尝试创建相机、位置信息或麦克风类型的前台服务,系统会发现您的应用目前不具备所需的权限,并抛出 SecurityException

同样,如果您的应用在后台运行并创建了一项需要 BODY_SENSORS_BACKGROUND 权限的健康服务,那么应用目前也没有该权限,系统会抛出异常。(如果它是需要不同权限的健康服务,例如 ACTIVITY_RECOGNITION,则不适用。)调用 ContextCompat.checkSelfPermission() 不会防止出现此问题。如果您的应用具有仅在使用时授予的权限,并且会调用 checkSelfPermission() 以检查自己是否具有该权限,即使应用在后台运行,该方法也会返回 PERMISSION_GRANTED。如果该方法返回 PERMISSION_GRANTED,则表明您的应用在使用期间具有此权限。

因此,如果您的前台服务需要“在使用时”权限,您必须在应用具有可见 activity 时调用 Context.startForegroundService()Context.bindService(),除非该服务属于定义的豁免情况之一。

不受使用时权限限制

在某些情况下,即使某个前台服务在应用 在后台运行时启动,当它在前台运行时(即“使用期间”),它仍然可以访问位置信息、摄像头和麦克风信息。

在相同情况下,如果服务声明的前台服务类型location,并且由具有 ACCESS_BACKGROUND_LOCATION 权限的应用启动,则此服务可以随时访问位置信息,即使应用在后台运行也是如此。

以下列表就包含这类情况:

  • 系统组件会启动该服务。
  • 首先,该服务会与应用微件交互。
  • 该服务首先与通知交互。
  • 该服务作为从其他可见应用发送的 PendingIntent 启动。
  • 该服务由作为在设备所有者模式下运行的设备政策控制器的应用启动。
  • 服务由提供 VoiceInteractionService 的应用启动。
  • 服务由具有 START_ACTIVITIES_FROM_BACKGROUND 特许权限的应用启动。
确定应用中的哪些服务受到影响

测试您的应用时,请启动其前台服务。如果启动的服务对位置信息、麦克风和摄像头的访问受到限制,Logcat 中就会显示以下消息:

Foreground service started from background can not have \
location/camera/microphone access: service SERVICE_NAME