Google Play משתמש במאפיינים <uses-sdk>
שמוצהרים במניפסט של האפליקציה כדי לסנן את האפליקציה ממכשירים
שלא עומדים בדרישות של גרסת הפלטפורמה. לפני שמגדירים את המאפיינים האלה, חשוב לוודא שאתם מבינים את המסננים של Google Play.
- תחביר:
<uses-sdk android:minSdkVersion="integer" android:targetSdkVersion="integer" android:maxSdkVersion="integer" />
- נמצא בתוך:
<manifest>- description:
מאפשר להביע את התאימות של אפליקציה לגרסה אחת או יותר של פלטפורמת Android באמצעות מספר של רמת API. רמת ה-API שמצוינת באפליקציה מושווית לרמת ה-API של מערכת Android נתונה, שיכולה להיות שונה במכשירי Android שונים.
למרות השם שלו, הרכיב הזה משמש לציון רמת ה-API, ולא מספר הגרסה של ערכת פיתוח התוכנה (SDK) או פלטפורמת Android. רמת ה-API היא תמיד מספר שלם יחיד. אי אפשר להסיק את רמת ה-API ממספר גרסת Android שמשויך אליה. לדוגמה, הוא לא זהה לגרסה הראשית או לסכום של הגרסה הראשית והגרסה המשנית.
אי אפשר לציין שאפליקציה מיועדת לגרסה משנית של SDK או דורשת אותה.
מומלץ גם לקרוא את המאמר בנושא ניהול גרסאות של אפליקציות.
- מאפיינים:
-
android:minSdkVersion- מספר שלם שמציין את רמת ה-API המינימלית שנדרשת כדי שהאפליקציה תפעל. מערכת Android מונעת מהמשתמש להתקין את האפליקציה אם רמת ה-API של המערכת נמוכה מהערך שצוין במאפיין הזה. חובה להצהיר על המאפיין הזה.
זהירות: אם לא תצהירו על המאפיין הזה, המערכת תניח ערך ברירת מחדל של '1', שמציין שהאפליקציה שלכם תואמת לכל הגרסאות של Android. אם לא הצהרתם על
minSdkVersionהמתאים, האפליקציה תקרוס במהלך ההפעלה כשתנסו לגשת לממשקי ה-API שלא זמינים. לכן, חשוב להצהיר על רמת ה-API המתאימה במאפייןminSdkVersion. android:targetSdkVersion- מספר שלם שמציין את רמת ה-API שהאפליקציה מטרגטת. אם לא מגדירים את הערך, ברירת המחדל
שווה לערך שמוגדר ב-
minSdkVersion.המאפיין הזה מודיע למערכת שביצעתם בדיקות מול גרסת היעד, והמערכת לא מפעילה התנהגויות תאימות כדי לשמור על תאימות קדימה של האפליקציה עם גרסת היעד. האפליקציה עדיין יכולה לפעול בגרסאות ישנות יותר (עד גרסה
minSdkVersion).מערכת Android מתפתחת עם כל גרסה חדשה, ולכן יכול להיות שחלק מההתנהגויות ואפילו המראה ישתנו. עם זאת, אם רמת ה-API של הפלטפורמה גבוהה מהגרסה שמוצהרת ב-
targetSdkVersionשל האפליקציה, המערכת יכולה להפעיל התנהגויות תאימות כדי שהאפליקציה תמשיך לפעול כמו שציפיתם. אפשר להשבית את התנהגויות התאימות האלה על ידי ציוןtargetSdkVersionכדי להתאים לרמת ה-API של הפלטפורמה שבה היא פועלת.לדוגמה, אם מגדירים את הערך הזה ל-11 ומעלה, המערכת מחילה את ערכת הנושא שמוגדרת כברירת מחדל של Holo על האפליקציה כשמריצים אותה ב-Android 3.0 ומעלה, וגם משביתה את מצב התאימות למסך כשמריצים אותה במסכים גדולים יותר, כי תמיכה ברמת API 11 תומכת באופן מרומז במסכים גדולים יותר.
יש הרבה התנהגויות תאימות שהמערכת יכולה להפעיל על סמך הערך שאתם מגדירים במאפיין הזה. חלק מההתנהגויות האלה מתוארות בגרסאות הפלטפורמה המתאימות במאמר בנושא
Build.VERSION_CODES.כדי לתחזק את האפליקציה עם כל גרסת Android, צריך להגדיל את הערך של המאפיין הזה כך שיתאים לרמת ה-API העדכנית ביותר, ואז לבדוק את האפליקציה באופן יסודי בגרסת הפלטפורמה המתאימה.
הוצג ב: רמת API 4
- מספר שלם שמציין את רמת ה-API המקסימלית שהאפליקציה מיועדת לפעול בה.
ב-Android 1.5, 1.6, 2.0 ו-2.0.1, המערכת בודקת את הערך של התכונה הזו כשמתקינים אפליקציה וכשמאמתים מחדש את האפליקציה אחרי עדכון מערכת. בכל מקרה, אם ערך המאפיין
maxSdkVersionשל האפליקציה נמוך מרמת ה-API שבה המערכת עצמה משתמשת, המערכת לא מאפשרת להתקין את האפליקציה. במקרה של אימות מחדש אחרי עדכון מערכת, הפעולה הזו למעשה מסירה את האפליקציה מהמכשיר.כדי להמחיש איך המאפיין הזה יכול להשפיע על האפליקציה אחרי עדכוני מערכת, נסתכל על הדוגמה הבאה:
אפליקציה שמצהירה על
maxSdkVersion="5"במניפסט שלה מתפרסמת ב-Google Play. משתמש שבמכשיר שלו פועלת גרסת Android 1.6 (רמת API 4) מוריד ומתקין את האפליקציה. אחרי כמה שבועות, המשתמש מקבל עדכון מערכת דרך האוויר ל-Android 2.0 (רמת API 5). אחרי התקנת העדכון, המערכת בודקת אתmaxSdkVersionשל האפליקציה ומאמתת אותה מחדש בהצלחה.האפליקציה פועלת כרגיל. אבל כעבור זמן מה, המכשיר מקבל עדכון מערכת נוסף, הפעם ל-Android 2.0.1 (API ברמה 6). אחרי העדכון, המערכת לא יכולה יותר לאמת מחדש את האפליקציה כי רמת ה-API של המערכת (6) גבוהה יותר מהרמה המקסימלית שהאפליקציה תומכת בה (5). המערכת מונעת מהמשתמש לראות את האפליקציה, ובפועל מסירה אותה מהמכשיר.
אזהרה: לא מומלץ להשתמש במאפיין הזה. קודם כל, אין צורך להגדיר את המאפיין כאמצעי לחסימת הפריסה של האפליקציה בגרסאות חדשות של פלטפורמת Android כשהן יוצאות. כברירת מחדל, גרסאות חדשות של הפלטפורמה תואמות לאחור באופן מלא. האפליקציה שלכם פועלת בצורה תקינה בגרסאות חדשות, בתנאי שהיא משתמשת רק בממשקי API רגילים ועומדת בשיטות המומלצות לפיתוח. שנית, במקרים מסוימים, הצהרה על המאפיין עלולה לגרום להסרת האפליקציה מהמכשירים של המשתמשים אחרי עדכון מערכת לרמת API גבוהה יותר. ברוב המכשירים שבהם סביר שהאפליקציה שלכם תותקן, מתקבלים עדכוני מערכת תקופתיים דרך האוויר, לכן כדאי לשקול את ההשפעה שלהם על האפליקציה לפני שמגדירים את המאפיין הזה.
הוצג ב: רמת API 4
בגרסאות מסוימות של Android (מעבר ל-Android 2.0.1) לא מתבצעת בדיקה או אכיפה של מאפייןmaxSdkVersionבמהלך ההתקנה או האימות מחדש. מערכת Google Play ממשיכה להשתמש במאפיין הזה כמסנן, אבל לא כשהיא מציגה למשתמשים אפליקציות שזמינות להורדה.
- הוצג ב:
- API level 1
מהי רמת API?
רמת ה-API היא ערך מספרי שמזהה באופן ייחודי את עדכון ה-API של מסגרת הפיתוח שמוצע על ידי גרסה של פלטפורמת Android.
פלטפורמת Android מספקת API של framework שאפליקציות יכולות להשתמש בו כדי ליצור אינטראקציה עם מערכת Android הבסיסית. ממשק ה-API של ה-framework מורכב מהרכיבים הבאים:
- קבוצה מרכזית של חבילות וכיתות
- קבוצה של רכיבי XML ומאפיינים להצהרה על קובץ מניפסט
- קבוצה של רכיבי XML ומאפיינים להצהרה על משאבים ולגישה אליהם
- קבוצה של כוונות
- קבוצת הרשאות שאפליקציות יכולות לבקש, וגם אכיפת הרשאות שכלולה במערכת
כל גרסה עוקבת של פלטפורמת Android יכולה לכלול עדכונים ל-API של מסגרת האפליקציות של Android שהיא מספקת.
העדכונים ב-API של המסגרת מתוכננים כך שה-API החדש יישאר תואם לגרסאות קודמות של ה-API. כלומר, רוב השינויים בממשק ה-API הם תוספתיים ומציגים פונקציונליות חדשה או חלופית. כשמשדרגים חלקים מה-API, החלקים הישנים שהוחלפו מוצאים משימוש אבל לא מוסרים, כדי שאפליקציות קיימות עדיין יוכלו להשתמש בהם.
במספר קטן מאוד של מקרים, חלקים מממשק ה-API משתנים או מוסרים, אבל בדרך כלל השינויים האלה נדרשים רק כדי לתמוך ביציבות של ממשק ה-API ובאבטחה של האפליקציה או המערכת. כל שאר חלקי ה-API מגרסאות קודמות מועברים לגרסה החדשה ללא שינוי.
ממשק ה-API של המסגרת שפלטפורמת Android מספקת מצוין באמצעות מזהה מספרי שנקרא רמת API. כל גרסה של פלטפורמת Android תומכת בדיוק ברמת API אחת, למרות שהתמיכה היא מרומזת לכל רמות ה-API הקודמות (עד רמת API 1). הגרסה הראשונה של פלטפורמת Android סיפקה רמת API 1, ובגרסאות הבאות רמת ה-API עלתה.
בטבלה הבאה מפורטת רמת ה-API שנתמכת בכל גרסה של פלטפורמת Android. מידע על המספרים היחסיים של המכשירים שבהם פועלת כל גרסה זמין בלוח הבקרה 'הפצה'.
שימושים ברמת ה-API ב-Android
מזהה רמת ה-API ממלא תפקיד חשוב בהבטחת חוויה מיטבית למשתמשים ולמפתחי אפליקציות:
- הוא מאפשר לפלטפורמת Android לתאר את הגרסה המקסימלית של framework API שהיא תומכת בה.
- הוא מאפשר לאפליקציות לתאר את הגרסה של ה-API של המסגרת שנדרשת להן.
- היא מאפשרת למערכת לנהל את ההתקנה של אפליקציות במכשיר של המשתמש, כך שאפליקציות עם גרסאות לא תואמות לא יותקנו.
כל גרסה של פלטפורמת Android מאחסנת את מזהה רמת ה-API שלה באופן פנימי, במערכת Android עצמה.
אפליקציות יכולות להשתמש ברכיב מניפסט שסופק על ידי ה-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 של הגרסה הכי מוקדמת של פלטפורמת Android
שבה האפליקציה יכולה לפעול.
כשמשתמש מנסה להתקין אפליקציה, או כשמבצעים אימות מחדש של אפליקציה אחרי עדכון מערכת, מערכת Android בודקת קודם את המאפיינים <uses-sdk> במניפסט של האפליקציה ומשווה את הערכים לרמת ה-API הפנימית שלה. המערכת תאפשר להתחיל בהתקנה רק אם התנאים הבאים יתקיימו:
- אם מוצהר מאפיין
android:minSdkVersion, הערך שלו קטן ממספר השלם של רמת ה-API של המערכת או שווה לו. אם לא מצהירים על רמת ה-API, המערכת מניחה שהאפליקציה דורשת רמת API 1. - אם מוצהר מאפיין
android:maxSdkVersion, הערך שלו שווה למספר השלם של רמת ה-API של המערכת או גדול ממנו. אם לא מצהירים על רמת ה-API המקסימלית, המערכת מניחה שלאפליקציה אין רמת API מקסימלית. מידע נוסף על אופן הטיפול של המערכת במאפיין הזה זמין בתיאור המאפיין.
כשמצהירים על רכיב <uses-sdk> במניפסט של אפליקציה, הוא עשוי להיראות כך:
<manifest> <uses-sdk android:minSdkVersion="5" /> ... </manifest>
הסיבה העיקרית לכך שאפליקציה מצהירה על רמת API ב-android:minSdkVersion היא להודיע למערכת Android שהיא משתמשת בממשקי API שהוצגו ברמת ה-API שצוינה.
אם האפליקציה מותקנת איכשהו בפלטפורמה עם רמת API נמוכה יותר, היא קורסת בזמן הריצה כשהיא מנסה לגשת לממשקי API שלא קיימים. המערכת מונעת את התוצאה הזו בכך שהיא לא מאפשרת להתקין את האפליקציה אם רמת ה-API הנמוכה ביותר שהיא דורשת גבוהה יותר מרמת ה-API של גרסת הפלטפורמה במכשיר היעד.
שיקולי פיתוח
בקטעים הבאים מפורט מידע שקשור לרמת ה-API, שחשוב לקחת בחשבון כשמפתחים את האפליקציה.
תאימות קדימה של אפליקציות
אפליקציות ל-Android בדרך כלל תואמות לגרסאות חדשות של פלטפורמת Android.
מכיוון שרוב השינויים ב-API של המסגרת הם תוספתיים, אפליקציית Android שפותחה באמצעות גרסה מסוימת של ה-API, כפי שמצוין ברמת ה-API שלה, תואמת לגרסאות מאוחרות יותר של פלטפורמת Android ולרמות API גבוהות יותר. האפליקציה יכולה לפעול בכל הגרסאות המאוחרות יותר של פלטפורמת Android, למעט במקרים מבודדים שבהם האפליקציה משתמשת בחלק מממשק ה-API שהוסר מאוחר יותר מסיבה כלשהי.
תאימות קדימה חשובה כי מכשירים רבים עם Android מקבלים עדכוני מערכת אלחוטיים (OTA). יכול להיות שהמשתמש יתקין את האפליקציה שלכם וישתמש בה בהצלחה, ואז יקבל עדכון OTA לגרסה חדשה של פלטפורמת Android. אחרי שהעדכון מותקן, האפליקציה פועלת בגרסה חדשה של זמן הריצה של הסביבה, אבל עדיין יש לה את ה-API ואת יכולות המערכת שהאפליקציה תלויה בהם.
שינויים מתחת ל-API, כמו שינויים במערכת הבסיסית עצמה, יכולים להשפיע על האפליקציה כשמריצים אותה בסביבה החדשה. חשוב לכם, כמפתחי האפליקציה, להבין איך האפליקציה נראית ואיך היא מתנהגת בכל סביבת מערכת.
כדי לעזור לכם לבדוק את האפליקציה בגרסאות שונות של פלטפורמת Android, Android SDK כולל פלטפורמות שונות שאפשר להוריד. כל פלטפורמה כוללת תמונת מערכת תואמת שאפשר להפעיל ב-AVD כדי לבדוק את האפליקציה.
תאימות לאחור של אפליקציות
אפליקציות ל-Android לא בהכרח תואמות לאחור לגרסאות של פלטפורמת Android שקודמות לגרסה שבה הן עברו קומפילציה.
כל גרסה חדשה של פלטפורמת Android יכולה לכלול ממשקי API חדשים של מסגרות, כמו אלה שנותנים לאפליקציות גישה ליכולות חדשות של הפלטפורמה או מחליפים חלקים קיימים של API. אפשר לגשת לממשקי ה-API החדשים מאפליקציות שפועלות בפלטפורמה החדשה, וגם מאפליקציות שפועלות בגרסאות מאוחרות יותר של הפלטפורמה, בהתאם לרמת ה-API. אבל מכיוון שגרסאות קודמות של הפלטפורמה לא כוללות את ממשקי ה-API החדשים, אפליקציות שמשתמשות בממשקי ה-API החדשים לא יכולות לפעול בפלטפורמות האלה.
למרות שלא סביר שמכשיר עם Android יחזור לגרסה קודמת של הפלטפורמה, חשוב להבין שסביר להניח שיש הרבה מכשירים בשטח שפועלות בהם גרסאות קודמות של הפלטפורמה. גם בין מכשירים שמקבלים עדכונים דרך האוויר, יכול להיות שחלק מהם יקבלו את העדכון באיחור, או שלא יקבלו אותו במשך תקופה ארוכה.
בחירת גרסת פלטפורמה ורמת API
כשמפתחים אפליקציה, בוחרים את גרסת הפלטפורמה שבה האפליקציה עוברת קומפילציה. באופן כללי, כדאי לקמפל את האפליקציה שלכם בהתאם לגרסה הכי נמוכה של הפלטפורמה שהאפליקציה יכולה לתמוך בה.
כדי לקבוע את הגרסה הכי נמוכה שאפשר להשתמש בה בפלטפורמה, צריך לקמפל את האפליקציה מול יעדי בנייה נמוכים יותר. אחרי שקובעים את הגרסה הכי נמוכה, יוצרים AVD באמצעות גרסת הפלטפורמה ורמת ה-API המתאימות, ובודקים את האפליקציה באופן מלא. חשוב להצהיר על מאפיין android:minSdkVersion במניפסט של האפליקציה ולהגדיר את הערך שלו לרמת ה-API של גרסת הפלטפורמה.
הצהרה על רמת API מינימלית
אם אתם מפתחים אפליקציה שמשתמשת בממשקי API או בתכונות מערכת שהוצגו בגרסה האחרונה של הפלטפורמה, צריך להגדיר את המאפיין android:minSdkVersion לרמת ה-API של הגרסה האחרונה של הפלטפורמה. הסיבה לכך היא שמשתמשים יוכלו להתקין את האפליקציה שלכם רק אם במכשירים שלהם פועלת גרסה תואמת של פלטפורמת Android. כך אפשר לוודא שהאפליקציה שלכם תפעל בצורה תקינה במכשירים שלהם.
אם האפליקציה שלכם משתמשת בממשקי API שהוצגו בגרסה האחרונה של הפלטפורמה, אבל לא מצהירה על מאפיין android:minSdkVersion, היא תפעל בצורה תקינה במכשירים שמותקנת בהם הגרסה האחרונה של הפלטפורמה, אבל לא במכשירים שמותקנות בהם גרסאות קודמות של הפלטפורמה. במקרה השני, האפליקציה קורסת בזמן הריצה כשהיא מנסה להשתמש בממשקי API שלא קיימים בגרסאות הקודמות.
בדיקה מול רמות API גבוהות יותר
אחרי שמקמפלים את האפליקציה, חשוב לבדוק אותה בפלטפורמה שצוינה במאפיין android:minSdkVersion של האפליקציה. כדי לעשות זאת, יוצרים מכשיר וירטואלי של Android (AVD) שמשתמש בגרסת הפלטפורמה שנדרשת על ידי האפליקציה. בנוסף, כדי לבדוק תאימות קדימה, מריצים את האפליקציה ובודקים אותה בכל הפלטפורמות שמשתמשות ברמת API גבוהה יותר מזו שבה משתמשת האפליקציה שלכם.
ערכת Android SDK כוללת כמה גרסאות של הפלטפורמה שאפשר להשתמש בהן, כולל הגרסה העדכנית ביותר, ומספקת כלי עדכון שבעזרתו אפשר להוריד גרסאות אחרות של הפלטפורמה לפי הצורך.
כדי לגשת לכלי העדכון, משתמשים בכלי שורת הפקודה android שנמצא בספרייה <sdk>/tools. כדי להפעיל את הכלי לעדכון ה-SDK, מריצים את הפקודה android sdk. אפשר גם ללחוץ לחיצה כפולה על הקובץ android.bat (Windows) או android (OS X/Linux).
כדי להריץ את האפליקציה שלכם מול גרסאות שונות של פלטפורמות באמולטור, צריך ליצור מכשיר וירטואלי של Android (AVD) לכל גרסת פלטפורמה שרוצים לבדוק. מידע נוסף על מכשירי AVD זמין במאמר יצירה וניהול של מכשירים וירטואליים. אם אתם משתמשים במכשיר פיזי לבדיקה, חשוב לדעת את רמת ה-API של פלטפורמת Android שפועלת בו. בטבלה במסמך הזה מפורטות גרסאות הפלטפורמה ורמות ה-API שלהן.
סינון מאמרי העזרה לפי רמת ה-API
בדפי העיון בפלטפורמת Android יש אמצעי בקרה של 'רמת API' בפינה הימנית העליונה של כל דף. אפשר להשתמש באמצעי הבקרה כדי להציג תיעוד רק לחלקים ב-API שאליהם יש לאפליקציה גישה בפועל, על סמך רמת ה-API שצוינה במאפיין android:minSdkVersion בקובץ המניפסט שלה.
כדי להשתמש בסינון, בוחרים בתפריט את רמת ה-API שצוינה באפליקציה. ממשקי API שהוצגו ברמת API מאוחרת יותר מוצגים באפור והתוכן שלהם מוסתר, כי אין לאפליקציה גישה אליהם.
סינון לפי רמת API במסמכים לא מאפשר לראות מה חדש או מה נוסף בכל רמת API. הוא מאפשר לראות את כל ה-API שמשויך לרמת API נתונה, תוך החרגה של רכיבי API שהוצגו ברמות API מאוחרות יותר.
כדי לחזור להצגת התיעוד המלא, בוחרים באפשרות REL בחלק העליון של תפריט רמת ה-API. כברירת מחדל, הסינון לפי רמת API מושבת, כדי שתוכלו לראות את ה-API המלא של המסגרת, ללא קשר לרמת ה-API.
במסמכי התיעוד של כל רכיב API מצוינת רמת ה-API שבה הרכיב הוצג. רמת ה-API של חבילות וסיווגים מצוינת כ'נוספה ברמת API' בפינה השמאלית העליונה של אזור התוכן בכל דף תיעוד. רמת ה-API של חברי הכיתה מצוינת בכותרות התיאור המפורט שלהם, בשוליים השמאליים.