To help developers be more intentional with defining user-facing foreground
services, Android 10 introduced the android:foregroundServiceType
attribute within the <service>
element.
If your app targets Android 14, it must specify appropriate foreground service types. As in previous versions of Android, multiple types can be combined. This list shows the foreground service types to choose from:
camera
connectedDevice
dataSync
health
location
mediaPlayback
mediaProjection
microphone
phoneCall
remoteMessaging
shortService
specialUse
systemExempted
If a use case in your app isn't associated with any of these types, we strongly recommend that you migrate your logic to use WorkManager or user-initiated data transfer jobs.
The health, remoteMessaging, shortService, specialUse
, and systemExempted
types are new in Android 14.
The following code snippet provides an example of a foreground service type declaration in the 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>
If an app that targets Android 14 doesn't define types for a given service in
the manifest, then the system will raise MissingForegroundServiceTypeException
upon calling startForeground()
for that service.
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
La best practice per le applicazioni che avviano i servizi in primo piano consiste nell'utilizzare la
versione ServiceCompat
di startForeground()
(disponibile in androidx-core
1.12 e versioni successive), in cui passi in un numero intero
a bit dei tipi di servizi in primo piano. Puoi scegliere di passare uno o più valori di tipo.
In genere, devi dichiarare solo i tipi richiesti per un determinato caso d'uso. In questo modo è più facile soddisfare le aspettative del sistema per ogni tipo di servizio in primo piano. Nei casi in cui un servizio in primo piano viene avviato con più tipi, il servizio in primo piano deve ottemperare ai requisiti di applicazione della piattaforma di tutti i tipi.
ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)
Se il tipo di servizio in primo piano non è specificato nella chiamata, il valore predefinito è costituito dai valori definiti nel manifest. Se non hai specificato il tipo di servizio nel manifest, il sistema genera un errore MissingForegroundServiceTypeException
.
Se il servizio in primo piano ha bisogno di nuove autorizzazioni dopo l'avvio, devi chiamare di nuovo startForeground()
e aggiungere i nuovi tipi di servizi. Ad esempio, supponiamo che un'app per il fitness esegua un servizio di monitoraggio della corsa che ha sempre bisogno di informazioni location
, ma potrebbe o meno richiedere le autorizzazioni media
. Nel
file manifest devi dichiarare sia location
sia mediaPlayback
. Se un
utente avvia un'esecuzione e vuole semplicemente che la propria posizione venga monitorata, la tua app dovrebbe chiamare
startForeground()
e trasmettere solo il tipo di servizio location
. Quindi, se l'utente
vuole iniziare a riprodurre l'audio, chiama di nuovo startForeground()
e passa
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
In order to use a given foreground service type, you must declare a particular permission in your manifest file, you must fulfill specific runtime requirements, and your app must fulfill one of the intended sets of use cases for that type. The following sections explain the permission that you must declare, the runtime prerequisites, and the intended use cases for each type.
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
CAMERA
Nota:l'autorizzazione di runtime
CAMERA
è soggetta a limitazioni durante l'utilizzo. Per questo motivo, non puoi creare un servizio in primo pianocamera
mentre 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:foregroundServiceType
connectedDevice
- 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:foregroundServiceType
dataSync
- 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:foregroundServiceType
health
- 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_SENSORS
nel file manifest.Richiedi e ottieni almeno una delle seguenti autorizzazioni di runtime:
BODY_SENSORS
con livello API 35 e versioni precedentiREAD_HEART_RATE
READ_SKIN_TEMPERATURE
READ_OXYGEN_SATURATION
ACTIVITY_RECOGNITION
Nota: le autorizzazioni di runtime
BODY_SENSORS
e LETTURA basate su sensori sono soggette a restrizioni durante l'uso. Per questo motivo, non puoi creare un servizio in primo pianohealth
che 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
- Foreground service type to declare in manifest under
android:foregroundServiceType
location
- Permission to declare in your manifest
FOREGROUND_SERVICE_LOCATION
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
- Runtime prerequisites
The user must have enabled location services and the app must be granted at least one of the following runtime permissions:
Note: In order to check that the user has enabled location services as well as granted access to the runtime permissions, use
PermissionChecker#checkSelfPermission()
Note: The location runtime permissions are subject to while-in-use restrictions. For this reason, you cannot create a
location
foreground service while your app is in the background, unless you've been granted theACCESS_BACKGROUND_LOCATION
runtime permission. For more information, see Restrictions on starting foreground services that need while-in-use permissions.- Description
Long-running use cases that require location access, such as navigation and location sharing.
- Alternatives
If your app needs to be triggered when the user reaches specific locations, consider using the geofence API instead.
Contenuti multimediali
- Foreground service type to declare in manifest under
android:foregroundServiceType
mediaPlayback
- Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PLAYBACK
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
- Runtime prerequisites
- None
- Description
- Continue audio or video playback from the background. Support Digital Video Recording (DVR) functionality on Android TV.
- Alternatives
- If you're showing picture-in-picture video, use Picture-in-Picture mode.
Proiezione di contenuti multimediali
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceType
mediaProjection
- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_MEDIA_PROJECTION
- Costante da passare a
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
- Prerequisiti di runtime
Chiama il metodo
createScreenCaptureIntent()
prima di avviare il servizio in primo piano. In questo modo viene mostrata una notifica di autorizzazione all'utente, che deve concedere l'autorizzazione prima che tu possa creare il servizio.Dopo aver creato il servizio in primo piano, puoi chiamare
MediaProjectionManager.getMediaProjection()
.- Descrizione
Proietta i contenuti su un display non principale o su un dispositivo esterno utilizzando le API
MediaProjection
. Questi contenuti non devono essere necessariamente contenuti media.- Alternative
Per riprodurre in streaming contenuti multimediali su un altro dispositivo, utilizza l'SDK Google Cast.
Microfono
- Foreground service type to declare in manifest under
android:foregroundServiceType
microphone
- Permission to declare in your manifest
FOREGROUND_SERVICE_MICROPHONE
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
- Runtime prerequisites
Request and be granted the
RECORD_AUDIO
runtime permission.Note: The
RECORD_AUDIO
runtime permission is subject to while-in-use restrictions. For this reason, you cannot create amicrophone
foreground service while your app is in the background, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.- Description
Continue microphone capture from the background, such as voice recorders or communication apps.
Telefonata
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceType
phoneCall
- 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_CALLS
nel 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
CallScreeningService
per filtrare le chiamate.
Messaggistica remota
- Foreground service type to declare in manifest under
android:foregroundServiceType
remoteMessaging
- Permission to declare in your manifest
FOREGROUND_SERVICE_REMOTE_MESSAGING
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
- Runtime prerequisites
- None
- Description
- Transfer text messages from one device to another. Assists with continuity of a user's messaging tasks when they switch devices.
Servizio di Short
- Foreground service type to declare in manifest under
android:foregroundServiceType
shortService
- Permission to declare in your manifest
- None
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
- Runtime prerequisites
- None
- Description
Quickly finish critical work that cannot be interrupted or postponed.
This type has some unique characteristics:
- Can only run for a short period of time (about 3 minutes).
- No support for sticky foreground services.
- Cannot start other foreground services.
- Doesn't require a type-specific permission, though it still
requires the
FOREGROUND_SERVICE
permission. - A
shortService
can only change to another service type if the app is currently eligible to start a new foreground service. - A foreground service can change its type to
shortService
at any time, at which point the timeout period begins.
The timeout for shortService begins from the moment that
Service.startForeground()
is called. The app is expected to callService.stopSelf()
orService.stopForeground()
before the timeout occurs. Otherwise, the newService.onTimeout()
is called, giving apps a brief opportunity to callstopSelf()
orstopForeground()
to stop their service.A short time after
Service.onTimeout()
is called, the app enters a cached state and is no longer considered to be in the foreground, unless the user is actively interacting with the app. A short time after the app is cached and the service has not stopped, the app receives an ANR. The ANR message mentionsFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
. For these reasons, it's considered best practice to implement theService.onTimeout()
callback.The
Service.onTimeout()
callback doesn't exist on Android 13 and lower. If the same service runs on such devices, it doesn't receive a timeout, nor does it ANR. Make sure that your service stops as soon as it finishes the processing task, even if it hasn't received theService.onTimeout()
callback yet.It's important to note that if the timeout of the
shortService
is not respected, the app will ANR even if it has other valid foreground services or other app lifecycle processes running.If an app is visible to the user or satisfies one of the exemptions that allow foreground services to be started from the background, calling
Service.StartForeground()
again with theFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
parameter extends the timeout by another 3 minutes. If the app isn't visible to the user and doesn't satisfy one of the exemptions, any attempt to start another foreground service, regardless of type, causes aForegroundServiceStartNotAllowedException
.If a user disables battery optimization for your app, it's still affected by the timeout of shortService FGS.
If you start a foreground service that includes the
shortService
type and another foreground service type, the system ignores theshortService
type declaration. However, the service must still adhere to the prerequisites of the other declared types. For more information, see the Foreground services documentation.
Uso speciale
- Foreground service type to declare in manifest under
android:foregroundServiceType
specialUse
- Permission to declare in your manifest
FOREGROUND_SERVICE_SPECIAL_USE
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
- Runtime prerequisites
- None
- Description
Covers any valid foreground service use cases that aren't covered by the other foreground service types.
In addition to declaring the
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
foreground service type, developers should declare use cases in the manifest. To do so, they specify the<property>
element within the<service>
element. These values and corresponding use cases are reviewed when you submit your app in the Google Play Console. The use cases you provide are free-form, and you should make sure to provide enough information to let the reviewer see why you need to use thespecialUse
type.<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:foregroundServiceType
systemExempted
- 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_ALARM
oUSE_EXACT_ALARM
e 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
Se la tua app ha come target Android 14 o versioni successive, devi dichiarare i tipi di servizi in primo piano della tua app nella pagina Contenuti app di Play Console (Norme > Contenuti app). Per ulteriori informazioni su come dichiarare i tipi di servizio in primo piano in Play Console, consulta Informazioni sui requisiti relativi al servizio in primo piano e all'intent a schermo intero.