Rafforzamento dell'audio in background

A partire da Android 17, il framework audio applica limitazioni alle interazioni audio in background, tra cui la riproduzione audio, le richieste di focus audio e le API di modifica del volume, per garantire che queste modifiche vengano avviate intenzionalmente dall'utente.

Tutte le app in esecuzione su Android 17 che hanno queste interazioni audio in background devono avere un'attività visibile o devono eseguire un servizio in primo piano non di tipo SHORT_SERVICE. Questo vale indipendentemente dal fatto che l'app abbia come target il livello API 37 o meno.

Se un'app ha come target Android 17 (livello API 37), esiste un'ulteriore limitazione. Se l'app è in esecuzione in background, deve eseguire un servizio in primo piano con funzionalità durante l'utilizzo (WIU). (A un servizio in primo piano vengono concesse funzionalità WIU se viene avviato in risposta a un'operazione avviata dall'utente o mentre l'app è visibile all'utente.) Tuttavia, il requisito relativo alle funzionalità WIU non è obbligatorio se all'app è stata concessa l'autorizzazione per la sveglia esatta e l'app sta apportando modifiche agli stream audio con l'attributo USAGE_ALARM.

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 di modifica del volume non vanno a buon fine senza generare un'eccezione o fornire un messaggio di errore. L'API Audio Focus non va a buon fine con il codice di risultato AUDIOFOCUS_REQUEST_FAILED.

Il motivo di questa modifica

L'introduzione di queste limitazioni ha lo scopo di ridurre le esperienze di bug 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 riattivata, riprende inaspettatamente la riproduzione audio, potenzialmente ore dopo.
• Le app che riproducono audio senza un servizio in primo piano erano soggette a varie limitazioni di esecuzione, che causavano prestazioni audio discontinue.
• Riproduzione scollegata dal ciclo di vita dell'attività, il che potrebbe comportare una sessione di riproduzione o eventi di stato attivo con leak che continuano senza che l'utente possa interrompere la riproduzione.

Invitiamo gli sviluppatori a testare le loro app e a fornire feedback sulla modifica del comportamento se esistono casi d'uso intenzionali dell'audio che ne risentono negativamente. Segnala eventuali problemi utilizzando questo Issue Tracker per la compatibilità delle app con Android 17.

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

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

Se la tua app è destinata solo alla riproduzione di audio o all'utilizzo di 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 tramite l'utilizzo delle API di telecomunicazione consigliate) per registrare correttamente l'audio, pertanto è improbabile che venga interessata.

Se la tua app prevede di continuare la riproduzione audio mentre lo schermo è spento o mentre la tua attività non è visibile, come accade più comunemente nelle app di streaming musicale o di podcast, si considera che l'app fornisca funzionalità audio in background e deve soddisfare i nuovi requisiti.

Scenari di audio in background che probabilmente subiranno un impatto

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

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

Best practice per l'audio in background per mitigare 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 venga 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 FGS mediaPlayback. Avvia sempre un servizio in primo piano mentre l'app è in primo piano se potrebbe essere riprodotto l'audio in background.

  Ad esempio, se la tua app è un'app di streaming video che in genere è solo in primo piano, ma contiene un affordance utente per continuare la riproduzione mentre lo schermo è spento, quando si verifica l'attivatore della riproduzione avviato dall'utente, l'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 riavvia la riproduzione solo se l'utente la riprende esplicitamente.

  In caso di un segnale permanente per terminare la riproduzione (ad esempio, i contenuti sono completi senza riproduzione automatica, un AUDIOFOCUS_LOSS, un evento di pausa dall'UMO o un evento di tasto multimediale) o un 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. In questo modo, la tua app non avrà più funzionalità di interazione audio in background.

  Successivamente, se l'utente riprende esplicitamente la riproduzione, ad esempio tramite l'UI della tua app o tramite il pulsante di riproduzione dell'oggetto multimediale universale, l'intent di avviare la riproduzione audio dovrebbe tornare, con conseguente avvio di un nuovo FGS.

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

Test delle modifiche in corso…

Puoi testare la conformità della tua app su app con Android 17 o versioni successive (a partire dalla versione beta 3) eseguendo il seguente comando ADB:

adb shell cmd audio set-enable-hardening <enable|disable|throw>

Questo comando ha le seguenti opzioni:

• enable: attiva tutte le limitazioni di protezione audio per tutte le app. Il requisito per i servizi in primo piano WIU viene applicato indipendentemente dal fatto che un'app abbia come target Android 17 (livello API 37). Inoltre, il requisito viene applicato anche se l'app apporta modifiche agli stream di sveglie e dispone dell'autorizzazione per la sveglia esatta.

• disable: disattiva tutte le limitazioni di protezione audio.

• throw: attiva tutte le limitazioni di protezione audio per tutte le app, ad esempio enable. Inoltre, questo flag attiva gli errori evidenti, generando IllegalStateException per le interazioni di volume e messa a fuoco. Per la riproduzione audio, il metodo di scrittura restituisce costantemente un codice di errore. Per le modalità di riproduzione senza scritture esplicite, l'app si arresta in modo anomalo.

Utilizza adb dumpsys audio o logcat per identificare se l'app ha riscontrato errori silenziosi a causa dell'applicazione dell'audio hardening. In questo caso, verrà visualizzata una voce con prefisso AudioHardening con il nome del pacchetto. Se il messaggio contiene level: full, la tua app esegue un servizio in primo piano, ma il servizio non dispone della funzionalità "durante l'uso". Se il messaggio contiene level: partial, la tua app non esegue alcun servizio in primo piano.

Informazioni su FGS con funzionalità di accesso durante l'uso

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 in genere non vengono concesse le funzionalità While-In-Use (WIU).

WIU funge da gateway di sicurezza: impedisce agli FGS avviati in background di adottare 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: ai servizi avviati mentre l'app è visibile o a cui è stata concessa la funzionalità di avvio dell'attività in background viene concesso l'accesso WIU.
• FGS avviati in background (BFSL): la maggior parte non concede l'accesso WIU. Le eccezioni principali che concedono l'interazione avviata dall'utente sono le interazioni che coinvolgono l'esplicito user intent, ad esempio i clic sulle notifiche, le interazioni con i widget o gli eventi dei tasti multimediali da un dispositivo esterno.
• FGS avviato dal sistema: ai servizi in primo piano viene concesso l'accesso WIU se vengono avviati dalla delega del server di sistema (ad esempio dalla libreria Jetpack Telecom) o da associazioni di sistema che rappresentano uno stato in primo piano elevato per eseguire funzionalità dedicate (ad esempio per un VoiceInteractionService).

Scopri di più in Limitazioni all'avvio di un servizio in primo piano dal background.

Elenco completo delle API audio interessate