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, potresti dover richiedere le autorizzazioni di runtime prima di avviare il servizio.
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
- 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 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 da passare a
startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
- Prerequisiti di runtime
- Nessuno
- 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:
- Descrizione
Eventuali casi d'uso di lunga durata per supportare le app nella categoria fitness, ad esempio gli activity tracker.
Posizione
- Tipo di servizio in primo piano da dichiarare nel manifest in
android:foregroundServiceType
location
- 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:
- 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:foregroundServiceType
mediaPlayback
- Autorizzazione da dichiarare nel file manifest
FOREGROUND_SERVICE_MEDIA_PLAYBACK
- Costante da 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 in modalità Picture in picture, utilizza la modalità Picture in picture.
Elaborazione contenuti multimediali in corso
- Foreground service type to declare in manifest under
android:foregroundServiceType
mediaProcessing
- Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PROCESSING
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
- Runtime prerequisites
- None
- Description
Service for performing time-consuming operations on media assets, like converting media to different formats. The system allows this service a limited time to run; under normal circumstances, this time limit would be 6 hours out of every 24. (This limit is shared by all of an app's
mediaProcessing
foreground services.)Your app should manually stop the media processing service in the following scenario:
- When the transcoding operation finishes or reaches a failure state, have the
service call
Service.stopForeground()
andService.stopSelf()
to stop the service completely.
- When the transcoding operation finishes or reaches a failure state, have the
service call
If the timeout period is reached, the system calls the service's
Service.onTimeout(int, int)
method. At this time, the service has a few seconds to callService.stopSelf()
. If the service does not callService.stopSelf()
, an ANR will occur with this error message: "A foreground service of <fgs_type> did not stop within its timeout: <component_name>".Note:
Service.onTimeout(int, int)
is not available on Android 14 or lower. On devices running those versions, if a media processing service reaches the timeout period, the system immediately caches the app. For this reason, your app shouldn't wait to get a timeout notification. Instead, it should terminate the foreground service or change it to a background service as soon as appropriate.
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
- Tipo di servizio in primo piano da dichiarare nel 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
Continuare l'acquisizione del microfono in background, ad esempio da registratori vocali o apps di 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 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
- 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
- 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 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.