Ö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:
- Hizmet, işlem içeren bir bildirimle ilişkilendirilmiş düğmeleriyle kullanılabilir.
- Hizmetin bir
foregroundServiceType
/mediaPlayback
,mediaProjection
veyaphoneCall
- Hizmet; telefon aramaları, navigasyon veya medya ile ilgili bir kullanım alanı sağlar (bildirimin kategorisinde tanımlandığı gibi) özelliği ekleyin.
- Hizmet,
FOREGROUND_SERVICE_IMMEDIATE
hedeflendisetForegroundServiceBehavior()
seçeneğine dokunun.
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
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.
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ı:
- Cihaz sahibi uygulamaları
- Profil sahibi uygulamalar
- Kalıcı uygulamalar
- Şuna sahip uygulamalar:
ROLE_DIALER
rolü
Ö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:
- Uygulamanız, kullanıcının görebileceği bir durumdan (ör. activity.
- Uygulamanız, şuradan etkinlik başlatabilir: arka plan (büyük/küçük harf kullanımı hariç) Bu durumda uygulama, mevcut bir görevin arka yığınında bir etkinlik bulundurur.
Uygulamanız, Firebase Cloud'u kullanarak yüksek öncelikli bir mesaj alıyor Mesajlaşma.
Kullanıcı, uygulamanızla ilgili bir kullanıcı arayüzü öğesinde bir işlem gerçekleştirir. Örneğin, bir balonla etkileşimde bulunabilirler, bildirim, widget veya etkinlik.
Uygulamanız tam alarm çağırarak Kullanıcının istediği bir işlemi tamamlamalıdır.
Uygulamanız, cihazın geçerli girişidir yöntemini kullanın.
Uygulamanız aşağıdakilerle ilgili bir etkinlik alır: coğrafi sınır belirleme veya etkinlik tanımlama geçişidir.
Cihaz yeniden başlatılıp
ACTION_BOOT_COMPLETED
ACTION_LOCKED_BOOT_COMPLETED
, veyaACTION_MY_PACKAGE_REPLACED
intent işlemi yayın alıcıda.Uygulamanız
ACTION_TIMEZONE_CHANGED
ACTION_TIME_CHANGED
, veyaACTION_LOCALE_CHANGED
intent işlemidir.Uygulamanız
ACTION_TRANSACTION_DETECTED
Etkinlik zamanı:NfcService
.device gibi belirli sistem rollerine veya izinlere sahip uygulamalar sahipler ve profile sahipler.
Uygulamanız Tamamlayıcı Cihaz Yöneticisi'ni kullanır ve şunu beyan eder:
REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND
veyaREQUEST_COMPANION_RUN_IN_BACKGROUND
izni gerekir. Mümkün olduğundaREQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND
Uygulamanız
SYSTEM_ALERT_WINDOW
izni gerekir.Kullanıcı, uygulamanız için pil optimizasyonlarını kapatır.
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:
- Hizmeti bir sistem bileşeni başlatır.
- Hizmet, uygulama ile etkileşimde bulunarak başlar widget'ları hakkında daha fazla bilgi edinin.
- Hizmet, bir bildirimle etkileşimde bulunarak başlar.
- Hizmet,
PendingIntent
görünür olması gerekir. - Hizmet, cihaz politikası olan bir uygulama tarafından başlatılır kumanda eder.
- Hizmet,
VoiceInteractionService
sağlayan bir uygulama ile başlar. - Hizmet,
START_ACTIVITIES_FROM_BACKGROUND
ayrıcalıklı izin.
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