行為變更：指定 Android 17 以上版本的應用程式

和先前版本一樣，Android 17 也包含可能會影響應用程式的行為變更。以下行為變更僅適用於指定 Android 17 以上版本的應用程式。如果應用程式指定 Android 17 以上版本，建議您視情況修改應用程式，以支援這些行為。

此外，無論應用程式的 targetSdkVersion 為何，請務必查看對所有 Android 17 應用程式有影響的行為變更清單。

使用者體驗和系統 UI

Android 17 包含下列異動項目，旨在打造更一致、直覺的使用者體驗。

記憶體限制小工具

从 Android 17 开始，系统会对以 Android 17（API 级别 37）或更高版本为目标平台的应用的 RemoteViews 更新强制执行严格的内存限制。当应用将 RemoteViews 对象传递给 AppWidgetManager.updateAppWidget 时，system_server 会计算载荷中每个方向和大小存储桶中所有图片数据的总内存占用。如果总内存超出系统上限 (mMaxWidgetBitmapMemory)，系统会拒绝更新并抛出 IllegalArgumentException：

java.lang.IllegalArgumentException: RemoteViews for widget update exceeds maximum bitmap memory usage (used: XXXXX, max: YYYYY)

对于以 API 级别 36 或更低级别为目标平台的应用，系统会将此内存违规行为记录为警告 (Slog.w)，而不会抛出异常。

系统如何计算内存上限

系统会将活跃显示配置的 widget 位图内存预算设置为 6 * width * height 字节（1.5 * 4 * width * height，相当于全屏 ARGB_8888 缓冲区大小的 1.5 倍）。在 API 级别 37 及更高级别下，此计算包括以下两项：

  • 存储在 RemoteViews.mBitmapCache 中的内存中 Bitmap 和位图支持的 Icon 对象（Icon.TYPE_BITMAP 和 Icon.TYPE_ADAPTIVE_BITMAP），例如对 setImageViewBitmap、Icon.createWithBitmap、Icon.createWithAdaptiveBitmap 或 Jetpack Glance ImageProvider(bitmap) 的调用。mBitmapCache 中每个唯一的 Bitmap 或位图支持的 Icon 实例在每个 RemoteViews 层次结构中都会被计数一次。
  • URI 支持的图片（Icon.createWithContentUri、setImageViewUri 或 Glance ImageProvider(uri)）不计入 system_server 中的 RemoteViews IPC 字节上限，但 widget 宿主进程会以完整分辨率将引用的 content:// 文件解码到其自己的堆中。在通过 FileProvider URI 公开降采样图片之前，请务必先将其写入 context.cacheDir。

缓解步骤

为了确保在手机、平板电脑和可折叠设备上，微件更新不会超出内存上限，请执行以下操作：

  1. 根据 WindowMetrics 计算运行时内存预算：在 API 级别 30 及更高级别，从 WindowManager.currentWindowMetrics.bounds 而不是 resources.displayMetrics 读取活动窗口边界。在多分辨率设备和可折叠设备上，displayMetrics 可能会报告非活动显示屏尺寸。将总微件图片预算估算为 6L * bounds.width() * bounds.height()，如以下示例所示：

    private const val FALLBACK_MAX_BYTES = 15_000_000L

fun calculateWidgetMemoryCapBytes(context: Context): Long {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
        val wm = context.getSystemService(WindowManager::class.java)
            ?: return FALLBACK_MAX_BYTES
        val bounds = wm.currentWindowMetrics.bounds
        return 6L * bounds.width().toLong() * bounds.height().toLong()
    }
    val dm = context.resources.displayMetrics
    return 6L * dm.widthPixels.toLong() * dm.heightPixels.toLong()
}

  2. 将图片降采样到微件的可查看尺寸，并使用 RGB_565：使用 2 的幂 BitmapFactory.Options.inSampleSize 值（大小为微件的最大显示尺寸 [maxWidthDp x maxHeightDp]）解码位图，并对不透明的照片和缩略图使用 Bitmap.Config.RGB_565（每个像素 2 字节）而不是 ARGB_8888（每个像素 4 字节）。

  3. 在 Jetpack Glance 中，将位图解码提升到 provideContent 之外：使用 SizeMode.Responsive 或 SizeMode.Exact 时，Glance 会针对每个尺寸分桶调用一次 provideContent lambda。在调用 provideContent 之前，在 provideGlance 中对每个共享的 Bitmap 解码一次，以便所有大小存储桶都引用 RemoteViews.mBitmapCache 中的同一 Bitmap 实例。

  4. 替换图片时使用完整的 updateAppWidget 调用：在传统 AppWidgetProvider 实现中，避免调用 AppWidgetManager.partiallyUpdateAppWidget 来交换 Bitmap 或 Icon 视图。部分更新会将新操作合并到 system_server 中的现有 RemoteViews 树中，而不会逐出之前缓存的映像操作。构建完整的 RemoteViews 布局，并改为调用 updateAppWidget。

  5. 提供错误后备布局：在 Jetpack Glance 中，替换 onCompositionError，以便在更新失败时呈现零位图 RemoteViews 后备。

您可以通过运行以下命令，在已连接的设备上检查微件当前的序列化位图内存用量：

adb shell dumpsys appwidget

核心功能

Android 17 包含下列異動項目，這類變更會修改或擴充 Android 系統的各種核心功能。

MessageQueue 的新無鎖定實作

从 Android 17 开始，以 Android 17（API 级别 37）或更高版本为目标平台的应用会收到 android.os.MessageQueue 的全新无锁实现。新实现可提升性能并减少丢帧，但可能会破坏反映 MessageQueue 私有字段和方法的客户端。

如需了解详情（包括缓解措施），请参阅 MessageQueue 行为变更指南。

靜態最終欄位現在無法修改

在 Android 17 或更高版本上运行且以 Android 17（API 级别 37）或更高版本为目标平台的应用无法更改 static final 字段。如果应用尝试使用反射来更改 static final 字段，则会导致 IllegalAccessException。尝试通过 JNI API（例如 SetStaticLongField()）修改其中一个字段会导致应用崩溃。

無障礙設定

Android 17 進行下列變更，提升無障礙功能。

支援複雜輸入法實體鍵盤輸入的無障礙功能

This feature introduces new AccessibilityEvent and TextAttribute APIs to enhance screen reader spoken feedback for CJKV language input. CJKV IME apps can now signal whether a text conversion candidate has been selected during text composition. Apps with edit fields can specify text change types when sending text changed accessibility events. For example, apps can specify that a text change occurred during text composition, or that a text change resulted from a commit. Doing this enables accessibility services such as screen readers to deliver more precise feedback based on the nature of the text modification.

App adoption

  • IME Apps: When setting composing text in edit fields, IMEs can use TextAttribute.Builder.setTextSuggestionSelected() to indicate whether a specific conversion candidate was selected.

  • Apps with Edit Fields: Apps that maintain a custom InputConnection can retrieve candidate selection data by calling TextAttribute.isTextSuggestionSelected(). These apps should then call AccessibilityEvent.setTextChangeTypes() when dispatching TYPE_VIEW_TEXT_CHANGED events. Apps targeting Android 17 (API level 37) that use the standard TextView will have this feature enabled by default. (That is, TextView will handle retrieving data from the IME and setting text change types when sending events to accessibility services).

  • Accessibility Services: Accessibility services that process TYPE_VIEW_TEXT_CHANGED events can call AccessibilityEvent.getTextChangeTypes() to identify the nature of the modification and adjust their feedback strategies accordingly.

隱私權

Android 17 包含下列異動，可提升使用者隱私。

已啟用 ECH (Encrypted Client Hello)

Android 17 introduces platform support for Encrypted Client Hello (ECH), a TLS extension that enhances user privacy by encrypting the Server Name Indication (SNI) in the TLS handshake. This encryption helps prevent network observers from easily identifying the specific domain your app is connecting to.

For apps targeting Android 17 (API level 37) or higher, ECH is used for TLS connections. ECH is active only if the networking library used by the app (for example, HttpEngine, WebView, or OkHttp) has integrated ECH support and the remote server also supports the ECH protocol. If ECH cannot be negotiated, the client sends an ECH extension with randomized contents (a mechanism called ECH GREASE). See RFC 9849 for more details on how ECH GREASE works.

To allow apps to customize this behavior, Android 17 adds a new <domainEncryption> element to the Network Security Configuration file. Developers can use <domainEncryption> within <base-config> or <domain-config> tags to select an ECH mode (for example, "enabled" or "disabled") on a global or per-domain basis.

For more information, see the Encrypted Client Hello documentation.

指定 Android 17 的應用程式需要區域網路權限

Android 17 引入了 ACCESS_LOCAL_NETWORK 运行时权限，以保护用户免遭未经授权的本地网络访问。由于此权限属于现有的 NEARBY_DEVICES 权限组，因此系统不会再次提示已授予其他 NEARBY_DEVICES 权限的用户。这项新要求可防止恶意应用利用不受限制的本地网络访问权限进行隐蔽的用户跟踪和指纹识别。通过声明和请求此权限，您的应用可以发现并连接到局域网 (LAN) 上的设备，例如智能家居设备或投屏接收器。

以 Android 17（API 级别 37）或更高版本为目标平台的应用现在可以通过两种方式与局域网设备保持通信：采用系统介导、可保护隐私的设备选择器来跳过权限提示，或在运行时明确请求这项新权限，以保持本地网络通信。

如需了解详情，请参阅本地网络权限文档。

在實體裝置上隱藏密碼

如果應用程式指定 Android 17 (API 級別 37) 以上版本，且使用者使用實體輸入裝置 (例如外接鍵盤)，Android 作業系統會將新的 show_passwords_physical 設定套用至密碼欄位中的所有字元。根據預設，這項設定會隱藏所有密碼字元。

Android 系統會顯示最後輸入的密碼字元，協助使用者確認是否輸入錯誤。不過，如果使用較大的外接鍵盤，就不太需要這麼做。此外，配備外接鍵盤的裝置通常螢幕較大，因此輸入的密碼更容易被他人看到。

如果使用者正在使用裝置的觸控螢幕，系統會套用新的 show_passwords_touch 設定。

標準簡訊動態密碼防護

Beginning with Android 17, Android is extending its SMS OTP protection to apply to standard SMS messages (SMS messages containing an OTP that do not use the WebOTP or SMS Retriever formats). For most apps targeting Android 17 (API level 37) or higher, these SMS messages do not become available until three hours after receipt. This delay is intended to help prevent OTP hijacking. During this three hour delay, the SMS_RECEIVED_ACTION broadcast is withheld and SMS provider database queries are filtered. The SMS message is available to these apps after the delay.

Certain apps such as the default SMS assistant app, connected device companion apps, etc., are exempted from this delay. All apps that rely on reading SMS messages for OTP extraction should transition to using SMS Retriever or SMS User Consent APIs to ensure continued functionality.

安全性

Android 17 對裝置和應用程式安全性進行了以下改善。

Activity 安全性

在 Android 17 中，平台继续向“默认安全”架构转变，引入了一系列旨在缓解高严重性漏洞利用（例如钓鱼式攻击、互动劫持和混淆代理攻击）的增强功能。此次更新要求开发者明确选择启用新的安全标准，以保持应用兼容性并保护用户。

对开发者产生的主要影响包括：

  • BAL 强化和改进的选择启用：我们正在优化后台 activity 启动 (BAL) 限制，将保护范围扩展到 IntentSender。开发者必须停止使用旧版 MODE_BACKGROUND_ACTIVITY_START_ALLOWED 常量。相反，您应该采用精细控制，例如 MODE_BACKGROUND_ACTIVITY_START_ALLOW_IF_VISIBLE，它会将 activity 启动限制在调用应用可见的场景中，从而显著减少攻击面。
  • 采用工具：开发者应利用严格模式和更新后的 lint 检查来识别旧版模式，并确保为未来的目标 SDK 要求做好准备。

預設啟用 CT

如果应用以 Android 17（API 级别 37）或更高版本为目标平台，则默认启用证书透明度 (CT)。（在 Android 16 中，CT 可用，但应用必须选择启用。）

更安全的原生 DCL - C

如果您的应用以 Android 17（API 级别 37）或更高版本为目标平台，Android 14 中针对 DEX 和 JAR 文件引入的更安全的动态代码加载 (DCL) 保护机制现在也适用于原生库。

使用 System.load() 加载的所有原生文件都必须标记为只读。 否则，系统会抛出 UnsatisfiedLinkError。

我们建议应用尽可能避免动态加载代码，因为这样做会大大增加应用因代码注入或代码篡改而遭到入侵的风险。

限制 CP2 資料檢視中的 PII 欄位

对于以 Android 17（API 级别 37）及更高版本为目标平台的应用，Contacts Provider 2 (CP2) 会限制数据视图中包含个人身份信息 (PII) 的某些列。启用此变更后，系统会从数据视图中移除这些列，以加强用户隐私保护。 受限列包括：

使用 ContactsContract.Data 中这些列的应用可以改为通过与 RAW_CONTACT_ID 联接，从 ContactsContract.RawContacts 中提取这些列。

在 CP2 中強制執行嚴格的 SQL 檢查

对于以 Android 17（API 级别 37）及更高版本为目标平台的应用，如果在没有 READ_CONTACTS 权限的情况下访问 ContactsContract.Data 表，Contacts Provider 2 (CP2) 会强制执行严格的 SQL 查询验证。

做出此项更改后，如果应用没有 READ_CONTACTS 权限，则在查询 ContactsContract.Data 表时会设置 StrictColumns 和 StrictGrammar 选项。如果查询使用的模式与这些模式不兼容，则会被拒绝并导致抛出异常。

情報

Android 17 對系統智慧功能進行了下列變更。

setContentCaptureEnabled 淘汰

部分裝置預設會啟用內容擷取功能，讓裝置端 AI 功能分析畫面內容，提供智慧型體驗。

自 Android 17 起，ContentCaptureManager.setContentCaptureEnabled(boolean) API 方法已淘汰。如果應用程式指定 Android 17 (API 級別 37) 以上版本，呼叫 setContentCaptureEnabled(false) 不會再停用內容擷取功能。

如果應用程式需要繼續停用內容擷取功能，或限制系統擷取螢幕內容，請改用 FLAG_SECURE 視窗版面配置參數。

如要停用內容擷取功能，請在視窗中設定 FLAG_SECURE 標記，如以下範例所示：

Kotlin

window.setFlags(
    WindowManager.LayoutParams.FLAG_SECURE,
    WindowManager.LayoutParams.FLAG_SECURE
)

Java

getWindow().setFlags(
    WindowManager.LayoutParams.FLAG_SECURE,
    WindowManager.LayoutParams.FLAG_SECURE
);

詳情請參閱 WindowManager.LayoutParams.FLAG_SECURE 參考文件。

媒體

Android 17 包含下列媒體行為變更。

背景音訊強化

Beginning with Android 17, the audio framework enforces restrictions on background audio interactions including audio playback, audio focus requests, and volume change APIs to ensure that these changes are started intentionally by the user.

Some audio restrictions apply to all apps. However, the restrictions are more stringent if an app targets Android 17 (API level 37). If one of these apps interacts with audio while it is in the background, it must have a foreground service running. In addition, the app must meet one or both of these requirements:

  • The foreground service must have while-in-use (WIU) capabilities.
  • The app must have the exact alarm permission and be interacting with USAGE_ALARM audio streams.

For more information, including mitigation strategies, see Background audio hardening.

裝置板型規格

Android 17 包含下列異動項目，可改善各種裝置尺寸和板型規格的使用者體驗。

平台 API 異動：在大螢幕 (sw>=600dp) 上忽略螢幕方向、大小調整和顯示比例限制

我們在 Android 16 中變更平台 API，針對指定目標 API 級別 36 以上版本的應用程式，忽略大螢幕 (sw >= 600dp) 的螢幕方向、大小調整和顯示比例限制。開發人員可以選擇不採用 SDK 36 的這些變更，但如果應用程式指定 Android 17 (API 級別 37) 以上版本，就無法再選擇不採用。

詳情請參閱「系統會忽略螢幕方向和大小調整限制」。

連線能力

Android 17 推出下列異動，提升藍牙 RFCOMM 通訊端的一致性，並與標準 Java InputStream 行為保持一致。

RFCOMM 的 BluetoothSocket read() 行為一致

对于以 Android 17（API 级别 37）为目标平台的应用，当套接字关闭或连接断开时，从基于 RFCOMM 的 BluetoothSocket 获取的 InputStream 的 read() 方法现在会返回 -1。

此项变更使 RFCOMM 套接字行为与 LE CoC 套接字保持一致，并与标准 InputStream.read() 文档保持一致，该文档指出，当到达数据流末尾时，会返回 -1。

仅依赖于捕获 IOException 来跳出读取循环的应用可能会受到此变更的影响，应更新 BluetoothSocket 读取循环，以明确检查返回值是否为 -1。这样可确保在远程设备断开连接或套接字关闭时，循环正确终止。如需查看推荐实现的示例，请参阅传输蓝牙数据指南中的代码段。