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

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

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

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

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

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

إذا لم تكن حالة استخدام في تطبيقك مرتبطة بأيّ من هذه الأنواع، ننصح بشدة بنقل منطقك لاستخدام WorkManager أو مهام نقل البيانات التي يبدأها المستخدم.

فرض إذن BLUETOOTH_CONNECT في BluetoothAdapter

يفرض الإصدار 14 من نظام التشغيل Android إذن BLUETOOTH_CONNECT عند استدعاء الأسلوب BluetoothAdapter getProfileConnectionState() للتطبيقات التي تستهدف Android 14 (المستوى 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 سلوك رد الاتصال والشبكة

تتوقع أداة Jobscheduler منذ إطلاقها أن يعود تطبيقك onStartJob أو onStopJob خلال بضع ثوانٍ. قبل Android 14، إذا كانت المهمة تستغرق وقتًا طويلاً، يتم إيقاف المهمة وتفشل تلقائيًا. إذا كان تطبيقك يستهدف الإصدار 14 من نظام التشغيل Android (المستوى 34 لواجهة برمجة التطبيقات) أو إصدارًا أحدث وتجاوز المدّة الممنوحة في سلسلة المهام الرئيسية، سيُنشئ التطبيق خطأ ANR مع رسالة الخطأ "ما مِن استجابة لـ onStartJob" أو "ما مِن استجابة لـ onStopJob".

قد يكون خطأ ANR هذا نتيجة لأحد السيناريوهَين التاليَين: 1. هناك عمل يحظر سلسلة المحادثات الرئيسية، ما يمنع عمليات معاودة الاتصال onStartJob. أو onStopJob من التنفيذ والإكمال خلال المهلة الزمنية المتوقّعة. 2. ينفِّذ المطوّر عمل حظر ضمن Job Scheduler استدعاء onStartJob أو onStopJob، ما يمنع معاودة الاتصال من لإنجازها خلال الحد الزمني المتوقع.

لمعالجة رقم 1، عليك إجراء المزيد من تصحيح الأخطاء التي تمنع سلسلة التعليمات الرئيسية. عند حدوث خطأ ANR، يمكنك القيام بذلك باستخدام ApplicationExitInfo#getTraceInputStream() للحصول على شاهد القبر وتتبع حدوث خطأ ANR. إذا كان بإمكانك إعادة إنتاج خطأ ANR يدويًا، يمكنك تسجيل تتبُّع للنظام وفحص التتبُّع باستخدام Android Studio أو Perfetto لفهم ما الذي يتم تشغيله في الخيط الرئيسي عند حدوث خطأ ANR بشكل أفضل. يُرجى العِلم أنّ هذا يمكن أن يحدث عند استخدام واجهة برمجة التطبيقات Jobscheduler API مباشرةً. أو استخدام WorkManager لمكتبة androidx.

لمعالجة رقم 2، ننصحك بإجراء عملية النقل إلى WorkManager، التي توفّر توفير إمكانية إكمال أي معالجة في onStartJob أو onStopJob في سلسلة محادثات غير متزامنة.

تفرض JobScheduler أيضًا شرطًا للإفصاح عن الإذن ACCESS_NETWORK_STATE في حال استخدام قيد setRequiredNetworkType أو setRequiredNetwork. إذا لم يفصح تطبيقك عن الحصول على إذن "ACCESS_NETWORK_STATE" عند تحديد موعد المهمة وتحديد الاستهداف الإصدار 14 من نظام التشغيل Android أو الإصدارات الأحدث، سيؤدي إلى حدوث SecurityException.

Tiles launch API

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

الخصوصية

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

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

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

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

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

تأمين إشعارات intent ملء الشاشة

في الإصدار 11 من Android (المستوى 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 (المستوى 34 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، يحظِر Android التطبيقات من إرسال نوايا ضمنية إلى مكوّنات التطبيقات الداخلية بالطُرق التالية:

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

تمنع هذه التغييرات التطبيقات الضارة من اعتراض الأهداف الضمنية المقصود استخدامها من قِبل المكوّنات الداخلية للتطبيق.

على سبيل المثال، في ما يلي فلتر أهداف يمكن تعريفه في ملف بيان تطبيقك:

<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>

إذا حاول تطبيقك تشغيل هذا النشاط باستخدام نية ضمنية، سيتم طرح استثناء ActivityNotFoundException:

Kotlin

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

Java

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

لبدء النشاط الذي لم يتم تصديره، يجب أن يستخدم تطبيقك نية صريحة بدلاً من ذلك:

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);

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

على التطبيقات والخدمات التي تستهدف الإصدار 14 من نظام التشغيل Android (المستوى 34 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث وتستخدم مستقبلات مسجّلة في السياق تحديد علامة للإشارة إلى ما إذا كان يجب تصدير المستقبل إلى جميع التطبيقات الأخرى على الجهاز أم لا: إما RECEIVER_EXPORTED أو RECEIVER_NOT_EXPORTED، على التوالي. يساعد هذا الشرط في حماية التطبيقات من الثغرات الأمنية من خلال الاستفادة من ميزات هذه الأجهزة المستلِمة التي تم تقديمها في Android 13.

استثناء لأجهزة الاستقبال التي تتلقّى عمليات بث النظام فقط

إذا كان تطبيقك يسجِّل جهاز استقبال فقط لتلقّي عمليات بث النظام من خلال Context#registerReceiver طُرق، مثل Context#registerReceiver()، يجب عدم تحديد علامة عند تسجيل جهاز الاستقبال.

تحميل الرموز الديناميكية بشكل أكثر أمانًا

إذا كان تطبيقك يستهدف الإصدار 14 من نظام التشغيل Android (المستوى 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);

التعامل مع الملفات الحالية التي يتم تحميلها ديناميكيًا

لمنع ظهور استثناءات في الملفات الحالية التي يتم تحميلها ديناميكيًا، ننصح بحذف الملفات وإعادة إنشائها قبل محاولة تحميلها مجددًا في تطبيقك ديناميكيًا. وعند إعادة إنشاء الملفات، اتّبِع التوجيهات السابقة لوضع علامة "للقراءة فقط" على الملفات في وقت الكتابة. بدلاً من ذلك، يمكنك إعادة تصنيف الملفات الحالية على أنها للقراءة فقط، ولكن في هذه الحالة، أنصحك بالتحقّق من سلامة الملفات أولاً (على سبيل المثال، من خلال التحقّق من توقيع الملف مقابل قيمة موثوق بها)، للمساعدة في حماية تطبيقك من الإجراءات الضارة.

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

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

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

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

Zip path traversal

بالنسبة إلى التطبيقات التي تستهدف الإصدار 14 من نظام التشغيل Android (المستوى 34 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، يمنع Android ثغرة ملف ZIP Path Traversal بالطريقة التالية: يعرض كل من ZipFile(String) و ZipInputStream.getNextEntry() خطأ ZipException إذا كانت أسماء إدخالات ملفات ZIP تحتوي على ".." أو تبدأ بـ "/".

يمكن للتطبيقات إيقاف عملية التحقّق هذه من خلال الاتصال بالرقم dalvik.system.ZipPathValidator.clearCallback().

بالنسبة إلى التطبيقات التي تستهدف الإصدار 14 من نظام التشغيل Android (المستوى 34 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، يتم طرح SecurityException من قِبل MediaProjection#createVirtualDisplay في أيّ من السيناريوهين التاليين:

يجب أن يطلب تطبيقك من المستخدم تقديم موافقته قبل كل جلسة تسجيل. جلسة تسجيل واحدة هي طلب واحد على MediaProjection#createVirtualDisplay، ويجب استخدام كل مثيل منMediaProjection مرّة واحدة فقط.

التعامل مع تغييرات الإعدادات

إذا كان تطبيقك بحاجة إلى استدعاء MediaProjection#createVirtualDisplay لمعالجة تغييرات الضبط (مثل تغيير اتجاه الشاشة أو حجمها)، يمكنك اتّباع الخطوات التالية لتعديل VirtualDisplay لمثيل MediaProjection الحالي:

  1. استخدِم VirtualDisplay#resize بالعرض والارتفاع الجديدَين.
  2. قدِّم Surface جديدًا بالعرض والارتفاع الجديدَين ل VirtualDisplay#setSurface.

تسجيل طلب معاودة الاتصال

يجب أن يسجِّل تطبيقك طلب استدعاء للتعامل مع الحالات التي لا يمنح فيها المستخدم الموافقة على مواصلة جلسة الالتقاط. لتنفيذ ذلك، عليك تنفيذ Callback#onStop وإصدار تطبيقك مع أي موارد ذات صلة (مثل VirtualDisplay وSurface).

إذا لم يسجِّل تطبيقك هذه الوظيفة المرجعية، يُرسِل MediaProjection#createVirtualDisplay IllegalStateException عند استدعائه من خلال تطبيقك.

تعديل القيود المفروضة على حِزم تطوير البرامج (SDK) غير التابعة لجهات خارجية

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

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

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

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