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

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

نسخه API

با شروع Android 11 (سطح API 30)، دستگاه‌های Android شامل مجموعه‌ای از برنامه‌های افزودنی SDK هستند. هنگامی که API های جدید اضافه می شوند، در سطح API گنجانده می شوند، اما ممکن است در افزونه SDK یک نسخه خاص نیز گنجانده شوند. برای مثال، ACTION_PICK_IMAGES API برای Photo Picker به SDK عمومی در Android 13 (سطح API 33) اضافه شد، اما از طریق برنامه‌های افزودنی SDK که در R Extensions نسخه 2 شروع می‌شوند نیز در دسترس است. نام‌های برنامه افزودنی SDK با یک عدد صحیح - یا یک ثابت مطابقت دارد. از Build.VERSION_CODES ، یا یکی تعریف شده در کلاس SdkExtensions (مانند SdkExtensions.AD_SERVICES ).

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

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

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

به عنوان مثال، ACTION_PICK_IMAGES به طور کلی در SDK عمومی با Android 13 (سطح API 33) در دسترس است، اما تا زمانی که دستگاه حداقل دارای برنامه‌های افزودنی R نسخه 2 باشد، در دستگاه‌هایی از Android 11 (سطح API 30) نیز موجود است. :

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

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

1. با بررسی مستندات ویژگی و مرجع API برای APIهایی که می خواهید استفاده کنید، حداقل نسخه افزونه های مورد نیاز خود را جستجو کنید.
2. پس از تعیین نسخه برنامه افزودنی مورد نیاز برای مجموعه ویژگی های خود، SDK Manager را در Android Studio باز کنید.
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) جستجو کنید، همانطور که در بخش‌های زیر توضیح داده شده است.

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

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

در این مورد، استفاده از بررسی نسخه افزونه می تواند به برنامه شما کمک کند تا عملکردهای بیشتری را به کاربران بیشتری ارائه دهد. نام ها و ثابت های برنامه افزودنی SDK را برای لیستی از تمام ثابت هایی که می توانید برای بررسی برخی برنامه های افزودنی SDK در یک دستگاه استفاده کنید، ببینید.

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

مشابه مجموعه کلی برنامه‌های افزودنی SDK، مرجع AdServices API گاهی اوقات نشان می‌دهد که یک API بخشی از نسخه «افزونه‌های خدمات تبلیغات» است. برخلاف برنامه‌های افزودنی SDK عمومی، برنامه‌های افزودنی Ad Services از ثابت 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 می تواند مشکلات نسخه های SDK Extension را به عنوان بخشی از بررسی NewAPI خود اسکن کند. علاوه بر این، Android Studio می‌تواند بررسی‌های نسخه صحیح را برای APIهایی که با استفاده از افزونه‌های SDK راه‌اندازی می‌شوند، به‌طور خودکار ایجاد کند.

نام ها و ثابت های برنامه افزودنی 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 را نشان می دهد که روی دستگاه به همراه نسخه برنامه افزودنی مربوطه (در این مورد 3) موجود است.