التوافق مع الأنظمة القديمة لوقت تشغيل حزمة تطوير البرامج (SDK)

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

يتم تحقيق التوافق مع الإصدارات السابقة من خلال المكوّنات التالية:

  • تنشئ إضافة Android Gradle (AGP) + الأداة Bundletool صيغة تطبيق للأجهزة التي لا تتوافق مع بيئة SDK Runtime من خلال تجميع بيئة SDK Runtime في حزمة APK.

  • تحمّل مكتبة عميل SDK Runtime (androidx.privacysandbox.sdkruntime:sdkruntime-client) حزمة SDK المجمّعة من مواد عرض التطبيق وتحاكي SDK Runtime على الأجهزة التي لا تتوافق معها.

  • توفّر مكتبة موفّر SDK Runtime (androidx.privacysandbox.sdkruntime:sdkruntime-provider) واجهة برمجة تطبيقات لحِزم SDK تتيح التحميل من مكتبة عميل SDK Runtime.

توفير حِزم تطوير البرامج (SDK) باستخدام أداة Bundletool

على الأجهزة المتوافقة مع SDK Runtime، سيتم تقديم حِزم SDK وتثبيتها كحِزم منفصلة.

ولإتاحة إصدارات النظام الأساسي التي لا تتوافق مع SDK Runtime، ستنشئ أداة Bundletool صيغة واحدة أو أكثر من مجموعة حِزم APK للتطبيق تتضمّن جميع حِزم SDK التي يعتمد عليها التطبيق. يتم تجميع كل حزمة تطوير برامج (SDK) كحزمة APK منفصلة. بالإضافة إلى ذلك، يتم إجراء عمليات التحويل التالية:

  1. نسخ ملفات الرمز الثانوي لحزمة تطوير البرامج (SDK) (ملفات DEX) إلى حزمة SDK المقسّمة كمواد عرض
  2. نسخ موارد Java الخاصة بحزمة SDK إلى حزمة SDK المقسّمة كملفات أصول
  3. إعادة ربط موارد حزمة SDK ودمجها مع موارد التطبيق
  4. إنشاء عمليات إعداد لمكتبة برامج SDK Runtime.

تحميل حِزم SDK باستخدام مكتبة برامج عميل "وقت تشغيل حزمة تطوير البرامج (SDK)"

توفّر مكتبة عميل "وقت تشغيل حِزمة تطوير البرامج" واجهات برمجة تطبيقات مشابهة لواجهات برمجة التطبيقات الخاصة بالمنصة، ولكنّها تتوافق مع كلّ من حِزم تطوير البرامج في بيئة "وقت تشغيل حِزمة تطوير البرامج" وحِزم تطوير البرامج المضمّنة في التطبيق المتغير.

لاستخدام مكتبة برامج SDK Runtime، أضِف التبعية androidx.privacysandbox.sdkruntime:sdkruntime-client، واستخدِم SdkSandboxManagerCompat بدلاً من SdkSandboxManager.

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

استخراج حزمة تطوير برامج (SDK) من مواد العرض

عندما يحاول تطبيق تحميل حزمة SDK، تتحقّق مكتبة عميل "وقت تشغيل SDK" مما إذا تم استخراج ملفات DEX الخاصة بحزمة SDK إلى مساحة تخزين الجهاز (code_cache) من قبل، وإذا لم يكن الأمر كذلك، يتم استخراجها من مواد العرض.

ستستخرج المكتبة الملفات عادةً مرة واحدة فقط بعد تثبيت تطبيق أو تحديثه.

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

أداة تحميل الفئات لفئات حزمة تطوير البرامج (SDK)

ولتجنُّب التعارضات بين حِزم SDK وفئات التطبيقات، يتم تحميل جميع فئات حِزم SDK باستخدام أداة تحميل فئات منفصلة ومستقلة تمامًا عن أداة تحميل فئات التطبيق الرئيسية.

في تصميم وقت تشغيل حزمة تطوير البرامج (SDK) الحالي، تتم جميع الاتصالات بين التطبيق وحِزم SDK باستخدام طلبات Binder IPC. يتم استخدام عناصر Binder نفسها لحِزم SDK المجمّعة، ويتيح تسلسل معاملات Binder للمطوّرين تحويل عناصر Binder الخاصة بحِزم SDK إلى واجهات Binder الخاصة بحِزم SDK على جانب التطبيق.

بالنسبة إلى التفاعلات الداخلية الأخرى (مثل إعداد حزمة SDK، وتوفير واجهة برمجة تطبيقات وحدة التحكّم لحزمة SDK، وما إلى ذلك)، تستخدم المكتبة Reflection وDynamic Proxies للعمل على مستوى أدوات تحميل الصفوف المختلفة.

بيئة حزمة تطوير البرامج (SDK)

توفّر مكتبة SDKRuntime Provider واجهات برمجة تطبيقات لمطوّري حِزم SDK. تشبه واجهات برمجة التطبيقات هذه واجهات برمجة التطبيقات الخاصة بالمنصة، ولكنها تسمح بتحميل حِزم تطوير البرامج (SDK) من خلال كلّ من بيئة SDK Runtime ومكتبة SDKRuntime Client.

لاستخدام حزمة SDK للمكتبة، عليك إضافة التبعية androidx.privacysandbox.sdkruntime:sdkruntime-provider وتوسيع SandboxedSdkProviderCompat بدلاً من SandboxedSdkProvider.

عليك أيضًا استخدام SandboxedSdkProviderAdapter كموفِّر حزمة تطوير البرامج (SDK) للسماح بتحميل موفِّر التوافق في بيئة SDK Runtime.

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

بالنسبة إلى حِزم SDK المجمّعة، تعدّل المكتبة بيئة حزمة SDK بطرق تحاكي السلوك المشابه لبيئة "وقت تشغيل SDK".

توضّح الأقسام التالية السلوكيات المتوقّعة عند تحميل حزمة SDK من خلال مكتبة SDKRuntime Client.

مراجع حِزم تطوير البرامج (SDK)

تتوفّر "موارد حزمة تطوير البرامج" (res/) عند تحميل حزمة تطوير البرامج في عملية التطبيق. تدمج أداة Bundletool جميع موارد حِزم تطوير البرامج مع موارد التطبيق.

لتجنُّب حدوث تعارضات، تتم إعادة ربط موارد حزمة SDK من خلال تغيير البادئة packageId في جميع معرّفات الموارد.

عندما يتم تحميل حزمة SDK بواسطة مكتبة SDKRuntime Client، يتم تعديل packageId في وقت التشغيل للسماح بالوصول إلى الموارد التي تمت إعادة ربطها باستخدام الفئة R.

مراجع Java

تتوفّر موارد Java عند تحميل حزمة SDK في عملية التطبيق. تنسخ أداة Bundletool جميع موارد Java الخاصة بحزمة تطوير البرامج (SDK) إلى دليل خاص في مواد عرض التطبيق. تستخدم مكتبة SDKRuntime Client أداة تحميل فئات وسيطة لإعادة توجيه جميع طلبات موارد Java ذات الصلة إلى دليل الجذر الجديد.

أصول حزمة تطوير البرامج (SDK)

يتم دمج مواد عرض حزمة SDK مع مواد عرض التطبيق بدون إعادة الربط.

مساحة تخزين حزمة تطوير البرامج (SDK)

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

يمكن استرداد هذا السياق من SandboxedSdkProviderCompat#getContext.

الطُرق المتوافقة ذات الصلة بمساحة التخزين:

  • getDataDir
  • getCacheDir
  • getCodeCacheDir
  • getNoBackupFilesDir
  • getDir
  • getFilesDir
  • openFileInput
  • openFileOutput
  • deleteFile
  • getFileStreamPath
  • fileList
  • getDatabasePath
  • openOrCreateDatabase
  • ‫moveDatabaseFrom - فقط بين سياقات حزمة تطوير البرامج (SDK)
  • deleteDatabase
  • databaseList
  • getSharedPreferences
  • ‫moveSharedPreferencesFrom - فقط بين سياقات حزمة تطوير البرامج (SDK)
  • deleteSharedPreferences

يمكن إنشاء سياق تخزين محمي على الجهاز من خلال استدعاء createDeviceProtectedStorageContext() في هذا السياق.

SdkSandboxControllerCompat

توفّر مكتبة عميل SDKRuntime عملية تنفيذ SdkSandboxControllerCompat لحِزم تطوير البرامج المجمَّعة التي يتم تحميلها في عملية التطبيق.

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

تحديد الإصدار

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

ننصح بشدة مطوّري التطبيقات وحِزم SDK باستخدام أحدث إصدار من المكتبة، وإلا قد لا تتوفّر الوظائف التي تتطلّب دعمًا في كلا الجزأين.

يمكن لأي إصدار من مكتبة SDKRuntime Client تحميل حزمة تطوير برامج (SDK) بأي إصدار من مكتبة SDKRuntime Provider، والعكس صحيح.

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

سيؤدي ذلك إلى الحدّ من التجزئة والمساعدة في ضمان توفّر معظم واجهات برمجة التطبيقات إذا تم تحميل حِزمة تطوير البرامج (SDK) المجمّعة بنجاح.