Начиная с Android 9 (уровень API 28), платформа ограничивает интерфейсы, не относящиеся к SDK, которые может использовать ваше приложение. Эти ограничения применяются всякий раз, когда приложение ссылается на интерфейс, отличный от SDK, или пытается получить его дескриптор с помощью отражения или JNI. Эти ограничения были введены, чтобы помочь улучшить взаимодействие с пользователем и разработчиком и снизить риски сбоев для пользователей и экстренного развертывания для разработчиков. Дополнительные сведения об этом решении см. в разделе Улучшение стабильности за счет сокращения использования интерфейсов, отличных от SDK .
Различие между интерфейсами SDK и не-SDK
Вообще говоря, общедоступные интерфейсы SDK — это те, которые описаны в Индексе пакетов платформы Android. Обработка интерфейсов, отличных от SDK, — это деталь реализации, которую API абстрагирует, поэтому эти интерфейсы могут быть изменены без предварительного уведомления.
Чтобы избежать сбоев и непредвиденного поведения, приложения должны использовать только официально задокументированные части классов в SDK. Это также означает, что вам не следует обращаться к методам или полям, которые не указаны в SDK, когда вы взаимодействуете с классом с использованием таких механизмов, как отражение.
Списки API, не входящих в SDK
В каждом выпуске Android дополнительные интерфейсы, не входящие в SDK, ограничиваются. Мы знаем, что эти ограничения могут повлиять на ваш рабочий процесс выпуска, и мы хотим быть уверены, что у вас есть инструменты для обнаружения использования интерфейсов, отличных от SDK, возможность оставить нам отзыв и время для планирования и адаптации к новым политикам.
Чтобы свести к минимуму влияние ограничений, не связанных с SDK, на рабочий процесс разработки, интерфейсы, не относящиеся к SDK, разделены на списки, которые определяют, насколько строго ограничено их использование, в зависимости от того, какой уровень API является целевым. В следующей таблице описан каждый из этих списков:
| Список | Теги кода | Описание |
|---|---|---|
| Черный список |
| Интерфейсы, не относящиеся к SDK, которые вы не можете использовать независимо от целевого уровня API вашего приложения. Если ваше приложение попытается получить доступ к одному из этих интерфейсов, система выдаст ошибку . |
| Условно заблокировано |
| Начиная с Android 9 (уровень API 28), каждый уровень API имеет интерфейсы, отличные от SDK, которые ограничены, когда приложение нацелено на этот уровень API. Эти списки помечены максимальным уровнем API ( Если ваше приложение пытается получить доступ к интерфейсу, который ограничен для вашего целевого уровня API, система ведет себя так, как если бы API был частью черного списка . |
| Не поддерживается |
| Интерфейсы, не относящиеся к SDK, которые не ограничены и могут использоваться вашим приложением. Однако обратите внимание, что эти интерфейсы не поддерживаются и могут быть изменены без предварительного уведомления. Ожидайте, что эти интерфейсы будут условно заблокированы в будущих версиях Android в списке max-target-x . |
| SDK |
| Интерфейсы, которые можно свободно использовать и которые теперь поддерживаются как часть официально документированного индекса пакетов платформы Android. |
| Тестовые API |
| Интерфейсы, используемые для внутреннего тестирования системы, например API-интерфейсы, упрощающие тестирование с помощью набора тестов совместимости (CTS). Тестовые API не являются частью SDK. Начиная с Android 11 (уровень API 30) , тестовые API включаются в черный список, поэтому приложениям не разрешается использовать их независимо от целевого уровня API. Все тестовые API не поддерживаются и могут быть изменены без предварительного уведомления независимо от уровня API платформы. |
Хотя вы можете использовать некоторые интерфейсы, не входящие в SDK (в зависимости от целевого уровня API вашего приложения), использование любого метода или поля, не входящего в SDK, всегда сопряжено с высоким риском поломки вашего приложения. Если ваше приложение использует интерфейсы, отличные от SDK, вам следует начать планировать переход на интерфейсы SDK или другие альтернативы. Если вы не можете найти альтернативу использованию интерфейса, отличного от SDK, для функции вашего приложения, вам следует запросить новый общедоступный API .
Определить, к какому списку принадлежит интерфейс
Списки интерфейсов, отличных от SDK, создаются как часть платформы. Дополнительные сведения о каждой версии Android см. в следующих разделах.
Андроид 15
Для Android 15 (уровень API 35) вы можете скачать следующий файл, описывающий все интерфейсы, не входящие в SDK, и их соответствующие списки:
Файл: hiddenapi-flags.csv
Контрольная сумма SHA-256: 40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9
Дополнительные сведения об изменениях в списке API, не входящих в SDK, в Android 15 см. в разделе Обновления ограничений интерфейса, не входящих в SDK, в Android 15 .
Андроид 14
Для Android 14 (уровень API 34) вы можете скачать следующий файл, описывающий все интерфейсы, не входящие в SDK, и их соответствующие списки:
Файл: hiddenapi-flags.csv
Контрольная сумма SHA-256: 7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f
Дополнительные сведения об изменениях в списке API, не входящих в SDK, в Android 14 см. в разделе Обновления ограничений интерфейса, не входящих в SDK, в Android 14 .
Андроид 13
Для Android 13 (уровень API 33) вы можете скачать следующий файл, описывающий все интерфейсы, не входящие в SDK, и их соответствующие списки:
Файл: hiddenapi-flags.csv
Контрольная сумма SHA-256: 233a277aa8ac475b6df61bffd95665d86aac6eb2ad187b90bf42a98f5f2a11a3
Чтобы узнать больше об изменениях в списке API, не входящих в SDK, в Android 13, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 13, см. раздел Обновления ограничений интерфейса, не входящих в SDK, в Android 13 .
Андроид 12
Для Android 12 (уровень API 31) вы можете скачать следующий файл, описывающий все интерфейсы, не входящие в SDK, и их соответствующие списки:
Файл: hiddenapi-flags.csv
Контрольная сумма SHA-256: 40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761
Чтобы узнать больше об изменениях в списке API, не входящих в SDK, в Android 12, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 12, см. раздел Изменения списка для Android 12 .
Андроид 11
Для Android 11 (уровень API 30) вы можете скачать следующий файл, описывающий все интерфейсы, не входящие в SDK, и их соответствующие списки:
Файл: hiddenapi-flags.csv
Контрольная сумма SHA-256: a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56
Чтобы узнать больше об изменениях в списке API, не входящих в SDK, в Android 11, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 11, см. раздел Изменения списка для Android 11 .
Андроид 10
Для Android 10 (уровень API 29) вы можете скачать следующий файл, описывающий все интерфейсы, не входящие в SDK, и их соответствующие списки:
Файл: hiddenapi-flags.csv
Контрольная сумма SHA-256: f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb
Чтобы узнать больше об изменениях в списке API, не входящих в SDK, в Android 10, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 10, см. раздел Изменения списка для Android 10 .
Андроид 9
Для Android 9 (уровень API 28) следующий текстовый файл содержит список API-интерфейсов, не входящих в SDK, которые не ограничены (внесены в серый список): hiddenapi-light-greylist.txt .
Черный список ( blacklist ) и список условно заблокированных API (темно-серый список) создаются во время сборки.
Генерировать списки из AOSP
При работе с AOSP вы можете создать файл hiddenapi-flags.csv , содержащий все интерфейсы, не входящие в состав SDK, и соответствующие им списки. Для этого загрузите исходный код AOSP и выполните следующую команду:
m out/soong/hiddenapi/hiddenapi-flags.csv
Затем вы сможете найти файл в следующем месте:
out/soong/hiddenapi/hiddenapi-flags.csv
Ожидаемое поведение при доступе к ограниченным интерфейсам, не относящимся к SDK
В следующей таблице описано поведение, которого можно ожидать, если ваше приложение попытается получить доступ к интерфейсу, отличному от SDK, который является частью черного списка.
| Средства доступа | Результат |
|---|---|
| Инструкция Dalvik, ссылающаяся на поле | Выброшена NoSuchFieldError |
| Инструкция Dalvik, ссылающаяся на метод | Выброшена NoSuchMethodError |
Отражение с использованием Class.getDeclaredField() или Class.getField() | Выброшено исключение NoSuchFieldException |
Отражение с использованием Class.getDeclaredMethod() , Class.getMethod() | Выброшено исключение NoSuchMethodException |
Отражение с использованием Class.getDeclaredFields() , Class.getFields() | Не члены SDK не в результатах |
Отражение с использованием Class.getDeclaredMethods() , Class.getMethods() | Не члены SDK не в результатах |
JNI с использованием env->GetFieldID() | Возвращается NULL , выдается NoSuchFieldError |
JNI с использованием env->GetMethodID() | Возвращается NULL , выдается NoSuchMethodError |
Проверьте свое приложение на наличие интерфейсов, отличных от SDK.
Существует несколько методов, которые вы можете использовать для проверки интерфейсов, отличных от SDK, в вашем приложении.
Тестирование с помощью отлаживаемого приложения
Вы можете протестировать интерфейсы, не относящиеся к SDK, создав и запустив отлаживаемое приложение на устройстве или эмуляторе под управлением Android 9 (уровень API 28) или более поздней версии. Убедитесь, что используемое вами устройство или эмулятор соответствует целевому уровню API вашего приложения.
При выполнении тестов вашего приложения система печатает сообщение журнала, если ваше приложение обращается к определенным интерфейсам, отличным от SDK. Вы можете просмотреть сообщения журнала вашего приложения, чтобы найти следующую информацию:
- Объявляющий класс, имя и тип (в формате, который используется средой выполнения Android).
- Средства доступа: либо связывание, либо использование отражения, либо использование JNI.
- К какому списку принадлежит интерфейс, отличный от SDK.
Вы можете использовать adb logcat для доступа к этим сообщениям журнала, которые отображаются под PID работающего приложения. Например, запись в журнале может выглядеть следующим образом:
Accessing hidden field Landroid/os/Message;->flags:I (light greylist, JNI)
Тестирование с использованием StrictMode API
Вы также можете протестировать интерфейсы, отличные от SDK, с помощью API StrictMode . Чтобы включить это, используйте detectNonSdkApiUsage . После включения API StrictMode вы можете получать обратный вызов для каждого использования интерфейса, отличного от SDK, с помощью penaltyListener , где вы можете реализовать пользовательскую обработку. Объект Violation , предоставленный в обратном вызове, является производным от Throwable , а вложенная трассировка стека предоставляет контекст использования.
Протестируйте с помощью инструмента veridex
Вы также можете запустить инструмент статического анализа veridex в своем APK. Инструмент veridex сканирует всю кодовую базу APK, включая любые сторонние библиотеки, и сообщает о любом обнаруженном использовании интерфейсов, отличных от SDK.
Ограничения инструмента veridex включают следующее:
- Он не может обнаружить вызовы через JNI.
- Он может обнаружить только подмножество вызовов посредством отражения.
- Его анализ неактивных путей кода ограничивается проверками на уровне API.
- Его можно запускать только на машинах, поддерживающих инструкции SSE4.2 и POPCNT.
Окна
Собственные двоичные файлы Windows не предоставляются, но вы можете запустить инструмент veridex в Windows, запустив двоичные файлы Linux с помощью подсистемы Windows для Linux (WSL). Прежде чем выполнять действия, описанные в этом разделе, установите WSL и выберите Ubuntu в качестве дистрибутива Linux.
После установки Ubuntu запустите терминал Ubuntu и выполните следующие действия:
- Загрузите инструмент veridex из репозитория готовых сборок среды выполнения Android.
- Извлеките содержимое файла
appcompat.tar.gz. - В извлеченной папке найдите файл
veridex-linux.zipи распакуйте его. Перейдите в разархивированную папку и выполните следующую команду, где
your-app.apk— это APK, который вы хотите протестировать:./appcompat.sh --dex-file=your-app.apk
macOS
Чтобы запустить инструмент veridex в macOS, выполните следующие действия:
- Загрузите инструмент veridex из репозитория готовых сборок среды выполнения Android.
- Извлеките содержимое файла
appcompat.tar.gz. - В извлеченной папке найдите файл
veridex-mac.zipи извлеките его. Перейдите в разархивированную папку и выполните следующую команду, где
/path-from-root/your-app.apk— это путь к APK, который вы хотите протестировать, начиная с корневого каталога вашей системы:./appcompat.sh --dex-file=/path-from-root/your-app.apk
Линукс
Чтобы запустить инструмент veridex в Linux, выполните следующие действия:
- Загрузите инструмент veridex из репозитория готовых сборок среды выполнения Android.
- Извлеките содержимое файла
appcompat.tar.gz. - В извлеченной папке найдите файл
veridex-linux.zipи распакуйте его. Перейдите в разархивированную папку и выполните следующую команду, где
your-app.apk— это APK, который вы хотите протестировать:./appcompat.sh --dex-file=your-app.apk
Протестируйте с помощью инструмента Android Studio lint.
Всякий раз, когда вы создаете свое приложение в Android Studio, инструмент проверки проверяет ваш код на наличие потенциальных проблем. Если ваше приложение использует интерфейсы, отличные от SDK, вы можете увидеть ошибки сборки или предупреждения, в зависимости от того, к какому списку принадлежат эти интерфейсы.
Вы также можете запустить инструмент lint из командной строки или вручную выполнить проверку конкретного проекта, папки или файла.
Тестирование с помощью Play Console
Когда вы загружаете свое приложение на тестовую версию в Play Console, оно автоматически проверяется на наличие потенциальных проблем и создается отчет о предварительном запуске. Если ваше приложение использует интерфейсы, отличные от SDK, в отчете о предварительном запуске отображается ошибка или предупреждение, в зависимости от того, к какому списку принадлежат эти интерфейсы.
Дополнительную информацию см. в разделе «Совместимость Android» статьи «Использование отчетов о тестировании для выявления проблем» .
Запросить новый общедоступный API
Если вы не можете найти альтернативу использованию интерфейса, отличного от SDK, для функции вашего приложения, вы можете запросить новый общедоступный API, создав запрос функции в нашем трекере проблем.
При создании запроса на функцию предоставьте следующую информацию:
- Какой неподдерживаемый API вы используете, включая полный дескриптор, указанный в сообщении Logcat
Accessing hidden .... - Почему вам нужно использовать эти API, включая подробную информацию о функциях высокого уровня, для которых необходим API, а не только подробности низкого уровня.
- Почему любые связанные общедоступные API SDK недостаточны для ваших целей.
- Любые другие альтернативы, которые вы пробовали, и почему они не сработали.
Когда вы предоставляете эти сведения в своем запросе на функцию, вы увеличиваете вероятность того, что будет предоставлен новый общедоступный API.
Другие вопросы
В этом разделе приведены некоторые ответы на другие вопросы, которые часто задают разработчики:
Общие вопросы
Как Google может быть уверен, что сможет отслеживать потребности всех приложений с помощью системы отслеживания ошибок?
Исходные списки для Android 9 (уровень API 28) мы создали путем статического анализа приложений, который был дополнен следующими методами:
- ручное тестирование лучших приложений Play и не Play
- внутренние отчеты
- автоматический сбор данных от внутренних пользователей
- отчеты предварительного просмотра для разработчиков
- дополнительный статический анализ, который был разработан для консервативного включения большего количества ложных срабатываний
При оценке списков для каждого нового выпуска мы учитываем использование API, а также отзывы разработчиков через систему отслеживания проблем.
Как я могу включить доступ к интерфейсам, отличным от SDK?
Вы можете включить доступ к интерфейсам, отличным от SDK, на устройствах разработки, используя команды adb для изменения политики применения API. Используемые вами команды различаются в зависимости от уровня API. Эти команды не требуют рутированного устройства.
- Android 10 (уровень API 29) или выше
Чтобы включить доступ, используйте следующий adb
команда:
adb shell settings put global hidden_api_policy 1
Чтобы сбросить политику применения API к настройкам по умолчанию, используйте следующую команду:
adb shell settings delete global hidden_api_policy
- Android 9 (уровень API 28)
Чтобы включить доступ, используйте следующие команды adb:
adb shell settings put global hidden_api_policy_pre_p_apps 1adb shell settings put global hidden_api_policy_p_apps 1Чтобы сбросить политику применения API к настройкам по умолчанию, используйте следующие команды:
adb shell settings delete global hidden_api_policy_pre_p_appsadb shell settings delete global hidden_api_policy_p_apps
В политике принудительного применения API можно установить одно из следующих значений:
- 0: отключить все обнаружения интерфейсов, отличных от SDK. Использование этого параметра отключает все сообщения журнала об использовании интерфейса, отличного от SDK, и не позволяет вам тестировать приложение с помощью
StrictModeAPI . Эта настройка не рекомендуется. - 1: разрешить доступ ко всем интерфейсам, не относящимся к SDK, но печатать сообщения журнала с предупреждениями для любого использования интерфейса, не относящегося к SDK. Использование этого параметра также позволяет протестировать ваше приложение с помощью
StrictModeAPI . - 2: Запретить использование интерфейсов, отличных от SDK, которые входят в черный список или условно заблокированы для вашего целевого уровня API .
Вопросы о списках интерфейсов, отличных от SDK
Где я могу найти списки API, не входящих в SDK, в образе системы?
Они закодированы в битах флага доступа к полям и методам в файлах платформы dex. В образе системы нет отдельного файла, содержащего эти списки.
Одинаковы ли списки API, не входящих в SDK, на разных OEM-устройствах с одинаковыми версиями Android?
OEM-производители могут добавлять свои собственные интерфейсы в черный список (черный список), но не могут удалять интерфейсы из списков API AOSP, не входящих в SDK. CDD предотвращает такие изменения, а тесты CTS гарантируют, что среда выполнения Android обеспечивает соблюдение списка.
Вопросы о совместимости связанных приложений
Есть ли какие-либо ограничения на интерфейсы, отличные от NDK, в собственном коде?
Android SDK включает интерфейсы Java. Платформа начала ограничивать доступ к интерфейсам, отличным от NDK, для собственного кода C/C++ в Android 7 (уровень API 26). Дополнительные сведения см. в разделе Повышение стабильности с помощью частных ограничений символов C/C++ в Android N.
Есть ли какой-либо план по ограничению манипуляций с файлами dex2oat или DEX?
У нас нет активных планов по ограничению доступа к двоичному файлу dex2oat, но мы не хотим, чтобы формат файла DEX был стабильным или общедоступным интерфейсом за пределами частей, которые публично указаны в формате исполняемого файла Dalvik . Мы оставляем за собой право изменять или удалять dex2oat и неуказанные части формата DEX в любое время. Также обратите внимание, что производные файлы, созданные dex2oat, такие как ODEX (также известный как OAT), VDEX и CDEX, являются неуказанными форматами.
Что, если важный сторонний SDK (например, обфускатор) не сможет избежать использования интерфейсов, отличных от SDK, но обязуется поддерживать совместимость с будущими версиями Android? Может ли Android в этом случае отказаться от требований совместимости?
У нас нет планов отказываться от требований совместимости для каждого SDK. Если разработчик SDK может поддерживать совместимость только в зависимости от интерфейсов из неподдерживаемых (ранее серых) списков, ему следует начать планировать переход на интерфейсы SDK или другие альтернативы и запрашивать новый общедоступный API всякий раз, когда он не может найти альтернативу использованию неподдерживаемых интерфейсов SDK. -Интерфейс SDK.
Применяются ли ограничения интерфейса, не связанные с SDK, ко всем приложениям, включая системные и сторонние, а не только к сторонним приложениям?
Да, однако мы освобождаем от ответственности приложения, подписанные с помощью ключа платформы, и некоторые приложения из образа системы. Обратите внимание, что эти исключения применяются только к приложениям, которые являются частью образа системы (или обновленных приложений образа системы). Список предназначен только для приложений, созданных на основе API частной платформы, а не API SDK (где LOCAL_PRIVATE_PLATFORM_APIS := true ).
Начиная с Android 9 (уровень API 28), платформа ограничивает интерфейсы, не относящиеся к SDK, которые может использовать ваше приложение. Эти ограничения применяются всякий раз, когда приложение ссылается на интерфейс, отличный от SDK, или пытается получить его дескриптор с помощью отражения или JNI. Эти ограничения были введены, чтобы помочь улучшить взаимодействие с пользователем и разработчиком и снизить риски сбоев для пользователей и экстренного развертывания для разработчиков. Дополнительные сведения об этом решении см. в разделе Улучшение стабильности за счет сокращения использования интерфейсов, отличных от SDK .
Различие между интерфейсами SDK и не-SDK
Вообще говоря, общедоступные интерфейсы SDK — это те, которые описаны в Индексе пакетов платформы Android. Обработка интерфейсов, отличных от SDK, — это деталь реализации, которую API абстрагирует, поэтому эти интерфейсы могут быть изменены без предварительного уведомления.
Чтобы избежать сбоев и непредвиденного поведения, приложения должны использовать только официально задокументированные части классов в SDK. Это также означает, что вам не следует обращаться к методам или полям, которые не указаны в SDK, когда вы взаимодействуете с классом с использованием таких механизмов, как отражение.
Списки API, не входящих в SDK
В каждом выпуске Android дополнительные интерфейсы, не относящиеся к SDK, ограничиваются. Мы знаем, что эти ограничения могут повлиять на ваш рабочий процесс выпуска, и мы хотим быть уверены, что у вас есть инструменты для обнаружения использования интерфейсов, отличных от SDK, возможность оставить нам отзыв и время для планирования и адаптации к новым политикам.
Чтобы свести к минимуму влияние ограничений, не связанных с SDK, на рабочий процесс разработки, интерфейсы, не относящиеся к SDK, разделены на списки, которые определяют, насколько строго ограничено их использование, в зависимости от того, какой уровень API является целевым. В следующей таблице описан каждый из этих списков:
| Список | Теги кода | Описание |
|---|---|---|
| Черный список |
| Интерфейсы, не относящиеся к SDK, которые вы не можете использовать независимо от целевого уровня API вашего приложения. Если ваше приложение попытается получить доступ к одному из этих интерфейсов, система выдаст ошибку . |
| Условно заблокировано |
| Начиная с Android 9 (уровень API 28), каждый уровень API имеет интерфейсы, отличные от SDK, которые ограничены, когда приложение нацелено на этот уровень API. Эти списки помечены максимальным уровнем API ( Если ваше приложение пытается получить доступ к интерфейсу, который ограничен для вашего целевого уровня API, система ведет себя так, как если бы API был частью черного списка . |
| Не поддерживается |
| Интерфейсы, не относящиеся к SDK, которые не имеют ограничений и могут использоваться вашим приложением. Однако обратите внимание, что эти интерфейсы не поддерживаются и могут быть изменены без предварительного уведомления. Ожидайте, что эти интерфейсы будут условно заблокированы в будущих версиях Android в списке max-target-x . |
| SDK |
| Интерфейсы, которые можно свободно использовать и которые теперь поддерживаются как часть официально документированного индекса пакетов платформы Android. |
| Тестовые API |
| Интерфейсы, используемые для внутреннего тестирования системы, например API-интерфейсы, упрощающие тестирование с помощью набора тестов совместимости (CTS). Тестовые API не являются частью SDK. Начиная с Android 11 (уровень API 30) , тестовые API включаются в черный список, поэтому приложениям не разрешается использовать их независимо от целевого уровня API. Все тестовые API не поддерживаются и могут быть изменены без предварительного уведомления независимо от уровня API платформы. |
Хотя вы можете использовать некоторые интерфейсы, не входящие в SDK (в зависимости от целевого уровня API вашего приложения), использование любого метода или поля, не входящего в SDK, всегда сопряжено с высоким риском поломки вашего приложения. Если ваше приложение использует интерфейсы, отличные от SDK, вам следует начать планировать переход на интерфейсы SDK или другие альтернативы. Если вы не можете найти альтернативу использованию интерфейса, отличного от SDK, для функции вашего приложения, вам следует запросить новый общедоступный API .
Определить, к какому списку принадлежит интерфейс
Списки интерфейсов, отличных от SDK, создаются как часть платформы. Дополнительные сведения о каждой версии Android см. в следующих разделах.
Андроид 15
Для Android 15 (уровень API 35) вы можете скачать следующий файл, описывающий все интерфейсы, не входящие в SDK, и их соответствующие списки:
Файл: hiddenapi-flags.csv
Контрольная сумма SHA-256: 40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9
Дополнительные сведения об изменениях в списке API, не входящих в SDK, в Android 15 см. в разделе Обновления ограничений интерфейса, не входящих в SDK, в Android 15 .
Андроид 14
Для Android 14 (уровень API 34) вы можете скачать следующий файл, описывающий все интерфейсы, не входящие в SDK, и их соответствующие списки:
Файл: hiddenapi-flags.csv
Контрольная сумма SHA-256: 7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f
Дополнительные сведения об изменениях в списке API, не входящих в SDK, в Android 14 см. в разделе Обновления ограничений интерфейса, не входящих в SDK, в Android 14 .
Андроид 13
Для Android 13 (уровень API 33) вы можете скачать следующий файл, описывающий все интерфейсы, не входящие в SDK, и их соответствующие списки:
Файл: hiddenapi-flags.csv
Контрольная сумма SHA-256: 233a277aa8ac475b6df61bffd95665d86aac6eb2ad187b90bf42a98f5f2a11a3
Чтобы узнать больше об изменениях в списке API, не входящих в SDK, в Android 13, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 13, см. раздел Обновления ограничений интерфейса, не входящих в SDK, в Android 13 .
Андроид 12
Для Android 12 (уровень API 31) вы можете скачать следующий файл, описывающий все интерфейсы, не входящие в SDK, и их соответствующие списки:
Файл: hiddenapi-flags.csv
Контрольная сумма SHA-256: 40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761
Чтобы узнать больше об изменениях в списке API, не входящих в SDK, в Android 12, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 12, см. раздел Изменения списка для Android 12 .
Андроид 11
Для Android 11 (уровень API 30) вы можете скачать следующий файл, описывающий все интерфейсы, не входящие в SDK, и их соответствующие списки:
Файл: hiddenapi-flags.csv
Контрольная сумма SHA-256: a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56
Чтобы узнать больше об изменениях в списке API, не входящих в SDK, в Android 11, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 11, см. раздел Изменения списка для Android 11 .
Андроид 10
Для Android 10 (уровень API 29) вы можете скачать следующий файл, описывающий все интерфейсы, не входящие в SDK, и их соответствующие списки:
Файл: hiddenapi-flags.csv
Контрольная сумма SHA-256: f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb
Чтобы узнать больше об изменениях в списке API, не входящих в SDK, в Android 10, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 10, см. раздел Изменения списка для Android 10 .
Андроид 9
Для Android 9 (уровень API 28) следующий текстовый файл содержит список API-интерфейсов, не входящих в SDK, которые не ограничены (внесены в серый список): hiddenapi-light-greylist.txt .
Черный список ( blacklist ) и список условно заблокированных API (темно-серый список) создаются во время сборки.
Генерировать списки из AOSP
При работе с AOSP вы можете создать файл hiddenapi-flags.csv , содержащий все интерфейсы, не входящие в состав SDK, и соответствующие им списки. Для этого загрузите исходный код AOSP и затем выполните следующую команду:
m out/soong/hiddenapi/hiddenapi-flags.csv
Затем вы сможете найти файл в следующем месте:
out/soong/hiddenapi/hiddenapi-flags.csv
Ожидаемое поведение при доступе к ограниченным интерфейсам, не относящимся к SDK
В следующей таблице описано поведение, которого можно ожидать, если ваше приложение попытается получить доступ к интерфейсу, отличному от SDK, который является частью черного списка.
| Средства доступа | Результат |
|---|---|
| Инструкция Dalvik, ссылающаяся на поле | Выброшено NoSuchFieldError |
| Инструкция Dalvik, ссылающаяся на метод | Выброшена NoSuchMethodError |
Отражение с использованием Class.getDeclaredField() или Class.getField() | Выброшено исключение NoSuchFieldException |
Отражение с использованием Class.getDeclaredMethod() , Class.getMethod() | Выброшено исключение NoSuchMethodException |
Отражение с использованием Class.getDeclaredFields() , Class.getFields() | Не члены SDK не в результатах |
Отражение с использованием Class.getDeclaredMethods() , Class.getMethods() | Не члены SDK не в результатах |
JNI с использованием env->GetFieldID() | Возвращается NULL , выдается NoSuchFieldError . |
JNI с использованием env->GetMethodID() | Возвращается NULL , выдается NoSuchMethodError |
Проверьте свое приложение на наличие интерфейсов, отличных от SDK.
Существует несколько методов, которые вы можете использовать для проверки интерфейсов, отличных от SDK, в вашем приложении.
Тестирование с помощью отлаживаемого приложения
Вы можете протестировать интерфейсы, не относящиеся к SDK, создав и запустив отлаживаемое приложение на устройстве или эмуляторе под управлением Android 9 (уровень API 28) или более поздней версии. Убедитесь, что используемое вами устройство или эмулятор соответствует целевому уровню API вашего приложения.
При выполнении тестов вашего приложения система печатает сообщение журнала, если ваше приложение обращается к определенным интерфейсам, отличным от SDK. Вы можете просмотреть сообщения журнала вашего приложения, чтобы найти следующую информацию:
- Объявляющий класс, имя и тип (в формате, который используется средой выполнения Android).
- Средства доступа: либо связывание, либо использование отражения, либо использование JNI.
- К какому списку принадлежит интерфейс, отличный от SDK.
Вы можете использовать adb logcat для доступа к этим сообщениям журнала, которые отображаются под PID работающего приложения. Например, запись в журнале может выглядеть следующим образом:
Accessing hidden field Landroid/os/Message;->flags:I (light greylist, JNI)
Тестирование с использованием StrictMode API
Вы также можете протестировать интерфейсы, отличные от SDK, с помощью API StrictMode . Чтобы включить это, используйте метод detectNonSdkApiUsage . После включения API StrictMode вы можете получать обратный вызов для каждого использования интерфейса, отличного от SDK, с помощью penaltyListener , где вы можете реализовать пользовательскую обработку. Объект Violation , предоставленный в обратном вызове, является производным от Throwable , а вложенная трассировка стека предоставляет контекст использования.
Протестируйте с помощью инструмента veridex
Вы также можете запустить инструмент статического анализа veridex в своем APK. Инструмент veridex сканирует всю кодовую базу APK, включая любые сторонние библиотеки, и сообщает о любом обнаруженном использовании интерфейсов, отличных от SDK.
Ограничения инструмента veridex включают следующее:
- Он не может обнаружить вызовы через JNI.
- Он может обнаружить только подмножество вызовов посредством отражения.
- Его анализ неактивных путей кода ограничивается проверками на уровне API.
- Его можно запускать только на машинах, поддерживающих инструкции SSE4.2 и POPCNT.
Окна
Собственные двоичные файлы Windows не предоставляются, но вы можете запустить инструмент veridex в Windows, запустив двоичные файлы Linux с помощью подсистемы Windows для Linux (WSL). Прежде чем выполнять действия, описанные в этом разделе, установите WSL и выберите Ubuntu в качестве дистрибутива Linux.
После установки Ubuntu запустите терминал Ubuntu и выполните следующие действия:
- Загрузите инструмент veridex из репозитория готовых сборок среды выполнения Android.
- Извлеките содержимое файла
appcompat.tar.gz. - В извлеченной папке найдите файл
veridex-linux.zipи распакуйте его. Перейдите в разархивированную папку и выполните следующую команду, где
your-app.apk— это APK, который вы хотите протестировать:./appcompat.sh --dex-file=your-app.apk
macOS
Чтобы запустить инструмент veridex в macOS, выполните следующие действия:
- Загрузите инструмент veridex из репозитория готовых сборок среды выполнения Android.
- Извлеките содержимое файла
appcompat.tar.gz. - В извлеченной папке найдите файл
veridex-mac.zipи извлеките его. Перейдите в разархивированную папку и выполните следующую команду, где
/path-from-root/your-app.apk— это путь к APK, который вы хотите протестировать, начиная с корневого каталога вашей системы:./appcompat.sh --dex-file=/path-from-root/your-app.apk
Линукс
Чтобы запустить инструмент veridex в Linux, выполните следующие действия:
- Загрузите инструмент veridex из репозитория готовых сборок среды выполнения Android.
- Извлеките содержимое файла
appcompat.tar.gz. - В извлеченной папке найдите файл
veridex-linux.zipи распакуйте его. Перейдите в разархивированную папку и выполните следующую команду, где
your-app.apk— это APK, который вы хотите протестировать:./appcompat.sh --dex-file=your-app.apk
Протестируйте с помощью инструмента Android Studio lint.
Всякий раз, когда вы создаете свое приложение в Android Studio, инструмент проверки проверяет ваш код на наличие потенциальных проблем. Если ваше приложение использует интерфейсы, отличные от SDK, вы можете увидеть ошибки сборки или предупреждения, в зависимости от того, к какому списку принадлежат эти интерфейсы.
Вы также можете запустить инструмент lint из командной строки или вручную выполнить проверку конкретного проекта, папки или файла.
Тестирование с помощью Play Console
Когда вы загружаете свое приложение на тестовую версию в Play Console, оно автоматически проверяется на наличие потенциальных проблем и создается отчет о предварительном запуске. Если ваше приложение использует интерфейсы, отличные от SDK, в отчете о предварительном запуске отображается ошибка или предупреждение, в зависимости от того, к какому списку принадлежат эти интерфейсы.
Дополнительную информацию см. в разделе «Совместимость Android» статьи «Использование отчетов о тестировании для выявления проблем» .
Запросить новый общедоступный API
Если вы не можете найти альтернативу использованию интерфейса, отличного от SDK, для функции вашего приложения, вы можете запросить новый общедоступный API, создав запрос функции в нашем трекере проблем.
При создании запроса на функцию предоставьте следующую информацию:
- Какой неподдерживаемый API вы используете, включая полный дескриптор, указанный в сообщении Logcat
Accessing hidden .... - Почему вам нужно использовать эти API, включая подробную информацию о функциях высокого уровня, для которых необходим API, а не только подробности низкого уровня.
- Почему любые связанные общедоступные API SDK недостаточны для ваших целей.
- Любые другие альтернативы, которые вы пробовали, и почему они не сработали.
Когда вы предоставляете эти сведения в своем запросе на функцию, вы увеличиваете вероятность того, что будет предоставлен новый общедоступный API.
Другие вопросы
В этом разделе приведены некоторые ответы на другие вопросы, которые часто задают разработчики:
Общие вопросы
Как Google может быть уверен, что сможет отслеживать потребности всех приложений с помощью системы отслеживания ошибок?
Мы создали первоначальные списки для Android 9 (API -уровень 28) посредством статического анализа приложений, который был дополнен с использованием следующих методов:
- Ручное тестирование приложений Top Play и Non Play
- Внутренние отчеты
- Автоматический сбор данных от внутренних пользователей
- Предварительный просмотр разработчиков отчеты
- Дополнительный статический анализ, который был разработан для консервативности, включает в себя больше ложных срабатываний
Когда мы оцениваем списки для каждого нового выпуска, мы учитываем использование API, а также обратную связь разработчика через трекер выпуска.
Как я могу включить доступ к не-SDK-интерфейсам?
Вы можете включить доступ к не-SDK-интерфейсам на устройствах разработки, используя команды ADB для изменения политики обеспечения соблюдения API. Команды, которые вы используете, различаются, в зависимости от уровня API. Эти команды не требуют корневого устройства.
- Android 10 (API -уровень 29) или выше
Чтобы включить доступ, используйте следующую ADB
Команда:
adb shell settings put global hidden_api_policy 1
Чтобы сбросить политику применения API в настройки по умолчанию, используйте следующую команду:
adb shell settings delete global hidden_api_policy
- Android 9 (уровень API 28)
Чтобы включить доступ, используйте следующие команды ADB:
adb shell settings put global hidden_api_policy_pre_p_apps 1adb shell settings put global hidden_api_policy_p_apps 1Чтобы сбросить политику применения API в настройки по умолчанию, используйте следующие команды:
adb shell settings delete global hidden_api_policy_pre_p_appsadb shell settings delete global hidden_api_policy_p_apps
Вы можете установить целое число в политике применения API на одно из следующих значений:
- 0: Отключить все обнаружение не-SDK интерфейсов. Использование этой настройки отключает все сообщения журнала для использования интерфейса без SDK и не позволяет вам тестировать ваше приложение с помощью API
StrictMode. Эта настройка не рекомендуется. - 1: Включите доступ ко всем не-SDK-интерфейсам, но печатайте сообщения журнала с предупреждениями для любого использования интерфейса, не связанного с SDK. Использование этой настройки также позволяет протестировать ваше приложение, используя API
StrictMode. - 2: запретить использование не-SDK-интерфейсов, которые принадлежат блочному списку или условно заблокированы для вашего целевого уровня API .
Вопросы о списках интерфейса без SDK
Где я могу найти списки API не-SDK на изображении системы?
Они кодируются в полевых и методах доступа к методам флага в файлах DEX платформы. В образе системы нет отдельного файла, который содержит эти списки.
Является ли API не SDK перечислены одинаковые на разных устройствах OEM с одинаковыми версиями Android?
OEM-производители могут добавить свои собственные интерфейсы в Blocklist (BlackList), но они не могут удалить интерфейсы из списков API API API API ASOSP. CDD предотвращает такие изменения, и тесты CTS гарантируют, что время выполнения Android обеспечивает соблюдение списка.
Вопросы о совместимости связанных приложений
Есть ли какие-либо ограничения на не-NDK-интерфейсы в собственном коде?
Android SDK включает в себя интерфейсы Java. Платформа начала ограничивать доступ к не-NDK-интерфейсам для нативного кода C/C ++ в Android 7 (API-уровне 26). Для получения дополнительной информации см. Улучшение стабильности с частными ограничениями символов C/C ++ в Android N.
Есть ли план ограничения манипуляции с файлами DEX2OAT или DEX?
У нас нет активных планов по ограничению доступа к двоичному файлу DEX2OAT, но мы не намерены, чтобы формат файла DEX был стабильным или публичным интерфейсом за пределами порций, которые публично указаны в исполняемом формате Dalvik . Мы оставляем за собой право изменять или устранять DEX2OAT и неопределенные части формата DEX в любое время. Также обратите внимание, что полученные файлы, созданные Dex2oat, такие как ODEX (также известный как OAT), VDEX и CDEX, являются неуказанными форматами.
Что, если важнейший сторонний SDK (например, сфускатор) не может избежать использования не-SDK-интерфейсов, но привержен ли поддерживать совместимость с будущими версиями Android? Может ли Android отказаться от требований к совместимости в этом случае?
У нас нет планов отказаться от требований к совместимости на основе SDK. Если разработчик SDK может поддерживать совместимость только в зависимости от интерфейсов в неподдерживаемых (ранее серых) списках, он должен начать планирование миграции в интерфейсы SDK или другие альтернативы и запросить новый публичный API , когда не может найти альтернативу использованию не -SDK Интерфейс.
Применяются ли ограничения не-SDK интерфейса ко всем приложениям, включая системные и первоклассные приложения, а не только сторонние приложения?
Да, однако, мы освобождаем приложения, подписанные с ключом платформы и некоторыми приложениями системного изображения. Обратите внимание, что эти исключения применяются только к приложениям, которые являются частью изображения системы (или обновленных приложений системного изображения). Список предназначен только для приложений, которые строятся против API частной платформы, а не API SDK (где LOCAL_PRIVATE_PLATFORM_APIS := true ).
Начиная с Android 9 (уровень API 28), платформа ограничивает, какие не SDK интерфейсы могут использовать ваше приложение. Эти ограничения применяются всякий раз, когда приложение ссылается на интерфейс не-SDK или пытается получить его ручку с использованием отражения или JNI. Эти ограничения были внесены для улучшения опыта пользователя и разработчиков и снижения рисков сбоев для пользователей и аварийных развертываний для разработчиков. Для получения дополнительной информации об этом решении см. Улучшение стабильности за счет сокращения использования не-SDK-интерфейсов .
Различать интерфейсы SDK и не SDK
Вообще говоря, общедоступные интерфейсы SDK - это те, которые найдены задокументированными в индексе пакета Android Framework. Обработка не-SDK-интерфейсов является детализацией реализации, которую API устраняет, поэтому эти интерфейсы могут быть изменены без уведомления.
Чтобы избежать сбоев и неожиданного поведения, приложения должны использовать только официально документированные части классов в SDK. Это также означает, что вы не должны получать доступ к методам или полям, которые не указаны в SDK, когда вы взаимодействуете с классом, используя такие механизмы, как отражение.
Не-SDK API списки
С каждым выпуском Android дополнительные не SDK-интерфейсы ограничены. Мы знаем, что эти ограничения могут повлиять на ваш рабочий процесс выпуска, и мы хотим убедиться, что у вас есть инструменты для обнаружения использования не-SDK-интерфейсов, возможность дать нам отзыв и время для планирования и адаптации к новым политикам.
Чтобы свести к минимуму влияние не-SDK-ограничений на ваш рабочий процесс разработки, интерфейсы без SDK разделены на списки, которые определяют, насколько тесно их использование ограничено, в зависимости от того, на какой уровень API нацелен. В следующей таблице описывается каждый из этих списков:
| Список | Кодовые теги | Описание |
|---|---|---|
| Блок -лист |
| Не-SDK интерфейсы, которые вы не можете использовать независимо от целевого уровня API вашего приложения. Если ваше приложение пытается получить доступ к одному из этих интерфейсов, система бросает ошибку . |
| Условно заблокирован |
| Начиная с Android 9 (уровень API 28), каждый уровень API имеет не-SDK интерфейсы, которые ограничены, когда приложение нацелено на уровень API. Эти списки помечены максимальным уровнем API ( Если ваше приложение пытается получить доступ к интерфейсу, который ограничен для вашего целевого уровня API, система ведет себя так, как будто API является частью BlockList . |
| Не поддерживается |
| Не-SDK интерфейсы, которые неограниченные и ваше приложение может использовать. Обратите внимание, что эти интерфейсы не поддерживаются и могут быть изменены без уведомления. Ожидайте, что эти интерфейсы будут условно заблокированы в будущих версиях Android в списке max-target-x . |
| SDK |
| Интерфейсы, которые могут быть свободно использованы и теперь поддерживаются в рамках официально документированного индекса пакета Android Framework. |
| Тестирование API |
| Интерфейсы, которые используются для внутреннего тестирования системы, таких как API, которые облегчают тестирование через набор тестов совместимости (CTS). Тестовые API не являются частью SDK. Начиная с Android 11 (API -уровень 30) , тестовые API включены в BlockList, поэтому приложения не разрешают их использовать независимо от их целевого уровня API. Все тестовые API не поддерживаются и подвергаются изменениям без уведомления, независимо от уровня API платформы. |
Хотя вы можете использовать некоторые не-SDK-интерфейсы (в зависимости от целевого уровня API вашего приложения), использование любого метода или поля не SDK всегда несет высокий риск разбивания вашего приложения. Если ваше приложение опирается на не-SDK-интерфейсы, вам следует начать планировать миграцию в интерфейсы SDK или другие альтернативы. Если вы не можете найти альтернативу использованию не-SDK-интерфейса для функции в вашем приложении, вам следует запросить новый публичный API .
Определить, какой список принадлежит интерфейсу
Списки не-SDK-интерфейсов построены как часть платформы. См. Следующие разделы для получения информации о каждом выпуске Android.
Android 15
Для Android 15 (уровень API 35) вы можете загрузить следующий файл, который описывает все не-SDK-интерфейсы и их соответствующие списки:
Файл: hiddenapi-flags.csv
SHA-256 Контрольная сумма: 40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9
Чтобы узнать больше об изменениях списка API не-SDK в Android 15, см. Обновления ограничений не-SDK интерфейса в Android 15 .
Андроид 14
Для Android 14 (уровень API 34) вы можете загрузить следующий файл, который описывает все не-SDK-интерфейсы и их соответствующие списки:
Файл: hiddenapi-flags.csv
SHA-256 Контрольная сумма: 7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f
Чтобы узнать больше об изменениях списка API, не связанных с SDK в Android 14, см. Обновления ограничений не-SDK интерфейса в Android 14 .
Андроид 13
Для Android 13 (уровень API 33) вы можете загрузить следующий файл, который описывает все не-SDK-интерфейсы и их соответствующие списки:
Файл: hiddenapi-flags.csv
SHA-256 Контрольная сумма: 233a277aa8ac475b6df61bffd95665d86aac6eb2ad187b90bf42a98f5f2a11a3
Чтобы узнать больше об изменениях списка API, не связанных с SDK, в Android 13, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 13, см. Обновления ограничений не-SDK в Android 13 .
Андроид 12
Для Android 12 (API-уровень 31) вы можете загрузить следующий файл, который описывает все не-SDK-интерфейсы и их соответствующие списки:
Файл: hiddenapi-flags.csv
SHA-256 Контрольная сумма: 40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761
Чтобы узнать больше об изменениях списка API, не связанных с SDK, в Android 12, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 12, см. Изменения списка для Android 12 .
Андроид 11
Для Android 11 (API-уровне 30) вы можете загрузить следующий файл, который описывает все не-SDK-интерфейсы и их соответствующие списки:
Файл: hiddenapi-flags.csv
SHA-256 Контрольная сумма: a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56
Чтобы узнать больше об изменениях списка API не-SDK в Android 11, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 11, см. Изменения списка для Android 11 .
Андроид 10
Для Android 10 (уровень API 29) вы можете загрузить следующий файл, который описывает все не-SDK-интерфейсы и их соответствующие списки:
Файл: hiddenapi-flags.csv
SHA-256 Контрольная сумма: f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb
Чтобы узнать больше об изменениях списка API не-SDK в Android 10, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 10, см. Изменения списка для Android 10 .
Android 9
Для Android 9 (уровень API 28) следующий текстовый файл содержит список не SDK API, которые не ограничены (в серого списках): hiddenapi-light-greylist.txt .
BlockList ( blacklist ) и список условно заблокированных API (список Darkgrey) получены во время сборки.
Генерировать списки из AOSP
При работе с AOSP вы можете генерировать файл hiddenapi-flags.csv , который содержит все не-SDK-интерфейсы и их соответствующие списки. Для этого загрузите источник AOSP , а затем запустите следующую команду:
m out/soong/hiddenapi/hiddenapi-flags.csv
Затем вы можете найти файл в следующем месте:
out/soong/hiddenapi/hiddenapi-flags.csv
Ожидаемое поведение, когда доступ к ограниченному не-SDK
В следующей таблице описывается поведение, которое вы можете ожидать, если ваше приложение попытается получить доступ к интерфейсу без SDK, который является частью BlockList.
| Средства доступа | Результат |
|---|---|
| Инструкция Dalvik ссылается на поле | NoSuchFieldError |
| Инструкция Dalvik ссылается на метод | NoSuchMethodError брошен |
Отражение с использованием Class.getDeclaredField() или Class.getField() | NoSuchFieldException брошен |
Отражение с использованием Class.getDeclaredMethod() , Class.getMethod() | NoSuchMethodException брошен |
Отражение с использованием Class.getDeclaredFields() , Class.getFields() | Члены не-SDK не в результатах |
Отражение с использованием Class.getDeclaredMethods() , Class.getMethods() | Члены не-SDK не в результатах |
Jni использует env->GetFieldID() | NULL вернулся, NoSuchFieldError брошен |
Jni с использованием env->GetMethodID() | NULL вернулся, выброшен NoSuchMethodError |
Проверьте свое приложение для не-SDK-интерфейсов
Есть несколько методов, которые вы можете использовать для тестирования на не SDK-интерфейсы в вашем приложении.
Тест с использованием отзываемого приложения
Вы можете протестировать не-SDK-интерфейсы, создавая и запустив отзываемое приложение на устройстве или эмуляторе под управлением Android 9 (уровень API 28) или выше. Убедитесь, что устройство или эмулятор, который вы используете, совпадает с целевым уровнем API вашего приложения.
При прохождении тестов в вашем приложении система печатает сообщение журнала, если ваше приложение обращается к определенным не-SDK-интерфейсам. Вы можете проверить сообщения журнала вашего приложения, чтобы найти следующие данные:
- Объявляющий класс, имя и тип (в формате, который используется во время выполнения Android).
- Средства доступа: либо связывание, используя отражение, либо использование JNI.
- Которые перечисляют не-SDK интерфейс принадлежит.
Вы можете использовать adb logcat для доступа к этим сообщениям журнала, которые отображаются под пистом приложения Running. Например, запись в журнале может прочитать следующее:
Accessing hidden field Landroid/os/Message;->flags:I (light greylist, JNI)
Тест с использованием API StrictMode
Вы также можете проверить на не-SDK интерфейсы, используя API StrictMode . Используйте метод detectNonSdkApiUsage , чтобы включить это. После того, как вы включили API StrictMode , вы можете получить обратный вызов для каждого использования не-SDK-интерфейса, используя penaltyListener , где вы можете реализовать пользовательскую обработку. Объект Violation , предоставленный в обратном вызове, происходит от Throwable , а приложенная трассировка стека обеспечивает контекст использования.
Тест с использованием инструмента Veridex
Вы также можете запустить инструмент статического анализа Veridex на своем APK. Инструмент Veridex сканирует всю кодовую базу APK, включая любые сторонние библиотеки, и сообщает о любом использовании не SDK-интерфейсов, которые он находит.
Ограничения инструмента Veridex включают следующее:
- Это не может обнаружить призывы через JNI.
- Он может обнаружить только подмножество призывов посредством размышлений.
- Его анализ неактивных путей кода ограничен проверками уровня API.
- Его можно запустить только на машинах, которые поддерживают инструкции SSE4.2 и POPCNT.
Окна
Народные двоичные файлы Windows не предоставляются, но вы можете запустить инструмент Veridex в Windows, выполнив двоичные файлы Linux, используя подсистему Windows для Linux (WSL). Прежде чем выполнять шаги в этом разделе, установите WSL и выберите Ubuntu в качестве распределения Linux.
После установки Ubuntu запустите терминал Ubuntu, а затем следуйте этим шагам:
- Загрузите инструмент Veridex из репозитория Android Runtime Prebuilts.
- Извлеките содержимое файла
appcompat.tar.gz. - В извлеченной папке найдите файл
veridex-linux.zipи извлеките его. Перейдите к папке с неказрированной, а затем запустите следующую команду, где
your-app.apk-это APK, который вы хотите проверить:./appcompat.sh --dex-file=your-app.apk
macOS
Чтобы запустить инструмент Veridex на macOS, выполните следующие действия:
- Загрузите инструмент Veridex из репозитория Android Runtime Prebuilts.
- Извлеките содержимое файла
appcompat.tar.gz. - В извлеченной папке найдите файл
veridex-mac.zipи извлеките его. Перейдите в папку с неказрированной, а затем запустите следующую команду, где
/path-from-root/your-app.apkпуть к APK, который вы хотите проверить, начиная с корневого каталога вашей системы:./appcompat.sh --dex-file=/path-from-root/your-app.apk
Линукс
Чтобы запустить инструмент Veridex на Linux, выполните следующие действия:
- Загрузите инструмент Veridex из репозитория Android Runtime Prebuilts.
- Извлеките содержимое файла
appcompat.tar.gz. - В извлеченной папке найдите файл
veridex-linux.zipи извлеките его. Перейдите к папке с неказрированной, а затем запустите следующую команду, где
your-app.apk-это APK, который вы хотите проверить:./appcompat.sh --dex-file=your-app.apk
Тест с использованием инструмента Android Studio Lint
Всякий раз, когда вы создаете свое приложение в Android Studio, инструмент Lint осматривает ваш код на наличие потенциальных проблем. Если ваше приложение использует не-SDK интерфейсы, вы можете увидеть ошибки или предупреждения сборки, в зависимости от того, к какому списку принадлежат эти интерфейсы.
Вы также можете запустить инструмент Lint из командной строки или запустить инспекции вручную по конкретному проекту, папке или файлу.
Тест с использованием игровой консоли
Когда вы загружаете ваше приложение на трек тестирования в консоли PLAY, ваше приложение автоматически протестируется на потенциальные проблемы, и генерируется отчет перед запуском. Если ваше приложение использует не-SDK интерфейсы, в отчете предварительно запуска отображается ошибка или предупреждение, в зависимости от того, к какому списку принадлежат эти интерфейсы.
Для получения дополнительной информации см. В разделе совместимости Android, в котором используются отчеты предварительных запуска для выявления проблем .
Запросить новый публичный API
Если вы не можете найти альтернативу использованию не-SDK-интерфейса для функции в вашем приложении, вы можете запросить новый публичный API, создав запрос функции в нашем трекере.
При создании запроса функции предоставьте следующую информацию:
- Какой не поддерживается API, который вы используете, включая полный дескриптор, который можно увидеть в
Accessing hidden ...сообщении LogCat. - Почему вам нужно использовать эти API, в том числе подробности о функции высокого уровня, для которой необходим API, а не только детали низкого уровня.
- Почему любые связанные публичные API SDK недостаточны для ваших целей.
- Любые другие альтернативы, которые вы попробовали, и почему они не сработали.
Когда вы предоставляете эти данные в своем запросе функции, вы увеличиваете вероятность того, что новый публичный API будет предоставлен.
Другие вопросы
Этот раздел включает в себя некоторые ответы на другие вопросы, которые разработчики часто задавали:
Общие вопросы
Как Google может быть уверен, что они могут запечатлеть потребности всех приложений через EvesueTracker?
Мы создали первоначальные списки для Android 9 (API -уровень 28) посредством статического анализа приложений, который был дополнен с использованием следующих методов:
- Ручное тестирование приложений Top Play и Non Play
- Внутренние отчеты
- Автоматический сбор данных от внутренних пользователей
- Предварительный просмотр разработчиков отчеты
- Дополнительный статический анализ, который был разработан для консервативности, включает в себя больше ложных срабатываний
Когда мы оцениваем списки для каждого нового выпуска, мы учитываем использование API, а также обратную связь разработчика через трекер выпуска.
Как я могу включить доступ к не-SDK-интерфейсам?
Вы можете включить доступ к не-SDK-интерфейсам на устройствах разработки, используя команды ADB для изменения политики обеспечения соблюдения API. Команды, которые вы используете, различаются, в зависимости от уровня API. Эти команды не требуют корневого устройства.
- Android 10 (API -уровень 29) или выше
Чтобы включить доступ, используйте следующую ADB
Команда:
adb shell settings put global hidden_api_policy 1
Чтобы сбросить политику применения API в настройки по умолчанию, используйте следующую команду:
adb shell settings delete global hidden_api_policy
- Android 9 (уровень API 28)
Чтобы включить доступ, используйте следующие команды ADB:
adb shell settings put global hidden_api_policy_pre_p_apps 1adb shell settings put global hidden_api_policy_p_apps 1Чтобы сбросить политику применения API в настройки по умолчанию, используйте следующие команды:
adb shell settings delete global hidden_api_policy_pre_p_appsadb shell settings delete global hidden_api_policy_p_apps
Вы можете установить целое число в политике применения API на одно из следующих значений:
- 0: Отключить все обнаружение не-SDK интерфейсов. Использование этой настройки отключает все сообщения журнала для использования интерфейса без SDK и не позволяет вам тестировать ваше приложение с помощью API
StrictMode. Эта настройка не рекомендуется. - 1: Включите доступ ко всем не-SDK-интерфейсам, но печатайте сообщения журнала с предупреждениями для любого использования интерфейса, не связанного с SDK. Использование этой настройки также позволяет протестировать ваше приложение, используя API
StrictMode. - 2: запретить использование не-SDK-интерфейсов, которые принадлежат блочному списку или условно заблокированы для вашего целевого уровня API .
Вопросы о списках интерфейса без SDK
Где я могу найти списки API не-SDK на изображении системы?
Они кодируются в полевых и методах доступа к методам флага в файлах DEX платформы. В образе системы нет отдельного файла, который содержит эти списки.
Является ли API не SDK перечислены одинаковые на разных устройствах OEM с одинаковыми версиями Android?
OEM-производители могут добавить свои собственные интерфейсы в Blocklist (BlackList), но они не могут удалить интерфейсы из списков API API API API ASOSP. CDD предотвращает такие изменения, и тесты CTS гарантируют, что время выполнения Android обеспечивает соблюдение списка.
Вопросы о совместимости связанных приложений
Есть ли какие-либо ограничения на не-NDK-интерфейсы в собственном коде?
Android SDK включает в себя интерфейсы Java. Платформа начала ограничивать доступ к не-NDK-интерфейсам для нативного кода C/C ++ в Android 7 (API-уровне 26). Для получения дополнительной информации см. Улучшение стабильности с частными ограничениями символов C/C ++ в Android N.
Есть ли план ограничения манипуляции с файлами DEX2OAT или DEX?
У нас нет активных планов по ограничению доступа к двоичному файлу DEX2OAT, но мы не намерены, чтобы формат файла DEX был стабильным или публичным интерфейсом за пределами порций, которые публично указаны в исполняемом формате Dalvik . Мы оставляем за собой право изменять или устранять DEX2OAT и неопределенные части формата DEX в любое время. Также обратите внимание, что полученные файлы, созданные Dex2oat, такие как ODEX (также известный как OAT), VDEX и CDEX, являются неуказанными форматами.
Что, если важнейший сторонний SDK (например, сфускатор) не может избежать использования не-SDK-интерфейсов, но привержен ли поддерживать совместимость с будущими версиями Android? Может ли Android отказаться от требований к совместимости в этом случае?
У нас нет планов отказаться от требований к совместимости на основе SDK. Если разработчик SDK может поддерживать совместимость только в зависимости от интерфейсов в неподдерживаемых (ранее серых) списках, он должен начать планирование миграции в интерфейсы SDK или другие альтернативы и запросить новый публичный API , когда не может найти альтернативу использованию не -SDK Интерфейс.
Применяются ли ограничения не-SDK интерфейса ко всем приложениям, включая системные и первоклассные приложения, а не только сторонние приложения?
Да, однако, мы освобождаем приложения, подписанные с ключом платформы и некоторыми приложениями системного изображения. Обратите внимание, что эти исключения применяются только к приложениям, которые являются частью изображения системы (или обновленных приложений системного изображения). Список предназначен только для приложений, которые строятся против API частной платформы, а не API SDK (где LOCAL_PRIVATE_PLATFORM_APIS := true ).
Начиная с Android 9 (уровень API 28), платформа ограничивает, какие не SDK интерфейсы могут использовать ваше приложение. Эти ограничения применяются всякий раз, когда приложение ссылается на интерфейс не-SDK или пытается получить его ручку с использованием отражения или JNI. Эти ограничения были внесены для улучшения опыта пользователя и разработчиков и снижения рисков сбоев для пользователей и аварийных развертываний для разработчиков. Для получения дополнительной информации об этом решении см. Улучшение стабильности за счет сокращения использования не-SDK-интерфейсов .
Различать интерфейсы SDK и не SDK
Вообще говоря, общедоступные интерфейсы SDK - это те, которые найдены задокументированными в индексе пакета Android Framework. Обработка не-SDK-интерфейсов является детализацией реализации, которую API устраняет, поэтому эти интерфейсы могут быть изменены без уведомления.
Чтобы избежать сбоев и неожиданного поведения, приложения должны использовать только официально документированные части классов в SDK. Это также означает, что вы не должны получать доступ к методам или полям, которые не указаны в SDK, когда вы взаимодействуете с классом, используя такие механизмы, как отражение.
Не-SDK API списки
С каждым выпуском Android дополнительные не SDK-интерфейсы ограничены. Мы знаем, что эти ограничения могут повлиять на ваш рабочий процесс выпуска, и мы хотим убедиться, что у вас есть инструменты для обнаружения использования не-SDK-интерфейсов, возможность дать нам отзыв и время для планирования и адаптации к новым политикам.
Чтобы свести к минимуму влияние не-SDK-ограничений на ваш рабочий процесс разработки, интерфейсы без SDK разделены на списки, которые определяют, насколько тесно их использование ограничено, в зависимости от того, на какой уровень API нацелен. В следующей таблице описывается каждый из этих списков:
| Список | Кодовые теги | Описание |
|---|---|---|
| Блок -лист |
| Не-SDK интерфейсы, которые вы не можете использовать независимо от целевого уровня API вашего приложения. Если ваше приложение пытается получить доступ к одному из этих интерфейсов, система бросает ошибку . |
| Условно заблокирован |
| Начиная с Android 9 (уровень API 28), каждый уровень API имеет не-SDK интерфейсы, которые ограничены, когда приложение нацелено на уровень API. Эти списки помечены максимальным уровнем API ( Если ваше приложение пытается получить доступ к интерфейсу, который ограничен для вашего целевого уровня API, система ведет себя так, как будто API является частью BlockList . |
| Не поддерживается |
| Не-SDK интерфейсы, которые неограниченные и ваше приложение может использовать. Обратите внимание, что эти интерфейсы не поддерживаются и могут быть изменены без уведомления. Ожидайте, что эти интерфейсы будут условно заблокированы в будущих версиях Android в списке max-target-x . |
| SDK |
| Интерфейсы, которые могут быть свободно использованы и теперь поддерживаются в рамках официально документированного индекса пакета Android Framework. |
| Тестирование API |
| Интерфейсы, которые используются для внутреннего тестирования системы, таких как API, которые облегчают тестирование через набор тестов совместимости (CTS). Тестовые API не являются частью SDK. Начиная с Android 11 (API -уровень 30) , тестовые API включены в BlockList, поэтому приложения не разрешают их использовать независимо от их целевого уровня API. Все тестовые API не поддерживаются и подвергаются изменениям без уведомления, независимо от уровня API платформы. |
Хотя вы можете использовать некоторые не-SDK-интерфейсы (в зависимости от целевого уровня API вашего приложения), использование любого метода или поля не SDK всегда несет высокий риск разбивания вашего приложения. Если ваше приложение опирается на не-SDK-интерфейсы, вам следует начать планировать миграцию в интерфейсы SDK или другие альтернативы. Если вы не можете найти альтернативу использованию не-SDK-интерфейса для функции в вашем приложении, вам следует запросить новый публичный API .
Определить, какой список принадлежит интерфейсу
Списки не-SDK-интерфейсов построены как часть платформы. См. Следующие разделы для получения информации о каждом выпуске Android.
Android 15
Для Android 15 (уровень API 35) вы можете загрузить следующий файл, который описывает все не-SDK-интерфейсы и их соответствующие списки:
Файл: hiddenapi-flags.csv
SHA-256 Контрольная сумма: 40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9
Чтобы узнать больше об изменениях списка API не-SDK в Android 15, см. Обновления ограничений не-SDK интерфейса в Android 15 .
Андроид 14
Для Android 14 (уровень API 34) вы можете загрузить следующий файл, который описывает все не-SDK-интерфейсы и их соответствующие списки:
Файл: hiddenapi-flags.csv
SHA-256 Контрольная сумма: 7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f
Чтобы узнать больше об изменениях списка API, не связанных с SDK в Android 14, см. Обновления ограничений не-SDK интерфейса в Android 14 .
Андроид 13
Для Android 13 (уровень API 33) вы можете загрузить следующий файл, который описывает все не-SDK-интерфейсы и их соответствующие списки:
Файл: hiddenapi-flags.csv
SHA-256 Контрольная сумма: 233a277aa8ac475b6df61bffd95665d86aac6eb2ad187b90bf42a98f5f2a11a3
Чтобы узнать больше об изменениях списка API, не связанных с SDK, в Android 13, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 13, см. Обновления ограничений не-SDK в Android 13 .
Андроид 12
Для Android 12 (API-уровень 31) вы можете загрузить следующий файл, который описывает все не-SDK-интерфейсы и их соответствующие списки:
Файл: hiddenapi-flags.csv
SHA-256 Контрольная сумма: 40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761
Чтобы узнать больше об изменениях списка API, не связанных с SDK, в Android 12, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 12, см. Изменения списка для Android 12 .
Андроид 11
Для Android 11 (API-уровне 30) вы можете загрузить следующий файл, который описывает все не-SDK-интерфейсы и их соответствующие списки:
Файл: hiddenapi-flags.csv
SHA-256 Контрольная сумма: a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56
Чтобы узнать больше об изменениях списка API не-SDK в Android 11, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 11, см. Изменения списка для Android 11 .
Андроид 10
Для Android 10 (уровень API 29) вы можете загрузить следующий файл, который описывает все не-SDK-интерфейсы и их соответствующие списки:
Файл: hiddenapi-flags.csv
SHA-256 Контрольная сумма: f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb
Чтобы узнать больше об изменениях списка API не-SDK в Android 10, включая предлагаемые общедоступные альтернативы API для API, которые условно заблокированы в Android 10, см. Изменения списка для Android 10 .
Android 9
Для Android 9 (уровень API 28) следующий текстовый файл содержит список не SDK API, которые не ограничены (в серого списках): hiddenapi-light-greylist.txt .
BlockList ( blacklist ) и список условно заблокированных API (список Darkgrey) получены во время сборки.
Генерировать списки из AOSP
При работе с AOSP вы можете генерировать файл hiddenapi-flags.csv , который содержит все не-SDK-интерфейсы и их соответствующие списки. Для этого загрузите источник AOSP , а затем запустите следующую команду:
m out/soong/hiddenapi/hiddenapi-flags.csv
Затем вы можете найти файл в следующем месте:
out/soong/hiddenapi/hiddenapi-flags.csv
Ожидаемое поведение, когда доступ к ограниченному не-SDK
В следующей таблице описывается поведение, которое вы можете ожидать, если ваше приложение попытается получить доступ к интерфейсу без SDK, который является частью BlockList.
| Средства доступа | Результат |
|---|---|
| Инструкция Dalvik ссылается на поле | NoSuchFieldError |
| Инструкция Dalvik ссылается на метод | NoSuchMethodError брошен |
Отражение с использованием Class.getDeclaredField() или Class.getField() | NoSuchFieldException брошен |
Отражение с использованием Class.getDeclaredMethod() , Class.getMethod() | NoSuchMethodException брошен |
Отражение с использованием Class.getDeclaredFields() , Class.getFields() | Члены не-SDK не в результатах |
Отражение с использованием Class.getDeclaredMethods() , Class.getMethods() | Члены не-SDK не в результатах |
Jni использует env->GetFieldID() | NULL вернулся, NoSuchFieldError брошен |
Jni с использованием env->GetMethodID() | NULL вернулся, выброшен NoSuchMethodError |
Проверьте свое приложение для не-SDK-интерфейсов
Есть несколько методов, которые вы можете использовать для тестирования на не SDK-интерфейсы в вашем приложении.
Тест с использованием отзываемого приложения
Вы можете протестировать не-SDK-интерфейсы, создавая и запустив отзываемое приложение на устройстве или эмуляторе под управлением Android 9 (уровень API 28) или выше. Убедитесь, что устройство или эмулятор, который вы используете, совпадает с целевым уровнем API вашего приложения.
При прохождении тестов в вашем приложении система печатает сообщение журнала, если ваше приложение обращается к определенным не-SDK-интерфейсам. Вы можете проверить сообщения журнала вашего приложения, чтобы найти следующие данные:
- Объявляющий класс, имя и тип (в формате, который используется во время выполнения Android).
- Средства доступа: либо связывание, используя отражение, либо использование JNI.
- Которые перечисляют не-SDK интерфейс принадлежит.
Вы можете использовать adb logcat для доступа к этим сообщениям журнала, которые отображаются под пистом приложения Running. Например, запись в журнале может прочитать следующее:
Accessing hidden field Landroid/os/Message;->flags:I (light greylist, JNI)
Test using the StrictMode API
You can also test for non-SDK interfaces by using the StrictMode API. Use the detectNonSdkApiUsage method to enable this. After enabling the StrictMode API, you can receive a callback for each usage of a non-SDK interface by using a penaltyListener , where you can implement custom handling. The Violation object provided in the callback derives from Throwable , and the enclosed stack trace provides the context of the usage.
Test using the veridex tool
You can also run the veridex static analysis tool on your APK. The veridex tool scans the entire codebase of the APK, including any third-party libraries, and reports any uses of non-SDK interfaces that it finds.
Limitations of the veridex tool include the following:
- It can't detect invocations through JNI.
- It can detect only a subset of invocations through reflection.
- Its analysis for inactive code paths is limited to API level checks.
- It can only be run on machines that support SSE4.2 and POPCNT instructions.
Окна
Native Windows binaries are not provided, but you can run the veridex tool on Windows by executing the Linux binaries using the Windows Subsystem for Linux (WSL). Before following the steps in this section, install the WSL and choose Ubuntu as your Linux distribution.
After Ubuntu is installed, launch a Ubuntu terminal and then follow these steps:
- Download the veridex tool from the Android runtime prebuilts repository.
- Extract the contents of the
appcompat.tar.gzfile. - In the extracted folder, locate the
veridex-linux.zipfile and extract it. Navigate to the unzipped folder and then run the following command, where
your-app.apkis the APK that you want to test:./appcompat.sh --dex-file=your-app.apk
macOS
To run the veridex tool on macOS, follow these steps:
- Download the veridex tool from the Android runtime prebuilts repository.
- Extract the contents of the
appcompat.tar.gzfile. - In the extracted folder, locate the
veridex-mac.zipfile and extract it. Navigate to the unzipped folder and then run the following command, where
/path-from-root/your-app.apkis the path to the APK that you want to test, starting from your system's root directory:./appcompat.sh --dex-file=/path-from-root/your-app.apk
Линукс
To run the veridex tool on Linux, follow these steps:
- Download the veridex tool from the Android runtime prebuilts repository.
- Extract the contents of the
appcompat.tar.gzfile. - In the extracted folder, locate the
veridex-linux.zipfile and extract it. Navigate to the unzipped folder and then run the following command, where
your-app.apkis the APK that you want to test:./appcompat.sh --dex-file=your-app.apk
Test using the Android Studio lint tool
Whenever you build your app in Android Studio, the lint tool inspects your code for potential issues. If your app uses non-SDK interfaces, you might see build errors or warnings, depending on which list those interfaces belong to.
You can also run the lint tool from the command line or run inspections manually on a specific project, folder, or file.
Test using the Play Console
When you upload your app to a testing track in the Play Console, your app is automatically tested for potential issues and a pre-launch report is generated. If your app uses non-SDK interfaces, an error or warning displays in the pre-launch report, depending on which list those interfaces belong to.
For more information, see the Android Compatibility section in Use pre-launch reports to identify issues .
Request a new public API
If you cannot find an alternative to using a non-SDK interface for a feature in your app, you can request a new public API by creating a feature request in our issue tracker.
When creating a feature request, provide the following information:
- Which unsupported API you are using, including the full descriptor seen in the
Accessing hidden ...logcat message. - Why you need to use these APIs, including details about the high-level feature that the API is necessary for, not just low level details.
- Why any related public SDK APIs are insufficient for your purposes.
- Any other alternatives you have tried and why these didn't work out.
When you provide these details in your feature request, you increase the likelihood that a new public API will be granted.
Другие вопросы
This section includes some answers to other questions that developers have frequently asked:
Общие вопросы
How can Google be sure they can capture the needs of all apps through the issuetracker?
We created the initial lists for Android 9 (API level 28) through static analysis of apps that was supplemented using the following methods:
- manual testing of top Play and non-Play apps
- internal reports
- automatic data collection from internal users
- developer preview reports
- additional static analysis that was designed to conservatively include more false positives
As we evaluate the lists for each new release, we take into account API usage as well as developer feedback through the issue tracker.
How can I enable access to non-SDK interfaces?
You can enable access to non-SDK interfaces on development devices by using adb commands to change the API enforcement policy. The commands that you use vary, depending on the API level. These commands don't require a rooted device.
- Android 10 (API level 29) or higher
To enable access, use the following adb
command:
adb shell settings put global hidden_api_policy 1
To reset the API enforcement policy to the default settings, use the following command:
adb shell settings delete global hidden_api_policy
- Android 9 (API level 28)
To enable access, use the following adb commands:
adb shell settings put global hidden_api_policy_pre_p_apps 1adb shell settings put global hidden_api_policy_p_apps 1To reset the API enforcement policy to the default settings, use the following commands:
adb shell settings delete global hidden_api_policy_pre_p_appsadb shell settings delete global hidden_api_policy_p_apps
You can set the integer in the API enforcement policy to one of the following values:
- 0: Disable all detection of non-SDK interfaces. Using this setting disables all log messages for non-SDK interface usage and prevents you from testing your app using the
StrictModeAPI . This setting is not recommended. - 1: Enable access to all non-SDK interfaces, but print log messages with warnings for any non-SDK interface usage. Using this setting also lets you test your app using the
StrictModeAPI . - 2: Disallow usage of non-SDK interfaces that belong to the blocklist or are conditionally blocked for your target API level .
Questions about non-SDK interface lists
Where can I find the non-SDK API lists in the system image?
They are encoded in the field and method access flag bits in platform dex files. There is no separate file in the system image that contains these lists.
Are the non-SDK API lists the same on different OEM devices with the same Android versions?
OEMs can add their own interfaces to the blocklist (blacklist), but they cannot remove interfaces from the AOSP non-SDK API lists. The CDD prevents such changes and CTS tests ensure that the Android Runtime is enforcing the list.
Questions about the compatibility of related apps
Is there any restriction on non-NDK interfaces in native code?
The Android SDK includes Java interfaces. The platform started restricting access to non-NDK interfaces for native C/C++ code in Android 7 (API level 26). For more information, see Improving Stability with Private C/C++ Symbol Restrictions in Android N .
Is there any plan to restrict dex2oat or DEX file manipulation?
We don't have active plans to restrict access to the dex2oat binary, but we don't intend for the DEX file format to be stable or a public interface beyond the portions that are publicly specified in the Dalvik Executable format . We reserve the right to modify or eliminate dex2oat and the unspecified portions of the DEX format at any time. Also note that derived files produced by dex2oat such as ODEX (also known as OAT), VDEX, and CDEX are all unspecified formats.
What if a crucial third-party SDK (for example, an obfuscator) cannot avoid using non-SDK interfaces, but does commit to maintain compatibility with future Android versions? Can Android waive its compatibility requirements in this case?
We don't have plans to waive compatibility requirements on a per-SDK basis. If an SDK developer can only maintain compatibility by depending on interfaces in the unsupported (formerly grey) lists, they should begin planning a migration to SDK interfaces or other alternatives, and request a new public API whenever they cannot find an alternative to using a non-SDK interface.
Do non-SDK interface restrictions apply to all apps including system and first-party apps, not just third-party apps?
Yes, however, we exempt apps signed with the platform key and some system image apps. Note that these exemptions only apply to apps that are part of the system image (or updated system image apps). The list is intended only for apps that build against the private platform APIs, rather than the SDK APIs (where LOCAL_PRIVATE_PLATFORM_APIS := true ).