Rafforzamento dell'audio in background

A partire da Android 17, il framework audio applica restrizioni 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 eseguire un servizio in primo piano di tipo diverso da SHORT_SERVICE. Questo vale indipendentemente dal fatto che l'app abbia come target il livello API 37.

Se un'app ha come target Android 17 (livello API 37), è presente una restrizione aggiuntiva. Se l'app è in esecuzione in background, deve eseguire un servizio in primo piano con funzionalità di accesso alla posizione in primo piano (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 delle funzionalità WIU non è valido se all'app è stata concessa l' autorizzazione di allarme esatta e se sta apportando modifiche ai flussi 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 funzionano senza generare un'eccezione o fornire un messaggio di errore. L'API di focus audio non funziona e restituisce il codice di risultato AUDIOFOCUS_REQUEST_FAILED.

Perché stiamo apportando questa modifica

L'intenzione di introdurre queste restrizioni è di ridurre le esperienze audio in background non intenzionali e con bug. Ecco alcuni esempi:

• Le app che riproducono audio senza un servizio in primo piano possono essere bloccate. Quando l'app viene sbloccata, riprende inaspettatamente la riproduzione audio, potenzialmente ore dopo.
• Le app che riproducono audio senza un servizio in primo piano sono soggette a varie restrizioni di esecuzione che comportano prestazioni audio instabili.
• La riproduzione è scollegata dal ciclo di vita dell'attività, il che potrebbe comportare una sessione di riproduzione o eventi di focus persi 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 che hanno un impatto negativo. Segnala eventuali problemi utilizzando questo strumento di monitoraggio dei problemi di compatibilità delle app Android 17.

Identificare i casi d'uso 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 audio o utilizzare le API audio solo quando mostra un'attività visibile all'utente, incluso l'utilizzo della modalità Picture in Picture (PiP), non è interessata da 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 telecomunicazioni consigliate) per registrare correttamente l'audio e, pertanto, è improbabile che sia interessata.

Se la tua app intende continuare la riproduzione audio quando lo schermo è spento o quando l'attività non è visibile, come avviene più comunemente nelle app di streaming musicale o nei podcast, la tua app è considerata in grado di fornire 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 avviata mentre l'app era aperta o in risposta a un trigger utente esplicito, è probabile che la funzionalità dell'app venga eliminata senza generare messaggi.

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à eliminata.

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 dal rafforzamento in background, poiché la libreria aiuta a gestire il ciclo di vita della riproduzione.

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

  Ad esempio, se la tua app è un'app di streaming video che in genere è solo in primo piano, ma contiene una funzionalità utente per continuare la riproduzione quando lo schermo è spento, quando si verifica l'attivatore di 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 l'FGS mediaPlayback 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 un'interruzione temporanea prevista come AUDIOFOCUS_LOSS_TRANSIENT, l'intento di riproduzione deve continuare. Pertanto, l'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 segnale permanente per terminare la riproduzione (ad esempio, il contenuto è completo senza riproduzione automatica, un AUDIOFOCUS_LOSS, un evento di pausa dall'UMO o un evento chiave multimediale) o di un errore non recuperabile, l'app deve interrompere l'interazione audio, arrestare il servizio in primo piano e terminare la sessione multimediale. Tutto ciò corrisponde alla concezione dell'utente di "completamento" dell'interazione audio in background desiderata. Dopo aver eseguito questa operazione, la tua app non dispone più di funzionalità di interazione audio in background.

  Successivamente, se l'utente riprende esplicitamente la riproduzione, ad esempio tramite l'UI dell'app o il pulsante di riproduzione dell'oggetto multimediale universale, l'intento di avviare la riproduzione audio deve essere ripristinato, con conseguente avvio di un nuovo FGS.

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

Test delle modifiche in corso…

Puoi testare la conformità della tua app su app che eseguono Android 17 o versioni successive (a partire dalla 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 restrizioni di protezione audio per tutte le app. Il requisito dei 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 sta apportando modifiche ai flussi di allarme e dispone dell'autorizzazione di allarme esatta.

• disable: disattiva tutte le restrizioni di rafforzamento audio.

• throw: attiva tutte le restrizioni di protezione audio per tutte le app, come enable. Inoltre, questo flag attiva gli errori ad alta voce, generando IllegalStateException per le interazioni di volume e focus. 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 verificare se l'app ha riscontrato errori silenziosi a causa dell'applicazione del rafforzamento audio. In caso affermativo, sarà presente una voce con il prefisso AudioHardening e il nome del pacchetto. Se il messaggio contiene level: full, l'app sta eseguendo un servizio in primo piano, ma il servizio non ha la funzionalità di accesso alla posizione in primo piano. Se il messaggio contiene level: partial, l'app non sta eseguendo alcun servizio in primo piano.

Informazioni sull'FGS con funzionalità di accesso alla posizione in primo piano

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 funzionalità di accesso alla posizione in primo piano (WIU).

WIU funge da porta di sicurezza: impedisce ai servizi in primo piano avviati in background di eseguire 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:

• Servizi in primo piano 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.
• Servizi in primo piano avviati in background (BFSL): la maggior parte non concede l'accesso WIU. Le eccezioni principali che concedono WIU sono le interazioni che coinvolgono l'intento esplicito dell'utente, ad esempio clic sulle notifiche, interazioni con i widget o eventi di tasti multimediali da un dispositivo esterno.
• Servizi in primo piano avviati 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 dai binding di sistema che rappresentano uno stato di primo piano elevato per eseguire funzionalità dedicate (ad esempio, per un VoiceInteractionService).

Scopri di più in Restrizioni sull'avvio di un servizio in primo piano dal background.

Elenco completo delle API audio interessate