<uses-sdk>

מערכת Google Play משתמשת במאפיינים של <uses-sdk> שמוצהרים בקובץ המניפסט של האפליקציה כדי לסנן את האפליקציה ממכשירים שלא עומדים בדרישות של גרסת הפלטפורמה. לפני שמגדירים את המאפיינים האלה, חשוב להבין את המסננים של Google Play.

תחביר:
<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />
מוכל ב:
<manifest>
תיאור:

מאפשרת לציין את התאימות של האפליקציה לגרסה אחת או יותר של פלטפורמת Android באמצעות מספר שלם של רמת API. רמת ה-API של האפליקציה מושווית לרמת ה-API של מערכת Android נתונה, שיכולה להשתנות בין מכשירי Android שונים.

למרות השם שלו, הרכיב הזה משמש לציון רמת ה-API, ולא את מספר הגרסה של ערכת הכלים לפיתוח תוכנה (SDK) או של פלטפורמת Android. רמת ה-API היא תמיד מספר שלם אחד. אי אפשר להסיק מהי רמת ה-API לפי מספר הגרסה של Android שמשויך אליה. לדוגמה, הוא לא זהה לגרסה הראשית או לסכום של הגרסאות הראשית והמשנית.

אי אפשר לציין שאפליקציה מטרגטת או דורשת גרסת SDK משנית.

‫כדאי גם לקרוא את המסמך בנושא ניהול גרסאות של אפליקציות.

מאפיינים:
android:minSdkVersion
מספר שלם שמציין את רמת ה-API המינימלית שנדרשת כדי להפעיל את האפליקציה. מערכת Android מונעת מהמשתמש להתקין את האפליקציה אם רמת ה-API של המערכת נמוכה מהערך שצוין במאפיין הזה. תמיד צריך להצהיר על המאפיין הזה.

זהירות: אם לא תצהירו על המאפיין הזה, המערכת תניח שערך ברירת המחדל הוא "1", מה שמציין שהאפליקציה שלכם תואמת לכל הגרסאות של Android. אם היא לא תואמת, ולא הצהרתם על minSdkVersion המתאים, האפליקציה תקרוס בזמן הריצה כשתנסו לגשת לממשקי ה-API הלא זמינים, כשהיא מותקנת במערכת עם רמת 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

android:maxSdkVersion
מספר שלם שמציין את רמת ה-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‏ 1

מהי רמת API?

רמת API היא ערך של מספר שלם שמזהה באופן ייחודי את גרסת ה-API של המסגרת שמוצעת על ידי גרסה של פלטפורמת Android.

פלטפורמת Android מספקת ממשק API של מסגרת שאפליקציות יכולות להשתמש בו כדי לקיים אינטראקציה עם מערכת Android הבסיסית. ה-API של המסגרת מורכב מהרכיבים הבאים:

  • קבוצה בסיסית של חבילות ומחלקות
  • קבוצה של רכיבים ומאפיינים ב-XML להצהרה על קובץ מניפסט
  • קבוצה של רכיבים ומאפיינים ב-XML להצהרה על משאבים ולגישה אליהם
  • קבוצה של כוונות
  • קבוצת הרשאות שאפליקציות יכולות לבקש, וגם אכיפת הרשאות שכלולה במערכת

כל גרסה חדשה של פלטפורמת Android יכולה לכלול עדכונים ל-API של framework האפליקציה ל-Android.

העדכונים ל-API של המסגרת מתוכננים כך שה-API החדש יישאר תואם לגרסאות קודמות של ה-API. כלומר, רוב השינויים ב-API הם תוספות, והם מציגים פונקציונליות חדשה או חלופית. כשמשדרגים חלקים מה-API, החלקים הישנים שהוחלפו יוצאים משימוש אבל לא מוסרים, כדי שאפליקציות קיימות עדיין יוכלו להשתמש בהם.

במקרים מעטים מאוד, חלקים מה-API משתנים או מוסרים, אבל בדרך כלל השינויים האלה נדרשים רק כדי לתמוך ביציבות של ה-API ובאבטחה של האפליקציה או המערכת. כל שאר חלקי ה-API מגרסאות קודמות מועברים ללא שינוי.

ממשק ה-API של ה-framework שפלטפורמת Android מספקת מצוין באמצעות מזהה של מספר שלם שנקרא רמת API. כל גרסה של פלטפורמת Android תומכת ברמת API אחת בדיוק, אבל התמיכה משתמעת בכל רמות ה-API הקודמות (עד רמת API‏ 1). הגרסה הראשונה של פלטפורמת Android סיפקה רמת API‏ 1, והגרסאות הבאות הגדילו את רמת ה-API. ממשקי API שהושקו או הוצאו משימוש בגרסאות טרום-השקה של ערכות SDK שלא הגיעו ליציבות פלטפורמה מסומנים כ"API בפיתוח" במקום מספר רמת API.

בטבלה הבאה מפורטת רמת ה-API שנתמכת בכל גרסה של פלטפורמת Android. במרכז הבקרה של ההפצה אפשר לראות את המספרים היחסיים של המכשירים שבהם פועלת כל גרסה.

גרסת פלטפורמהרמת ממשק API:VERSION_CODEהערות
Android 17 37 CINNAMON_BUN הדגשים בפלטפורמה
Android 16 36 BAKLAVA הדגשים בפלטפורמה
Android 15 35 VANILLA_ICE_CREAM הדגשים בפלטפורמה
Android 14 34 UPSIDE_DOWN_CAKE הדגשים בפלטפורמה
Android 13 33 TIRAMISU הדגשים בפלטפורמה
Android 12 32 S_V2 הדגשים בפלטפורמה
31 S הדגשים בפלטפורמה
Android 11 30 R הדגשים בפלטפורמה
Android 10 29 Q הדגשים בפלטפורמה
Android 9 28 P הדגשים בפלטפורמה
Android 8.1 27 O_MR1 הדגשים בפלטפורמה
Android 8.0 26 O הדגשים בפלטפורמה
Android 7.1.1
Android 7.1		 25 N_MR1 הדגשים בפלטפורמה
Android 7.0 24 N הדגשים בפלטפורמה
Android 6.0 23 M הדגשים בפלטפורמה
Android 5.1 22 LOLLIPOP_MR1 תקציר הפלטפורמה
Android 5.0 21 LOLLIPOP
Android 4.4W 20 KITKAT_WATCH ‫KitKat לגאדג'טים לבישים בלבד
Android 4.4 19 KITKAT תקציר הפלטפורמה
Android 4.3 18 JELLY_BEAN_MR2 תקציר הפלטפורמה
Android 4.2, 4.2.2 17 JELLY_BEAN_MR1 תקציר הפלטפורמה
Android 4.1, 4.1.1 16 JELLY_BEAN תקציר הפלטפורמה
Android 4.0.3, 4.0.4 15 ICE_CREAM_SANDWICH_MR1 תקציר הפלטפורמה
Android 4.0, 4.0.1, 4.0.2 14 ICE_CREAM_SANDWICH
Android 3.2 13 HONEYCOMB_MR2
‫Android 3.1.x 12 HONEYCOMB_MR1 הדגשים בפלטפורמה
Android 3.0.x 11 HONEYCOMB הדגשים בפלטפורמה
Android 2.3.4
Android 2.3.3		 10 GINGERBREAD_MR1 תקציר הפלטפורמה
Android 2.3.2
Android 2.3.1
Android 2.3		 9 GINGERBREAD
Android 2.2.x 8 FROYO הדגשים בפלטפורמה
אנדרואיד 2.1.x 7 ECLAIR_MR1 תקציר הפלטפורמה
Android 2.0.1 6 ECLAIR_0_1
Android 2.0 5 ECLAIR
Android 1.6 4 DONUT הדגשים בפלטפורמה
Android 1.5 3 CUPCAKE הדגשים בפלטפורמה
Android 1.1 2 BASE_1_1
Android 1.0 1 BASE

ממשקי API בפיתוח

במאמרי העזרה של Android API, ממשקי API שנוספו או הוצאו משימוש בגרסת טרום-השקה של SDK מסומנים בתווית "API בפיתוח" במקום במספר רמת API. התווית הזו חלה על ההודעות "נוסף בגרסה" ו "הוצא משימוש בגרסה" עד שה-SDK מגיע ליציבות בפלטפורמה ומקבל רמת API סופית, ראשית או משנית. לממשקי API שנמצאים בפיתוח יש את המאפיינים הבאים:

  • סטטוס גרסת טרום-השקה (Preview): הוספת ה-API או הוצאתו משימוש הן חלק מגרסת טרום-השקה (Preview) פעילה של SDK בגרסת בטא או Canary, לפני סיום הפיתוח של רמת ה-API.
  • אין הבטחה ליציבות: בניגוד לממשקי API שפורסמו (שיש להם רמת API קבועה והם תואמים לדורות קודמים בגרסאות עתידיות), ממשקי API שנמצאים בפיתוח עשויים לשנות חתימות, לשנות את השם או להיות מוסרים לחלוטין בין גרסאות ה-SDK של גרסת טרום-ההשקה (Preview).

בדיקה אם יש ממשקי API בפיתוח בזמן הריצה (PREVIEW_SDK_INT)

ממשקי API שנמצאים בפיתוח יכולים להשתנות או להיעלם בין גרסאות טרום-השקה, לכן אף פעם אל תשתמשו בבדיקה של "גדול או שווה ל-" (>=) כדי להגן על קריאות לממשקי API שלא הושקו. יכול להיות ש-API שקיים בגרסת טרום-השקה 1 ישתנה או יוסר בגרסת טרום-השקה 2.

במקום זאת, אפליקציות שמתנסות בתכונות בגרסת טרום-השקה (Preview) צריכות לבדוק את הערך של Build.VERSION.PREVIEW_SDK_INT לשוויון מחמיר (==) מול גרסת טרום-ההשקה המדויקת שהאפליקציה קומפלה מולה:

  • בגרסאות build וגרסאות סופיות לסביבת הייצור, הערך של Build.VERSION.PREVIEW_SDK_INT הוא תמיד 0.
  • בגרסאות טרום-השקה (Preview), הערך של PREVIEW_SDK_INT הוא ייחודי לכל גרסה.

שימושים ברמת ה-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, שצריך להביא בחשבון כשמפתחים אפליקציה.

תאימות האפליקציה לגרסאות עתידיות

באופן כללי, אפליקציות ל-Android תואמות לגרסאות חדשות של פלטפורמת Android.

כמעט כל השינויים ב-API של ה-framework הם תוספות, ולכן אפליקציה ל-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 ישודרג לאחור לגרסה קודמת של הפלטפורמה, חשוב להבין שסביר להניח שיש הרבה מכשירים בשטח שפועלות בהם גרסאות קודמות של הפלטפורמה. גם במכשירים שמקבלים עדכוני OTA, יכול להיות שחלק מהם יתעכבו ולא יקבלו עדכון במשך זמן רב.

בוחרים גרסת פלטפורמה ורמת API

כשמפתחים את האפליקציה, בוחרים את גרסת הפלטפורמה שבה רוצים להדר את האפליקציה. באופן כללי, כדאי לקמפל את האפליקציה לגרסה הנמוכה ביותר של הפלטפורמה שהאפליקציה יכולה לתמוך בה.

כדי לקבוע את גרסת הפלטפורמה הנמוכה ביותר האפשרית, אפשר לקמפל את האפליקציה מול יעדי build נמוכים יותר ברצף. אחרי שקובעים מהי הגרסה הנמוכה ביותר, יוצרים AVD באמצעות גרסת הפלטפורמה ורמת ה-API המתאימות, ובודקים את האפליקציה באופן מלא. חשוב להצהיר על מאפיין android:minSdkVersion במניפסט של האפליקציה ולהגדיר את הערך שלו לרמת ה-API של גרסת הפלטפורמה.

הצהרה על רמת API מינימלית

אם אתם מפתחים אפליקציה שמשתמשת בממשקי API או בתכונות מערכת שהוצגו בגרסת הפלטפורמה האחרונה, הגדירו את המאפיין android:minSdkVersion לרמת ה-API של גרסת הפלטפורמה האחרונה. כך המשתמשים יוכלו להתקין את האפליקציה רק אם במכשירים שלהם פועלת גרסה תואמת של פלטפורמת Android. כך תוכלו לוודא שהאפליקציה שלכם תפעל כמו שצריך במכשירים שלהם.

אם האפליקציה משתמשת בממשקי API שהוצגו בגרסת הפלטפורמה האחרונה, אבל לא מצהירה על מאפיין android:minSdkVersion, היא פועלת כמו שצריך במכשירים שבהם פועלת הגרסה האחרונה של הפלטפורמה, אבל לא במכשירים שבהם פועלות גרסאות קודמות של הפלטפורמה. במקרה השני, האפליקציה קורסת בזמן הריצה כשהיא מנסה להשתמש בממשקי API שלא קיימים בגרסאות הקודמות.

בדיקה מול רמות API גבוהות יותר

אחרי שאתם מקמפלים את האפליקציה, חשוב לבדוק אותה בפלטפורמה שצוינה במאפיין android:minSdkVersion של האפליקציה. כדי לעשות את זה, יוצרים AVD שמשתמש בגרסת הפלטפורמה שהאפליקציה דורשת. בנוסף, כדי לבדוק תאימות קדימה, צריך להריץ ולבדוק את האפליקציה בכל הפלטפורמות שמשתמשות ברמת API גבוהה יותר מזו שבה האפליקציה משתמשת.

ערכת ה-Android SDK כוללת כמה גרסאות של פלטפורמות שאפשר להשתמש בהן, כולל הגרסה העדכנית, ומספקת כלי עדכון שבעזרתו אפשר להוריד גרסאות אחרות של פלטפורמות לפי הצורך.

כדי לגשת לכלי העדכון, משתמשים בכלי שורת הפקודה android שנמצא בספרייה <sdk>/tools. כדי להפעיל את כלי העדכון של ה-SDK, מריצים את הפקודה android sdk. אפשר גם ללחוץ לחיצה כפולה על הקובץ android.bat (Windows) או android (OS X/Linux).

כדי להריץ את האפליקציה בגרסאות שונות של הפלטפורמה באמולטור, צריך ליצור 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 המלא של ה-framework, בלי קשר לרמת ה-API.

במאמרי העזרה של רכיבי API ספציפיים מצוינת רמת ה-API שבה כל רכיב נוסף או הוצא משימוש. רמת ה-API של החבילות והמחלקות מצוינת בפינה השמאלית העליונה של אזור התוכן בכל דף תיעוד, בתור Added in API level (נוסף ברמת API) ו-Deprecated in API level (הוצא משימוש ברמת API), אם רלוונטי. רמת ה-API של חברי המחלקה מצוינת בכותרות התיאור המפורט שלהם, בשוליים הימניים. במקומות האלה, במקום מספר רמת API, מוצג הכיתוב API under development (API בפיתוח) לתוספות או להוצאות משימוש של API בגרסת טרום-השקה שלא הגיעו ליציבות בפלטפורמה.