Tipi di servizi in primo piano

A partire da Android 14 (livello API 34), devi dichiarare una per ogni servizio in primo piano. Ciò significa che devi dichiarare tipo di servizio nel file manifest dell'app e richiedi anche il primo piano appropriato autorizzazione del servizio per quel tipo (oltre a richiedere il FOREGROUND_SERVICE autorizzazione). Inoltre, a seconda del tipo di servizio in primo piano, è possibile devi 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:

  • CHANGE_NETWORK_STATE
  • CHANGE_WIFI_STATE
  • CHANGE_WIFI_MULTICAST_STATE
  • NFC
  • TRANSMIT_IR

• Richiedi e ti viene concessa almeno una delle seguenti autorizzazioni di runtime:

  • BLUETOOTH_CONNECT
  • BLUETOOTH_ADVERTISE
  • BLUETOOTH_SCAN
  • UWB_RANGING

• 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

Nessuna

Descrizione

Operazioni di trasferimento di dati come le seguenti:

• 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

要在清单中的以下位置声明的前台服务类型

android:foregroundServiceType

health

在清单中声明的权限

FOREGROUND_SERVICE_HEALTH

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_HEALTH

运行时前提条件

必须至少满足以下其中一个条件：

• 在清单中声明 HIGH_SAMPLING_RATE_SENSORS 权限。

• 至少请求并被授予以下其中一项运行时权限：

  • BODY_SENSORS
  • ACTIVITY_RECOGNITION

说明

为健身类别的应用（例如锻炼追踪器）提供支持的所有长时间运行的用例。

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:

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION

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

Nessuna

Descrizione

Continua la riproduzione audio o video in background. Video digitale di assistenza Funzionalità di registrazione (DVR) su Android TV.

Alternative

Se visualizzi video Picture in picture, usa 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() e Service.stopSelf() di interrompere completamente il 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 chiamare Service.stopSelf(). Se il servizio non chiama Service.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 API di MediaProjection. Questi contenuti non devono essere esclusivamente multimediali contenuti.

Alternative

Per trasmettere contenuti multimediali a un altro dispositivo, utilizza l'SDK Google Cast.

Microfono

要在清单中声明的前台服务类型

android:foregroundServiceType

microphone

在清单中声明的权限

FOREGROUND_SERVICE_MICROPHONE

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_MICROPHONE

运行时前提条件

请求并获得 RECORD_AUDIO 运行时权限。

说明

在后台继续捕获麦克风内容，例如录音器或通信应用。

Telefonata

要在清单中的以下位置声明的前台服务类型

android:foregroundServiceType

phoneCall

在清单中声明的权限

FOREGROUND_SERVICE_PHONE_CALL

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_PHONE_CALL

运行时前提条件

必须至少满足以下其中一个条件：

• 应用已在其清单文件中声明 MANAGE_OWN_CALLS 权限。

• 应用是通过 ROLE_DIALER 角色。

说明

使用 ConnectionService API 继续当前通话。

替代方案

如果您需要拨打电话、视频或 VoIP 通话，请考虑使用 android.telecom 库。

考虑使用 CallScreeningService 来过滤来电。

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

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

要在清单中声明的前台服务类型

android:foregroundServiceType

specialUse

在清单中声明的权限

FOREGROUND_SERVICE_SPECIAL_USE

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_SPECIAL_USE

运行时前提条件

无

说明

涵盖其他前台服务类型未涵盖的所有有效前台服务用例。

除了声明 FOREGROUND_SERVICE_TYPE_SPECIAL_USE 前台服务类型之外，开发者还应在清单中声明用例。为此，他们会在 <service> 元素内指定 <property> 元素。这些值和相应的应用场景 。用途 您提供的案例均为自由形式，因此，您应确保提供足够的 提供相关信息，让审核者了解您为何需要使用 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>

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

如果您的应用以 Android 14 或更高版本为目标平台，您需要在 Play 管理中心的“应用内容”页面（政策 > 应用内容）中声明应用的前台服务类型。如需详细了解如何在 Play 管理中心内声明前台服务类型，请参阅了解前台服务和全屏 intent 要求。