Rafforzamento dell'audio in background

A partire da Android 17, il framework audio impone restrizioni alle interazioni audio in background, tra cui riproduzione audio, richieste di messa a fuoco audio e API di modifica del volume, per garantire che queste modifiche vengano avviate intenzionalmente dall'utente.

Se uno sviluppatore di app intende controllare l'audio senza un'attività visibile, deve assicurarsi che l'app abbia un servizio in primo piano (che non sia di tipo SHORT_SERVICE) avviato con funzionalità in uso. A un servizio in primo piano vengono concesse funzionalità WIU se viene avviato in risposta a un MediaSessionEvent o mentre l'app è visibile all'utente.

Se l'app tenta di chiamare le API audio mentre non si trova in un ciclo di vita valido, le API di riproduzione audio e modifica del volume non vanno a buon fine senza generare un'eccezione o fornire un messaggio di errore. L'API Audio Focus non funziona e restituisce il codice di risultato AUDIOFOCUS_REQUEST_FAILED.

L'intenzione di introdurre queste limitazioni è quella di ridurre le esperienze buggy di audio in background non intenzionali. Ecco alcuni esempi:

• Le app che riproducono audio senza un servizio in primo piano possono essere bloccate. Quando l'app viene scongelata, la riproduzione audio riprende in modo imprevisto, potenzialmente ore dopo.
• Le app che riproducono audio senza un servizio in primo piano hanno dovuto affrontare varie limitazioni di esecuzione che hanno comportato prestazioni audio instabili.
• Riproduzione separata dal ciclo di vita dell'attività, che potrebbe comportare una sessione di riproduzione o eventi di messa a fuoco trapelati che continuano senza che l'utente possa interrompere la riproduzione.

Invitiamo gli sviluppatori a testare le proprie app e a fornire feedback sulla modifica del comportamento se sono presenti casi d'uso audio intenzionali interessati negativamente. Segnala eventuali problemi utilizzando questo strumento di monitoraggio dei problemi di compatibilità delle app con Android 17.

Identificare i casi d'uso dell'audio in background interessati

Controlla l'implementazione della riproduzione audio e verifica se la tua app intende fornire funzionalità di interazione audio in background anche in circostanze condizionali.

Se la tua app intende riprodurre solo audio o utilizzare API audio mentre mostra un'attività visibile all'utente, incluso l'utilizzo della modalità Picture in Picture (PIP), non è interessata da nessuna di queste modifiche.

Se la tua app fornisce funzionalità VOIP, incluse le app di videochiamate, deve già soddisfare i requisiti introdotti per la riproduzione (in genere utilizzando le API di telecomunicazioni consigliate) per registrare correttamente l'audio, pertanto è improbabile che venga interessata.

Se la tua app intende continuare la riproduzione audio mentre lo schermo è spento o mentre l'utente ha chiuso completamente l'attività, come si vede più comunemente nelle app di streaming musicale o di podcast, la tua app è considerata fornire la funzionalità audio in background e deve soddisfare i nuovi requisiti.

Scenari audio in background che potrebbero essere interessati

Se la tua app non segue il modello di continuazione di un'interazione audio iniziata mentre l'app era aperta o in risposta a un trigger utente esplicito, è probabile che la funzionalità dell'app venga eliminata in modo silenzioso.

Ad esempio, se la tua app avvia un servizio in primo piano in risposta a BOOT_COMPLETE e tenta di interagire con l'audio, verrà soppressa.

Best practice per l'audio in background per ridurre l'impatto

• Utilizza il componente MediaSessionService della libreria Jetpack media3 per gestire la riproduzione audio in background.

  In questo caso, è improbabile che la tua app sia interessata dall'hardening in background, poiché la libreria aiuta a gestire il ciclo di vita della riproduzione.

• Se non utilizzi la libreria media3, dovrai avviare manualmente un mediaPlayback FGS. Avvia sempre un servizio in primo piano mentre l'app è in primo piano se è possibile che si verifichi la riproduzione audio in background.

  Ad esempio, se la tua app è un'app di streaming video che in genere è solo in primo piano, ma contiene un'agevolazione per l'utente per continuare la riproduzione mentre lo schermo è spento, quando si verifica l'attivazione della riproduzione avviata dall'utente, la tua app deve comunque avviare un servizio in primo piano.

  In questo modo, il servizio in primo piano viene avviato con le funzionalità WIU.

• Mantieni attivo il mediaPlayback FGS durante gli errori temporanei di durata inferiore a 10 minuti.

  Se la tua app presenta un errore temporaneo, ad esempio un problema di buffering dovuto all'attività di rete, o se si verifica un'interruzione temporanea prevista, ad esempio AUDIOFOCUS_LOSS_TRANSIENT, l'intent di riproduzione deve continuare. Pertanto, il tuo FGS deve rimanere attivo.

• Interrompi il servizio in primo piano al termine della riproduzione e riavviala solo se l'utente riprende esplicitamente la riproduzione.

  In caso di segnale permanente per terminare la riproduzione (ad esempio, contenuti completi senza riproduzione automatica, un AUDIOFOCUS_LOSS, un evento di pausa dall'UMO o un evento chiave multimediale) o di errore non recuperabile, l'app deve interrompere l'interazione audio, arrestare il servizio in primo piano e terminare la sessione multimediale. Tutto questo corrisponde alla concezione dell'utente di "completamento" dell'interazione audio in background desiderata. Dopo averlo fatto, la tua app non ha più funzionalità di interazione audio in background.

  Successivamente, se l'utente riprende esplicitamente la riproduzione, ad esempio tramite l'interfaccia utente della tua app o tramite il pulsante di riproduzione dell'oggetto multimediale universale, l'intent per avviare la riproduzione audio deve essere restituito, con conseguente avvio di un nuovo servizio in primo piano.

• Testa il comportamento di riproduzione audio con i comandi adb shell.

Test delle modifiche su Android 16 e Android 17

La funzionalità è già implementata a livello di "avviso" a partire da Android 16. Ciò significa che le app possono utilizzare adb shell cmd audio set-enable-hardening per testare manualmente l'applicazione della protezione dell'audio in background.

Per abilitare l'applicazione sui dispositivi con Android 16, esegui il seguente comando:

adb shell cmd audio set-enable-hardening 1

Per disattivare l'applicazione su dispositivi con Android 17, esegui questo comando:

adb shell cmd audio set-enable-hardening 0

Ti consigliamo inoltre di utilizzare logcat o il comando adb adb dumpsys audio per identificare se l'app ha riscontrato errori silenziosi a causa dell'applicazione dell'hardening audio. In questo caso, il log avrà una voce con il prefisso AudioHardening con il nome del pacchetto.

Informazioni sul servizio di geolocalizzazione con funzionalità di utilizzo

In genere, i servizi in primo piano (FGS) devono essere avviati mentre un'app è in primo piano per estendere le operazioni avviate dall'utente. In alcuni casi specifici, le app possono avviare un servizio in primo piano mentre l'app è in background. Tuttavia, a questi servizi in primo piano di solito non vengono concesse le funzionalità "durante l'uso".

WIU funge da barriera di sicurezza: impedisce agli FGS avviati in background di intraprendere determinati comportamenti sensibili quando l'utente potrebbe non essere a conoscenza dell'attività dell'app. Impedisce all'app di accedere a dati sensibili come posizione, fotocamera o microfono e, a partire da Android 17, blocca anche le API audio che in genere richiedono un contesto UI visibile.

Ecco un riferimento utile:

• FGS standard: i servizi avviati mentre l'app è visibile o a cui è stata concessa la funzionalità di avvio dell'attività in background hanno accesso a WIU.
• Servizio in primo piano avviato in background (BFSL): la maggior parte non concede l'accesso WIU. Le eccezioni principali che concedono l'intento di utilizzo sono interazioni che coinvolgono l'intento esplicito dell'utente, ad esempio clic sulle notifiche, interazioni con i widget o eventi dei tasti multimediali da un dispositivo esterno.
• System started FGS: FGS started using system-server delegation (for example, by using Telecom jetpack library) are granted WIU access.

Scopri di più in Limitazioni all'avvio di un servizio in primo piano dallo sfondo.

Elenco completo delle API audio interessate

Funzione audio	Risultato	API interessate
Riproduzione audio	La riproduzione è silenziata Nessuna eccezione, nessun messaggio di errore fornito da alcuna API	AudioTrack.write() (NDK) AAudioStream_write OpenSL ES per Android Potrebbero essere interessate anche le librerie multimediali lato client che gestiscono la riproduzione, come media3, ExoPlayer e Oboe.
Richiesta di focus audio	Restituisce AUDIOFOCUS_REQUEST_FAILED Nessun effetto sulla riproduzione audio di altre app, nessun focus acquisito	AudioManager.requestAudioFocus()
API per la modalità suoneria e il volume	Nessun effetto sulla modalità Suoneria o sul volume (la chiamata al metodo viene ignorata in modo silenzioso) Nessuna eccezione, nessun messaggio di errore fornito da alcuna API	AudioManager.setStreamVolume() AudioManager.setStreamMute() AudioManager.adjustStreamVolume() AudioManager.adjustVolume() AudioManager.adjustSuggestedStreamVolume() AudioManager.setRingerMode()