برنامه های افزودنی SDK

افزونه‌های SDK از اجزای سیستم ماژولار برای اضافه کردن APIها به SDK عمومی برای سطوح API خاصی که قبلاً منتشر شده‌اند، استفاده می‌کنند. این APIها زمانی به دستگاه‌ها ارائه می‌شوند که کاربران نهایی به‌روزرسانی‌های ماژول را از طریق به‌روزرسانی‌های سیستم Google Play دریافت کنند. توسعه‌دهندگان برنامه می‌توانند از این APIها در برنامه‌های خود برای ارائه قابلیت‌های اضافی که در ابتدا در SDK برای این نسخه‌های قبلی اندروید در دسترس نبود، استفاده کنند.

نسخه‌بندی API

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

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

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

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

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

برای استفاده از این API، باید روی یک SDK که حداقل سطح API 33 یا سطح توسعه حداقل 2 دارد، کامپایل کنید.

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

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

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

   گرووی

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }

   کاتلین

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

بررسی کنید که آیا افزونه‌های SDK در دسترس هستند یا خیر

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

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

برنامه شما می‌تواند در زمان اجرا با استفاده از متد getExtensionVersion() بررسی کند که آیا افزونه‌های SDK برای نسخه پلتفرم مشخص در دسترس هستند یا خیر. برای مثال، کد زیر بررسی می‌کند که آیا افزونه SDK نسخه ۲ یا بالاتر برای اندروید ۱۱ (سطح API 30) در دسترس است یا خیر:

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 در برخی از دستگاه‌ها حتی با وجود موجود بودن API افزونه، مقدار false برمی‌گرداند. در نتیجه، بررسی SDK_INT بهینه نیست و بررسی نسخه افزونه، روش بهتری برای بررسی در دسترس بودن API است. همه دستگاه‌هایی که SDK_INT آنها بزرگتر یا مساوی 33 است (اندروید ۱۳ یا بالاتر) APIهای Photo Picker را در SDK عمومی دارند، اما دستگاه‌هایی با SDK_INT کمتر از ۳۳ وجود دارند (مانند اندروید ۱۱، ۱۲ و ۱۲L) که در صورت داشتن نسخه‌های افزونه R حداقل 2 می‌توانند به APIها نیز دسترسی داشته باشند.

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

افزونه‌های خدمات تبلیغاتی

مشابه مجموعه عمومی افزونه‌های SDK، مرجع API مربوط AdServices گاهی اوقات نشان می‌دهد که یک API بخشی از یک نسخه "افزونه‌های خدمات تبلیغاتی" است. برخلاف افزونه‌های SDK عمومی، افزونه‌های خدمات تبلیغاتی از ثابت 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;
}

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

روش‌های کاربردی

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

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

در اندروید استودیو فلامینگو | 2022.2.1 یا بالاتر، ابزار lint می‌تواند به عنوان بخشی از بررسی NewAPI خود، مشکلات مربوط به نسخه‌های SDK Extension را اسکن کند. علاوه بر این، اندروید استودیو می‌تواند به طور خودکار بررسی‌های نسخه صحیح را برای APIهایی که با استفاده از SDK Extensions راه‌اندازی می‌شوند، ایجاد کند.

نام‌ها و ثابت‌های افزونه‌های SDK

جدول زیر نحوه‌ی نگاشت مجموعه‌های مختلف افزونه‌های SDK که در مستندات مرجع API فهرست شده‌اند را به ثابت‌هایی که برنامه‌ی شما می‌تواند برای بررسی در دسترس بودن API در زمان اجرا استفاده کند، شرح می‌دهد. مجموعه‌ی کلی افزونه‌های SDK برای هر SDK عمومی به مقادیر Build.VERSION_CODES نگاشت می‌شود.

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

برای بررسی اینکه کدام افزونه‌های SDK با استفاده از 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

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