Per aiutare gli sviluppatori a definire con più precisione 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 servizi 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:
camera
connectedDevice
dataSync
health
location
mediaPlayback
mediaProjection
microphone
phoneCall
remoteMessaging
shortService
specialUse
systemExempted
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 nuovi in Android 14.
Il seguente snippet di codice fornisce un esempio di dichiarazione di tipo di servizio in primo piano nel 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 file manifest, il sistema aumenterà MissingForegroundServiceTypeException
quando chiama startForeground()
per il servizio in questione.
Dichiara una nuova autorizzazione per l'utilizzo dei tipi di servizi in primo piano
Se le app destinate ad Android 14 utilizzano un servizio in primo piano, devono dichiarare un'autorizzazione specifica introdotta da Android 14 in base al tipo di servizio in primo piano. Queste autorizzazioni sono visualizzate nelle sezioni "Autorizzazione che devi dichiarare nel file manifest" nella sezione relativa ai casi d'uso previsti e all'applicazione forzata 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 runtime
La best practice per le applicazioni che avviano i servizi in primo piano prevede l'utilizzo della versione ServiceCompat
di startForeground()
(disponibile in androidx-core 1.12 e versioni successive), in cui passi un numero intero bit a bit dei tipi di servizi in primo piano. Puoi scegliere di passare
uno o più valori di tipo.
In genere, è necessario 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 rispettare i 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, per impostazione predefinita verranno utilizzati i valori definiti nel manifest. Se non hai specificato il tipo di servizio nel manifest, il sistema genera MissingForegroundServiceTypeException
.
Se, dopo il lancio, il servizio in primo piano ha bisogno di nuove autorizzazioni, devi
chiamare di nuovo startForeground()
e aggiungere i nuovi tipi di servizio. Ad esempio, supponi che un'app per l'attività fisica esegue un servizio di monitoraggio del funzionamento che richiede sempre informazioni su location
, ma potrebbe o meno avere bisogno delle autorizzazioni media
. Devi
dichiarare sia location
sia mediaPlayback
nel file manifest. Se un
utente inizia una corsa e vuole solo che la sua posizione venga monitorata, la tua app deve chiamare
startForeground()
e trasmettere solo il tipo di servizio location
. Quindi, se l'utente
vuole avviare la riproduzione dell'audio, chiama di nuovo startForeground()
e passa
location|mediaPlayback
.
Controlli di runtime del sistema
Il sistema verifica l'utilizzo corretto dei tipi di servizi in primo piano e verifica che l'app abbia richiesto le autorizzazioni di runtime appropriate o che 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ò significa che le app devono seguire un ordine molto specifico delle operazioni 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 delle operazioni e richiedere l'autorizzazione prima di avviare il servizio in primo piano.
Le specifiche dell'applicazione della piattaforma sono riportate nelle sezioni etichettate come "requisiti di runtime" nella sezione relativa ai casi d'uso previsti e all'applicazione per ogni tipo di servizio in primo piano in 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, devi soddisfare requisiti di runtime specifici e la tua app deve soddisfare uno degli insiemi di casi d'uso previsti per quel tipo. Le seguenti sezioni spiegano l'autorizzazione da dichiarare, i prerequisiti di runtime e i casi d'uso previsti per ogni tipo.
Fotocamera
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
camera
- Autorizzazione da dichiarare nel manifest
FOREGROUND_SERVICE_CAMERA
- Costante per 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 restrizioni durante l'uso. Per questo motivo, non puoi creare un serviziocamera
in primo piano mentre la tua app è in background, con alcune eccezioni. Per maggiori informazioni, consulta Limitazioni relative all'avvio di servizi in primo piano che richiedono le autorizzazioni durante l'uso.- Descrizione
Continua ad accedere alla fotocamera in background, ad esempio con le app di video chat che consentono il multitasking.
Dispositivo connesso
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
connectedDevice
- Autorizzazione da dichiarare nel manifest
FOREGROUND_SERVICE_CONNECTED_DEVICE
- Costante per 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 ti viene concessa almeno una delle seguenti autorizzazioni di runtime:
Chiama il numero
UsbManager.requestPermission()
- Descrizione
Le interazioni con dispositivi esterni che richiedono una connessione di rete, Bluetooth, NFC, IR, USB.
- Alternative
Se la tua app deve effettuare un trasferimento di dati continuo su un dispositivo esterno, valuta l'utilizzo di Gestione dispositivi associati. Utilizza l'API companion device Presence per mantenere l'app in esecuzione quando il dispositivo associato è nel raggio d'azione.
Se la tua app deve cercare dispositivi Bluetooth, valuta la possibilità di utilizzare l'API Bluetooth Scan.
Sincronizzazione dati
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
dataSync
- Autorizzazione da dichiarare nel manifest
FOREGROUND_SERVICE_DATA_SYNC
- Costante per passare a
startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
- Prerequisiti di runtime
- Nessuno
- Descrizione
Operazioni di trasferimento di 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 su una rete
- Alternative
Per informazioni dettagliate, consulta le alternative ai servizi in primo piano di sincronizzazione dei dati.
Integrità
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
health
- Autorizzazione da dichiarare nel manifest
FOREGROUND_SERVICE_HEALTH
- Costante per 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 tuo manifest.Richiedi e ti viene concessa almeno una delle seguenti autorizzazioni di runtime:
Nota: l'autorizzazione di runtime
BODY_SENSORS
è soggetta a restrizioni durante l'uso. Per questo motivo, non puoi creare un servizio in primo pianohealth
che utilizzi i sensori del corpo mentre l'app è in background, con alcune eccezioni. Per maggiori informazioni, consulta Limitazioni relative all'avvio di servizi in primo piano che richiedono le autorizzazioni durante l'uso.- Descrizione
Qualsiasi caso d'uso a lungo termine per supportare app nella categoria di fitness, come i tracker per allenamenti.
Posizione
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
location
- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_LOCATION
- Costante per passare a
startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
- Prerequisiti di runtime
L'utente deve aver attivato i servizi di geolocalizzazione e all'app deve essere concessa almeno una delle seguenti autorizzazioni di runtime:
Nota: per verificare che l'utente abbia attivato i servizi di geolocalizzazione e concesso l'accesso alle autorizzazioni di runtime, utilizza
PermissionChecker#checkSelfPermission()
Nota:le autorizzazioni di runtime per la posizione sono soggette a limitazioni durante l'utilizzo. Per questo motivo, non puoi creare un servizio in primo piano
location
mentre la tua app è in background, a meno che ti sia stata concessa l'autorizzazione di runtimeACCESS_BACKGROUND_LOCATION
. Per maggiori informazioni, consulta Limitazioni relative all'avvio di servizi in primo piano che richiedono autorizzazioni durante l'uso.- Descrizione
Casi d'uso di lunga data 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 località specifiche, valuta la possibilità di utilizzare invece l'API geofence.
Contenuti multimediali
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
mediaPlayback
- Autorizzazione da dichiarare nel manifest
FOREGROUND_SERVICE_MEDIA_PLAYBACK
- Costante per passare a
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
- Prerequisiti di runtime
- Nessuno
- 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 Picture in picture, usa la modalità Picture in picture.
Proiezione di contenuti multimediali
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
mediaProjection
- Autorizzazione da dichiarare nel manifest
FOREGROUND_SERVICE_MEDIA_PROJECTION
- Costante per 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 visualizzata una notifica di autorizzazione all'utente; l'utente deve concedere l'autorizzazione prima di poter creare il servizio.Dopo aver creato il servizio in primo piano, puoi chiamare
MediaProjectionManager.getMediaProjection()
.- Descrizione
Proietta i contenuti su un dispositivo esterno o non principale utilizzando le API
MediaProjection
. Questi contenuti non devono essere esclusivamente contenuti multimediali.- Alternative
Per riprodurre in streaming contenuti multimediali su un altro dispositivo, utilizza l'SDK Google Cast.
Microfono
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
microphone
- Autorizzazione da dichiarare nel manifest
FOREGROUND_SERVICE_MICROPHONE
- Costante per passare a
startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
- Prerequisiti di runtime
Richiedere e ottenere l'autorizzazione di runtime
RECORD_AUDIO
.Nota: l'autorizzazione di runtime
RECORD_AUDIO
è soggetta a restrizioni durante l'uso. Per questo motivo, non puoi creare un serviziomicrophone
in primo piano mentre la tua app è in background, con alcune eccezioni. Per maggiori informazioni, consulta Limitazioni relative all'avvio di servizi in primo piano che richiedono le autorizzazioni durante l'uso.- Descrizione
Continua l'acquisizione del microfono in background, ad esempio registratori vocali o app di comunicazione.
Telefonata
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
phoneCall
- Autorizzazione da dichiarare nel manifest
FOREGROUND_SERVICE_PHONE_CALL
- Costante per passare a
startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
- Prerequisiti di runtime
Deve essere vera almeno una di queste condizioni:
- L'app ha dichiarato l'autorizzazione
MANAGE_OWN_CALLS
nel file manifest.
- L'app ha dichiarato l'autorizzazione
- App è l'app tastiera predefinita tramite il ruolo
ROLE_DIALER
.
- App è l'app tastiera predefinita tramite il ruolo
- Descrizione
Continuare una chiamata in corso utilizzando le API
ConnectionService
.- Alternative
Se devi effettuare chiamate telefoniche, video o VoIP, valuta di utilizzare la libreria di
android.telecom
.Valuta la possibilità di utilizzare
CallScreeningService
per filtrare le chiamate.
Messaggistica remota
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
remoteMessaging
- Autorizzazione da dichiarare nel manifest
FOREGROUND_SERVICE_REMOTE_MESSAGING
- Costante per passare a
startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
- Prerequisiti di runtime
- Nessuno
- Descrizione
- Trasferisci messaggi da un dispositivo a un altro. Agevola la continuità delle attività di messaggistica di un utente quando cambia dispositivo.
Servizio breve
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
shortService
- Autorizzazione da dichiarare nel manifest
- Nessuno
- Costante per passare a
startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
- Prerequisiti di runtime
- Nessuno
- Descrizione
Completa rapidamente il lavoro critico che non può essere interrotto o posticipato.
Questo tipo presenta alcune caratteristiche uniche:
- Può essere eseguito solo per un breve periodo di tempo (circa 3 minuti).
- Nessun supporto per i servizi in primo piano fissi.
- Impossibile avviare altri servizi in primo piano.
- Non richiede un'autorizzazione specifica per tipo, ma
richiede comunque l'autorizzazione
FOREGROUND_SERVICE
. - Un
shortService
può passare a un altro tipo di servizio solo se l'app è attualmente idonea ad avviare un nuovo servizio in primo piano. - Un servizio in primo piano può modificare il proprio tipo in
shortService
in qualsiasi momento, dopodiché inizia il periodo di timeout.
Il timeout per shortService inizia nel momento in cui viene chiamato
Service.startForeground()
. L'app dovrebbe chiamareService.stopSelf()
oService.stopForeground()
prima del timeout. In caso contrario, viene chiamato il nuovoService.onTimeout()
, che offre alle app una breve possibilità di chiamarestopSelf()
ostopForeground()
per interrompere il servizio.Poco tempo dopo la chiamata di
Service.onTimeout()
, l'app entra in uno stato memorizzato nella cache e non è più considerata in primo piano, a meno che l'utente non stia interagendo attivamente con l'app. Poco tempo dopo che l'app viene 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 callback
Service.onTimeout()
non esiste su Android 13 e versioni precedenti. Se su questi dispositivi viene eseguito lo stesso servizio, non riceve alcun timeout, né l'errore ANR. Assicurati che il servizio si interrompa non appena termina l'attività di elaborazione, anche se non ha ancora ricevuto il callbackService.onTimeout()
.È importante notare che se il timeout di
shortService
non viene rispettato, l'app restituirà un errore ANR anche se ha altri servizi in primo piano validi o altri processi del ciclo di vita delle app in esecuzione.Se un'app è visibile all'utente o soddisfa una delle esenzioni che consentono l'avvio dei servizi in primo piano in background, la chiamata
Service.StartForeground()
di nuovo con il parametroFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
estende 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, causerà unaForegroundServiceStartNotAllowedException
.Se un utente disattiva l'ottimizzazione della batteria per la tua app, l'evento viene comunque influenzato dal timeout di shortService FGS.
Se avvii un servizio in primo piano che include il tipo
shortService
e 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 sui servizi in primo piano.
Uso speciale
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
specialUse
- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_SPECIAL_USE
- Costante per passare a
startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
- Prerequisiti di runtime
- Nessuna
- Descrizione
Riguarda casi d'uso di servizi in primo piano validi che non sono coperti dall'altro i tipi di servizi in primo piano.
Oltre a dichiarare il
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
servizio in primo piano, gli sviluppatori devono dichiarare i casi d'uso del file manifest. Per farlo, specifica l'elemento<property>
all'interno della sezione<service>
. Questi valori e i casi d'uso corrispondenti vengono esaminata quando invii l'app in Google Play Console. L'utilizzo di assistenza forniti sono in formato libero e dovresti assicurarti di fornire abbastanza informazioni per far capire al revisore perché è necessario utilizzarespecialUse
di testo.<service android:name="fooService" android:foregroundServiceType="specialUse"> <property android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE" android:value="explanation_for_special_use"/> </service>
Sistema esente
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
systemExempted
- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
- Costante per passare a
startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
- Prerequisiti di runtime
- Nessuna
- Descrizione
Riservato per applicazioni di sistema e integrazioni di sistema specifiche, per continuano a utilizzare i servizi in primo piano.
Per utilizzare questo tipo, un'app deve soddisfare almeno uno dei seguenti criteri:
- Il dispositivo è in modalità demo
- L'app è proprietario del dispositivo
- L'app è proprietario di Profiler
- App per la sicurezza con il ruolo
ROLE_EMERGENCY
- App di amministrazione dispositivo
- App con
SCHEDULE_EXACT_ALARM
oUSE_EXACT_ALARM
e che utilizzano Servizio in primo piano per continuare gli allarmi in background, incluse le sveglie solo con tecnologia aptica. App VPN (configurate utilizzando Impostazioni > Rete e internet > VPN)
In caso contrario, la dichiarazione di questo tipo comporta la generazione di un
ForegroundServiceTypeNotAllowedException
.
Applicazione delle norme di Google Play per l'utilizzo di 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 dell'app nella pagina Contenuti app di Play Console (Norme > Contenuti app). Per maggiori informazioni su come dichiarare i tipi di servizi in primo piano in Play Console, consulta Informazioni sui requisiti relativi al servizio in primo piano e all'intent a schermo intero.