Ön plan hizmetleri

Ön plan hizmetleri, kullanıcının fark edebileceği işlemleri gerçekleştirir.

Ön plan hizmetleri, uygulamanızın ön planda bir işlem gerçekleştirdiğini ve sistem kaynaklarını kullandığını belirtmek için durum çubuğu bildirimi gösterir.

Ön plan hizmetlerini kullanan uygulamalara örnek olarak şunlar verilebilir:

  • Ön plan hizmetinde müzik çalan bir müzik çalma uygulaması. Bildirimde, çalmakta olan şarkı gösterilebilir.
  • Kullanıcıdan izin aldıktan sonra kullanıcının koşusunu ön plan hizmetinde kaydeden bir fitness uygulaması. Bildirimde, kullanıcının mevcut fitness oturumu sırasında kat ettiği mesafe gösterilebilir.

Uygulamanızın, kullanıcı tarafından fark edilebilecek bir işlemi gerçekleştirmesi gerektiğinde (uygulamayla doğrudan etkileşimde bulunmadığında bile) yalnızca ön plan hizmetini kullanın. İşlemin önem düzeyi, minimum öncelikli bildirim kullanmanızı gerektirecek kadar düşükse bunun yerine bir arka plan görevi oluşturun.

Bu dokümanda, ön plan hizmetlerini kullanmak için gereken izin ve ön plan hizmetinin nasıl başlatılacağı ve arka plandan nasıl kaldırılacağı açıklanmaktadır. Ayrıca belirli kullanım alanlarının ön plan hizmet türleriyle nasıl ilişkilendirileceği ve arka planda çalışan bir uygulamadan ön plan hizmeti başlattığınızda geçerli olan erişim kısıtlamaları da açıklanmaktadır.

Kullanıcı varsayılan olarak bildirimi kapatabilir

Android 13'ten (API düzeyi 33) itibaren kullanıcılar, ön plan hizmetiyle ilişkili bildirimi varsayılan olarak kapatabilir. Bunun için kullanıcılar bildirimde kaydırma hareketi yapar. Geleneksel olarak, ön plan hizmeti durdurulmadığı veya ön plandan kaldırılmadığı sürece bildirim kapatılmaz.

Bildirimin kullanıcı tarafından kapatılamaması için Notification.Builder kullanarak bildiriminizi oluştururken true değerini setOngoing() yöntemine iletin.

Bildirimi hemen gösteren hizmetler

Bir ön plan hizmetinde aşağıdaki özelliklerden en az biri varsa sistem, Android 12 veya sonraki sürümleri çalıştıran cihazlarda bile hizmet başladıktan hemen sonra ilişkili bildirimi gösterir:

Android 13 (API düzeyi 33) veya sonraki sürümlerde kullanıcı bildirim iznini reddederse ön plan hizmetleriyle ilgili bildirimleri Görev Yöneticisi'nde görmeye devam eder ancak bildirim çekmecesinde görmez.

Ön plan hizmetlerini manifest'inizde beyan etme

Uygulamanızın manifest dosyasında, ön plan hizmetlerinizin her birini <service> öğesiyle beyan edin. Her hizmet için hizmetin ne tür bir iş yaptığını belirtmek üzere bir android:foregroundServiceType özelliği kullanın.

Örneğin, uygulamanız müzik çalan bir ön plan hizmeti oluşturuyorsa hizmeti şu şekilde tanımlayabilirsiniz:

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

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

Hizmetiniz için birden fazla tür geçerliyse bunları | operatörüyle ayırın. Örneğin, kamera ve mikrofon kullanan bir hizmet bunu şöyle belirtir:

android:foregroundServiceType="camera|microphone"

Ön plan hizmeti izinlerini isteme

Android 9 (API düzeyi 28) veya sonraki sürümleri hedefleyen ve ön plan hizmetlerini kullanan uygulamaların, aşağıdaki kod snippet'inde gösterildiği gibi uygulama manifestinde FOREGROUND_SERVICE isteğinde bulunması gerekir. Bu normal bir izin olduğundan sistem, izni istekte bulunan uygulamaya otomatik olarak verir.

Ayrıca, API düzeyi 34 veya sonraki sürümleri hedefleyen uygulamalar, ön plan hizmetinin yapacağı çalışma için uygun izin türünü istemelidir. Her ön plan hizmet türünün karşılık gelen bir izin türü vardır. Örneğin, bir uygulama kamerayı kullanan bir ön plan hizmeti başlatırsa hem FOREGROUND_SERVICE hem de FOREGROUND_SERVICE_CAMERA izinlerini istemeniz gerekir. Bunların tümü normal izinler olduğundan, manifest dosyasında listelenirlerse sistem bunları otomatik olarak verir.

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

Ön plan hizmeti ön koşulları

Android 14'ten (API düzeyi 34) itibaren bir ön plan hizmetini kullanıma sunduğunuzda sistem, hizmet türüne göre belirli ön koşulları kontrol eder. Örneğin, location türündeki bir ön plan hizmetini başlatmaya çalışırsanız sistem, uygulamanızın ACCESS_COARSE_LOCATION veya ACCESS_FINE_LOCATION iznine sahip olup olmadığını kontrol eder. Aksi takdirde sistem SecurityException hatası verir.

Bu nedenle, ön plan hizmetini başlatmadan önce gerekli ön koşulların karşılandığını onaylamanız gerekir. Ön plan hizmet türü dokümanlarında, her ön plan hizmet türü için gerekli ön koşullar listelenir.

Ön plan hizmetini başlatma

Sistemden bir hizmeti ön plan hizmeti olarak çalıştırmasını istemeden önce hizmeti başlatın:

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

Hizmetin içinde, genellikle onStartCommand() içinde, hizmetinizin ön planda çalışmasını isteyebilirsiniz. Bunu yapmak için ServiceCompat.startForeground() işlevini çağırın (androidx-core 1.12 ve sonraki sürümlerde kullanılabilir). Bu yöntem aşağıdaki parametreleri alır:

  • Hizmet
  • Durum çubuğundaki bildirimi benzersiz bir şekilde tanımlayan pozitif bir tam sayı
  • Notification nesnesinin kendisi
  • Hizmetin yaptığı işi tanımlayan ön plan hizmet türleri

Bu türler, belirli kullanım alanına bağlı olarak manifest'te tanımlanan türlerin alt kümesi olabilir. Ardından, daha fazla hizmet türü eklemeniz gerekirse startForeground() numaralı telefonu tekrar arayabilirsiniz.

Örneğin, bir fitness uygulamasının her zaman location bilgisine ihtiyaç duyan ancak medya oynatması gerekebilecek ya da gerekmeyebilecek bir koşu takip aracı hizmeti çalıştırdığını varsayalım. Manifestte hem location hem de mediaPlayback öğelerini belirtmeniz gerekir. Bir kullanıcı koşuya başlar ve yalnızca konumunun izlenmesini isterse uygulamanız startForeground() işlevini çağırmalı ve yalnızca ACCESS_FINE_LOCATION iznini iletmelidir. Ardından, kullanıcı ses çalmaya başlamak isterse startForeground() işlevini tekrar çağırın ve tüm ön plan hizmeti türlerinin bit kombinasyonunu (bu durumda ACCESS_FINE_LOCATION|FOREGROUND_SERVICE_MEDIA_PLAYBACK) iletin.

Aşağıda, bir kamera ön plan hizmetini başlatan bir örnek 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)
            }
            // ...
        }
    }

    //...
}

Bir hizmeti ön plandan kaldırma

Hizmeti ön plandan kaldırmak için stopForeground() çağrısını yapın. Bu yöntem, durum çubuğu bildiriminin de kaldırılıp kaldırılmayacağını belirten bir boole alır. Hizmetin çalışmaya devam ettiğini unutmayın.

Hizmet ön planda çalışırken durdurulursa bildirimi kaldırılır.

Ön plan hizmetlerini çalıştıran uygulamaların kullanıcı tarafından başlatılan durdurulmasını yönetme

Bildirim çekmecesinin alt kısmında, şu anda arka planda çalışan uygulamaların sayısını gösteren bir düğme bulunur. Bu düğmeye bastığınızda, farklı uygulamaların adlarının listelendiği bir iletişim kutusu görünür. Durdur düğmesi her uygulamanın sağ tarafındadır.
Şekil 1. Android 13 veya sonraki sürümlerin yüklü olduğu cihazlarda Görev Yöneticisi iş akışı.

Android 13'ten (API düzeyi 33) itibaren kullanıcılar, devam eden ön plan hizmetleri olan bir uygulamayı durdurmak için bildirim çekmecesinden bir iş akışını tamamlayabilir. Bu işlem, uygulamanın hedef SDK sürümünden bağımsız olarak gerçekleştirilebilir. Görev Yöneticisi olarak adlandırılan bu kolaylık, şu anda ön plan hizmeti çalıştıran uygulamaların listesini gösterir.

Bu liste Etkin uygulamalar olarak etiketlenir. Her uygulamanın yanında bir Durdur düğmesi bulunur. Şekil 1'de, Android 13 çalıştıran bir cihazdaki Görev Yöneticisi iş akışı gösterilmektedir.

Kullanıcı Görev Yöneticisi'nde uygulamanızın yanındaki Durdur düğmesine bastığında aşağıdaki işlemler gerçekleşir:

  • Sistem, uygulamanızı bellekten kaldırır. Bu nedenle, yalnızca çalışan ön plan hizmeti değil, uygulamanızın tamamı durur.
  • Sistem, uygulamanızın etkinlik geri yığınını kaldırır.
  • Tüm medya oynatmaları durdurulur.
  • Ön plan hizmetiyle ilişkili bildirim kaldırılır.
  • Uygulamanız geçmişte kalır.
  • Planlanmış işler planlanan zamanda yürütülür.
  • Alarmlar planlanan saatte veya zaman aralığında çalar.

Bir kullanıcı uygulamanızı durdururken ve durdurduktan sonra uygulamanızın beklendiği gibi davranıp davranmadığını test etmek için terminal penceresinde aşağıdaki ADB komutunu çalıştırın:

adb shell cmd activity stop-app PACKAGE_NAME

Muafiyetler

Sistem, belirli uygulama türleri için aşağıdaki bölümlerde açıklanan çeşitli muafiyet düzeyleri sunar.

Muafiyetler işlem başına değil, uygulama başına geçerlidir. Sistem bir uygulamadaki bir işlemi muaf tutarsa bu uygulamadaki diğer tüm işlemler de muaf tutulur.

Görev Yöneticisi'nde hiç görünmeme muafiyeti

Aşağıdaki uygulamalar ön plan hizmeti çalıştırabilir ve Görev Yöneticisi'nde hiç görünmeyebilir:

Kullanıcılar tarafından durdurulabilir olmama muafiyeti

Aşağıdaki uygulama türleri ön plan hizmeti çalıştırdığında Görev Yöneticisi'nde görünür ancak kullanıcının uygulama adının yanında dokunabileceği bir Durdur düğmesi yoktur:

Ön plan hizmetleri yerine özel olarak tasarlanmış API'leri kullanma

Birçok kullanım alanında, ön plan hizmetini kullanabileceğiniz işlemleri yapmak için kullanabileceğiniz platform veya Jetpack API'leri vardır. Amaca yönelik uygun bir API varsa neredeyse her zaman ön plan hizmeti yerine onu kullanmanız gerekir. Özel olarak tasarlanmış API'ler genellikle, aksi takdirde kendi başınıza oluşturmanız gereken kullanım alanına özel ek özellikler sunar. Örneğin, Bubbles API, sohbet balonu özelliklerini uygulamak zorunda olan mesajlaşma uygulamaları için karmaşık kullanıcı arayüzü mantığını yönetir.

Ön plan hizmet türleri ile ilgili dokümanda, ön plan hizmetleri yerine kullanılabilecek iyi alternatifler listelenmiştir.

Arka planda ön plan hizmeti başlatmayla ilgili kısıtlamalar

Android 12 veya sonraki sürümleri hedefleyen uygulamalar, birkaç özel durum dışında, uygulama arka planda çalışırken ön plan hizmetlerini başlatamaz. Bir uygulama arka planda çalışırken ön plan hizmeti başlatmaya çalışırsa ve ön plan hizmeti istisna durumlarından birini karşılamıyorsa sistem bir ForegroundServiceStartNotAllowedException oluşturur.

Ayrıca, kullanım sırasında izinlere (ör. vücut sensörü, kamera, mikrofon veya konum izinleri) ihtiyaç duyan bir ön plan hizmeti başlatmak isteyen uygulamalar, arka planda başlatma kısıtlamalarından istisna olan uygulamalardan biri olsa bile arka plandayken hizmeti oluşturamaz. Bunun nedeni, Kullanımdayken izinlere ihtiyaç duyan ön plan hizmetlerini başlatmayla ilgili kısıtlamalar bölümünde açıklanmıştır.

Arka planda başlatma kısıtlamalarından muaf olanlar

Uygulamanız arka planda çalışırken bile aşağıdaki durumlarda ön plan hizmetlerini başlatabilir:

Kullanımdayken izinlere ihtiyaç duyan ön plan hizmetlerini başlatmayla ilgili kısıtlamalar

Android 14 (API düzeyi 34) veya sonraki sürümlerde, kullanım sırasında izinlere ihtiyaç duyan bir ön plan hizmeti başlatıyorsanız dikkat etmeniz gereken özel durumlar vardır.

Uygulamanız Android 14 veya sonraki sürümleri hedefliyorsa işletim sistemi, ön plan hizmeti oluşturduğunuzda uygulamanızın ilgili hizmet türü için tüm uygun izinlere sahip olduğundan emin olmak üzere kontrol yapar. Örneğin, mikrofon türüne sahip bir ön plan hizmeti oluşturduğunuzda işletim sistemi, uygulamanızın şu anda RECORD_AUDIO iznine sahip olduğunu doğrular. Bu izniniz yoksa sistem bir SecurityException hatası verir.

Bu durum, kullanım sırasında izinler için olası bir soruna neden olur. Uygulamanızın kullanım sırasında izni varsa bu izne yalnızca ön plandayken sahip olur. Yani uygulamanız arka plandaysa ve kamera, konum veya mikrofon türünde bir ön plan hizmeti oluşturmaya çalışırsa sistem, uygulamanızın şu anda gerekli izinlere sahip olmadığını görür ve SecurityException verir.

Benzer şekilde, uygulamanız arka plandaysa ve BODY_SENSORS iznine ihtiyaç duyan bir sağlık hizmeti oluşturuyorsa uygulama şu anda bu izne sahip değildir ve sistem bir istisna uygular. (Bu, ACTIVITY_RECOGNITION gibi farklı izinlere ihtiyaç duyan bir sağlık hizmeti söz konusu olduğunda geçerli değildir.) PermissionChecker.checkSelfPermission() çağrısı bu sorunu önlemez. Uygulamanızın kullanım sırasında izni varsa ve bu izne sahip olup olmadığını kontrol etmek için checkSelfPermission() yöntemini çağırıyorsa uygulama arka planda olsa bile bu yöntem PERMISSION_GRANTED değerini döndürür. Yöntem PERMISSION_GRANTED döndürdüğünde "Uygulama kullanılırken uygulamanız bu izne sahiptir." anlamına gelir.

Bu nedenle, ön plan hizmetinizin kullanımdayken iznine ihtiyacı varsa hizmet tanımlanmış muafiyetler arasında yer almadığı sürece uygulamanızda görünür bir etkinlik varken Context.startForegroundService() veya Context.bindService() çağrısını yapmanız gerekir.

Kullanımdayken izinleriyle ilgili kısıtlamalardan muafiyet

Bazı durumlarda, bir ön plan hizmeti uygulama arka planda çalışırken başlatılsa bile, uygulama ön planda ("kullanımdayken") konum, kamera ve mikrofon bilgilerine erişebilir.

Aynı durumlarda, hizmet location ön plan hizmet türü beyan ediyorsa ve ACCESS_BACKGROUND_LOCATION iznine sahip bir uygulama tarafından başlatılıyorsa bu hizmet, uygulama arka planda çalışırken bile konum bilgilerine her zaman erişebilir.

Aşağıdaki listede bu durumlar yer alır:

  • Bir sistem bileşeni hizmeti başlatır.
  • Hizmet, uygulama widget'larıyla etkileşime geçerek başlar.
  • Hizmet, bir bildirimle etkileşimde bulunarak başlar.
  • Hizmet, farklı ve görünür bir uygulamadan gönderilen bir PendingIntent olarak başlar.
  • Hizmet, cihaz sahibi modunda çalışan bir cihaz politikası denetleyici olan uygulama tarafından başlatılır.
  • Hizmet, VoiceInteractionService sağlayan bir uygulama tarafından başlatılır.
  • Hizmet, START_ACTIVITIES_FROM_BACKGROUND ayrıcalıklı iznine sahip bir uygulama tarafından başlatılır.
Uygulamanızda hangi hizmetlerin etkilendiğini belirleme

Uygulamanızı test ederken ön plan hizmetlerini başlatın. Başlatılan bir hizmet konum, mikrofon ve kamera erişimini kısıtlamışsa Logcat'te aşağıdaki mesaj görünür:

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