التغييرات في السلوك: التطبيقات التي تستهدف الإصدار 14 من نظام التشغيل Android أو الإصدارات الأحدث

كما هو الحال في الإصدارات السابقة، يتضمّن Android 14 تغييرات في السلوك قد تؤثّر في تطبيقك. تنطبق التغييرات التالية في السلوك حصريًا على التطبيقات التي تستهدف Android 14 (المستوى 34 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث. إذا كان تطبيقك يستهدف الإصدار 14 من نظام التشغيل Android أو إصدارًا أحدث، عليك تعديل تطبيقك للتوافق مع هذه السلوكيات بشكل صحيح، حيثما ينطبق ذلك.

احرص أيضًا على مراجعة قائمة تغييرات السلوك التي تؤثر على جميع التطبيقات التي تعمل بنظام التشغيل Android 14 بغض النظر عن targetSdkVersion في التطبيق.

الوظيفة الأساسية

يجب تحديد أنواع الخدمات التي تعمل في المقدّمة.

如果您的应用以 Android 14（API 级别 34）或更高版本为目标平台，则必须为应用中的每项前台服务指定至少一个前台服务类型。您应该选择一个能够代表应用用例的前台服务类型。系统需要特定类型的前台服务满足特定用例。

注意：Android 14 针对运行状况和远程消息传递用例引入了前台服务类型。系统还为简短服务、特殊用例和系统豁免保留新的类型。

如果应用中的用例与这些类型均不相关，强烈建议您迁移逻辑以使用 WorkManager 或用户发起的数据传输作业。

تنفيذ إذن BLUETOOTH_CONNECT في محوّل Bluetooth

Android 14 在调用BLUETOOTH_CONNECT BluetoothAdapter 用于应用定位的 getProfileConnectionState() 方法 Android 14（API 级别 34）或更高版本。

此方法已需要 BLUETOOTH_CONNECT 权限，但这不是必需的 强制执行。请确保您的应用在应用的BLUETOOTH_CONNECT AndroidManifest.xml 文件（如以下代码段所示）检查 在调用之前 getProfileConnectionState。

<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

تحديثات OpenJDK 17

Android 14 将继续更新 Android 的核心库，以与最新 OpenJDK LTS 版本中的功能保持一致，包括适合应用和平台开发者的库更新和 Java 17 语言支持。

以下变更可能会影响应用兼容性：

• 对正则表达式的更改：现在，为了更严格地遵循 OpenJDK 的语义，不允许无效的组引用。您可能会看到 java.util.regex.Matcher 类抛出 IllegalArgumentException 的新情况，因此请务必测试应用中使用正则表达式的情形。如需在测试期间启用或停用此变更，请使用兼容性框架工具切换 DISALLOW_INVALID_GROUP_REFERENCE 标志。
• UUID 处理：现在，验证输入参数时，java.util.UUID.fromString() 方法会执行更严格的检查，因此您可能会在反序列化期间看到 IllegalArgumentException。如需在测试期间启用或停用此变更，请使用兼容性框架工具切换 ENABLE_STRICT_VALIDATION 标志。
• ProGuard 问题：有时，在您尝试使用 ProGuard 缩减、混淆和优化应用时，添加 java.lang.ClassValue 类会导致问题。问题源自 Kotlin 库，该库会根据 Class.forName("java.lang.ClassValue") 是否会返回类更改运行时行为。如果您的应用是根据没有 java.lang.ClassValue 类的旧版运行时开发的，则这些优化可能会将 computeValue 方法从派生自 java.lang.ClassValue 的类中移除。

تعزز أداة Jobscheduler سلوك معاودة الاتصال والشبكة

Since its introduction, JobScheduler expects your app to return from onStartJob or onStopJob within a few seconds. Prior to Android 14, if a job runs too long, it stops and fails silently. If your app targets Android 14 (API level 34) or higher and exceeds the granted time on the main thread, the app triggers an ANR with the error message "No response to onStartJob" or "No response to onStopJob". Consider migrating to WorkManager, which provides support for asynchronous processing or migrating any heavy work into a background thread.

JobScheduler also introduces a requirement to declare the ACCESS_NETWORK_STATE permission if using setRequiredNetworkType or setRequiredNetwork constraint. If your app does not declare the ACCESS_NETWORK_STATE permission when scheduling the job and is targeting Android 14 or higher, it will result in a SecurityException.

واجهة برمجة التطبيقات لإطلاق الشاشات

بالنسبة إلى التطبيقات التي تستهدف المستوى 14 والمستويات الأعلى، تم إيقاف TileService#startActivityAndCollapse(Intent) نهائيًا، وأصبح لديه الآن استثناء عند طلبه. إذا كان تطبيقك يشغِّل الأنشطة من المربّعات، استخدِم TileService#startActivityAndCollapse(PendingIntent) بدلاً من ذلك.

الخصوصية

وصول جزئي إلى الصور والفيديوهات

يقدّم Android 14 ميزة "الوصول إلى الصور المحدّدة" التي تسمح للمستخدمين بمنح التطبيقات إمكانية الوصول إلى صور وفيديوهات معيّنة في مكتبتهم، بدلاً من منح الوصول إلى جميع الوسائط من نوع معيّن.

لا يتمّ تفعيل هذا التغيير إلّا إذا كان تطبيقك يستهدف الإصدار Android 14 (المستوى 34 من واجهة برمجة التطبيقات) أو الإصدارات الأحدث. وإذا لم تكن تستخدم "أداة اختيار الصور" حتى الآن، ننصحك بتنفيذها في تطبيقك لتوفير تجربة متّسقة لاختيار الصور والفيديوهات التي تعمل أيضًا على تحسين خصوصية المستخدم بدون الحاجة إلى طلب أي أذونات للتخزين.

إذا كنت تحتفظ بأداة اختيار معرض الصور الخاصة بك باستخدام أذونات مساحة التخزين وكنت بحاجة إلى التحكّم الكامل في عملية التنفيذ، يمكنك تعديل طريقة التنفيذ لاستخدام إذن READ_MEDIA_VISUAL_USER_SELECTED الجديد. إذا كان تطبيقك لا يستخدم الإذن الجديد، سيشغِّل النظام تطبيقك في وضع التوافق.

تجربة المستخدم

إشعارات الأهداف الآمنة بملء الشاشة

في نظام التشغيل Android 11 (المستوى 30 من واجهة برمجة التطبيقات)، يمكن لأي تطبيق استخدام Notification.Builder.setFullScreenIntent لإرسال إشعارات بملء الشاشة أثناء قفل الهاتف. يمكنك منح الإذن تلقائيًا عند تثبيت التطبيق من خلال تقديم بيان عن إذن USE_FULL_SCREEN_INTENT في AndroidManifest.

تم تصميم إشعارات العرض بملء الشاشة للإشعارات ذات الأولوية العالية للغاية والتي تتطلّب اهتمامًا فوريًا من المستخدم، مثل إعدادات المكالمة الهاتفية الواردة أو المنبّه التي يضبطها المستخدم. بالنسبة إلى التطبيقات التي تستهدف Android 14 (المستوى 34 من واجهة برمجة التطبيقات) أو الإصدارات الأحدث، تقتصر التطبيقات المسموح لها باستخدام هذا الإذن على تلك التي توفّر ميزات الاتصال والمنبّهات فقط. يؤدي "متجر Google Play" إلى إبطال أذونات USE_FULL_SCREEN_INTENT التلقائية لأي تطبيقات لا تناسب هذا الملف الشخصي. الموعد النهائي لتطبيق هذه التغييرات على السياسة هو 31 أيار (مايو) 2024.

يظل هذا الإذن مفعَّلاً للتطبيقات المثبّتة على الهاتف قبل تحديث المستخدم إلى الإصدار 14 من نظام التشغيل Android. ويمكن للمستخدمين تفعيل هذا الإذن وإيقافه.

يمكنك استخدام واجهة برمجة التطبيقات الجديدة NotificationManager.canUseFullScreenIntent للتحقّق مما إذا كان تطبيقك حاصل على الإذن. وإذا لم يكن الأمر كذلك، يمكن لتطبيقك استخدام الغرض الجديد ACTION_MANAGE_APP_USE_FULL_SCREEN_INTENT لإطلاق صفحة الإعدادات التي يمكن للمستخدمين من خلالها منح الإذن.

الأمان

القيود المفروضة على الأهداف الضمنية وتلك التي لا تزال في انتظار المراجعة

对于以 Android 14（API 级别 34）或更高版本为目标平台的应用，Android 会限制应用 将隐式 intent 发送到内部应用组件：

• 隐式 intent 只能传送到导出的组件。应用必须使用显式 intent 传送到未导出的组件，或将该组件标记为已导出。
• 如果应用使用 指定组件或软件包，系统会抛出异常。

这些变更可防止恶意应用拦截意在供应用内部组件使用的隐式 intent。

例如，下面是可以在应用的清单文件中声明的 intent 过滤器：

<activity
    android:name=".AppActivity"
    android:exported="false">
    <intent-filter>
        <action android:name="com.example.action.APP_ACTION" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

如果应用尝试使用隐式 intent 启动此 activity，则系统会抛出异常：

Kotlin

// Throws an exception when targeting Android 14.
context.startActivity(Intent("com.example.action.APP_ACTION"))

Java

// Throws an exception when targeting Android 14.
context.startActivity(new Intent("com.example.action.APP_ACTION"));

如需启动非导出的 activity，应用应改用显式 intent：

Kotlin

// This makes the intent explicit.
val explicitIntent =
        Intent("com.example.action.APP_ACTION")
explicitIntent.apply {
    package = context.packageName
}
context.startActivity(explicitIntent)

Java

// This makes the intent explicit.
Intent explicitIntent =
        new Intent("com.example.action.APP_ACTION")
explicitIntent.setPackage(context.getPackageName());
context.startActivity(explicitIntent);

على مستقبلات البث المسجّلة في وقت التشغيل تحديد سلوك التصدير

Apps and services that target Android 14 (API level 34) or higher and use context-registered receivers are required to specify a flag to indicate whether or not the receiver should be exported to all other apps on the device: either RECEIVER_EXPORTED or RECEIVER_NOT_EXPORTED, respectively. This requirement helps protect apps from security vulnerabilities by leveraging the features for these receivers introduced in Android 13.

Exception for receivers that receive only system broadcasts

If your app is registering a receiver only for system broadcasts through Context#registerReceiver methods, such as Context#registerReceiver(), then it shouldn't specify a flag when registering the receiver.

تحميل رمز ديناميكي أكثر أمانًا

如果您的应用以 Android 14（API 级别 34）或更高版本为目标平台并使用动态代码 正在加载 (DCL) 功能，则必须将所有动态加载的文件标记为只读。 否则，系统会抛出异常。我们建议应用应避免 动态加载代码 因为这样做会大大增加 可能会遭到代码注入或代码篡改

如果必须动态加载代码，请使用以下方法，在动态文件（例如 DEX、JAR 或 APK 文件）打开并写入任何内容之前立即将其设为只读：

Kotlin

val jar = File("DYNAMICALLY_LOADED_FILE.jar")
val os = FileOutputStream(jar)
os.use {
    // Set the file to read-only first to prevent race conditions
    jar.setReadOnly()
    // Then write the actual file content
}
val cl = PathClassLoader(jar, parentClassLoader)

Java

File jar = new File("DYNAMICALLY_LOADED_FILE.jar");
try (FileOutputStream os = new FileOutputStream(jar)) {
    // Set the file to read-only first to prevent race conditions
    jar.setReadOnly();
    // Then write the actual file content
} catch (IOException e) { ... }
PathClassLoader cl = new PathClassLoader(jar, parentClassLoader);

处理已存在的动态加载文件

为防止系统对现有动态加载的文件抛出异常，我们建议您先删除并重新创建文件，然后再尝试在应用中重新动态加载这些文件。重新创建文件时，请按照上述指南在写入时将文件标记为只读。或者，您可以将现有文件重新标记为只读，但在这种情况下，我们强烈建议您先验证文件的完整性（例如，对照可信值检查文件的签名）以保护应用免遭恶意操作的影响。

قيود إضافية على بدء الأنشطة من الخلفية

بالنسبة إلى التطبيقات التي تستهدف Android 14 (المستوى 34 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، يقيّد النظام أيضًا الحالات التي يُسمح فيها للتطبيقات ببدء الأنشطة من الخلفية:

• عندما يرسل أحد التطبيقات PendingIntent باستخدام PendingIntent#send() أو طرق مشابهة، يجب أن يوافق التطبيق إذا كان يريد منح امتيازات تشغيل النشاط في الخلفية لبدء الغرض الذي في انتظار المراجعة. لتفعيل هذه الميزة، يجب أن يمرّر التطبيق حزمة ActivityOptions مع setPendingIntentBackgroundActivityStartMode(MODE_BACKGROUND_ACTIVITY_START_ALLOWED).
• عندما يربط تطبيق مرئي خدمة في تطبيق آخر في الخلفية باستخدام طريقة bindService()، يجب أن يفعّل التطبيق المرئي الآن إذا أراد منح امتيازات تشغيل النشاط في الخلفية إلى الخدمة المرتبطة. لتفعيل هذه الميزة، يجب أن يتضمّن التطبيق علامة BIND_ALLOW_ACTIVITY_STARTS عند طلب إجراء bindService().

تؤدّي هذه التغييرات إلى توسيع مجموعة القيود الحالية لحماية المستخدمين من خلال منع التطبيقات الضارة من إساءة استخدام واجهات برمجة التطبيقات لبدء أنشطة مزعجة من الخلفية.

اجتياز مسار Zip

对于以 Android 14（API 级别 34）或更高版本为目标平台的应用，Android 会通过以下方式防止 Zip 路径遍历漏洞：如果 zip 文件条目名称包含“..”或以“/”开头，则 ZipInputStream.getNextEntry() 会抛出 ZipException。ZipFile(String)

应用可以通过调用 dalvik.system.ZipPathValidator.clearCallback() 选择停用此验证。

يجب الحصول على موافقة المستخدم لكل جلسة تسجيل في MediaProjection

For apps targeting Android 14 (API level 34) or higher, a SecurityException is thrown by MediaProjection#createVirtualDisplay in either of the following scenarios:

• Your app caches the Intent that is returned from MediaProjectionManager#createScreenCaptureIntent, and passes it multiple times to MediaProjectionManager#getMediaProjection.
• Your app invokes MediaProjection#createVirtualDisplay multiple times on the same MediaProjection instance.

Your app must ask the user to give consent before each capture session. A single capture session is a single invocation on MediaProjection#createVirtualDisplay, and each MediaProjection instance must be used only once.

Handle configuration changes

If your app needs to invoke MediaProjection#createVirtualDisplay to handle configuration changes (such as the screen orientation or screen size changing), you can follow these steps to update the VirtualDisplay for the existing MediaProjection instance:

1. Invoke VirtualDisplay#resize with the new width and height.
2. Provide a new Surface with the new width and height to VirtualDisplay#setSurface.

Register a callback

Your app should register a callback to handle cases where the user doesn't grant consent to continue a capture session. To do this, implement Callback#onStop and have your app release any related resources (such as the VirtualDisplay and Surface).

If your app doesn't register this callback, MediaProjection#createVirtualDisplay throws an IllegalStateException when your app invokes it.

تم تعديل القيود غير المستندة إلى حزمة تطوير البرامج (SDK).

يتضمّن الإصدار Android 14 قوائم معدَّلة من الواجهات المفروض عليها قيود غير المتوافقة مع حزمة SDK، وذلك استنادًا إلى التعاون مع مطوّري تطبيقات Android وأحدث الاختبارات الداخلية. كلّما أمكن، نحرص على توفُّر بدائل عامة قبل حظر الواجهات التي لا تستخدم حزمة SDK.

إذا كان تطبيقك لا يستهدف الإصدار 14 من نظام التشغيل Android، قد لا تؤثر بعض هذه التغييرات في تطبيقك على الفور. ومع ذلك، على الرغم من أنّه يمكنك حاليًا استخدام بعض الواجهات غير المتوفّرة في حزمة SDK (بناءً على مستوى واجهة برمجة التطبيقات المستهدَف في تطبيقك)، قد يؤدي استخدام أي طريقة أو حقل غير تلك المتوفّرة في حزمة SDK دائمًا إلى تعطُّل تطبيقك.

إذا لم تكن متأكدًا مما إذا كان تطبيقك يستخدم واجهات غير متوفّرة في SDK، يمكنك اختبار تطبيقك لمعرفة ذلك. إذا كان تطبيقك يعتمد على واجهات غير متوفّرة في حزمة SDK، عليك بدء التخطيط للنقل إلى بدائل حزمة SDK. ومع ذلك، ندرك أنّ بعض التطبيقات لديها حالات استخدام صالحة لاستخدام واجهات غير متوفّرة في حزمة SDK. إذا لم تتمكن من العثور على بديل لاستخدام واجهة غير متوفرة في حزمة SDK لميزة في تطبيقك، فعليك طلب واجهة برمجة تطبيقات عامة جديدة.

للحصول على مزيد من المعلومات حول التغييرات في هذا الإصدار من نظام التشغيل Android، يمكنك الاطّلاع على تعديلات على قيود الواجهة غير المستندة إلى حزمة SDK في نظام التشغيل Android 14. للحصول على مزيد من المعلومات حول الواجهات التي لا تستخدم حزمة SDK بشكل عام، يمكنك الاطّلاع على القيود المفروضة على الواجهات غير المتوفرة في حزمة SDK.