<uses-sdk>

מערכת 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. לדוגמה, היא לא זהה לגרסה הראשית או לסכום של הגרסה הראשית והגרסה המשנית.

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

מאפיינים:

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" ב-manifest שלה מתפרסמת ב-Google Play. משתמש שמשתמש במכשיר עם Android 1.6 (רמת API 4) מוריד ומתקין את האפליקציה. אחרי כמה שבועות, המשתמש מקבל עדכון מערכת אוויר ל-Android 2.0 (רמת API 5). אחרי התקנת העדכון, המערכת בודקת את maxSdkVersion של האפליקציה ומאמתת אותו מחדש בהצלחה.

האפליקציה פועלת כרגיל. עם זאת, זמן מה לאחר מכן המכשיר מקבל עדכון מערכת נוסף, הפעם ל-Android 2.0.1 (API ברמה 6). אחרי העדכון, המערכת לא יכולה יותר לאמת מחדש את האפליקציה כי רמת ה-API של המערכת (6) גבוהה עכשיו מרמת ה-API המקסימלית שנתמכת באפליקציה (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 של מסגרת האפליקציות של Android.

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

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

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

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

שימושים ברמת ה-API ב-Android

המזהה ברמת ה-API ממלא תפקיד מפתח במתן חוויית המשתמש הטובה ביותר למשתמשים ולמפתחי האפליקציות:

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

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

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

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

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

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

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

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

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

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

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

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