Ön plan hizmetleri

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

Ön plan hizmetlerinde bir durum çubuğu bildirim göndermesi durumunda, uygulamasının ön planda bir işlem gerçekleştirdiğini ve sistem kaynaklarını kullandığını gösterir.

Ön plan hizmetlerini kullanan uygulamalara örnek olarak aşağıdakiler verilebilir:

  • Ön plan hizmetinde müzik çalan bir müzik çalma uygulaması. Bildirim çalan şarkıyı gösterebilir.
  • Kullanıcının koşusunu ön plan hizmetinde kaydeden bir fitness uygulaması Kullanıcıdan izin alınması gerekir. Bildirimde uzaklık gösterilebilir geçerli fitness oturumu sırasında seyahat etti.

Ön plan hizmetini yalnızca uygulamanızın bir görevi yerine getirmesi gerektiğinde kullanın Kullanıcılar, reklamlarla doğrudan etkileşim kurmasa bile bunların fark edebileceği görebilirsiniz. İşlemin önem düzeyi düşükse minimum öncelikli bildirim için arka plan görevi ile ilgili daha fazla bilgi edinin.

Bu belgede, ön plan hizmetlerini kullanmak için gereken izin açıklanmaktadır. başlatılmasını ve arka plandan kaldırılacağını açıklayacağım. Aynı zamanda Belirli kullanım alanlarının ön plan hizmeti türleriyle nasıl ilişkilendirileceğini açıklıyor ve Bir ön plan hizmetini başlattığınızda geçerli olan erişim kısıtlamaları arka planda çalışan bir uygulamadan alırsınız.

Kullanıcı bildirimi varsayılan olarak kapatabilir

Android 13'ten (API düzeyi 33) itibaren kullanıcılar bildirimi kapatabilir varsayılan olarak bir ön plan hizmetiyle ilişkilidir. Kullanıcılar bunun için ekranı kaydırır hareket ettirebilirsiniz. Geleneksel olarak, ön plan hizmeti durdurulmadığı veya kaldırılmadığı sürece kapatılmaz arka planda çalışır.

Bildirimin kullanıcı tarafından kapatılamaması için setOngoing() içine true yöntemini Notification.Builder kullanarak bildiriminizi oluşturun.

Hemen bildirim gösteren hizmetler

Bir ön plan hizmeti aşağıdaki özelliklerden en az birine sahipse sistem, ilgili bildirimi hizmet başladıktan hemen sonra gösterir. Android 12 veya sonraki sürümleri çalıştıran cihazlarda bile:

Android 13 (API düzeyi 33) veya sonraki sürümlerde kullanıcı bildirim izni, o sırada ön plan hizmetleriyle ilgili bildirimler görmeye devam ederler. Görev Yöneticisi bunları bildirim çekmecesinde görmezsiniz.

Manifest'inizde ön plan hizmetlerini beyan edin

Uygulamanızın manifest dosyasında, uygulamanızın ön plan hizmetlerinin her birini beyan edin bir <service> ile öğesine dokunun. Her hizmet için bir android:foregroundServiceType özelliği belirten bir açıklama girin.

Örneğin, uygulamanız müzik çalan bir ön plan hizmeti oluşturuyorsa hizmeti aşağıdaki gibi beyan edebilir:

<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ı | ile ayırın. operatörümüzü kullanabilirsiniz. Örneğin, kamera ve mikrofonu kullanan bir hizmet bu ifade şu şekilde belirtilir:

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 şu soruyu sormam gerekiyor: FOREGROUND_SERVICE aşağıdaki kod snippet'inde gösterildiği gibi uygulama manifest'inde yer alır. Bu, normal söz konusu olabilir. istekte bulunan uygulamaya otomatik olarak izin verir.

Ayrıca, API düzeyi 34 veya üstünü hedefleyen uygulamaların ön plan hizmetinin olacağı çalışma türüne uygun izin türü yapıyor. Her bir ön plan hizmeti türü karşılık gelen bir izin türüne sahip. Örneğin, bir uygulama bir ön plan hizmeti sunuyorsanız hem FOREGROUND_SERVICE ve FOREGROUND_SERVICE_CAMERA izin verir. Bunların tümü normal izinler olduğundan sistem bunlara manifestoda listelenirse otomatik olarak gösterilir.

<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 başlattığınızda 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, ve uygulamanızda ACCESS_COARSE_LOCATION veya ACCESS_FINE_LOCATION izni. Bağlanmıyorsa sistem SecurityException.

Bu nedenle, gerekli ön koşulların karşılandığını onaylamanız gerekir önce test etmeniz gerekir. Ön plan hizmeti type belgeleri her ön plan hizmet türü için gerekli ön koşulları listeler.

Ön plan hizmeti başlatma

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

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()) çalışmaya devam etmesini sağlar. Bunun için şu numarayı arayın: ServiceCompat.startForeground() (androidxcore 1.12 ve sonraki sürümlerde kullanılabilir.) Bu yöntem şunları alır: parametre:

  • Hizmet
  • Durum çubuğunda bildirimi benzersiz bir şekilde tanımlayan pozitif bir tam sayı
  • Notification nesnesinin kendisi
  • Ön plan hizmeti türleri hizmet tarafından yapılan işleri tanımlama

Bu türler, manifest dosyasında belirtilen türlerin alt kümesi olabilir. kullanım alanına göre değişebilir. Daha fazla hizmet türü eklemeniz gerekirse startForeground() adlı kişiyi tekrar arayabilirsiniz.

Örneğin, bir fitness uygulamasının koşu takip uygulaması hizmetini her zaman location bilgisine ihtiyacı var, ancak medya oynatması gerekebilir veya gerekmeyebilir. Siz manifest dosyasında hem location hem de mediaPlayback öğesini beyan etmesi gerekir. koşuya başlayan bir kullanıcı yalnızca konumunun izlenmesini istiyorsa, uygulamanız startForeground() ve yalnızca ACCESS_FINE_LOCATION iznini iletin. Ardından, Kullanıcı ses çalmaya başlamak isterse startForeground() numaralı telefonu tekrar arayın ve tüm ön plan hizmet türlerinin bit tabanlı kombinasyonunu (bu örnekte ACCESS_FINE_LOCATION|FOREGROUND_SERVICE_MEDIA_PLAYBACK) tıklayın.

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 şunu arayın: stopForeground(). Bu yöntem, durum çubuğunun kaldırılıp kaldırılmayacağını gösteren bir boole alır. bildirimi de alabilirsiniz. Hizmetin çalışmaya devam ettiğini unutmayın.

Hizmeti ön planda çalışırken durdurursanız 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, bildirimin o anda arka planda çalışan uygulama sayısı. Şuna bastığınızda: Bu düğmeyi tıkladığınızda, farklı uygulamaların adlarının yer aldığı bir iletişim kutusu görünür. İlgili içeriği oluşturmak için kullanılan Durdur düğmesi her uygulamanın sağındadır
Şekil 1. Şu cihazlarda Görev Yöneticisi iş akışı: Android 13 veya sonraki sürümleri çalıştırmanız gerekir.

Android 13 (API düzeyi 33) sürümünden itibaren, kullanıcılar bildirim çekmecesi devam eden ön plan hizmetleri olan bir uygulamayı durdurmak için hedef SDK sürümü. Google Haritalar'daki Görev Yöneticisi, şu özelliklere sahip uygulamaların bir listesini gösterir: şu anda bir ön plan hizmeti çalıştırıyor.

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

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

  • Sistem, uygulamanızı bellekten kaldırır. Bu nedenle, uygulamanızın tamamı durdurulur çalışmasını sağlamalısınız.
  • Sistem, uygulamanızın etkinlik geri yığınını kaldırır.
  • Her medya oynatma işlemi durur.
  • Ön plan hizmetiyle ilişkili bildirim kaldırılır.
  • Uygulamanız geçmişte gösterilmeye devam ediyor.
  • Planlanan işler, programlanan zamanda yürütülür.
  • Alarmlar programlanan zamanda veya zaman aralığında çalar.
ziyaret edin.

Bir kullanıcı bir 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 çeşitli muafiyetler sağlar. Bunlar aşağıdaki bölümlerde açıklanmıştır.

Muafiyetler işlem başına değil, uygulama başına geçerlidir. Sistem, bir testte bir işlemi muaf tutarsa söz konusu uygulamadaki diğer tüm işlemler de muaftır.

Görev Yöneticisi'nde görüntülenmekten hiç muaf tutma

Aşağıdaki uygulamalar bir ön plan hizmetini çalıştırabilir ve Görev Yöneticisi:

  • Sistem düzeyindeki uygulamalar
  • Güvenlik uygulamaları özellikleri olan ROLE_EMERGENCY rolü
  • Şurada bulunan cihazlar: demo modu

Kullanıcıların durdurmasına engel olan muafiyetler

Aşağıdaki türlerde bir ön plan hizmeti çalıştırıldığında, bunlar Görev Yöneticisi'ne sahip ancak kullanıcının dokunacağı uygulamanın adı:

Ön plan hizmetleri yerine amaca yönelik API'ler kullanın

Birçok kullanım alanında iş yapmak için kullanabileceğiniz platform veya Jetpack API'leri vardır. ön plan hizmetini kullanabilirsiniz. Uygun bir özel amaca yönelik API'lerden yararlanıyorsanız, hemen hemen her zaman ön plan yerine bu API'yi geliştirmenizi sağlar. Amaca yönelik API'ler genellikle kullanım alanına özgü ek bilgiler sağlar yararlanabileceğiniz yeni olanaklar da tanıyoruz. Örneğin, Bubbles API aşağıdakiler için karmaşık kullanıcı arayüzü mantığını ele alır: özellikleri kullanması gereken mesajlaşma uygulamalarıdır.

Ön plan hizmet türleri listeleriyle ilgili dokümanlar yerine ön plan hizmetleri yerine iyi alternatifler oluşturabilirsiniz.

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

Android 12 veya sonraki sürümleri hedefleyen uygulamalar ön planı başlatamaz uygulama arka planda çalışırken birkaç özel durumlar için de geçerlidir. Uygulama bir Uygulama arka planda çalışırken ve ön planda çalışırken istisnai durumlardan birini karşılamazsa, sistem bir uyarı gönderir. ForegroundServiceStartNotAllowedException.

Ayrıca, uygulamanız gereken ön plan hizmetini kullanımdayken izinler (örneğin, vücut sensörü, kamera, mikrofon veya konum uygulama arka plandayken hizmeti oluşturamaz. Uygulama arka planda başlatmanın muafiyetlerinden birine girse bile kısıtlamalar. Bunun nedeni, bkz. kullanım sırasında gereken ön plan hizmetlerini başlatma izinleriyle ilgili daha fazla bilgi edinin.

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

Aşağıdaki durumlarda, uygulamanız şu an için ön plan hizmetlerini başlatırken bile Uygulamanız arka planda çalışıyor:

Kullanım sırasında izin gerektiren ön plan hizmetlerinin başlatılmasıyla ilgili kısıtlamalar

Android 14 (API düzeyi 34) veya sonraki sürümlerde dikkat edilmesi gereken özel durumlar vardır kullanım izni gerektiren bir ön plan hizmeti başlatıyorsanız

Uygulamanız Android 14 veya sonraki bir sürümü hedefliyorsa işletim sistemi ön plan hizmeti oluşturduğunuzda, uygulamanızın tüm arka plan söz konusu hizmet türü için uygun izinleri verebilirsiniz. Örneğin, şu tür ön plan hizmeti mikrofon, sistem, uygulamanızın şu anda RECORD_AUDIO izni gerekir. Bu izne sahip değilseniz, sistem bir SecurityException.

Bu durum, kullanımdaki izinler için olası bir soruna neden olur. Uygulamanızda kullanım izni olduğunda ise yalnızca ön planı seçin. Yani uygulamanız arka planda çalışıyorsa ve kamera, konum veya mikrofon türünde bir ön plan hizmeti sunduğunuzda sistem, uygulamanızın şu anda gerekli izinlere sahip olmadığını ve bunun sonucunda SecurityException.

Benzer bir şekilde, uygulamanız arka plandaysa ve BODY_SENSORS_BACKGROUND iznine ihtiyacı olan bir sağlık hizmeti, uygulama şu anda bu izne sahip değil ve sistem bir istisna atıyor. (Bu durum, farklı izinler gerektiren bir sağlık hizmetleri için geçerli değildir. ACTIVITY_RECOGNITION gibi.) Arama yapılıyor PermissionChecker.checkSelfPermission() bu sorunu engellemez. Uygulamanızın kullanımdayken izni varsa ve bu izne sahip olup olmadığını kontrol etmek için checkSelfPermission() yöntemini çağırır. Uygulama arka planda olsa bile PERMISSION_GRANTED değerini döndürür. yöntemi PERMISSION_GRANTED sonucunu döndürüyor ve "uygulamanızda bu izne sahip" yazıyor uygulama kullanılırken."

Bu nedenle, ön plan hizmetinizin kullanım sırasında izin alması gerekiyorsa şu sırada Context.startForegroundService() veya Context.bindService() çağrılmalıdır: uygulamanızın görünür bir etkinliği olması, tanımlanmış muafiyetler hakkında daha fazla bilgi edinin.

Kullanımdayken izinlerle ilgili kısıtlamalardan muaflar

Bazı durumlarda, uygulama sırasında bir ön plan hizmeti başlatılsa bile koşu arka planda çalışırsa konuma erişmeye, Uygulama ön planda çalışırken kamera ve mikrofon bilgileri ("kullanımdayken").

Aynı durumlarda hizmet; location adlı bir ön plan hizmeti türündeyse ve CANNOT TRANSLATE ACCESS_BACKGROUND_LOCATION bu hizmet, konum bilgilerine her zaman erişebilir. Uygulama arka planda çalışıyor.

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

Uygulamanızda hangi hizmetlerin etkilendiğini belirleyin

Uygulamanızı test ederken ön plan hizmetlerini başlatın. Başlatılan bir hizmet konum, mikrofon ve kameraya erişimi kısıtladığında, Logcat'te görünür:

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