符合 Google Play 的目标 API 级别要求

您上传的 APK 需要符合 Google Play 的目标 API 级别要求。全新应用和新版应用的目标运行环境必须为 Android 10（API 级别 29）或更高版本；Wear OS 应用除外，此类应用的目标运行环境必须为 API 级别 28 或更高级别。

自 2021 年 8 月起，全新应用需要：

• 使用 Android App Bundle 格式发布。
• 使用 Play Asset Delivery 或 Play Feature Delivery 分发所有下载体积超过 150MB 的资源或功能。对于全新应用，扩展文件 (OBB) 将不再受支持。
• 以 API 级别 30 (Android 11) 或更高级别为目标运行环境，并针对行为变更进行调整；Wear OS 应用除外，此类应用必须继续以 API 级别 28 或更高级别为目标运行环境。

从 2021 年 11 月开始，新版应用必须以 API 级别 30 或更高版本为目标运行环境，并针对 Android 11 中的行为变更进行调整。未收到更新的现有应用不会受到影响，用户可以继续从 Play 商店下载。Wear OS 应用必须继续以 API 级别 28 或更高级别为目标运行环境。

改用 Android App Bundle 发布方式也会影响使用旧版免安装应用 ZIP 格式的免安装体验。自 2021 年 8 月起，如果开发者要发布新的免安装应用或更新现有免安装应用，必须发布支持免安装体验的 App Bundle。

为何要以较新的 SDK 为目标平台？

每个新的 Android 版本都会发生变更，带来安全性和性能方面的重大改进，并提升 Android 的整体用户体验。部分变更只会影响通过 targetSdkVersion 清单属性（也称为目标 API 级别）明确声明支持这些变更的应用。

将您的应用配置为使用新近的 API 级别可确保用户享受这些改进带来的好处，同时您的应用仍然可以在较低版本的 Android 上运行。支持最新的 API 级别还有助于让您的应用利用平台的最新功能，为用户提供愉悦的体验。此外，从 Android 10（API 级别 29）开始，如果应用的目标平台为 Android 5.1（API 级别 22）或更低版本，则用户首次启动应用时会看到警告。

本文重点介绍了有关更新目标 API 级别的重要须知，以便您满足 Google Play 的要求。

注意：如果您的 Gradle 文件包含清单条目，您可以按照配置您的 build 中的说明，确认或更改应用的 Gradle 文件中当前的 targetSdkVersion 值。或者，您也可以按照 <uses-sdk> 清单元素文档中的说明，使用清单文件中的 android:targetSdkVersion 属性。

从 Android 10（API 级别 29）迁移到 Android 11（API 级别 30）

• 隐私权
  • 强制执行分区存储：应用应使用分区存储模式，将应用专有的文件、媒体文件以及其他类型的文件保存到其专属的位置，并通过这些位置访问这些文件。
  • 自动重置权限：如果用户几个月未与应用互动，系统会自动重置应用的敏感权限。此设置不会影响大多数应用。如果您的应用主要在后台运行，无需用户与之互动，您可以考虑请求用户停用自动重置功能。
  • 后台位置信息访问权限：针对前台位置信息获取权限和后台位置信息获取权限，应用必须分开进行请求。用户只能在应用设置中授予后台位置信息获取权限，而不是通过运行时权限对话框授予该权限。
  • 软件包可见性：当应用查询设备上已安装应用和服务的列表时，系统会过滤返回的列表。
    • 如果您使用文字转语音或语音识别服务，则需在清单文件中为这些服务添加 <queries> 元素。
• 安全性
  • 压缩的 resource.arsc 文件不再受支持。
  • 现在需要使用 APK 签名方案 v2。为实现向后兼容性，开发者还应继续使用 APK 签名方案 v1 签名。
  • 限制非 SDK 接口。对于以 API 级别 30 为目标平台的应用，建议不要使用非 SDK 接口，因为其中一些接口现已被屏蔽。如需查看已屏蔽的非 SDK 接口的完整列表，请参阅目前在 Android 11 中被屏蔽的非 SDK 接口。

如需查看 Android 11（API 级别 30）所推出变更的详尽列表，请参阅行为变更页面。

从低于 Android 10（API 级别 29）的版本迁移

请选择您要迁出数据的 Android 版本：

迁移到 Android 5（API 级别 21）

请查看下列每个版本对应的“行为变更”页面，以确保您的应用已将这些版本推出的变更纳入考量：

• Android 5.0（API 级别 21）
• Android 4.4（API 级别 19）。
• Android 4.1.x（API 级别 16）。

如要继续，请按照下一部分中的说明操作。

迁移到 Android 6（API 级别 23）

以下注意事项适用于以 Android 6.0 及更高版本为目标平台的应用：

• 运行时权限

  • 危险权限只能在运行时授予。您的界面操作流程必须提供授予这些权限的手动启示。

  • 确保您的应用尽可能做好准备，以应对权限请求遭拒的情况。例如，如果用户拒绝应用访问设备 GPS 的请求，您的应用应该能够以其他方式继续运行。

如需查看 Android 6.0（API 级别 23）所推出变更的详尽列表，请参阅相应平台版本的行为变更页面。

如要继续，请按照下一部分中的说明操作。

迁移到 Android 7（API 级别 24）

以下注意事项适用于以 Android 7.0 及更高版本为目标平台的应用：

• 低电耗模式和应用待机模式

  按照针对低电耗模式和应用待机模式进行优化一文的说明设计应用行为；这篇文章同时也说明了在多个平台版本中推出的增量变更。

  当设备处于低电耗模式和应用待机模式时，系统的行为如下：

  • 限制网络访问权限
  • 延迟提醒、同步和作业
  • 限制 GPS 和 WLAN 扫描
  • 限制一般优先级的 Firebase Cloud Messaging 消息。

• 权限更改

  • 系统限制访问应用的私有目录。
  • 在您的应用之外显示 file:// URI 会触发 FileUriExposedException。如果您需要将文件共享到自己的应用之外，请实现 FileProvider

• 系统禁止链接到非 NDK 库。

如需查看 Android 7.0（API 级别 24）所推出变更的详尽列表，请参阅相应平台版本的行为变更页面。

如要继续，请按照下一部分中的说明操作。

迁移到 Android 8（API 级别 26）

以下注意事项适用于以 Android 8.0 及更高版本为目标平台的应用：

• 后台执行限制
  • 系统会限制不在前台运行的应用获取服务。
    • 现在，如果应用在 startService() 被禁止时尝试调用它，startService() 会抛出异常。
    • 如需启动前台服务，应用必须使用 startForeground() 和 startForegroundService()。
    • 仔细查看对 JobScheduler API 所做的变更；这些变更记录在 Android 8.0（API 级别 26）“行为变更”页面中。
    • Firebase Cloud Messaging 要求使用 Google Play 服务 SDK 的 10.2.1 版或更高版本。
    • 使用 Firebase Cloud Messaging 时，消息的传递会受到后台执行限制的约束。如果收到消息后需要执行后台工作（如执行后台数据同步），您的应用应通过 Firebase Job Dispatcher 或 JobIntentService 调度作业。如需了解详情，请参阅 Firebase Cloud Messaging 文档。
  • 隐式广播
    • 隐式广播的使用会受到限制。如需了解如何处理后台事件，请参阅 JobScheduler API 的文档。
  • 对于在后台访问位置信息的限制
    • 在后台运行的应用对位置数据的访问权限会受到限制。
      • 在有 Google Play 服务的设备上，请使用一体化位置信息提供程序定期获取位置信息更新。
• 通知渠道
  • 您应该为每个渠道定义通知中断属性。
  • 您必须为渠道分配通知，才会显示通知。
  • 这个平台版本支持 NotificationCompat.Builder。
• 隐私权
  • 为每个应用签名密钥指定 ANDROID_ID。

如需查看 Android 8.0（API 级别 26）所推出变更的详尽列表，请参阅相应平台版本的行为变更页面。

从 Android 8 (API 26) 迁移到 Android 9 (API 28)

• 电源管理
  • 应用待机分桶会根据应用互动度施加新的后台限制，例如延迟作业、警报和高优先级消息配额
  • 省电模式改进增加了对处于应用待机模式的应用的限制
• 前台服务权限
  • 需要请求常规权限 FOREGROUND_SERVICE（不是运行时权限）
• 隐私权相关变更
  • 限制了在后台对传感器的访问权限
  • 限制了对通话记录的访问权限（现在位于 CALL_LOG 权限组中）
  • 限制了对电话号码的访问权限（需要 READ_CALL_LOG 权限）
  • 限制了对 WLAN 信息的访问权限

如需查看 Android 9.0（API 级别 28）所推出变更的详尽列表，请参阅行为变更。

从 Android 9（API 级别 28）迁移到 Android 10（API 级别 29）

• 包含全屏 intent 的通知
  • 需要请求常规权限 USE_FULL_SCREEN_INTENT（不是运行时权限）
• 支持可折叠设备和大屏幕设备
  • 现在，可以有多个 Activity 同时处于“已恢复”状态，但实际只有一个 Activity 拥有焦点。
    • 此更改会影响 onResume() 和 onPause() 的行为。
    • 新增了生命周期概念“在最顶层处于已恢复状态”，可通过订阅 onTopResumedActivityChanged() 进行检测。
      • 只有一个 Activity 可以“在最顶层处于已恢复状态”。
  • 当 resizeableActivity 设为 false 时，应用可以另外指定 minAspectRatio，以便在宽高比较小的屏幕上自动为应用添加黑边。
• 隐私权相关变更
  • 分区存储
    • 外部存储空间访问权限仅限于访问应用专属目录，以及该应用所创建的特定类型的媒体文件。
  • 限制了应用在后台运行时对位置信息的访问权限，需要获得 ACCESS_BACKGROUND_LOCATION 权限后才能访问。
  • 限制了对不可重置的标识符（例如 IMEI 和序列号）的访问权限。
  • 限制了对身体活动信息（例如用户的步数）的访问权限，需要获得 ACTIVITY_RECOGNITION 权限后才能访问。
  • 限制了对某些电话、蓝牙和 WLAN API 的访问权限，需要获得 ACCESS_FINE_LOCATION 权限后才能访问。
  • 限制了对 WLAN 设置的访问权限
    • 应用无法再直接启用或停用 WLAN，需要使用设置面板来进行该设置。
    • 限制了发起 WLAN 网络连接的操作，要求使用 WifiNetworkSpecifier 或 WifiNetworkSuggestion 来建立连接。

按照上一部分中的说明继续更新到 API 30。

翻新您的应用

更新应用的目标 API 级别时，不妨考虑采用最新的平台功能翻新应用，为用户提供愉悦的体验。

• 考虑使用 Beta 版 CameraX 充分发挥相机功能。
• 使用 Jetpack 组件可以帮助您遵循最佳做法、省去编写样板代码的工作并简化复杂任务，以便集中精力编写重要的代码。
• 使用 Kotlin，通过更少的代码更快地编写出更优秀的应用。
• 确保您遵循隐私保护要求和最佳做法。
• 为您的应用添加深色主题支持。
• 为您的应用添加手势导航支持。
• 将您的应用从 Google Cloud Messaging (GCM) 迁移至最新版 Firebase Cloud Messaging。
• 利用高级窗口管理。
  • 支持更大的宽高比（大于 16:9），以便利用硬件方面的最新发展成果。请确保您的应用可调整大小以填充可用的屏幕空间。只在万不得已时声明最大宽高比。如需详细了解最大宽高比，请参阅声明受限屏幕支持。
  • 添加多窗口支持，以帮助应用提高工作效率以及管理多个显示器。
  • 如果出色的最小化应用体验能够提升用户体验，则添加对画中画功能的支持。
  • 针对配备刘海屏的设备进行优化。
  • 请勿假定状态栏高度，而应使用 WindowInsets 和 View.OnApplyWindowInsetsListener。如需了解这样做的原因，请观看此视频。
  • 请勿假定应用会占满整个窗口，而应使用 View.getLocationInWindow() 来确认它的位置，切勿使用 View.getLocationOnScreen()。
  • 处理 MotionEvent 时，请使用 MotionEvent.getX() 和 MotionEvent.getY()（而非 MotionEvent.getRawX() 和 MotionEvent.getRawY()）。

检查及更新您的 SDK 和库

请确保您的第三方 SDK 依赖项支持 API 29：部分 SDK 提供商会在清单中发布这项信息；而对于其他 SDK 提供商，则需要再进行调查。如果您使用的 SDK 不支持 API 29，请与 SDK 提供商合作，优先解决该问题。

另请注意，您的应用或游戏的 targetSdkVersion 可能会限制对私有 Android 平台库的访问；如需了解详情，请参阅 NDK 应用链接至平台库。

您还应确认正在使用的 Android 支持库版本中存在哪些限制。与以往一样，您必须确保 Android 支持库的主要版本与您的应用的 compileSdkVersion 兼容。

我们建议您选择不高于支持库主要版本的 targetSdkVersion。您最好更新至最新的兼容支持库，以便利用最新的兼容性功能和问题修复程序。

测试您的应用

适当更新应用的 API 级别和功能后，您应测试部分核心用例。下面仅列举部分建议，旨在引导您进行测试。我们建议您针对以下方面进行测试：

• 您的应用已编译为 API 29，且没有出现错误或警告。
• 您的应用对用户拒绝权限请求的情况已有应对策略，且会提示用户授予权限。测试方法如下：
  • 转到应用的“应用信息”屏幕，然后停用所有权限。
  • 打开应用，确保不会出现崩溃问题。
  • 执行核心用例测试，并确保系统会再次提示用户授予所需权限。

• 低电耗模式可呈现预期效果，且不会出现错误。
  • 使用 adb，让测试设备在您的应用正在运行时进入低电耗模式。
    • 测试所有会触发 Firebase 云消息传递消息的用例。
    • 测试所有使用闹钟或作业的用例。
    • 消除后台服务的所有依赖项。
  • 将您的应用设为应用待机模式
    • 测试所有会触发 Firebase 云消息传递消息的用例。
    • 测试所有使用闹钟的用例。

• 处理拍摄的新照片/视频
  • 确认您的应用能正确处理受限的 ACTION_NEW_PICTURE 和 ACTION_NEW_VIDEO 广播（即移动至 JobScheduler 作业）。
  • 确保所有依赖于此类事件的重大用例都能正常运行。
• 处理将文件共享给其他应用的操作
  • 测试所有将文件数据共享给任何其他应用（甚至是同一开发者推出的其他应用）的用例
  • 测试内容是否在其他应用中可见而不会触发崩溃。

更多信息

在 Google Play 管理中心内选择接收电子邮件，以便接收我们向您发送的 Android 和 Google Play 重要更新及公告，包括每月的合作伙伴简报。