Ön plan hizmeti başlatma

Uygulamanızdan ön plan hizmeti başlatmak için iki adım vardır. İlk olarak, context.startForegroundService() yöntemini çağırarak hizmeti başlatmanız gerekir. Ardından, hizmetin kendisini ön plan hizmetine yükseltmek için ServiceCompat.startForeground() yöntemini çağırmasını sağlayın.

Ön koşullar

Uygulamanızın hedeflediği API düzeyine bağlı olarak, uygulamanın ön plan hizmetini ne zaman başlatabileceğiyle ilgili bazı kısıtlamalar vardır.

• Android 12 (API düzeyi 31) veya sonraki sürümleri hedefleyen uygulamaların, birkaç istisna dışında uygulama arka plandayken ön plan hizmeti başlatmasına izin verilmez. Daha fazla bilgi ve bu kuralın istisnaları hakkında bilgi için Arka plandan ön plan hizmeti başlatmayla ilgili kısıtlamalar başlıklı makaleyi inceleyin.

• Android 14 (API düzeyi 34) veya sonraki sürümleri hedefleyen uygulamalar, ön plan hizmeti türü için uygun izinleri istemelidir. Uygulama, bir hizmeti ön plana taşımaya çalıştığında sistem uygun izinleri kontrol eder ve uygulamada eksik izin varsa SecurityException hatası verir. Örneğin, location türünde bir ön plan hizmeti başlatmaya çalışırsanız sistem, uygulamanızın ACCESS_COARSE_LOCATION veya ACCESS_FINE_LOCATION iznine sahip olup olmadığını kontrol eder. Ön plan hizmeti türü dokümanlarında, her ön plan hizmeti türü için gerekli ön koşullar listelenir.

Hizmet başlatma

Bir ön plan hizmeti başlatmak için önce bunu sıradan (ön plan olmayan) bir hizmet olarak başlatmanız gerekir:

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

Kodla ilgili önemli noktalar

• Kod snippet'i bir hizmet başlatır. Ancak hizmet henüz ön planda çalışmıyor. Hizmetin içinde, hizmeti ön plan hizmetine yükseltmek için ServiceCompat.startForeground() yöntemini çağırmanız gerekir.

Bir hizmeti ön plana çıkarma

Bir hizmet çalışmaya başladıktan sonra hizmetin ön planda çalışmasını istemek için ServiceCompat.startForeground() yöntemini çağırmanız gerekir. Normalde bu yöntemi hizmetin onStartCommand() yönteminde çağırırsınız.

ServiceCompat.startForeground() aşağıdaki parametreleri alır:

• Hizmet.
• Durum çubuğunda hizmetin bildirimini benzersiz şekilde tanımlayan pozitif bir tam sayı.
• Notification nesnesinin kendisi.
• Hizmet tarafından yapılan işi tanımlayan ön plan hizmet türü veya türleri

Not: Manifest dosyasında beyan etmediğiniz bir ön plan hizmet türünü startForeground yöntemine iletirseniz sistem IllegalArgumentException hatası verir.

startForeground() yöntemine ilettiğiniz ön plan hizmet türleri, belirli kullanım alanına bağlı olarak manifest dosyasında beyan edilen türlerin bir alt kümesi olmalıdır. Daha fazla hizmet türü eklemeniz gerekirse startForeground() numarasını tekrar arayabilirsiniz.

Örneğin, bir fitness uygulamasının her zaman location bilgisine ihtiyaç duyan ancak medya oynatması gerekebilen veya gerekmeyebilen bir koşu takip hizmeti çalıştırdığını varsayalım. Manifest dosyasında hem location hem de mediaPlayback öğesini beyan etmeniz gerekir. Kullanıcı koşuya başlayıp yalnızca konumunun takip edilmesini istiyorsa uygulamanız startForeground() yöntemini çağırıp yalnızca ACCESS_FINE_LOCATION iznini iletmelidir. Ardından, kullanıcı ses çalmaya başlamak isterse startForeground() yöntemini tekrar çağırın ve tüm ön plan hizmeti türlerinin bit düzeyinde kombinasyonunu (bu örnekte ACCESS_FINE_LOCATION|FOREGROUND_SERVICE_MEDIA_PLAYBACK) iletin.

Not: Durum çubuğu bildirimi, PRIORITY_LOW veya daha yüksek bir öncelik kullanmalıdır. Uygulamanız önceliği PRIORITY_LOW değerinden düşük olan bir bildirim kullanmaya çalışırsa sistem, bildirim çekmecesine bir mesaj ekleyerek kullanıcıyı uygulamanın ön plan hizmeti kullandığı konusunda uyarır.

Aşağıdaki örnekte, bir kamera hizmetinin kendisini ön plan hizmetine yükseltmek için kullanacağı kod gösterilmektedir:

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

    //...
}

Kodla ilgili önemli noktalar

• Uygulama, manifest dosyasında CAMERA iznine ihtiyacı olduğunu zaten beyan etmiştir. Ancak uygulamanın, kullanıcının bu izni verdiğinden emin olmak için çalışma zamanında da kontrol etmesi gerekir. Uygulama doğru izinlere sahip değilse kullanıcıyı sorun hakkında bilgilendirmelidir.
• Android platformunun farklı sürümlerinde farklı ön plan hizmeti türleri kullanıma sunuldu. Bu kod, hangi Android sürümünde çalıştığını kontrol eder ve uygun izinleri ister.
• Kod, izin verilmeyen bir durumda ön plan hizmeti başlatmaya çalışıp çalışmadığını (örneğin, uygulama arka plandayken hizmeti ön plana taşımaya çalışıp çalışmadığını) belirlemek için ForegroundServiceStartNotAllowedException değerini kontrol eder.