前台服务

前台服务执行用户可感知的操作。

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

以下是一些使用前台服务的应用示例

  • 一个在前台服务中播放音乐的音乐播放器应用。通知可能会显示正在播放的当前歌曲。
  • 一个在获得用户许可后在前台服务中记录用户跑步的健身应用。通知可能会显示用户在当前健身期间行驶的距离。

仅当您的应用需要执行用户可感知的任务时，即使他们在不直接与应用交互时，也才使用前台服务。如果操作的重要性较低，您希望使用最低优先级的通知，则改为创建 后台任务。

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

用户可以默认情况下关闭通知

从 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" ...>
  <application ...>

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

如果您的服务适用多种类型，请使用 | 运算符将它们分隔开。例如，使用相机和麦克风的服务将像这样声明它

android:foregroundServiceType="camera|microphone"

请求前台服务权限

面向 Android 9（API 级别 28）或更高版本并使用前台服务的应用需要在应用清单中请求 FOREGROUND_SERVICE，如下面的代码片段所示。这是一个 普通权限，因此系统会自动将其授予请求应用。

此外，如果应用的目标 API 级别为 34 或更高版本，则必须为前台服务将执行的工作类型请求相应的权限类型。每个 前台服务类型 都有一个相应的权限类型。例如，如果应用启动了一个使用相机的前台服务，则必须同时请求 FOREGROUND_SERVICE 和 FOREGROUND_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_LOCATION 或 ACCESS_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 信息，但可能需要也可能不需要播放媒体。您需要在清单中声明 location 和 mediaPlayback。如果用户开始跑步并且只想跟踪其位置，则您的应用应调用 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 =
            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)
        }
        // ...
    }
  }
}

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()。此方法采用一个布尔值，指示是否也移除状态栏通知。请注意，服务将继续运行。

如果在服务在前台运行时停止服务，则会移除其通知。

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

At the bottom of the notification drawer is a button that indicates the number of apps that are currently running in the background. When you press this button, a dialog appears, which lists the names of different apps. The Stop button is to the right of each app
图 1. 在运行 Android 13 或更高版本的设备上的任务管理器工作流程。

从 Android 13（API 级别 33）开始，用户可以完成从 通知抽屉 到停止具有正在进行的前台服务的应用的工作流程，而不管该应用的目标 SDK 版本如何。此功能称为任务管理器，它显示当前正在运行前台服务的应用列表。

此列表标记为正在运行的应用。每个应用旁边都有一个停止按钮。图 1 说明了在运行 Android 13 的设备上的任务管理器工作流程。

当用户按下任务管理器中应用旁边的停止按钮时，会发生以下操作

  • 系统会将您的应用从内存中移除。因此，您的整个应用都会停止，而不仅仅是正在运行的前台服务。
  • 系统会移除应用的 Activity 后退栈。
  • 任何媒体播放都会停止。
  • 与前台服务关联的通知将被移除。
  • 您的应用将保留在历史记录中。
  • 计划的作业将在其计划时间执行。
  • 闹钟将在其计划时间或时间窗口响起。

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

adb shell cmd activity stop-app PACKAGE_NAME

豁免

系统为某些类型的应用提供了多个级别的豁免，以下各部分对此进行了说明。

豁免按应用而非按进程进行。如果系统豁免应用中的一个进程，则该应用中的所有其他进程也将被豁免。

完全豁免出现在任务管理器中

以下应用可以运行前台服务，并且根本不会出现在任务管理器中

豁免用户停止

当以下类型的应用运行前台服务时，它们会出现在任务管理器中，但用户无法点击应用名称旁边的停止按钮

使用专用的 API 而不是前台服务

对于许多用例，可以使用平台或 Jetpack API 来执行您可能原本使用前台服务执行的工作。如果存在合适的专用 API，则几乎始终应使用它而不是使用前台服务。专用 API 通常提供其他用例特定的功能，否则您需要自己构建这些功能。例如，气泡 API 处理需要实现聊天气泡功能的消息应用的复杂 UI 逻辑。

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

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

针对 Android 12 或更高版本的应用，除非在少数特殊情况下，否则无法在应用在后台运行时启动前台服务。如果应用尝试在后台运行时启动前台服务，且该前台服务不满足任何例外情况，系统将抛出一个ForegroundServiceStartNotAllowedException。

此外，如果应用想要启动一个需要使用中权限（例如，人体传感器、摄像头、麦克风或位置权限）的前台服务，则即使应用属于不受后台启动限制的豁免情况之一，也无法在应用处于后台时创建该服务。原因在需要使用中权限的前台服务的启动限制部分进行了说明。

后台启动限制的豁免

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

需要使用中权限的前台服务的启动限制

在 Android 14（API 级别 34）或更高版本上，如果您要启动需要使用中权限的前台服务，则需要注意一些特殊情况。

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

对于使用中权限，这会导致潜在问题。如果您的应用具有使用中权限，则它仅在处于前台时才具有该权限。这意味着，如果您的应用在后台，并且它尝试创建类型为摄像头、位置或麦克风的前台服务，系统会发现您的应用当前没有所需的权限，并抛出一个SecurityException。

同样，如果您的应用在后台并且它创建了一个需要BODY_SENSORS权限的健康服务，则该应用当前没有该权限，系统会抛出异常。（如果这是一个需要不同权限的健康服务，例如ACTIVITY_RECOGNITION，则不适用。）调用PermissionChecker.checkSelfPermission()不会解决此问题。如果您的应用具有使用中权限，并且它调用checkSelfPermission()来检查它是否具有该权限，则即使应用在后台，该方法也会返回PERMISSION_GRANTED。当该方法返回PERMISSION_GRANTED时，表示“您的应用在使用时具有此权限”。

因此，如果您的前台服务需要使用中权限，则必须在您的应用具有可见 Activity 时调用Context.startForegroundService()或Context.bindService()，除非该服务属于已定义的豁免。

使用中权限限制的豁免

在某些情况下，即使前台服务是在应用在后台运行时启动的，它仍然可以在应用在前台运行时（“使用中”）访问位置、摄像头和麦克风信息。

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

以下列表包含这些情况

  • 系统组件启动服务。
  • 服务通过与应用 Widget交互启动。
  • 服务通过与通知交互启动。
  • 服务作为来自不同可见应用的PendingIntent启动。
  • 服务由以设备所有者模式运行的设备策略控制器应用启动。
  • 服务由提供VoiceInteractionService的应用启动。
  • 服务由具有START_ACTIVITIES_FROM_BACKGROUND特权权限的应用启动。
确定您的应用中受影响的服务

在测试您的应用时，启动其前台服务。如果启动的服务对位置、麦克风和摄像头的访问受到限制，则 Logcat 中会出现以下消息

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