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

Od Androida 17 framework 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 zapewnić, że te zmiany są inicjowane celowo 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ę na pierwszym planie, która nie jest typu SHORT_SERVICE. Dotyczy to niezależnie od tego, czy aplikacja jest kierowana na poziom interfejsu API 37.

Jeśli aplikacja jest kierowana na Androida 17 (poziom interfejsu API 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 działania podczas używania. (Usługa na pierwszym planie otrzymuje możliwości działania podczas używania, jeśli jest uruchamiana w odpowiedzi na operację zainicjowaną przez użytkownika lub gdy aplikacja jest widoczna dla użytkownika). Wymóg dotyczący możliwości działania podczas używania nie obowiązuje jednak, jeśli aplikacja otrzymała uprawnienia do alarmu precyzyjnego i wprowadza zmiany w strumieniach audio, które mają atrybut USAGE_ALARM.

Jeśli aplikacja pró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 nie działają bez zgłaszania wyjątku ani wyświetlania komunikatu o błędzie. Interfejs API aktywności audio nie działa i zwraca kod wyniku AUDIOFOCUS_REQUEST_FAILED.

Dlaczego wprowadzamy tę zmianę

Wprowadzenie tych ograniczeń ma na celu zmniejszenie liczby niezamierzonych błędów związanych 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 wznowi odtwarzanie dźwięku, nawet po kilku godzinach.
• Aplikacje odtwarzające dźwięk bez usługi na pierwszym planie były objęte różnymi ograniczeniami dotyczącymi działania, co powodowało przerywanie dźwięku.
• Odtwarzanie odłączone od cyklu życia działania, co mogło spowodować wyciek sesji odtwarzania lub wyciek zdarzeń fokusu, które są kontynuowane bez możliwości zatrzymania odtwarzania przez użytkownika.

Zachęcamy deweloperów do testowania aplikacji i przekazywania opinii na temat zmiany zachowania, jeśli występują przypadki użycia dźwięku, na które ta zmiana ma negatywny wpływ. Zgłaszaj problemy za pomocą tego narzędzia do śledzenia problemów ze zgodnością aplikacji na Androidzie 17.

Identyfikowanie przypadków użycia dźwięku w tle, których dotyczy problem

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

Jeśli 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 (PiP), nie dotyczy jej żadna z tych zmian.

Jeśli aplikacja zapewnia funkcję VOIP, w tym aplikacje do rozmów wideo, musi już spełniać wymagania dotyczące odtwarzania (zwykle przez korzystanie z zalecanych interfejsów API telekomunikacyjnych), aby móc nagrywać dźwięk, dlatego jest mało prawdopodobne, że ta zmiana będzie miała na nią wpływ.

Jeśli aplikacja ma kontynuować odtwarzanie dźwięku gdy ekran jest wyłączony lub gdy aktywność nie jest widoczna (co najczęściej występuje w aplikacjach do odtwarzania strumieniowego muzyki lub podcastów), jest ona uznawana za aplikację zapewniającą funkcję dźwięku w tle i musi spełniać nowe wymagania.

Scenariusze dźwięku w tle, na które ta zmiana może mieć wpływ

Jeśli aplikacja nie postępuje zgodnie z modelem kontynuowania interakcji audio zainicjowanej, gdy aplikacja była otwarta, lub w odpowiedzi na wyraźne działanie użytkownika, prawdopodobnie jej działanie zostanie cicho wstrzymane.

Jeśli na przykład aplikacja uruchamia usługę na pierwszym planie w odpowiedzi na BOOT_COMPLETE i próbuje wejść w interakcję z dźwiękiem, zostanie ona wstrzymana.

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

• Do zarządzania odtwarzaniem dźwięku w tle używaj komponentu MediaSessionService z biblioteki Jetpack media3.

  Jeśli to zrobisz, prawdopodobnie nie będziesz mieć problemów ze wzmacnianiem 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ę na pierwszym planie mediaPlayback. Jeśli może wystąpić dźwięk w tle, zawsze uruchamiaj usługę na pierwszym planie, gdy aplikacja działa na pierwszym planie.

  Jeśli na przykład Twoja aplikacja jest aplikacją do odtwarzania strumieniowego wideo, która zwykle działa tylko na pierwszym planie, ale zawiera afordancję umożliwiającą użytkownikowi kontynuowanie odtwarzania, gdy ekran jest wyłączony, to gdy użytkownik zainicjuje odtwarzanie, aplikacja powinna nadal uruchamiać usługę działającą na pierwszym planie.

  Dzięki temu usługa na pierwszym planie jest uruchamiana z możliwościami działania podczas używania.

• Utrzymuj usługę na pierwszym planie mediaPlayback aktywną 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, intencja odtwarzania powinna być kontynuowana. Dlatego usługa na pierwszym planie powinna pozostać aktywna.

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

  W przypadku trwałego sygnału zakończenia odtwarzania (np. gdy treść jest kompletna i nie ma automatycznego odtwarzania, wystąpi AUDIOFOCUS_LOSS, zdarzenie wstrzymania z UMO lub zdarzenie klawisza multimedialnego) lub nieodwracalnej awarii aplikacja powinna przerwać interakcję audio, zatrzymać usługę na pierwszym planie i zakończyć sesję multimedialną. Wszystkie te czynności odpowiadają koncepcji użytkownika „zakończenia” żądanej interakcji audio w tle. Po wykonaniu tych czynności aplikacja nie ma już możliwości interakcji audio w tle.

  Jeśli użytkownik wyraźnie wznowi odtwarzanie, np. za pomocą interfejsu aplikacji lub przycisku odtwarzania w uniwersalnym obiekcie multimedialnym, 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), wykonując to polecenie 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. Wymóg dotyczący usług na pierwszym planie działających podczas używania jest stosowany niezależnie od tego, czy aplikacja jest kierowana na Androida 17 (poziom interfejsu API 37). Ponadto wymóg jest egzekwowany nawet wtedy, gdy aplikacja wprowadza zmiany w strumieniach alarmów i ma dokładne uprawnienia do alarmu.

• disable: wyłącza wszystkie ograniczenia dotyczące wzmacniania zabezpieczeń audio.

• throw: włącza wszystkie ograniczenia dotyczące wzmacniania zabezpieczeń audio we wszystkich aplikacjach, podobnie jak enable. Ponadto ta flaga włącza głośne awarie, zgłaszając 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 wyraźnych zapisów aplikacja ulega awarii.

Użyj adb dumpsys audio lub logcat, aby sprawdzić, czy aplikacja napotkała ciche awarie z powodu egzekwowania zabezpieczeń audio. Jeśli tak, pojawi się wpis z prefiksem AudioHardening i nazwą pakietu. Jeśli komunikat zawiera level: full, aplikacja uruchamia usługę na pierwszym planie, ale usługa nie ma możliwości działania podczas używania. Jeśli komunikat zawiera level: partial, aplikacja nie uruchamia usługi na pierwszym planie.

Informacje o usłudze na pierwszym planie z możliwościami działania podczas używania

Usługi na pierwszym planie muszą być uruchamiane, gdy aplikacja działa na pierwszym planie, aby rozszerzyć operacje zainicjowane przez użytkownika. W niektórych przypadkach, aplikacje mogą uruchamiać usługę na pierwszym planie, gdy aplikacja działa w tle. Jednak te usługi na pierwszym planie zwykle nie mają możliwości działania podczas używania.

Możliwości działania podczas używania działają jako zabezpieczenie – uniemożliwiają usługom na pierwszym planie uruchamianym w tle wykonywanie niektórych wrażliwych działań, gdy użytkownik może nie być świadomy aktywności aplikacji. Uniemożliwiają aplikacji dostęp do danych wrażliwych, takich jak lokalizacja, aparat czy mikrofon, a od Androida 17 blokują też interfejsy API audio, które zwykle wymagają widocznego kontekstu interfejsu.

Oto przydatne informacje:

• Standardowa usługa na pierwszym planie: usługi uruchamiane, gdy aplikacja jest widoczna lub ma możliwość uruchamiania aktywności w tle, mają dostęp do możliwości działania podczas używania.
• Usługa na pierwszym planie uruchamiana w tle: większość nie ma dostępu do możliwości działania podczas używania. Główne wyjątki które przyznają możliwości działania podczas używania, to interakcje obejmujące wyraźną intencję użytkownika, np. kliknięcia powiadomień, interakcje z widżetami lub zdarzenia klawiszy multimedialnych z urządzenia zewnętrznego.
• Usługa na pierwszym planie uruchamiana przez system: usługi na pierwszym planie mają dostęp do możliwości działania podczas używania, jeśli są uruchamiane przez delegowanie 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 w tle.

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