A partire da Android 14 (livello API 34), devi dichiarare un tipo di servizio
appropriato per ogni servizio in primo piano. Ciò significa che devi dichiarare il tipo di servizio nel file manifest dell'app e richiedere anche l'autorizzazione per il servizio in primo piano appropriata per quel tipo (oltre a richiedere l'autorizzazione FOREGROUND_SERVICE
). Inoltre, a seconda del tipo di servizio in primo piano, potrebbe essere necessario richiedere autorizzazioni di runtime prima di avviare il servizio.
Fotocamera
- Tipo di servizio in primo piano da dichiarare nel file 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
- Descrizione
Continua ad accedere alla fotocamera in background, ad esempio le app di videochiamata 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 manifest in
android:foregroundServiceType
dataSync
- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_DATA_SYNC
- Costante per 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, consulta 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 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 file manifest.Richiedi e ottieni almeno una delle seguenti autorizzazioni di runtime:
- Descrizione
Eventuali casi d'uso di lunga durata per supportare app nella categoria fitness, come i tracker di allenamento.
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:
- 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
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceType
mediaPlayback
- Autorizzazione da dichiarare nel file 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 visualizzi video Picture in picture, utilizza la modalità Picture in picture.
Elaborazione contenuti multimediali in corso
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
mediaProcessing
- Autorizzazione da dichiarare nel manifest
FOREGROUND_SERVICE_MEDIA_PROCESSING
- Costante per passare a
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
- Prerequisiti di runtime
- Nessuno
- Descrizione
Servizio per l'esecuzione di operazioni dispendiose in termini di tempo sugli asset multimediali, come la conversione dei contenuti multimediali in formati diversi. Il sistema consente l'esecuzione di questo servizio per un tempo limitato; in circostanze normali, questo limite di tempo è di 6 ore ogni 24. Questo limite è condiviso da tutti i
mediaProcessing
servizi in primo piano di un'app.L'app deve interrompere manualmente il servizio di elaborazione dei contenuti multimediali nel seguente scenario:
- Quando l'operazione di transcodifica termina o raggiunge uno stato di errore, chiedi alla
chiamata di servizio
Service.stopForeground()
eService.stopSelf()
di interrompere completamente il servizio.
- Quando l'operazione di transcodifica termina o raggiunge uno stato di errore, chiedi alla
chiamata di servizio
Se viene raggiunto il periodo di timeout, il sistema chiama il metodo
Service.onTimeout(int, int)
del servizio. In questo momento, il servizio ha pochi secondi per chiamareService.stopSelf()
. Se il servizio non chiamaService.stopSelf()
, si verificherà un errore ANR con questo messaggio di errore: "Un servizio in primo piano di <fgs_type> non è stato interrotto durante il timeout: <component_name>".Nota:
Service.onTimeout(int, int)
non è disponibile su Android 14 o versioni precedenti. Sui dispositivi che eseguono queste versioni, se un servizio di elaborazione multimediale raggiunge il periodo di timeout, il sistema memorizza immediatamente l'app nella cache. Per questo motivo, l'app non deve attendere di ricevere una notifica di timeout. Dovrebbe invece terminare il servizio in primo piano o passare a un servizio in background non appena opportuno.
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 necessariamente essere esclusivamente 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 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
.- Descrizione
Continua l'acquisizione del microfono in background, ad esempio da registratori vocali o app per la comunicazione.
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 proprio 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
- 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 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
- 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>
Esenzione dal sistema
- Tipo di servizio in primo piano da dichiarare nel file manifest in
android:foregroundServiceType
systemExempted
- Autorizzazione da dichiarare nel manifest
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
- Costante per passare a
startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
- Prerequisiti di runtime
- Nessuno
- 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 modalità demo
- L'app è un proprietario del dispositivo
- L'app è proprietario di Profiler
- App per la sicurezza con il ruolo
ROLE_EMERGENCY
- App Amministratore dispositivo
- App con autorizzazione
SCHEDULE_EXACT_ALARM
oUSE_EXACT_ALARM
App VPN (configurate con Impostazioni > Rete e internet > VPN)
In caso contrario, la dichiarazione di questo tipo fa sì che il sistema restituisca un elemento
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 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.