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

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

ويتحقق التوافق مع الأنظمة القديمة من خلال المكونات التالية:

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

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

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

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

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

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

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

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

توفّر مكتبة برامج "وقت تشغيل SDK" واجهات برمجة تطبيقات مشابهة لواجهات برمجة تطبيقات النظام الأساسي، ولكنّها تتوافق مع حزمتَي تطوير البرامج (SDK) في بيئة "وقت تشغيل SDK" وحِزم تطوير البرامج (SDK) المضمّنة في التطبيق المتنوّع.

لاستخدام مكتبة برامج وقت تشغيل حزمة تطوير البرامج (SDK)، أضِف التبعية 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. يتم استخدام كائنات SDK Binder نفسها لحِزم SDK، ويسمح تسلسل معاملات Binder لمطوّري التطبيقات ببث كائنات SDK حافظة لواجهات SDK Binder على جانب التطبيق.

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

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

توفّر مكتبة موفّر SDKRuntime واجهات برمجة تطبيقات لمطوّري حِزم SDK. تتشابه واجهات برمجة التطبيقات هذه مع واجهات برمجة التطبيقات للنظام الأساسي، ولكنّها تسمح بتحميل حِزم SDK بواسطة بيئة وقت تشغيل SDK ومكتبة عميل SDKRuntime.

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

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

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

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

تصف الأقسام التالية السلوكيات المتوقعة عند تحميل حزمة تطوير البرامج (SDK) من خلال مكتبة عميل SDKRuntime.

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

يتم توفير موارد حزمة تطوير البرامج (SDK) عند تحميل حزمة تطوير البرامج (SDK) في عملية التطبيق. تدمج Bundletool جميع موارد حِزم SDK مع موارد التطبيقات.

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

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

موارد Java

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

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

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

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

لإتاحة مساحة تخزين حزمة SDK، تنشئ مكتبة عميل SDK Runtime دليلاً جذريًا مخصّصًا لكل حزمة 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 المجمَّعة التي تم تحميلها في عملية التطبيق.

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

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

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

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

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

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

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