行为变更:面向 Android 13 或更高版本的应用

与早期版本一样,Android 13 包含可能影响您应用的行为变更。以下行为变更仅适用于面向 Android 13 或更高版本的应用。如果您的应用面向 Android 13 或更高版本,则应酌情修改您的应用以正确支持这些行为。

务必同时查看影响所有在 Android 13 上运行的应用的行为变更列表。

隐私

通知权限影响前台服务显示

如果用户拒绝通知权限,他们将不会在通知抽屉中看到与前台服务相关的通知。但是,无论是否授予通知权限,用户仍会在任务管理器中看到与前台服务相关的通知。

附近 Wi-Fi 设备的新运行时权限

在 Android 早期版本中,用户需要授予您的应用 ACCESS_FINE_LOCATION 权限才能完成多个常见的 Wi-Fi 用例。

由于用户很难将位置权限与 Wi-Fi 功能相关联,因此 Android 13 (API 级别 33) 在 NEARBY_DEVICES 权限组中引入了运行时权限,适用于管理设备与附近 Wi-Fi 接入点连接的应用。此权限 NEARBY_WIFI_DEVICES 可满足以下 Wi-Fi 用例:

  • 查找或连接附近的设备,例如打印机或媒体投射设备。此工作流程允许您的应用完成此类任务
    • 带外接收 AP 信息,例如通过 BLE。
    • 通过 Wi-Fi Aware 发现并连接设备,并使用仅限本地的热点进行连接。
    • 通过 Wi-Fi Direct 发现并连接设备。
  • 启动与已知 SSID 的连接,例如汽车或智能家居设备。
  • 启动仅限本地的热点。
  • 测距到附近的 Wi-Fi Aware 设备。

只要您的应用不从 Wi-Fi API 获取物理位置信息,当您面向 Android 13 或更高版本并使用 Wi-Fi API 时,请请求 NEARBY_WIFI_DEVICES 而不是 ACCESS_FINE_LOCATION。当您声明 NEARBY_WIFI_DEVICES 权限时,请明确声明您的应用绝不从 Wi-Fi API 获取物理位置信息。为此,请将 android:usesPermissionFlags 属性设置为 neverForLocation。此过程类似于您在 Android 12 (API 级别 31) 及更高版本中声明蓝牙设备信息从不用于位置信息时所做的操作。

详细了解如何请求访问附近 Wi-Fi 设备的权限

精细媒体权限

The 2 buttons for the dialog, from top to bottom, are Allow and Don't
  allow
图 1. 当您请求 READ_MEDIA_AUDIO 权限时用户看到的系统权限对话框。

如果您的应用面向 Android 13 或更高版本,并且需要访问其他应用创建的媒体文件,则必须请求以下一项或多项精细媒体权限,而不是 READ_EXTERNAL_STORAGE 权限:

媒体类型 请求权限
图片和照片 READ_MEDIA_IMAGES
视频 READ_MEDIA_VIDEO
音频文件 READ_MEDIA_AUDIO

在您访问其他应用的媒体文件之前,请验证用户是否已向您的应用授予相应的精细媒体权限。

图 1 显示了一个请求 READ_MEDIA_AUDIO 权限的应用。

如果您同时请求 READ_MEDIA_IMAGES 权限和 READ_MEDIA_VIDEO 权限,则只会出现一个系统权限对话框。

如果您的应用之前已被授予 READ_EXTERNAL_STORAGE 权限,则在升级时,任何请求的 READ_MEDIA_* 权限都将自动授予。您可以使用以下 ADB 命令查看升级后的权限:

adb shell cmd appops get --uid PACKAGE_NAME

在后台使用身体传感器需要新权限

Android 13 引入了身体传感器(例如心率、体温和血氧饱和度)的“使用中”访问概念。此访问模型与系统在 Android 10 (API 级别 29) 中针对位置信息引入的模型非常相似。

如果您的应用面向 Android 13,并且需要在后台运行时访问身体传感器信息,则除了现有的 BODY_SENSORS 权限外,还必须声明新的 BODY_SENSORS_BACKGROUND 权限。

性能和电池

电池资源利用

如果用户在您的应用面向 Android 13 时,将您的应用置于后台电池用量的“受限”状态,系统将不会发送 BOOT_COMPLETED 广播或 LOCKED_BOOT_COMPLETED 广播,直到应用因其他原因启动。

用户体验

PlaybackState 派生的媒体控件

对于面向 Android 13 (API 级别 33) 及更高版本的应用,系统会从 PlaybackState 操作派生媒体控件。这使得系统能够显示一组更丰富的控件,这些控件在手机和平板设备之间技术上保持一致,并且与媒体控件在其他 Android 平台(如 Android Auto 和 Android TV)上的呈现方式保持一致。

图 2 分别显示了在手机和平板设备上的外观示例。

Media controls in terms of how they appear on phone and tablets devices,
            using an example of a sample track showing how the buttons may appear
图 2:手机和平板设备上的媒体控件

在 Android 13 之前,系统按照它们被添加的顺序显示 MediaStyle 通知中的最多五项操作。在紧凑模式下(例如,在折叠的快速设置中),最多显示通过 setShowActionsInCompactView() 指定的三项操作。

从 Android 13 开始,系统会根据 PlaybackState 显示最多五个操作按钮,如以下表格所述。在紧凑模式下,只显示前三个操作槽位。对于不面向 Android 13 的应用或不包含 PlaybackState 的应用,系统将根据添加到 MediaStyle 通知中的 Action 列表显示控件,如上段所述。

槽位 操作 条件
1 播放 PlaybackState 的当前状态是以下之一:
  • STATE_NONE
  • STATE_STOPPED
  • STATE_PAUSED
  • STATE_ERROR
加载旋转器 PlaybackState 的当前状态是以下之一:
  • STATE_CONNECTING
  • STATE_BUFFERING
暂停 PlaybackState 的当前状态不是上述任何一种。
2 上一曲 PlaybackState 操作包括 ACTION_SKIP_TO_PREVIOUS
自定义 PlaybackState 操作不包括 ACTION_SKIP_TO_PREVIOUS,且 PlaybackState 自定义操作包括尚未放置的自定义操作。
PlaybackState 附加数据包含键 SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREVtrue 布尔值。
3 下一曲 PlaybackState 操作包括 ACTION_SKIP_TO_NEXT
自定义 PlaybackState 操作不包括 ACTION_SKIP_TO_NEXT,且 PlaybackState 自定义操作包括尚未放置的自定义操作。
PlaybackState 附加数据包含键 SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXTtrue 布尔值。
4 自定义 PlaybackState 自定义操作包括尚未放置的自定义操作。
5 自定义 PlaybackState 自定义操作包括尚未放置的自定义操作。

自定义操作按照它们被添加到 PlaybackState 的顺序放置。

应用颜色主题自动应用于 WebView 内容

对于面向 Android 13 (API 级别 33) 或更高版本的应用,setForceDark() 方法已弃用,如果调用该方法,将导致无操作。

相反,WebView 现在总是根据应用的 thème 属性 isLightTheme 设置媒体查询 prefers-color-scheme。换句话说,如果 isLightThemetrue 或未指定,则 prefers-color-schemelight;否则,为 dark。这种行为意味着如果 Web 内容支持,其亮色或暗色样式会自动应用以匹配应用的主题。

对于大多数应用,新行为应自动应用相应的应用样式,但是您应该测试您的应用,以检查是否存在您可能手动控制暗模式设置的情况。

如果您仍然需要自定义应用的颜色主题行为,请改用 setAlgorithmicDarkeningAllowed() 方法。为了向后兼容以前的 Android 版本,我们建议在 AndroidX 中使用等效的 setAlgorithmicDarkeningAllowed() 方法。

请参阅该方法的文档,详细了解根据您的应用的 targetSdkVersion 和主题设置,您可以在应用中预期的行为。

连接性

BluetoothAdapter#enable()BluetoothAdapter#disable() 已弃用

对于面向 Android 13 (API 级别 33) 或更高版本的应用,BluetoothAdapter#enable()BluetoothAdapter#disable() 方法已弃用,并且始终返回 false

以下类型的应用不受这些变更影响:

  • 设备所有者应用
  • 资料所有者应用
  • 系统应用

Google Play 服务

广告 ID 所需权限

使用 Google Play 服务广告 ID 并面向 Android 13 (API 级别 33) 及更高版本的应用,必须在其应用的清单文件中声明 AD_ID 普通权限,如下所示:

<manifest ...>
    <!-- Required only if your app targets Android 13 or higher. -->
    <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

    <application ...>
        ...
    </application>
</manifest>

如果您的应用在面向 Android 13 或更高版本时未声明此权限,则广告 ID 会自动移除并替换为零字符串。

如果您的应用使用在库的清单中声明 AD_ID 权限的 SDK,则默认情况下该权限会与您的应用的清单文件合并。在这种情况下,您无需在应用的清单文件中声明该权限。

要了解更多信息,请参阅 Play 管理中心帮助中的广告 ID

更新的非 SDK 限制

Android 13 包含基于与 Android 开发者合作和最新内部测试更新的受限制非 SDK 接口列表。我们尽可能确保在限制非 SDK 接口之前提供公共替代方案。

如果您的应用不面向 Android 13,其中一些变更可能不会立即影响您。但是,虽然您目前可以使用某些非 SDK 接口(取决于您的应用的目标 API 级别),但使用任何非 SDK 方法或字段始终存在应用崩溃的高风险。

如果您不确定您的应用是否使用非 SDK 接口,您可以测试您的应用以找出答案。如果您的应用依赖非 SDK 接口,您应该开始计划迁移到 SDK 替代方案。尽管如此,我们理解某些应用在使用非 SDK 接口方面有合理的用例。如果您无法为应用中的某个功能找到使用非 SDK 接口的替代方案,您应该请求新的公共 API

要详细了解此 Android 版本中的变更,请参阅Android 13 中非 SDK 接口限制的更新。要详细了解非 SDK 接口,请参阅非 SDK 接口限制