Per aiutare gli sviluppatori a definire in modo più intenzionale i servizi in primo piano rivolti agli utenti, Android 10 ha introdotto l'attributo android:foregroundServiceType all'interno dell'elemento <service>.
Se la tua app ha come target Android 14, deve specificare i tipi di servizio in primo piano appropriati. Come nelle versioni precedenti di Android, è possibile combinare più tipi. Questo elenco mostra i tipi di servizi in primo piano tra cui scegliere:
cameraconnectedDevicedataSynchealthlocationmediaPlaybackmediaProjectionmicrophonephoneCallremoteMessagingshortServicespecialUsesystemExempted
Se un caso d'uso nella tua app non è associato a nessuno di questi tipi, ti consigliamo vivamente di eseguire la migrazione della logica per utilizzare WorkManager o i job di trasferimento di dati avviati dall'utente.
I tipi health, remoteMessaging, shortService, specialUse e systemExempted
sono una novità di Android 14.
Il seguente snippet di codice fornisce un esempio di dichiarazione di un tipo di servizio in primo piano nel file manifest:
<manifest ...>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<application ...>
<service
android:name=".MyMediaPlaybackService"
android:foregroundServiceType="mediaPlayback"
android:exported="false">
</service>
</application>
</manifest>
Se un'app che ha come target Android 14 non definisce i tipi per un determinato servizio nel manifest, il sistema attiverà MissingForegroundServiceTypeException
quando viene chiamata startForeground() per quel servizio.
Dichiara la nuova autorizzazione per utilizzare i tipi di servizi in primo piano
Se le app destinate ad Android 14 utilizzano un servizio in primo piano, devono dichiarare un'autorizzazione specifica, in base al tipo di servizio in primo piano, introdotta da Android 14. Queste autorizzazioni vengono visualizzate nelle sezioni contrassegnate come "Autorizzazione da dichiarare nel file manifest" nella sezione Casi d'uso previsti e applicazione per ogni tipo di servizio in primo piano di questa pagina.
Tutte le autorizzazioni sono definite autorizzazioni normali e vengono concesse per impostazione predefinita. Gli utenti non possono revocare queste autorizzazioni.
Includi il tipo di servizio in primo piano in fase di esecuzione
The best practice for applications starting foreground services is to use the
ServiceCompat version of startForeground() (available in androidx-core
1.12 and higher) where you pass in a bitwise
integer of foreground service types. You can choose to pass one or more type
values.
Usually, you should declare only the types required for a particular use case. This makes it easier to meet the system's expectations for each foreground service type. In cases where a foreground service is started with multiple types, then the foreground service must adhere to the platform enforcement requirements of all types.
ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)
If the foreground service type is not specified in the call, the type defaults
to the values defined in the manifest. If you didn't specify the service
type in the manifest, the system throws
MissingForegroundServiceTypeException.
If the foreground service needs new permissions after you launch it, you
should call startForeground() again and add the new service types. For
example, suppose a fitness app runs a running-tracker service that always needs
location information, but might or might not need media permissions. You
would need to declare both location and mediaPlayback in the manifest. If a
user starts a run and just wants their location tracked, your app should call
startForeground() and pass just the location service type. Then, if the user
wants to start playing audio, call startForeground() again and pass
location|mediaPlayback.
Controlli di runtime del sistema
Il sistema controlla l'utilizzo corretto dei tipi di servizi in primo piano e conferma che
l'app abbia richiesto le autorizzazioni di runtime appropriate o utilizzi le API richieste.
Ad esempio, il sistema si aspetta che le app che utilizzano il tipo di servizio in primo piano
FOREGROUND_SERVICE_TYPE_LOCATION richiedano
ACCESS_COARSE_LOCATION o ACCESS_FINE_LOCATION.
Ciò implica che le app devono seguire un ordine di operazioni molto specifico quando richiedono autorizzazioni all'utente e avviano i servizi in primo piano. Le autorizzazioni devono essere richieste e concesse prima che l'app tenti di chiamare startForeground(). Le app che richiedono le autorizzazioni appropriate dopo l'avvio del servizio in primo piano devono modificare questo ordine di operazioni e richiedere l'autorizzazione prima di avviare il servizio in primo piano.
Le specifiche dell'applicazione della piattaforma vengono visualizzate nelle sezioni etichettate come "Requisiti di runtime" nella sezione Casi d'uso previsti e applicazione per ogni tipo di servizio in primo piano di questa pagina.
Casi d'uso previsti e applicazione forzata per ogni tipo di servizio in primo piano
Per utilizzare un determinato tipo di servizio in primo piano, devi dichiarare una determinata autorizzazione nel file manifest, soddisfare requisiti di runtime specifici e la tua app deve soddisfare uno degli insiemi di casi d'uso previsti per quel tipo. Le sezioni seguenti spiegano l'autorizzazione che devi dichiarare, i prerequisiti di runtime e i casi d'uso previsti per ciascun tipo.
Fotocamera
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceType camera- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_CAMERA- Costante da passare a
startForeground() FOREGROUND_SERVICE_TYPE_CAMERA- Prerequisiti di runtime
Richiedere e ottenere l'autorizzazione di runtime
CAMERANota:l'autorizzazione di runtime
CAMERAè soggetta a limitazioni durante l'utilizzo. Per questo motivo, non puoi creare un servizio in primo pianocameramentre l'app è in background, con alcune eccezioni. Per ulteriori informazioni, consulta Limitazioni all'avvio di servizi in primo piano che richiedono autorizzazioni in uso.- Descrizione
Continuare ad accedere alla fotocamera in background, ad esempio le app di video chat che consentono il multitasking.
Dispositivo connesso
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceTypeconnectedDevice- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_CONNECTED_DEVICE- Costante da passare a
startForeground() FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE- Prerequisiti di runtime
Deve essere vera almeno una delle seguenti condizioni:
Dichiara almeno una delle seguenti autorizzazioni nel file manifest:
Richiedi e ottieni almeno una delle seguenti autorizzazioni di runtime:
- Descrizione
Interazioni con dispositivi esterni che richiedono Bluetooth, NFC, IR, USB o una connessione di rete.
- Alternative
Se la tua app deve eseguire il trasferimento continuo di dati su un dispositivo esterno, puoi utilizzare il gestore dei dispositivi complementari. Utilizza l'API di presenza del dispositivo complementare per consentire alla tua app di continuare a funzionare mentre il dispositivo complementare è in portata.
Se la tua app deve cercare dispositivi Bluetooth, ti consigliamo di utilizzare l'API di ricerca Bluetooth.
Sincronizzazione dati
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceTypedataSync- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_DATA_SYNC- Costante da passare a
startForeground() FOREGROUND_SERVICE_TYPE_DATA_SYNC- Prerequisiti di runtime
- Nessuna
- Descrizione
Operazioni di trasferimento dati, ad esempio:
- Caricamento o download di dati
- Operazioni di backup e ripristino
- Operazioni di importazione o esportazione
- Recupera dati
- Elaborazione file locale
- Trasferire dati tra un dispositivo e il cloud tramite una rete
- Alternative
Per informazioni dettagliate, vedi Alternative ai servizi in primo piano per la sincronizzazione dei dati.
Salute
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceTypehealth- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_HEALTH- Costante da passare a
startForeground() FOREGROUND_SERVICE_TYPE_HEALTH- Prerequisiti di runtime
Deve essere vera almeno una delle seguenti condizioni:
Dichiara l'autorizzazione
HIGH_SAMPLING_RATE_SENSORSnel file manifest.Richiedi e ottieni almeno una delle seguenti autorizzazioni di runtime:
BODY_SENSORScon livello API 35 e versioni precedentiREAD_HEART_RATEREAD_SKIN_TEMPERATUREREAD_OXYGEN_SATURATIONACTIVITY_RECOGNITION
Nota: le autorizzazioni di runtime
BODY_SENSORSe LETTURA basate su sensori sono soggette a restrizioni durante l'uso. Per questo motivo, non puoi creare un servizio in primo pianohealthche utilizza i sensori del corpo mentre la tua app è in background, a meno che non ti siano state concesse le autorizzazioniBODY_SENSORS_BACKGROUND(livello API da 33 a 35) oREAD_HEALTH_DATA_IN_BACKGROUND(livello API 36 e versioni successive). Per ulteriori informazioni, consulta Limitazioni all'avvio dei servizi in primo piano che necessitano di autorizzazioni durante l'utilizzo.- Descrizione
Eventuali casi d'uso di lunga durata per supportare le app nella categoria fitness, come i tracker per l'esercizio fisico.
Posizione
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceTypelocation- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_LOCATION- Costante da passare a
startForeground() FOREGROUND_SERVICE_TYPE_LOCATION- Prerequisiti di runtime
L'utente deve aver attivato i servizi di geolocalizzazione e all'app deve essere stata concessa almeno una delle seguenti autorizzazioni di runtime:
Nota: per verificare che l'utente abbia attivato i servizi di geolocalizzazione e abbia concesso l'accesso alle autorizzazioni di runtime, utilizza
PermissionChecker#checkSelfPermission()Nota:le autorizzazioni di runtime per l'accesso alla posizione sono soggette a limitazioni durante l'utilizzo. Per questo motivo, non puoi creare un servizio in primo piano
locationmentre l'app è in background, a meno che non ti sia stata concessa l'autorizzazione di runtimeACCESS_BACKGROUND_LOCATION. Per ulteriori informazioni, consulta Limitazioni all'avvio di servizi in primo piano che richiedono autorizzazioni in uso.- Descrizione
Casi d'uso di lunga durata che richiedono l'accesso alla posizione, come la navigazione e la condivisione della posizione.
- Alternative
Se la tua app deve essere attivata quando l'utente raggiunge posizioni specifiche, consigliamo di utilizzare l'API geofence.
Contenuti multimediali
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceTypemediaPlayback- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_MEDIA_PLAYBACK- Costante da passare a
startForeground() FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK- Prerequisiti di runtime
- Nessuna
- Descrizione
- Continua la riproduzione audio o video in background. Supporta la funzionalità di registrazione video digitale (DVR) su Android TV.
- Alternative
- Se stai mostrando un video in modalità Picture in picture, utilizza la modalità Picture in picture.
Proiezione di contenuti multimediali
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceTypemediaProjection- 在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PROJECTION- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION- 运行时前提条件
在启动前台服务之前调用
createScreenCaptureIntent()方法。这样做会向用户显示权限通知;用户必须先授予权限,您才能创建服务。创建前台服务后,您可以调用
MediaProjectionManager.getMediaProjection()。- 说明
使用
MediaProjectionAPI 将内容投影到非主要显示屏或外部设备。这些内容不必全都为媒体内容。- 替代方案
如需将媒体流式传输到其他设备,请使用 Google Cast SDK。
Microfono
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceTypemicrophone- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_MICROPHONE- Costante da passare a
startForeground() FOREGROUND_SERVICE_TYPE_MICROPHONE- Prerequisiti di runtime
Richiedi e ottieni l'autorizzazione di runtime
RECORD_AUDIO.Nota:l'autorizzazione di runtime
RECORD_AUDIOè soggetta a limitazioni durante l'utilizzo. Per questo motivo, non puoi creare un servizio in primo pianomicrophonementre la tua app è in background, con alcune eccezioni. Per ulteriori informazioni, consulta Limitazioni all'avvio di servizi in primo piano che richiedono autorizzazioni in uso.- Descrizione
Continuare l'acquisizione del microfono in background, ad esempio da registratori vocali o app di comunicazione.
Telefonata
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceTypephoneCall- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_PHONE_CALL- Costante da passare a
startForeground() FOREGROUND_SERVICE_TYPE_PHONE_CALL- Prerequisiti di runtime
Almeno una di queste condizioni deve essere vera:
- L'app ha dichiarato l'autorizzazione
MANAGE_OWN_CALLSnel suo file manifest.
- L'app ha dichiarato l'autorizzazione
- L'app è l'app Telefono predefinita tramite il ruolo
ROLE_DIALER.
- L'app è l'app Telefono predefinita tramite il ruolo
- Descrizione
Continuare una chiamata in corso utilizzando le API
ConnectionService.- Alternative
Se devi effettuare chiamate vocali, videochiamate o VoIP, ti consigliamo di utilizzare la raccolta
android.telecom.Valuta la possibilità di utilizzare
CallScreeningServiceper filtrare le chiamate.
Messaggistica remota
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceTyperemoteMessaging- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_REMOTE_MESSAGING- Costante da passare a
startForeground() FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING- Prerequisiti di runtime
- Nessuna
- Descrizione
- Trasferisci i messaggi da un dispositivo all'altro. Assiste con la continuità delle attività di messaggistica di un utente quando cambia dispositivo.
Servizio di Short
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceTypeshortService- Autorizzazione da dichiarare nel file manifest
- Nessuna
- Costante da passare a
startForeground() FOREGROUND_SERVICE_TYPE_SHORT_SERVICE- Prerequisiti di runtime
- Nessuna
- Descrizione
Completare rapidamente i lavori critici che non possono essere interrotti o posticipati.
Questo tipo ha alcune caratteristiche uniche:
- Può essere eseguito solo per un breve periodo di tempo (circa 3 minuti).
- Nessun supporto per i servizi in primo piano permanenti.
- Impossibile avviare altri servizi in primo piano.
- Non richiede un'autorizzazione specifica per tipo, ma richiede comunque l'autorizzazione
FOREGROUND_SERVICE. - Un
shortServicepuò passare a un altro tipo di servizio solo se l'app è attualmente idonea a avviare un nuovo servizio in primo piano. - Un servizio in primo piano può modificare il proprio tipo in
shortServicein qualsiasi momento, a quel punto inizia il periodo di timeout.
Il timeout per shortService inizia dal momento in cui viene chiamato
Service.startForeground(). L'app deve chiamareService.stopSelf()oService.stopForeground()prima che si verifichi il timeout. In caso contrario, viene chiamato il nuovoService.onTimeout(), offrendo alle app una breve opportunità di chiamarestopSelf()ostopForeground()per interrompere il servizio.Poco dopo la chiamata a
Service.onTimeout(), l'app entra in uno stato memorizzato nella cache e non è più considerata in primo piano, a meno che l'utente non interagisca attivamente con l'app. Poco dopo che l'app è stata memorizzata nella cache e il servizio non è stato interrotto, l'app riceve un ANR. Il messaggio ANR menzionaFOREGROUND_SERVICE_TYPE_SHORT_SERVICE. Per questi motivi, è considerata una best practice implementare il callbackService.onTimeout().Il richiamata
Service.onTimeout()non esiste su Android 13 e versioni precedenti. Se lo stesso servizio viene eseguito su questi dispositivi, non riceve un timeout né un ANR. Assicurati che il servizio si fermi non appena completa l'attività di elaborazione, anche se non ha ancora ricevuto ilService.onTimeout()callback.È importante notare che se il timeout di
shortServicenon viene rispettato, l'app genera un ANR anche se sono in esecuzione altri servizi in primo piano validi o altri processi del ciclo di vita dell'app.Se un'app è visibile all'utente o soddisfa una delle esenzioni che consentono l'avvio dei servizi in primo piano dal background, la chiamata
Service.StartForeground()di nuovo con il parametroFOREGROUND_SERVICE_TYPE_SHORT_SERVICEprolunga il timeout di altri 3 minuti. Se l'app non è visibile all'utente e non soddisfa una delle esenzioni, qualsiasi tentativo di avviare un altro servizio in primo piano, indipendentemente dal tipo, genera unForegroundServiceStartNotAllowedException.Se un utente disattiva l'ottimizzazione batteria per la tua app, quest'ultima è comunque interessata dal timeout di shortService FGS.
Se avvii un servizio in primo piano che include il tipo
shortServicee un altro tipo di servizio in primo piano, il sistema ignora la dichiarazione del tiposhortService. Tuttavia, il servizio deve comunque rispettare i prerequisiti degli altri tipi dichiarati. Per ulteriori informazioni, consulta la documentazione relativa ai servizi in primo piano.
Uso speciale
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceTypespecialUse- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_SPECIAL_USE- Costante da passare a
startForeground() FOREGROUND_SERVICE_TYPE_SPECIAL_USE- Prerequisiti di runtime
- Nessuna
- Descrizione
Copre tutti i casi d'uso validi dei servizi in primo piano non coperti dagli altri tipi di servizi in primo piano.
Oltre a dichiarare il
FOREGROUND_SERVICE_TYPE_SPECIAL_USEtipo di servizio in primo piano, gli sviluppatori devono dichiarare i casi d'uso nel manifest. A tal fine, specificano l'elemento<property>all'interno dell'elemento<service>. Questi valori e i casi d'uso corrispondenti vengono esaminati quando invii l'app in Google Play Console. I casi d'uso che fornisci sono in formato libero e devi assicurarti di fornire informazioni sufficienti per consentire all'esaminatore di capire perché devi utilizzare il tipospecialUse.<service android:name="fooService" android:foregroundServiceType="specialUse"> <property android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE" android:value="explanation_for_special_use"/> </service>
Esenzione dal sistema
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceTypesystemExempted- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_SYSTEM_EXEMPTED- Costante da passare a
startForeground() FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED- Prerequisiti di runtime
- Nessuna
- Descrizione
Riservato per applicazioni di sistema e integrazioni di sistema specifiche, per continuare a utilizzare i servizi in primo piano.
Per utilizzare questo tipo, un'app deve soddisfare almeno uno dei seguenti criteri:
- Il dispositivo è in stato di modalità demo
- L'app è un proprietario del dispositivo
- L'app è un proprietario del profiler
- App di emergenza con il ruolo
ROLE_EMERGENCY - App Amministrazione dispositivo
- App che dispongono dell'autorizzazione
SCHEDULE_EXACT_ALARMoUSE_EXACT_ALARMe che utilizzano il servizio in primo piano per continuare le sveglie in background, incluse le sveglie solo aptica. App VPN (configurate utilizzando Impostazioni > Rete e internet > VPN)
In caso contrario, la dichiarazione di questo tipo fa sì che il sistema generi un
ForegroundServiceTypeNotAllowedException.
Applicazione delle norme di Google Play per l'utilizzo dei tipi di servizi in primo piano
如果您的应用以 Android 14 或更高版本为目标平台,您需要在 Play 管理中心的“应用内容”页面(政策 > 应用内容)中声明应用的前台服务类型。如需详细了解如何在 Play 管理中心内声明前台服务类型,请参阅了解前台服务和全屏 intent 要求。