افزونه‌های کیت توسعه نرم‌افزار

«افزونه‌های کیت توسعه نرم‌افزار» از مؤلفه‌های سیستم پیمانه‌ای برای افزودن میاناهای برنامه‌سازی کاربردی به کیت توسعه نرم‌افزار عمومی برای برخی‌از سطوح میانای برنامه‌سازی کاربردی که قبلاً منتشر شده‌اند استفاده می‌کنند. این میاناهای برنامه‌سازی کاربردی زمانی به دستگاه‌ها ارائه می‌شوند که کاربران نهایی به‌روزرسانی‌های واحد را ازطریق به‌روزرسانی‌های سیستم Google Play دریافت کنند. توسعه‌دهندگان نرم‌افزار می‌توانند از این میاناهای برنامه‌سازی کاربردی در برنامه‌هایشان استفاده کنند تا عملکرد اضافی‌ای را که در ابتدا در کیت توسعه نرم‌افزار برای این نسخه‌های قبلی Android دردسترس نبود ارائه دهند.

نسخه‌بندی میانای برنامه‌سازی کاربردی

از Android 11 (سطح API‏ ۳۰) به بعد، دستگاه‌های Android شامل مجموعه‌ای از افزونه‌های SDK هستند. وقتی میاناهای برنامه‌سازی کاربردی جدیدی اضافه می‌شود، این میاناهای برنامه‌سازی کاربردی در سطح میانای برنامه‌سازی کاربردی گنجانده می‌شوند، اما ممکن است در افزونه کیت توسعه نرم‌افزار نسخه خاصی نیز گنجانده شوند. برای مثال، ACTION_PICK_IMAGES میانای برنامه‌سازی کاربردی برای «انتخاب‌گر عکس» در Android نسخه ۱۳ (سطح میانای برنامه‌سازی کاربردی ۳۳) به کیت توسعه نرم‌افزار عمومی اضافه شد، اما ازطریق افزونه‌های کیت توسعه نرم‌افزار که از «افزونه‌های R نسخه ۲» شروع می‌شود نیز دردسترس است. نام‌های «افزونه کیت توسعه نرم‌افزار» با یک ثابت عدد صحیح مطابقت دارد–یا ثابتی از Build.VERSION_CODES، یا ثابتی تعریف‌شده در کلاس SdkExtensions (مانند SdkExtensions.AD_SERVICES).

تعیین اینکه از کدام «افزونه‌های کیت توسعه نرم‌افزار» استفاده شود

قبل‌از اینکه بتوانید از SDK Extension API استفاده کنید، ابتدا باید تعیین کنید کدام کیت‌های توسعه نرم‌افزار شامل میاناهای برنامه‌سازی کاربردی‌ای هستند که از موارد استفاده برنامه‌تان پشتیبانی می‌کنند.

صفحه‌های مرجع میانای برنامه‌سازی کاربردی برای میاناهای برنامه‌سازی کاربردی «افزونه کیت توسعه نرم‌افزار» اولین نسخه افزونه کیت توسعه نرم‌افزار را که برنامه‌تان می‌تواند برای دسترسی به میانای برنامه‌سازی کاربردی استفاده کند مشخص می‌کند. اگر در اسناد، نسخه پلاتفرم Android (با ارجاع به سطح میانای برنامه‌سازی کاربردی) نیز مشخص شده باشد، آن میانای برنامه‌سازی کاربردی برای همه دستگاه‌هایی که آن نسخه Android یا بالاتر را اجرا می‌کنند نیز دردسترس است.

برای مثال، ACTION_PICK_IMAGES به‌طور کلی در کیت توسعه نرم‌افزار عمومی از Android 13 (سطح میانای برنامه‌سازی کاربردی ۳۳) دردسترس است، اما در دستگاه‌های قدیمی‌تر تا Android 11 (سطح میانای برنامه‌سازی کاربردی ۳۰) نیز دردسترس است، به‌شرطی که دستگاه حداقل نسخه ۲ افزونه‌های R را داشته باشد:

برای استفاده از این میانای برنامه‌سازی کاربردی، باید دربرابر کیت توسعه نرم‌افزاری که حداقل سطح میانای برنامه‌سازی کاربردی ۳۳ یا سطح افزونه حداقل ۲ دارد کامپایل کنید.

برای استفاده از کیت توسعه نرم‌افزار افزونه، این مراحل را دنبال کنید:

1. با بررسی اسناد ویژگی و مرجع میانای برنامه‌سازی کاربردی برای میاناهای برنامه‌سازی کاربردی‌ای که می‌خواهید استفاده کنید، حداقل نسخه افزونه‌های موردنیازتان را پیدا کنید.
2. پس‌از تعیین نسخه افزونه موردنیاز برای مجموعه ویژگی‌هایتان، «مدیر SDK» را در Android Studio باز کنید.
3. ورودی «پلاتفرم کیت توسعه نرم‌افزار Android» را با نسخه افزونه مربوطه (یا نسخه بالاتر، چون میاناهای برنامه‌سازی کاربردی افزایشی هستند) انتخاب کنید. برای مثال: Android SDK Platform 33،‏ Extension Level 4.

4. این مقادیر را در فایل build.gradle.kts یا build.gradle برنامه‌تان اعلام کنید:

   شیک

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }

   کاتلین

   android {
       compileSdk = 33
       compileSdkExtension = 4
       ...
   }

بررسی کنید آیا «افزونه‌های کیت توسعه نرم‌افزار» دردسترس است یا نه

برنامه شما می‌تواند بررسی کند که کدام نسخه‌های «افزونه کیت توسعه نرم‌افزار» در زمان اجرا دردسترس هستند، و هنگام توسعه می‌توانید نسخه‌های افزونه را بااستفاده از فرمان‌های Android Debug Bridge (adb)‎ جستجو کنید، همان‌طور که در بخش‌های زیر شرح داده شده است.

بررسی در زمان اجرا

برنامه شما می‌تواند در زمان اجرا بااستفاده از روش getExtensionVersion() بررسی کند که آیا «افزونه‌های کیت توسعه نرم‌افزار» برای نسخه پلاتفرم خاصی دردسترس است یا نه. برای مثال، کد زیر بررسی می‌کند که آیا نسخه افزونه ۲ یا بالاتر برای «افزونه کیت توسعه نرم‌افزار» Android 11 (سطح API‏ ۳۰) دردسترس است یا نه:

fun isPhotoPickerAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2
    // Safely use extension APIs that are available with Android 11 (API level 30) Extensions Version 2, such as Photo Picker.
}

public static final boolean isPhotoPickerAvailable() {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2;
}

این کار شبیه به انجام بررسی براساس Build.VERSION.SDK_INT است:

fun isPhotoPickerAvailable(): Boolean {
    return Build.VERSION.SDK_INT >= 33
}

public static final boolean isPhotoPickerAvailable() {
    return Build.VERSION.SDK_INT >= 33;
}

این بررسی SDK_INT همچنان ایمن و معتبر است، اما isPhotoPickerAvailable در برخی‌از دستگاه‌ها مقدار false را برمی‌گرداند، هرچند API افزونه دردسترس است. درنتیجه، بررسی SDK_INT بهینه نیست و بررسی نسخه افزونه روش بهتری برای بررسی دردسترس بودن API است. همه دستگاه‌های دارای SDK_INT بزرگ‌تر از یا مساوی با 33 (Android 13 یا بالاتر) دارای میاناهای برنامه‌سازی کاربردی «انتخاب‌گر عکس» در کیت توسعه نرم‌افزار عمومی هستند، اما دستگاه‌هایی با SDK_INT کمتر از ۳۳ (مانند Android ‏۱۱، ۱۲، و 12L) نیز وجود دارند که اگر نسخه‌های افزونه R حداقل 2 را داشته باشند، می‌توانند به میاناهای برنامه‌سازی کاربردی دسترسی پیدا کنند.

در این مورد، استفاده از بررسی نسخه افزونه می‌تواند به برنامه شما کمک کند تا عملکرد بیشتری را به کاربران بیشتری ارائه دهد. برای مشاهده فهرست همه ثابت‌هایی که می‌توانید برای بررسی «افزونه‌های کیت توسعه نرم‌افزار» خاص در دستگاه استفاده کنید، به نام‌ها و ثابت‌های «افزونه کیت توسعه نرم‌افزار» مراجعه کنید.

افزونه‌های سرویس‌های تبلیغاتی

مشابه مجموعه کلی «افزونه‌های کیت توسعه نرم‌افزار»، AdServices مرجع میانای برنامه‌سازی کاربردی گاهی اوقات نشان می‌دهد که میانای برنامه‌سازی کاربردی بخشی از نسخه «افزونه‌های سرویس‌های آگهی» است. برخلاف «افزونه‌های کیت توسعه نرم‌افزار» عمومی، «افزونه‌های سرویس‌های تبلیغاتی» از ثابت SdkExtensions.AD_SERVICES برای تعیین اینکه کدام نسخه در دستگاه وجود دارد استفاده می‌کنند:

fun isAdServicesAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4
}

public static final boolean isAdServicesAvailable() {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4;
}

برای آشنایی بیشتر با ویژگی‌های «افزونه‌های سرویس‌های تبلیغاتی» و نحوه شروع به کار، به اسناد افزونه‌های سرویس‌های تبلیغاتی مراجعه کنید.

روش‌های سودمند

در برخی موارد، «افزونه‌های کیت توسعه نرم‌افزار» دارای روش‌های سودمند Jetpack برای بررسی دردسترس بودن «میاناهای برنامه‌سازی کاربردی افزونه کیت توسعه نرم‌افزار» هستند. برای مثال، می‌توانید از تابع کتابخانه Jetpack برای بررسی دردسترس بودن PhotoPicker استفاده کنید که بررسی‌های نسخه شرطی را انتزاعی می‌کند.

پشتیبانی ابزارها

در Android Studio Flamingo | نسخه ۲۰۲۲.۲.۱ یا بالاتر، ابزار lint می‌تواند مشکلات مربوط به نسخه‌های «افزونه کیت توسعه نرم‌افزار» را به‌عنوان بخشی از بررسی NewAPI خود اسکن کند. علاوه‌براین، Android Studio می‌تواند بررسی‌های نسخه صحیح را برای میاناهای برنامه‌سازی کاربردی که بااستفاده از «افزونه‌های کیت توسعه نرم‌افزار» راه‌اندازی شده‌اند به‌طور خودکار تولید کند.

نام‌ها و ثابت‌های «افزونه کیت توسعه نرم‌افزار»

جدول زیر شرح می‌دهد که چگونه مجموعه‌های مختلف «افزونه‌های کیت توسعه نرم‌افزار» که در سند مرجع میانای برنامه‌سازی کاربردی فهرست شده‌اند با ثابت‌هایی که برنامه‌تان می‌تواند برای بررسی دردسترس بودن میانای برنامه‌سازی کاربردی در زمان اجرا استفاده کند مطابقت دارند. مجموعه عمومی «افزونه‌های کیت توسعه نرم‌افزار» برای هر کیت توسعه نرم‌افزار عمومی با مقادیر Build.VERSION_CODES مطابقت دارد.

بررسی بااستفاده از adb

برای بررسی اینکه کدام «افزونه‌های کیت توسعه نرم‌افزار» در دستگاهی که از adb استفاده می‌کند دردسترس است، فرمان زیر را اجرا کنید:

adb shell getprop | grep build.version.extensions

پس‌از اجرای فرمان، خروجی‌ای مشابه این خواهید دید:

[build.version.extensions.r]: [3] # Android 11 (API level 30) and higher
[build.version.extensions.s]: [3] # Android 12 (API level 31) and higher
[build.version.extensions.t]: [3] # Android 13 (API level 33) and higher

هر خط یک «افزونه کیت توسعه نرم‌افزار» را که در دستگاه وجود دارد به‌همراه نسخه افزونه مربوطه (در این مورد ۳) نشان می‌دهد.