I tipi di servizi in primo piano sono obbligatori

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:

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

If apps that target Android 14 use a foreground service, they must declare a specific permission, based on the foreground service type, that Android 14 introduces. These permissions appear in the sections labeled "permission that you must declare in your manifest file" in the intended use cases and enforcement for each foreground service type section on this page.

All of the permissions are defined as normal permissions and are granted by default. Users cannot revoke these permissions.

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

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 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 servizio camera 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:

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

Foreground service type to declare in manifest under
android:foregroundServiceType
dataSync
Permission to declare in your manifest
FOREGROUND_SERVICE_DATA_SYNC
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
Runtime prerequisites
None
Description

Data transfer operations, such as the following:

  • Data upload or download
  • Backup-and-restore operations
  • Import or export operations
  • Fetch data
  • Local file processing
  • Transfer data between a device and the cloud over a network
Alternatives

See Alternatives to data sync foreground services for detailed information.

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:

Nota: l'autorizzazione di runtime BODY_SENSORS è soggetta a restrizioni durante l'uso. Per questo motivo, non puoi creare un servizio in primo piano health 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 runtime ACCESS_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

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 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

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 a microphone 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 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:

  • App è l'app tastiera predefinita tramite il ruolo ROLE_DIALER.
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

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 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 chiamare Service.stopSelf() o Service.stopForeground() prima del timeout. In caso contrario, viene chiamato il nuovo Service.onTimeout(), che offre alle app una breve possibilità di chiamare stopSelf() o stopForeground() 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 menziona FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. Per questi motivi, è considerata una best practice implementare il callback Service.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 callback Service.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 parametro FOREGROUND_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à una ForegroundServiceStartNotAllowedException.

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 tipo shortService. 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 manifest
FOREGROUND_SERVICE_SPECIAL_USE
Costante per passare a startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
Prerequisiti di runtime
Nessuno
Descrizione

Copre tutti i casi d'uso di servizi in primo piano validi che non sono contemplati dagli altri tipi di servizi in primo piano.

Oltre a dichiarare il tipo di servizio in primo piano FOREGROUND_SERVICE_TYPE_SPECIAL_USE, gli sviluppatori devono dichiarare i casi d'uso nel file manifest. Per farlo, specificano l'elemento <property> all'interno dell'elemento <service>. Questi valori e i casi d'uso corrispondenti vengono esaminati quando invii la tua app in Google Play Console. I casi d'uso forniti sono in formato libero e devi assicurarti di fornire informazioni sufficienti per consentire al revisore di capire perché è necessario utilizzare il tipo specialUse.

<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 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:

Applicazione delle norme di Google Play per l'utilizzo di tipi di servizi in primo piano

If your app targets Android 14 or higher, you'll need to declare your app's foreground service types in the Play Console's app content page (Policy > App content). For more information on how to declare your foreground service types in Play Console, see Understanding foreground service and full-screen intent requirements.