Google Play：针对非 SDK 接口的限制

小提示：您能找到这篇{Google Play：针对非 SDK 接口的限制}绝对不是偶然，我们能帮您找到潜在客户，解决您的困扰。如果您对本页介绍的Google Play：针对非 SDK 接口的限制内容感兴趣，有相关需求意向欢迎拨打我们的服务热线，或留言咨询，我们将第一时间联系您！

< ">从Android 9（API级别28）开始，Android平台对应用能使用的非SDK接口实施了限制。只要应用引用非SDK接口或尝试使用反射或JNI来获取其句柄，这些限制就适用。这些限制旨在帮助提升用户体验和开发者体验，为用户降低应用发生崩溃的风险，同时为开发者降低紧急发布的风险。

< ">区分SDK接口和非SDK接口

< ">一般而言，公共SDK接口是在Android框架软件包索引中记录的那些接口。非SDK接口的处理是API抽象出来的实现细节，因此这些接口可能会在不另行通知的情况下随时发生更改。

< ">为了避免发生崩溃和意外行为，应用应仅使用SDK中经过正式记录的类。这也意味着当您的应用通过反射等机制与类互动时，不应访问SDK中未列出的方法或字段。

< ">非SDK API名单

< ">随着每个Android版本的发布，会有更多非SDK接口受到限制。我们知道这些限制会影响您的发布工作流，同时我们希望确保您拥有相关工具来检测非SDK接口的使用情况、有机会向我们提供反馈，并且有时间根据相应新政策做出规划和调整。

< ">为最大程度地降低非SDK使用限制对开发工作流的影响，我们将非SDK接口分成了几个名单，这些名单界定了非SDK接口使用限制的严格程度（取决于应用的目标API级别）。下表介绍了这些名单：

< ">尽管您目前仍可以使用某些非SDK接口（取决于应用的目标API级别），但只要您使用任何非SDK方法或字段，终归存在导致应用出问题的显著风险。如果您的应用依赖于非SDK接口，建议您开始计划迁移到SDK接口或其他替代方案。如果您无法为应用中的功能找到无需使用非SDK接口的替代方案，我们建议您请求添加新的公共API。

< ">确定接口属于哪个名单

< ">非SDK接口的名单会构建为Android平台的一部分。如需了解每个Android版本的相关信息，请参阅以下部分。

< ">Android 11

< ">以下文件针对Android 11（API级别30）介绍了所有非SDK接口及其对应的名单：hiddenapi-flags.csv。

< ">如需详细了解Android 11中的非SDK API名单更改，包括针对在Android 11中有条件屏蔽的API建议的公共API替代选项，请参阅Android 11的名单更改。

< ">Android 10

< ">以下文件针对Android 10（API级别29）介绍了所有非SDK接口及其对应的名单：hiddenapi-flags.csv。

< ">如需详细了解Android 10中的非SDK API名单更改，包括针对在Android 10中有条件屏蔽的API建议的公共API替代选项，请参阅Android 10的名单更改。

< ">Android 9

< ">以下文本文件针对Android 9（API级别28）列出了不受限制（已列入灰名单）的非SDK API：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接口时可能会出现的预期行为。

< ">测试您的应用是否使用非SDK接口

< ">您可以通过多种方法来测试您的应用是否使用非SDK接口。

< ">使用可调试的应用进行测试

< ">您可以通过在搭载Android 9（API级别28）或更高版本的设备或模拟器上构建和运行可调试应用来测试该应用是否使用非SDK接口。请确保您使用的设备或模拟器与应用的目标API级别相匹配。

< ">在您的应用上运行测试时，如果该应用访问了某些非SDK接口，系统就会输出一条日志消息。您可以检查应用的日志消息，查找以下详细信息：

< ">声明的类、名称和类型（采用Android运行时所使用的格式）。

< ">访问方式：链接、反射或JNI

< ">所访问的非SDK接口属于哪个名单。

< ">您可以使用adb logcat来查看这些日志消息，这些消息显示在所运行应用的PID下。举例而言，日志中可能包含如下条目：

< ">Accessing hidden field Landroid/os/Message;-&gt;flags:I(light greylist,JNI)

< ">使用StrictMode API进行测试

< ">您还可以利用StrictMode API来测试您的应用是否使用非SDK接口。请使用detectNonSdkApiUsage方法来启用此API。启用StrictMode API后，您可以使用penaltyListener来接收每次使用非SDK接口时触发的回调，并且您可以在其中实现自定义处理。回调中提供的Violation对象派生自Throwable，并且封闭式堆栈轨迹会提供相应使用行为的具体情境。

< ">使用veridex工具进行测试

< ">您还可以在APK上运行静态分析工具veridex。veridex工具会扫描APK的整个代码库（包括所有第三方库），并报告发现的所有使用非SDK接口的行为。

< ">veridex工具存在以下局限性：

< ">它无法检测到通过JNI实现的调用。

< ">它只能检测到一部分舆情指数通过反射实现的调用。

< ">它对非活动代码路径的分析仅限于API级别的检查。

< ">它只能在支持SSE4.2和POPCNT指令的机器上运行。

< ">Windows

< ">虽然不提供本机Windows二进制文件，但您可以使用适用于Linux的Windows子系统(WSL)来执行Linux二进制文件，从而在Windows上运行veridex工具。在执行本节中的步骤之前，请安装WSL，然后选择Ubuntu作为您的Linux发行版本。

< ">安装Ubuntu后，启动Ubuntu终端，然后按以下步骤操作：

< ">1.从Android运行时预建代码库下载veridex工具。

< ">2.解压缩appco帖易网mpat.tar.gz文件的内容。

< ">3.在解压缩的文件夹中，找到veridex-linux.zip文件并将其解压缩。

< ">4.转到解压缩的文件夹，然后运行以下命令，其中your-app.apk是您要测试的APK：

< ">./appcompat.sh--dex-file=your-app.apk

< ">macOS

< ">如需在macOS上运行veridex工具，请按以下步骤操作：

< ">1.从Android运行时预建代码库下载veridex工论坛营销方案具。

< ">2.解压缩appcompat.tar.gz文件的内容。

< ">3.在解压缩的文件夹中，找到veridex-mac.zip文件并将其解压缩。

< ">4.转到解压缩的文件夹，然后运行以下命令，其中/path-from-root/your-app.apk是您要测试的APK的路径，从系统的根目录开始：

< ">./appcompat.sh--dex-file=/path-from-root/your-app.apk

< ">Linux

< ">如需在Linux上运行veridex工具，请按以下步骤操作：

< ">1.从Android运行时预建代码库下载veridex工具。

< ">2.解压缩appcompat.tar.gz文件的内容。

< ">3.在解压缩的文件夹中，找到veridex-linux.zip文件并将其解压缩。

< ">4.转到解压缩的文件夹，然后运行以下命令，其中your-app.apk是您要测试的APK：

< ">./appcompat.sh--dex-file=your-app.apk

< ">使用Android Studio lint工具进行测试

< ">每当您在Android Studio中构建应用时，lint工具都会检查您的代码中是否存在潜在问题。如果您的应用使用非SDK接口，则可能会看到构建错误或警告，具体取决于这些接口所属的名单。

< ">您也可以通过命令行运行lint工具，或者在特定项目、文件夹或文件中手动运行检查。

< ">使用Play管理中心进行测试

< ">当您将应用上传到Play管理中心的测试轨道时，系统会自动测试应用以找出是否存在潜在问题，并生成发布前测试报告。如果您的应用使用非SDK接口，发布前测试报告中会显示错误或警告，具体取决于这些接口所属的名单。

< ">如需了解详细信息，请参阅使用发布前测试报告找出问题中的“Android兼容性”部分。

< ">请求新的公共API

< ">如果您无法为应用中的功能找到无需使用非SDK接口的替代方案，则可以在问题跟踪器中通过创建功能请求来请求新的公共API。

< ">创建功能请求时，请提供以下方面的信息：

< ">您目前使用的是灰名单中的哪些API，包括Accessing hidden...logcat消息中显示的完整描述符。

< ">为什么需要使用这些API，包括与需要使用这些API的高级功能相关的详情，而不仅是关于相应低级功能的详情。

< ">为什么所有相关的公共SDK API都不足以满足您的需要。

< ">您尝试过的其他替代方案，以及这些方案都无效的原因。

< ">如果您在功能请求中提供这些详细信息，我们批准添加新公共API的可能性就会更高。

< ">其他问题

< ">本部分针对开发者经常会提出的其他一些问题给出了解答：

< ">常见问题

< ">Google如何确保通过问题跟踪器捕获所有应用的需求？

< ">我们对应用进行静态分析，并以下面的方法作为补充，从而针对Android 9（API级别28）创建了初始列表：

< ">对热门的Play应用和非Play应用进行手动测试

< ">查看内部报告

< ">自动在内部用户中收集数据

< ">查看开发者预览报告

< ">执行额外的静态分析，以基于谨慎原则包含更多假正例

< ">在我们评估针对每个新版本的列表时，我们会考虑API使用情况以及开发者通过问题跟踪器提供的反馈。

< ">如何允许访问非SDK接口？

< ">您可以使用adb命令来更改API强制执行策略，从而允许在开发设备上访问非SDK接口：您使用的命令因API级别而异。这些命令无需设备取得root权限即可执行。

< ">Android 10（API级别29）

< ">如需允许访问非SDK接口，请使用以下adb命令：

< ">adb shell settings put global hidden_api_policy 1

< ">如需将API强制执行策略重置为默认设置，请使用以下命令：

< ">adb shell settings delete global hidden_api_policy

< ">Android 9（API级别28）

< ">如需允许访问非SDK接口，请使用以下adb命令：

< ">adb shell settings put global hidden_api_policy_pre_p_apps 1

< ">adb shell settings put global hidden_api_policy_p_apps 1

< ">如需将API强制执行策略重置为默认设置，请使用以下命令：

< ">adb shell settings delete global hidden_api_policy_pre_p_apps

< ">adb shell settings delete global hidden_api_policy_p_apps

< ">您可以将API强制执行策略中的整数设置为以下值之一：

< ">0：停用所有非SDK接口检测。如果您使用此设置，系统会停止输出针对非SDK接口使用行为的所有日志消息，并阻止您使用StrictMode API测试应用。建议不要使用此设置。

< ">1：允许访问所有非SDK接口，但同时输出日志消息，并且在其中显示针对所有非SDK接口使用情况的警告。如果使用此设置，您仍可以使用StrictMode API来测试应用。

< ">2：禁止使用列于屏蔽名单中的非SDK接口，或针对您的目标API级别被有条件屏蔽的非SDK接口。

< ">有关非SDK接口名单的问题

< ">在系统映像中的什么位置可以找到非SDK API名单？

< ">它们是在平台dex文件中的字段和方法访问标记位中编码的。系统镜像中没有单独的文件包含这些名单。

< ">搭载同一Android版本的不同OEM设备上的非SDK API名单是否相同？

< ">原始设备制造商(OEM)可以将自己的接口添加到屏蔽名单（黑名单）中，但是无法从AOSP非SDK API名单中移除接口。CDD会阻止此类更改，并且CTS测试会确保Android运行时强制执行相应名单。

< ">有关相关应用兼容性的问题

< ">对原生代码中的非NDK接口是否有任何限制？

< ">Android SDK包含Java接口。Android平台从Android 7（API级别26）开始限制访问原生C/C++代码中的非NDK接口。如需了解详情，请参阅通过在Android N中限制私有C/C++符号提升稳定性。

< ">Google是否计划限制对dex2oat或DEX文件的操作？

< ">我们没有现有计划要限制对dex2oat二进制文件的访问，但并不打算让DEX成为一种固定的文件格式，并且除了在Dalvik可执行文件格式中公开指定的部分之外，我们也不打算让它成为一个公共接口。我们保留随时修改或清除dex2oat和DEX格式的未指定部分的权利。另请注意，由dex2oat生成的派生文件都属于未指定的格式，例如ODEX（也称为OAT）、VDEX和CDEX。

< ">如果某个重要的第三方SDK（例如混淆器）无法避免使用非SDK接口，但确实承诺维持对未来Android版本的兼容性，该怎么办？在这种情况下，Android可以免除其兼容性要求吗？

< ">我们不打算针对单个SDK免除兼容性要求。如果SDK开发者目前只能依赖于灰名单中的接口来维持兼容性，那么他们应该着手计划迁移到SDK接口或其他替代方案；倘若找不到无需使用非SDK接口的替代方案，可请求新的公共API。

< ">针对非SDK接口的限制是否适用于包括系统应用和第一方应用在内的所有应用，而不仅是第三方应用？

< ">是，但我们对使用平台密钥进行签名的应用和某些系统映像应用免除这项限制。请注意，免除限制的情况仅适用于系统映像应用（或更新后的系统映像应用）。软件包白名单仅适用于针对私有平台API（而不是SDK API）构建的应用（其中LOCAL_PRIVATE_PLATFORM_APIS:=true）。