Zwiększanie bezpieczeństwa dźwięku w tle

Od Androida 17 platforma audio wymusza ograniczenia dotyczące interakcji audio w tle, w tym odtwarzania dźwięku, żądań aktywności audio i interfejsów API zmiany głośności, aby mieć pewność, że te zmiany są inicjowane przez użytkownika.

Wszystkie aplikacje działające na Androidzie 17, które mają te interakcje audio w tle, muszą mieć widoczną aktywność lub muszą uruchamiać usługę działającą na pierwszym planie, która nie jest typu SHORT_SERVICE. Dotyczy to wszystkich aplikacji, niezależnie od tego, czy są kierowane na poziom API 37.

Jeśli aplikacja jest kierowana na Androida 17 (API na poziomie 37), obowiązuje dodatkowe ograniczenie. Jeśli aplikacja działa w tle, musi uruchamiać usługę na pierwszym planie, która ma możliwości podczas używania (WIU). (Usługa działająca na pierwszym planie uzyskuje uprawnienia do działania w trybie nieograniczonego użytkowania, jeśli jest uruchamiana w odpowiedzi na działanie zainicjowane przez użytkownika lub gdy aplikacja jest widoczna dla użytkownika). Wymóg dotyczący funkcji WIU nie obowiązuje jednak, jeśli aplikacja ma uprawnienia do alarmu precyzyjnego i wprowadza zmiany w strumieniach audio, które mają atrybut USAGE_ALARM.

Jeśli aplikacja spróbuje wywołać interfejsy API audio, gdy nie znajduje się w prawidłowym cyklu życia, interfejsy API odtwarzania dźwięku i zmiany głośności zakończą działanie bez zgłaszania wyjątku ani wyświetlania komunikatu o błędzie. Interfejs API aktywności audio zwraca kod wyniku AUDIOFOCUS_REQUEST_FAILED.

Dlaczego wprowadzamy tę zmianę

Wprowadzenie tych ograniczeń ma na celu zmniejszenie liczby przypadkowych problemów z dźwiękiem w tle. Oto kilka przykładów:

• Aplikacje odtwarzające dźwięk bez usługi na pierwszym planie mogą zostać zamrożone. Gdy aplikacja zostanie odblokowana, nieoczekiwanie wznawia odtwarzanie dźwięku, potencjalnie po kilku godzinach.
• Aplikacje odtwarzające dźwięk bez usługi na pierwszym planie były objęte różnymi ograniczeniami, które powodowały przerywane odtwarzanie dźwięku.
• Odtwarzanie jest odłączone od cyklu życia działania, co może powodować wyciek sesji odtwarzania lub wyciek zdarzeń związanych z ogniskiem, które są kontynuowane bez możliwości zatrzymania odtwarzania przez użytkownika.

Zachęcamy deweloperów do testowania aplikacji i przesyłania opinii na temat zmiany zachowania, jeśli ma ona negatywny wpływ na zamierzone przypadki użycia dźwięku. Wszelkie problemy zgłaszaj za pomocą tego narzędzia do śledzenia problemów z kompatybilnością aplikacji z Androidem 17.

Określanie przypadków użycia dźwięku w tle, na które ma to wpływ

Sprawdź implementację odtwarzania dźwięku i określ, czy aplikacja ma zapewniać funkcję interakcji z dźwiękiem w tle nawet w określonych okolicznościach.

Jeśli Twoja aplikacja ma odtwarzać dźwięk lub korzystać z interfejsów API audio tylko wtedy, gdy wyświetla aktywność widoczną dla użytkownika, w tym w trybie obrazu w obrazie, żadna z tych zmian nie będzie miała na nią wpływu.

Jeśli Twoja aplikacja zapewnia funkcje VoIP, w tym aplikacje do rozmów wideo, musi już spełniać wymagania wprowadzane w przypadku odtwarzania (zwykle poprzez korzystanie z rekomendowanych interfejsów API telekomunikacyjnych), aby móc nagrywać dźwięk. W związku z tym prawdopodobnie nie będzie to miało na nią wpływu.

Jeśli Twoja aplikacja ma odtwarzać dźwięk przy wyłączonym ekranie lub gdy aktywność nie jest widoczna (co najczęściej występuje w aplikacjach do strumieniowego przesyłania muzyki lub podcastów), uznaje się, że zapewnia ona funkcję odtwarzania dźwięku w tle, i musi spełniać nowe wymagania.

Scenariusze dotyczące dźwięku w tle, na które prawdopodobnie wpłynie ta zmiana

Jeśli aplikacja nie działa zgodnie z modelem kontynuowania interakcji głosowej rozpoczętej, gdy była otwarta, lub w odpowiedzi na wyraźne działanie użytkownika, jej funkcje prawdopodobnie zostaną wyciszone.

Jeśli na przykład aplikacja uruchamia usługę na pierwszym planie w odpowiedzi na BOOT_COMPLETE i próbuje wchodzić w interakcje z dźwiękiem, zostanie to zablokowane.

Sprawdzone metody dotyczące dźwięku w tle, które pozwalają ograniczyć wpływ

• Użyj komponentu MediaSessionService biblioteki Jetpack media3, aby zarządzać odtwarzaniem dźwięku w tle.

  W takim przypadku na Twoją aplikację prawdopodobnie nie będą miały wpływu zmiany w zakresie wzmacniania zabezpieczeń w tle, ponieważ biblioteka pomaga w zarządzaniu cyklem życia odtwarzania.

• Jeśli nie korzystasz z biblioteki media3, musisz ręcznie uruchomić usługę mediaPlaybackna pierwszym planie. Zawsze uruchamiaj usługę na pierwszym planie, gdy aplikacja działa na pierwszym planie, jeśli może wystąpić dźwięk w tle.

  Jeśli na przykład Twoja aplikacja to aplikacja do strumieniowego przesyłania wideo, która zwykle działa tylko na pierwszym planie, ale zawiera funkcję umożliwiającą kontynuowanie odtwarzania przy wyłączonym ekranie, to po wywołaniu przez użytkownika odtwarzania aplikacja powinna nadal uruchamiać usługę na pierwszym planie.

  Dzięki temu usługa działająca na pierwszym planie zostanie uruchomiona z możliwościami WIU.

• Utrzymuj aktywność mediaPlayback FGS podczas przejściowych awarii trwających krócej niż 10 minut.

  Jeśli w aplikacji wystąpi przejściowa awaria, np. problem z buforowaniem spowodowany aktywnością sieciową, lub wystąpi spodziewane przejściowe przerwanie, np. AUDIOFOCUS_LOSS_TRANSIENT, odtwarzanie powinno być kontynuowane. Dlatego usługa FGS powinna pozostać aktywna.

• Zatrzymaj usługę na pierwszym planie po zakończeniu odtwarzania i uruchom je ponownie tylko wtedy, gdy użytkownik wyraźnie wznowi odtwarzanie.

  W przypadku trwałego sygnału zakończenia odtwarzania (np. gdy treść jest kompletna i nie ma autoodtwarzania, wystąpi AUDIOFOCUS_LOSS, zdarzenie wstrzymania z UMO lub zdarzenie klawisza multimedialnego) lub nieodwracalnej awarii aplikacja powinna zakończyć interakcję audio, zatrzymać usługę na pierwszym planie i zakończyć sesję multimedialną. Wszystkie te czynności odpowiadają pojęciu „zakończenia” interakcji z żądanym dźwiękiem w tle. Po wykonaniu tej czynności aplikacja nie będzie już mogła wchodzić w interakcje z dźwiękiem w tle.

  Jeśli użytkownik wyraźnie wznowi odtwarzanie, np. za pomocą interfejsu aplikacji lub przycisku odtwarzania uniwersalnego obiektu multimedialnego, intencja rozpoczęcia odtwarzania dźwięku powinna powrócić, co spowoduje uruchomienie nowej usługi na pierwszym planie.

• Testuj zachowanie odtwarzania dźwięku za pomocą poleceń adb shell.

Testowanie zmian

Zgodność aplikacji możesz sprawdzić na urządzeniach z Androidem 17 lub nowszym (od wersji beta 3) za pomocą tego polecenia ADB:

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

To polecenie ma te opcje:

• enable: włącza wszystkie ograniczenia dotyczące wzmacniania zabezpieczeń audio we wszystkich aplikacjach. Wymaganie dotyczące usług działających na pierwszym planie WIU obowiązuje niezależnie od tego, czy aplikacja jest kierowana na Androida 17 (interfejs API na poziomie 37). Dodatkowo ten wymóg jest egzekwowany nawet wtedy, gdy aplikacja wprowadza zmiany w strumieniach alarmów i ma uprawnienia do alarmów precyzyjnych.

• disable: wyłącza wszystkie ograniczenia dotyczące wzmacniania dźwięku.

• throw: włącza wszystkie ograniczenia dotyczące wzmacniania zabezpieczeń audio we wszystkich aplikacjach, np. enable. Dodatkowo ta flaga włącza głośne błędy, zgłaszając wyjątki IllegalStateException w przypadku interakcji z głośnością i fokusem. W przypadku odtwarzania dźwięku metoda zapisu stale zwraca kod błędu. W przypadku trybów odtwarzania bez jawnego zapisu aplikacja ulega awarii.

Użyj symbolu adb dumpsys audio lub logcat, aby sprawdzić, czy w aplikacji wystąpiły ciche błędy z powodu wymuszenia zabezpieczeń dźwięku. Jeśli tak, pojawi się wpis z prefiksem AudioHardening i nazwą pakietu. Jeśli wiadomość zawiera level: full, oznacza to, że aplikacja uruchamia usługę działającą na pierwszym planie, ale usługa nie ma możliwości działania podczas używania. Jeśli wiadomość zawiera level: partial, Twoja aplikacja w ogóle nie uruchamia usługi na pierwszym planie.

Informacje o usłudze FGS z funkcją używania podczas korzystania z aplikacji

Usługi na pierwszym planie muszą być uruchamiane, gdy aplikacja działa na pierwszym planie, aby przedłużyć operacje zainicjowane przez użytkownika. W niektórych przypadkach aplikacje mogą uruchamiać usługę na pierwszym planie, gdy działają w tle. Usługi działające w pierwszym planie zwykle nie mają jednak uprawnień obowiązujących podczas używania.

WIU działa jak brama zabezpieczająca – uniemożliwia usługom działającym na pierwszym planie uruchamianym w tle wykonywanie określonych działań wymagających dostępu do informacji poufnych, gdy użytkownik może nie być świadomy aktywności aplikacji. Uniemożliwia to aplikacji dostęp do danych wrażliwych, takich jak lokalizacja, aparat czy mikrofon. Od Androida 17 blokuje też interfejsy API audio, które zwykle wymagają widocznego kontekstu interfejsu.

Oto przydatne informacje:

• Standardowa usługa działająca na pierwszym planie: usługi uruchamiane, gdy aplikacja jest widoczna lub ma możliwość uruchamiania aktywności w tle, mają dostęp do WIU.
• Usługi działające na pierwszym planie uruchamiane w tle (BFSL): większość nie przyznaje dostępu do WIU. Główne wyjątki, które przyznają WIU, to interakcje obejmujące wyraźny zamiar użytkownika, np. kliknięcia powiadomień, interakcje z widżetami lub zdarzenia klawiszy multimedialnych z urządzenia zewnętrznego.
• Usługa działająca na pierwszym planie uruchomiona przez system: usługi działające na pierwszym planie uzyskują dostęp do WIU, jeśli są uruchamiane przez delegowanie z serwera systemowego (np. z biblioteki Jetpack Telecom) lub przez powiązania systemowe reprezentujące podwyższony stan pierwszego planu w celu wykonywania określonych funkcji (np. w przypadku VoiceInteractionService).

Więcej informacji znajdziesz w artykule Ograniczenia dotyczące uruchamiania usługi na pierwszym planie podczas działania w tle.

Pełna lista interfejsów Audio API, których dotyczy problem