启动前台服务

从应用启动前台服务分为两步。首先，您必须通过调用 context.startForegroundService() 来启动服务。然后，让该服务调用 ServiceCompat.startForeground() 将自身提升为前台服务。

前提条件

应用可以启动前台服务的时间受到一些限制，具体取决于应用以哪个 API 级别为目标平台。

  • 以 Android 12（API 级别 31）或更高版本为目标平台的应用不得在后台运行时启动前台服务，但少数特定情况除外。如需了解详情以及此规则的例外情况，请参阅与从后台启动前台服务相关的限制。

  • 如果应用以 Android 14（API 级别 34）或更高版本为目标平台，则必须为相应前台服务类型请求适当的权限。当应用尝试将服务提升到前台时，系统会检查是否有适当的权限，如果应用缺少任何权限，则会抛出 SecurityException。例如，如果您尝试启动类型为 location 的前台服务，系统会进行检查，确保您的应用已拥有 ACCESS_COARSE_LOCATION 或 ACCESS_FINE_LOCATION 权限。前台服务类型文档列出了每种前台服务类型的必需前提条件。

启动服务

如需启动前台服务，您必须先将其作为普通（非前台）服务启动：

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);

代码要点

  • 该代码段会启动服务。不过，该服务尚未在前台运行。在服务本身内，您需要调用 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）。

以下示例展示了相机服务将自己提升为前台服务时所使用的代码：

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)
            }
            // ...
        }
    }

    //...
}

代码要点

  • 应用已在清单中声明它需要 CAMERA 权限。不过，应用还必须在运行时进行检查，以确保用户已授予该权限。如果应用实际上没有正确的权限，则应告知用户存在此问题。
  • 不同版本的 Android 平台引入了不同的前台服务类型。此代码会检查其所运行的 Android 版本，并请求适当的权限。
  • 该代码会检查 ForegroundServiceStartNotAllowedException，以防在禁止的情况下尝试启动前台服务（例如，在应用在后台运行时尝试将服务提升到前台）。