گوگل پلی از ویژگیهای <uses-sdk> که در مانیفست برنامه شما تعریف شده است، برای فیلتر کردن برنامه شما از دستگاههایی که الزامات نسخه پلتفرم آن را برآورده نمیکنند، استفاده میکند. قبل از تنظیم این ویژگیها، مطمئن شوید که فیلترهای گوگل پلی را درک میکنید.
- نحو:
<uses-sdk android:minSdkVersion="integer" android:targetSdkVersion="integer" android:maxSdkVersion="integer" />
- مندرج در:
-
<manifest> - شرح:
به شما امکان میدهد سازگاری یک برنامه را با یک یا چند نسخه از پلتفرم اندروید با استفاده از یک عدد صحیح سطح API بیان کنید. سطح API بیان شده توسط یک برنامه با سطح API یک سیستم اندروید مشخص مقایسه میشود که میتواند در بین دستگاههای مختلف اندروید متفاوت باشد.
علیرغم نامش، این عنصر برای مشخص کردن سطح API استفاده میشود، نه شماره نسخه کیت توسعه نرمافزار (SDK) یا پلتفرم اندروید. سطح API همیشه یک عدد صحیح است. شما نمیتوانید سطح API را از شماره نسخه اندروید مرتبط با آن استخراج کنید. به عنوان مثال، با نسخه اصلی یا مجموع نسخههای اصلی و فرعی یکسان نیست.
نمیتوان مشخص کرد که یک برنامه یا نسخه فرعی SDK را هدف قرار میدهد یا به آن نیاز دارد.
همچنین سند مربوط به نسخهبندی برنامههایتان را مطالعه کنید.
- ویژگیها:
-
android:minSdkVersion - یک عدد صحیح که حداقل سطح API مورد نیاز برای اجرای برنامه را مشخص میکند. اگر سطح API سیستم پایینتر از مقداری باشد که در این ویژگی مشخص شده است، سیستم اندروید از نصب برنامه توسط کاربر جلوگیری میکند. همیشه این ویژگی را تعریف کنید.
احتیاط: اگر این ویژگی را تعریف نکنید، سیستم مقدار پیشفرض "1" را در نظر میگیرد که نشان میدهد برنامه شما با تمام نسخههای اندروید سازگار است. اگر اینطور نباشد و شما
minSdkVersionمناسب را تعریف نکرده باشید، هنگام نصب روی سیستمی با سطح API ناسازگار، برنامه هنگام تلاش برای دسترسی به APIهای غیرقابل دسترس، در زمان اجرا از کار میافتد. به همین دلیل، حتماً سطح API مناسب را در ویژگیminSdkVersionتعریف کنید. -
android:targetSdkVersion - یک عدد صحیح که سطح API مورد نظر برنامه را مشخص میکند. اگر تنظیم نشود، مقدار پیشفرض برابر با مقدار داده شده به
minSdkVersionاست.این ویژگی به سیستم اطلاع میدهد که شما روی نسخه هدف آزمایش انجام دادهاید و سیستم هیچ رفتار سازگاری را برای حفظ سازگاری رو به جلوی برنامه شما با نسخه هدف فعال نمیکند. برنامه همچنان قادر به اجرا روی نسخههای پایینتر (تا
minSdkVersion) است.با تکامل اندروید با هر نسخه جدید، برخی از رفتارها و حتی ظاهرها ممکن است تغییر کنند. با این حال، اگر سطح API پلتفرم بالاتر از نسخه اعلام شده توسط
targetSdkVersionبرنامه شما باشد، سیستم میتواند رفتارهای سازگاری را فعال کند تا برنامه شما به روشی که انتظار دارید به کار خود ادامه دهد. میتوانید با تعیینtargetSdkVersionبرای مطابقت با سطح API پلتفرمی که روی آن اجرا میشود، چنین رفتارهای سازگاری را غیرفعال کنید.برای مثال، تنظیم این مقدار روی "11" یا بالاتر به سیستم اجازه میدهد تا هنگام اجرای برنامه روی اندروید 3.0 یا بالاتر، تم پیشفرض Holo را روی برنامه شما اعمال کند و همچنین هنگام اجرا روی صفحه نمایشهای بزرگتر، حالت سازگاری صفحه نمایش را غیرفعال کند، زیرا پشتیبانی از API سطح 11 به طور ضمنی از صفحه نمایشهای بزرگتر پشتیبانی میکند.
رفتارهای سازگاری زیادی وجود دارد که سیستم میتواند بر اساس مقداری که برای این ویژگی تعیین میکنید، فعال کند. تعدادی از این رفتارها توسط نسخههای پلتفرم مربوطه در مرجع
Build.VERSION_CODESشرح داده شدهاند.برای حفظ برنامه خود همراه با هر نسخه اندروید، مقدار این ویژگی را افزایش دهید تا با آخرین سطح API مطابقت داشته باشد، سپس برنامه خود را روی نسخه پلتفرم مربوطه به طور کامل آزمایش کنید.
معرفی شده در: API سطح ۴
- یک عدد صحیح که حداکثر سطح API را که برنامه برای اجرا روی آن طراحی شده است، مشخص میکند.
در اندروید ۱.۵، ۱.۶، ۲.۰ و ۲.۰.۱، سیستم مقدار این ویژگی را هنگام نصب برنامه و هنگام اعتبارسنجی مجدد برنامه پس از بهروزرسانی سیستم بررسی میکند. در هر دو حالت، اگر ویژگی
maxSdkVersionبرنامه پایینتر از سطح API مورد استفاده خود سیستم باشد، سیستم اجازه نصب برنامه را نمیدهد. در صورت اعتبارسنجی مجدد پس از بهروزرسانی سیستم، این امر عملاً برنامه شما را از دستگاه حذف میکند.برای نشان دادن اینکه چگونه این ویژگی میتواند پس از بهروزرسانیهای سیستم بر برنامه شما تأثیر بگذارد، مثال زیر را در نظر بگیرید:
برنامهای که در مانیفست خود
maxSdkVersion="5"را اعلام میکند، در گوگل پلی منتشر شده است. کاربری که دستگاهش اندروید ۱.۶ (API سطح ۴) را اجرا میکند، برنامه را دانلود و نصب میکند. پس از چند هفته، کاربر یک بهروزرسانی سیستمی به اندروید ۲.۰ (API سطح ۵) را به صورت بیسیم دریافت میکند. پس از نصب بهروزرسانی، سیستمmaxSdkVersionبرنامه را بررسی کرده و با موفقیت آن را دوباره اعتبارسنجی میکند.برنامه به طور عادی کار میکند. با این حال، مدتی بعد، دستگاه بهروزرسانی سیستم دیگری را دریافت میکند، این بار به اندروید ۲.۰.۱ (سطح API ۶). پس از بهروزرسانی، سیستم دیگر نمیتواند برنامه را دوباره اعتبارسنجی کند زیرا سطح API خود سیستم (۶) اکنون بالاتر از حداکثر پشتیبانی شده توسط برنامه (۵) است. سیستم از مشاهده برنامه توسط کاربر جلوگیری میکند و در واقع آن را از دستگاه حذف میکند.
هشدار: ما توصیه نمیکنیم که این ویژگی را تعریف کنید. اولاً، نیازی نیست این ویژگی را به عنوان وسیلهای برای مسدود کردن استقرار برنامه خود بر روی نسخههای جدید پلتفرم اندروید هنگام انتشار آنها تنظیم کنید. از نظر طراحی، نسخههای جدید پلتفرم کاملاً با نسخههای قبلی سازگار هستند. برنامه شما به درستی روی نسخههای جدید کار میکند، مشروط بر اینکه فقط از APIهای استاندارد استفاده کند و از بهترین شیوههای توسعه پیروی کند. ثانیاً، در برخی موارد، تعریف این ویژگی میتواند منجر به حذف برنامه شما از دستگاههای کاربران پس از بهروزرسانی سیستم به سطح API بالاتر شود. اکثر دستگاههایی که احتمالاً برنامه شما روی آنها نصب میشود، بهروزرسانیهای دورهای سیستم را از طریق بیسیم دریافت میکنند، بنابراین قبل از تنظیم این ویژگی، تأثیر آنها را بر برنامه خود در نظر بگیرید.
معرفی شده در: API سطح ۴
برخی از نسخههای اندروید (بعد از اندروید ۲.۰.۱) ویژگیmaxSdkVersionرا در حین نصب یا اعتبارسنجی مجدد بررسی یا اعمال نمیکنند. با این حال، گوگل پلی همچنان از این ویژگی به عنوان یک فیلتر، هنگام ارائه برنامههای موجود برای دانلود به کاربران، استفاده میکند.
-
- معرفی شده در:
- API سطح ۱
سطح API چیست؟
سطح API یک مقدار صحیح است که به طور منحصر به فرد، نسخه API چارچوب ارائه شده توسط یک نسخه از پلتفرم اندروید را مشخص میکند.
پلتفرم اندروید یک API چارچوبی (framework API) ارائه میدهد که برنامهها میتوانند از آن برای تعامل با سیستم اندروید استفاده کنند. API چارچوبی شامل موارد زیر است:
- مجموعهای اصلی از بستهها و کلاسها
- مجموعهای از عناصر و ویژگیهای XML برای اعلان یک فایل مانیفست
- مجموعهای از عناصر و ویژگیهای XML برای اعلان و دسترسی به منابع
- مجموعهای از اهداف
- مجموعهای از مجوزهایی که برنامهها میتوانند درخواست کنند، و همچنین مجوزهای اعمالشده در سیستم
هر نسخه بعدی از پلتفرم اندروید میتواند شامل بهروزرسانیهایی برای API چارچوب برنامه اندروید باشد که ارائه میدهد.
بهروزرسانیهای API چارچوب به گونهای طراحی شدهاند که API جدید با نسخههای قبلی API سازگار باقی بماند. یعنی، اکثر تغییرات در API افزایشی هستند و قابلیتهای جدید یا جایگزینی را معرفی میکنند. با ارتقاء بخشهایی از API، بخشهای قدیمیتر جایگزین شده منسوخ میشوند اما حذف نمیشوند، به طوری که برنامههای موجود هنوز میتوانند از آنها استفاده کنند.
در تعداد بسیار کمی از موارد، بخشهایی از API اصلاح یا حذف میشوند، اگرچه معمولاً چنین تغییراتی فقط برای پشتیبانی از استحکام API و امنیت برنامه یا سیستم مورد نیاز هستند. سایر بخشهای API از نسخههای قبلی بدون تغییر به نسخههای بعدی منتقل میشوند.
API چارچوبی که یک پلتفرم اندروید ارائه میدهد با استفاده از یک شناسه عدد صحیح به نام سطح API مشخص میشود. هر نسخه پلتفرم اندروید دقیقاً از یک سطح API پشتیبانی میکند، اگرچه پشتیبانی برای تمام سطوح API قبلی (تا سطح API 1) ضمنی است. نسخه اولیه پلتفرم اندروید، API سطح 1 را ارائه میداد و نسخههای بعدی سطح API را افزایش دادهاند.
جدول زیر سطح API پشتیبانی شده توسط هر نسخه از پلتفرم اندروید را مشخص میکند. برای اطلاعات مربوط به تعداد نسبی دستگاههایی که هر نسخه را اجرا میکنند، به داشبورد Distribution مراجعه کنید.
کاربردهای سطح API در اندروید
شناسه سطح API نقش کلیدی در تضمین بهترین تجربه ممکن برای کاربران و توسعهدهندگان برنامه ایفا میکند:
- این به پلتفرم اندروید اجازه میدهد تا حداکثر نسخه API چارچوبی که پشتیبانی میکند را توصیف کند.
- این به برنامهها اجازه میدهد تا ویرایش API چارچوب مورد نیاز خود را توصیف کنند.
- این به سیستم اجازه میدهد تا نصب برنامهها را روی دستگاه کاربر انجام دهد تا برنامههای ناسازگار با نسخه نصب نشوند.
هر نسخه از پلتفرم اندروید، شناسه سطح API خود را به صورت داخلی، در خود سیستم اندروید ذخیره میکند.
برنامهها میتوانند از یک عنصر مانیفست ارائه شده توسط API چارچوب - <uses-sdk> - برای توصیف حداقل و حداکثر سطوح API که تحت آن قادر به اجرا هستند و همچنین سطح API ترجیحی که برای پشتیبانی از آن طراحی شدهاند، استفاده کنند. این عنصر سه ویژگی کلیدی ارائه میدهد:
-
android:minSdkVersion: حداقل سطح API که برنامه قادر به اجرا در آن است. مقدار پیشفرض "1" است. -
android:targetSdkVersion: سطح API که برنامه برای اجرا روی آن طراحی شده است. در برخی موارد، این به برنامه اجازه میدهد تا از عناصر یا رفتارهای مانیفست تعریف شده در سطح API هدف استفاده کند، نه اینکه فقط به استفاده از موارد تعریف شده برای حداقل سطح API محدود شود. -
android:maxSdkVersion: حداکثر سطح API که برنامه قادر به اجرای آن است. مهم: قبل از استفاده از این ویژگی، اطلاعات مربوط به آن را در این صفحه مطالعه کنید.
برای مثال، برای مشخص کردن حداقل سطح API سیستم که یک برنامه برای اجرا نیاز دارد، برنامه در مانیفست خود یک عنصر <uses-sdk> با ویژگی android:minSdkVersion قرار میدهد. مقدار android:minSdkVersion عدد صحیحی است که مربوط به سطح API اولین نسخه پلتفرم اندروید است که برنامه میتواند تحت آن اجرا شود.
وقتی کاربر سعی میکند برنامهای را نصب کند، یا وقتی پس از بهروزرسانی سیستم، اعتبارسنجی مجدد برنامه را انجام میدهد، سیستم اندروید ابتدا ویژگیهای <uses-sdk> را در مانیفست برنامه بررسی میکند و مقادیر را با سطح API داخلی خود مقایسه میکند. سیستم فقط در صورتی اجازه نصب را میدهد که این شرایط برآورده شوند:
- اگر ویژگی
android:minSdkVersionتعریف شده باشد، مقدار آن کمتر یا مساوی عدد صحیح سطح API سیستم خواهد بود. اگر تعریف نشده باشد، سیستم فرض میکند که برنامه به API سطح ۱ نیاز دارد. - اگر یک ویژگی
android:maxSdkVersionتعریف شود، مقدار آن برابر یا بزرگتر از عدد صحیح سطح API سیستم است. اگر تعریف نشود، سیستم فرض میکند که برنامه حداکثر سطح API ندارد. برای اطلاعات بیشتر در مورد نحوه مدیریت سیستم، توضیحات این ویژگی را بخوانید.
وقتی در مانیفست یک برنامه اعلام میشود، یک عنصر <uses-sdk> ممکن است به این شکل باشد:
<manifest> <uses-sdk android:minSdkVersion="5" /> ... </manifest>
دلیل اصلی اینکه یک برنامه سطح API را در android:minSdkVersion اعلام میکند، این است که به سیستم اندروید بگوید از APIهایی استفاده میکند که در سطح API مشخص شده معرفی شدهاند.
اگر برنامه به نحوی روی پلتفرمی با سطح API پایینتر نصب شود، در زمان اجرا هنگام تلاش برای دسترسی به APIهایی که وجود ندارند، از کار میافتد. سیستم با اجازه ندادن به نصب برنامه در صورتی که پایینترین سطح API مورد نیاز آن بالاتر از نسخه پلتفرم در دستگاه هدف باشد، از این نتیجه جلوگیری میکند.
ملاحظات توسعه
بخشهای زیر اطلاعات مربوط به سطح API را ارائه میدهند که هنگام توسعه برنامه خود باید در نظر بگیرید.
سازگاری رو به جلوی برنامه
برنامههای اندروید معمولاً با نسخههای جدید پلتفرم اندروید سازگار هستند.
از آنجا که تقریباً همه تغییرات در API چارچوب، افزایشی هستند، یک برنامه اندروید که با استفاده از هر نسخه مشخصی از API، همانطور که توسط سطح API آن مشخص شده است، توسعه داده شده است، با نسخههای بعدی پلتفرم اندروید و سطوح بالاتر API سازگار است. این برنامه میتواند روی تمام نسخههای بعدی پلتفرم اندروید اجرا شود، مگر در موارد خاص که برنامه از بخشی از API استفاده میکند که بعداً به دلایلی حذف میشود.
سازگاری رو به جلو مهم است زیرا بسیاری از دستگاههای اندروید بهروزرسانیهای سیستمی OTA (بیسیم) را دریافت میکنند. کاربر ممکن است برنامه شما را نصب کرده و با موفقیت از آن استفاده کند، سپس بعداً بهروزرسانی OTA را برای نسخه جدیدی از پلتفرم اندروید دریافت کند. پس از نصب بهروزرسانی، برنامه شما در یک نسخه جدید از محیط اجرا میشود، اما نسخهای که هنوز API و قابلیتهای سیستمی مورد نیاز برنامه شما را دارد.
تغییرات زیر API، مانند تغییراتی که در خود سیستم اصلی رخ میدهد، میتواند هنگام اجرای برنامه شما در محیط جدید، بر آن تأثیر بگذارد. برای شما، به عنوان توسعهدهنده برنامه، مهم است که بدانید برنامه در هر محیط سیستم چگونه به نظر میرسد و رفتار میکند.
برای کمک به شما در آزمایش برنامهتان روی نسخههای مختلف پلتفرم اندروید، Android SDK شامل پلتفرمهای متعددی است که میتوانید دانلود کنید. هر پلتفرم شامل یک تصویر سیستم سازگار است که میتوانید آن را در AVD اجرا کنید تا برنامهتان را آزمایش کنید.
سازگاری معکوس برنامه
برنامههای اندروید لزوماً با نسخههای قدیمیتر پلتفرم اندروید که با آنها کامپایل شدهاند، سازگار نیستند.
هر نسخه جدید از پلتفرم اندروید میتواند شامل APIهای چارچوب جدیدی باشد، مانند آنهایی که به برنامهها امکان دسترسی به قابلیتهای جدید پلتفرم را میدهند یا بخشهای API موجود را جایگزین میکنند. APIهای جدید هنگام اجرا روی پلتفرم جدید و همچنین هنگام اجرا روی نسخههای بعدی پلتفرم، طبق سطح API مشخص شده، برای برنامهها قابل دسترسی هستند. اما از آنجا که نسخههای قبلی پلتفرم شامل APIهای جدید نیستند، برنامههایی که از APIهای جدید استفاده میکنند نمیتوانند روی آن پلتفرمها اجرا شوند.
اگرچه بعید است که یک دستگاه مبتنی بر اندروید به نسخه قبلی پلتفرم ارتقا یابد، اما مهم است بدانید که احتمالاً دستگاههای زیادی در این حوزه وجود دارند که نسخههای قبلی این پلتفرم را اجرا میکنند. حتی در بین دستگاههایی که بهروزرسانیهای OTA را دریافت میکنند، برخی ممکن است با تأخیر مواجه شوند و برای مدت زمان قابل توجهی بهروزرسانی دریافت نکنند.
نسخه پلتفرم و سطح API را انتخاب کنید
وقتی در حال توسعه برنامه خود هستید، نسخه پلتفرمی را که برنامه را با آن کامپایل میکنید انتخاب میکنید. به طور کلی، برنامه خود را با کمترین نسخه ممکن از پلتفرمی که برنامه شما میتواند پشتیبانی کند، کامپایل کنید.
شما میتوانید با کامپایل کردن برنامه در برابر اهداف ساخت متوالی پایینتر، پایینترین نسخه پلتفرم ممکن را تعیین کنید. پس از تعیین پایینترین نسخه، یک AVD با استفاده از نسخه پلتفرم و سطح API مربوطه ایجاد کنید و برنامه خود را به طور کامل آزمایش کنید. حتماً ویژگی android:minSdkVersion را در مانیفست برنامه تعریف کنید و مقدار آن را برابر با سطح API نسخه پلتفرم قرار دهید.
حداقل سطح API را اعلام کنید
اگر برنامهای میسازید که از APIها یا ویژگیهای سیستمی معرفیشده در آخرین نسخه پلتفرم استفاده میکند، ویژگی android:minSdkVersion را روی سطح API آخرین نسخه پلتفرم تنظیم کنید. این کار به این دلیل انجام میشود که کاربران فقط در صورتی بتوانند برنامه شما را نصب کنند که دستگاههایشان نسخه سازگار با پلتفرم اندروید را اجرا کند. در عوض، این کار به اطمینان از عملکرد صحیح برنامه شما در دستگاههای آنها کمک میکند.
اگر برنامه شما از APIهای معرفیشده در آخرین نسخه پلتفرم استفاده میکند اما ویژگی android:minSdkVersion را تعریف نکرده باشد، در این صورت روی دستگاههایی که آخرین نسخه پلتفرم را اجرا میکنند به درستی اجرا میشود، اما روی دستگاههایی که نسخههای قبلی پلتفرم را اجرا میکنند، اجرا نمیشود . در حالت دوم، برنامه هنگام تلاش برای استفاده از APIهایی که در نسخههای قبلی وجود ندارند، در زمان اجرا از کار میافتد.
تست در برابر سطوح بالاتر API
پس از کامپایل برنامه، مطمئن شوید که آن را روی پلتفرم مشخص شده در ویژگی android:minSdkVersion برنامه آزمایش میکنید. برای انجام این کار، یک AVD ایجاد کنید که از نسخه پلتفرم مورد نیاز برنامه شما استفاده کند. علاوه بر این، برای بررسی سازگاری رو به جلو، برنامه را روی تمام پلتفرمهایی که از سطح API بالاتری نسبت به سطح مورد استفاده برنامه شما استفاده میکنند، اجرا و آزمایش کنید.
کیت توسعه نرمافزار اندروید (SDK) شامل نسخههای پلتفرمهای مختلفی است که میتوانید از آنها استفاده کنید، از جمله آخرین نسخه، و یک ابزار بهروزرسانی ارائه میدهد که میتوانید در صورت لزوم برای دانلود نسخههای پلتفرمهای دیگر از آن استفاده کنید.
برای دسترسی به بهروزرسانی، از ابزار خط فرمان android که در دایرکتوری <sdk>/tools قرار دارد استفاده کنید. میتوانید بهروزرسانی SDK را با اجرای android sdk اجرا کنید. همچنین میتوانید روی فایل android.bat (ویندوز) یا android (OS X/Linux) دوبار کلیک کنید.
برای اجرای برنامه خود در برابر نسخههای مختلف پلتفرم در شبیهساز، برای هر نسخه پلتفرمی که میخواهید آزمایش کنید، یک AVD ایجاد کنید. برای اطلاعات بیشتر در مورد AVDها، به بخش ایجاد و مدیریت دستگاههای مجازی مراجعه کنید. اگر از یک دستگاه فیزیکی برای آزمایش استفاده میکنید، مطمئن شوید که سطح API پلتفرم اندروید مورد استفاده را میدانید. برای مشاهده فهرست نسخههای پلتفرم و سطوح API آنها، به جدول موجود در این سند مراجعه کنید.
فیلتر کردن مستندات مرجع بر اساس سطح API
صفحات مستندات مرجع پلتفرم اندروید، یک کنترل "سطح API" در قسمت بالا سمت چپ هر صفحه ارائه میدهند. شما میتوانید از این کنترل برای نمایش مستندات فقط برای بخشهایی از API که در واقع برای برنامه شما قابل دسترسی هستند، بر اساس سطح API که در ویژگی android:minSdkVersion فایل مانیفست آن مشخص شده است، استفاده کنید.
برای استفاده از فیلترینگ، سطح API مشخص شده توسط برنامه خود را از منو انتخاب کنید. APIهایی که در سطح API بعدی معرفی میشوند، خاکستری میشوند و محتوای آنها پوشانده میشود، زیرا برای برنامه شما قابل دسترسی نیستند.
فیلتر کردن بر اساس سطح API در مستندات، نمایی از موارد جدید یا معرفیشده در هر سطح API را ارائه نمیدهد. این روش، روشی برای مشاهده کل API مرتبط با یک سطح API مشخص فراهم میکند، در حالی که عناصر API معرفیشده در سطوح API بعدی را حذف میکند.
برای بازگشت به مشاهده مستندات کامل، REL را در بالای منوی سطح API انتخاب کنید. به طور پیشفرض، فیلتر کردن سطح API غیرفعال است، بنابراین میتوانید API کامل چارچوب را صرف نظر از سطح API مشاهده کنید.
مستندات مرجع برای عناصر API منفرد، سطح API که هر عنصر در آن معرفی میشود را مشخص میکند. سطح API برای بستهها و کلاسها با عنوان "اضافه شده در سطح API" در گوشه بالا سمت راست قسمت محتوا در هر صفحه مستندات مشخص شده است. سطح API برای اعضای کلاس در سربرگهای توضیحات مفصل آنها، در حاشیه سمت راست، مشخص شده است.