I tipi di servizi in primo piano sono obbligatori

Per aiutare gli sviluppatori a definire in modo più intenzionale 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 servizio 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 una novità di Android 14.

Il seguente snippet di codice fornisce un esempio di dichiarazione di un tipo di servizio in primo piano nel file 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 manifest, il sistema attiverà MissingForegroundServiceTypeException quando viene chiamata startForeground() per quel servizio.

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

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:

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

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

  • 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

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 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 file manifest
FOREGROUND_SERVICE_SPECIAL_USE
Costante per passare a startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
Prerequisiti di runtime
Nessuna
Descrizione

Copre tutti i casi d'uso validi dei servizi in primo piano non coperti dagli altri 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. A tal fine, specificano l'elemento <property> all'interno dell'elemento <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 utilizzare specialUse 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:

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.