Ö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, mevcut fitness oturumu sırasında kullanıcının katettiği mesafe gösterilebilir.

Ön plan hizmetini yalnızca uygulamanızın, doğrudan uygulamayla etkileşimde olmayan kullanıcıların bile fark edebileceği işleri yapması gerektiğinde kullanın. İşlem, minimum öncelikli bildirim kullanmak isteyeceğiniz kadar önemsizse 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ılamayacağını istiyorsanız bildiriminizi Notification.Builder ile oluştururken setOngoing() yöntemine true ekleyin.

Hemen bildirim gösteren hizmetler

Bir ön plan hizmeti aşağıdaki özelliklerden en az birine sahipse sistem, ilişkili bildirimi Android 12 veya sonraki sürümleri çalıştıran cihazlarda bile hizmet başlatıldıktan hemen sonra 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 geçerli birden fazla tür varsa 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 manifest'inde FOREGROUND_SERVICE iznini istemesi gerekir. Bu bir normal izin olduğundan sistem, istek yapan uygulamaya otomatik olarak izin verir.

Ayrıca, uygulama API düzeyi 34 veya üstünü hedefliyorsa ön plan hizmetinin yapacağı iş türü 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 izinlerdir. Bu nedenle, manifestte listelendikleri takdirde 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ünde bir ön plan hizmeti başlatmaya çalışırsanız sistem, uygulamanızın zaten ACCESS_COARSE_LOCATION veya ACCESS_FINE_LOCATION iznine sahip olup olmadığını kontrol eder. Bağlanmıyorsa sistem SecurityException komutunu atar.

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() (androidxcore 1.12 ve sonraki sürümlerde mevcuttur) numaralı telefonu arayın. Bu yöntem aşağıdaki parametreleri alır:

Bu türler, belirli kullanım alanına bağlı olarak manifest dosyasında 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. Manifest'te hem location hem de mediaPlayback öğesini beyan etmeniz 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 değeri alır. Hizmetin çalışmaya devam ettiğini unutmayın.

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

Ön plan hizmeti çalıştıran uygulamaların kullanıcı tarafından durdurulmasını işleme

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ı listeleyen 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ümleri çalıştıran 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 adı verilen bu olanak, şu anda bir ö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ı durdurduğunda 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 bazında değil, uygulama bazındadır. 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ın durdurmalarına engel olan muafiyetler

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 plandan ön plan hizmeti başlatmayla ilgili kısıtlamalar

Android 12 veya sonraki sürümleri hedefleyen uygulamalar, birkaç özel durum hariç olmak üzere uygulama arka planda çalışırken ön plan hizmetlerini başlatamaz. Bir uygulama arka planda çalışırken bir ön plan hizmeti başlatmaya çalışır ve ön plan hizmeti istisnai durumlardan birini karşılamazsa sistem bir ForegroundServiceStartNotAllowedException atar.

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 izin alması gereken ön plan hizmetlerinin başlatılmasıyla 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 kullanımdayken iznine sahipse bu izne yalnızca ön plandayken sahip olur. Yani uygulamanız arka plandayken kamera, konum veya mikrofon türündeki bir ön plan hizmeti oluşturmaya çalışırsa sistem, uygulamanızın şu anda gerekli izinlere sahip olmadığını görür ve bir SecurityException oluşturur.

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 oluşturur. (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 kullanım sırasında izine sahipse ve bu iznin olup olmadığını kontrol etmek için checkSelfPermission() yöntemini çağırıyorsa uygulama arka planda olsa bile 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, uygulama arka planda çalışırken başlatılmış olsa bile ön planda çalışırken ("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 almaktadır:

  • Hizmeti bir sistem bileşeni başlatır.
  • Hizmet, uygulama widget'larıyla etkileşime geçerek başlar.
  • Hizmet, bir bildirimle etkileşime geçerek 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 ile başlar.
  • 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