啟動前景服務

從應用程式啟動前景服務有兩個步驟。首先，您必須呼叫 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，以防在系統不允許的情況下嘗試啟動前景服務 (例如，在應用程式處於背景執行狀態時，嘗試將服務提升至前景)。