תוספים ל-SDK

תוספי SDK מסתמכים על רכיבי מערכת מודולריים כדי להוסיף ממשקי API ל-SDK הציבורי לרמות מסוימות של API שפורסמו בעבר. ה-APIs האלה מועברים למכשירים כשמשתמשי הקצה מקבלים עדכוני מודולים דרך עדכוני המערכת של Google Play. מפתחי אפליקציות יכולים להשתמש בממשקי ה-API האלה באפליקציות שלהם כדי לספק פונקציונליות נוספת שלא הייתה זמינה במקור ב-SDK לגרסאות הקודמות האלה של Android.

ניהול גרסאות של API

החל מ-Android 11 (רמת API‏ 30), מכשירי Android כוללים קבוצה של תוספי SDK. כשמוסיפים ממשקי API חדשים, הם נכללים ברמת API, אבל יכול להיות שהם ייכללו גם בתוסף SDK של גרסה מסוימת. לדוגמה, ה-API של כלי בחירת התמונות ACTION_PICK_IMAGES נוסף ל-SDK הציבורי ב-Android 13 (רמת API‏ 33), אבל הוא זמין גם דרך תוספי SDK החל מגרסה 2 של תוספי R. השמות של תוספי ה-SDK תואמים לקבוע מספרי – קבוע מ-Build.VERSION_CODES, או קבוע שמוגדר במחלקה SdkExtensions (כמו SdkExtensions.AD_SERVICES).

קובעים באילו תוספי SDK להשתמש

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

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

לדוגמה, ACTION_PICK_IMAGES זמין באופן כללי ב-SDK הציבורי החל מ-Android 13 (רמת API‏ 33), אבל הוא זמין גם במכשירים עם גרסאות ישנות יותר עד Android 11 (רמת API‏ 30), כל עוד במכשיר מותקנת לפחות גרסה 2 של R Extensions:

כדי להשתמש ב-API הזה, צריך לבצע קומפילציה מול SDK ברמת API 33 לפחות, או ברמת Extension 2 לפחות.

כדי להשתמש ב-SDK של תוסף:

1. כדי לדעת מהי הגרסה המינימלית של התוספים שדרושה לכם, צריך לעיין במסמכי העזרה של התכונה ובמאמרי העזרה של ה-API שבו אתם רוצים להשתמש.
2. אחרי שקובעים את גרסת התוסף הנדרשת עבור קבוצת התכונות, פותחים את SDK Manager ב-Android Studio.
3. בוחרים את הרשומה של פלטפורמת Android SDK עם גרסת התוסף המתאימה (או גרסה גבוהה יותר, כי ממשקי ה-API הם מצטברים). לדוגמה: Android SDK Platform 33, Extension Level 4.

4. מצהירים על הערכים האלה בקובץ build.gradle.kts או build.gradle של האפליקציה:

   מגניב

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }

   Kotlin

   android {
       compileSdk = 33
       compileSdkExtension = 4
       ...
   }

בדיקה אם תוספי SDK זמינים

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

בדיקה בזמן ריצה

האפליקציה יכולה לבדוק בזמן הריצה אם תוספי SDK זמינים לגרסה מסוימת של הפלטפורמה באמצעות ה-method‏ 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 של בוחר התמונות ב-SDK הציבורי, אבל יש מכשירים עם SDK_INT קטן מ-33 (כמו Android 11,‏ Android 12 ו-Android 12L) שיכולים גם לגשת לממשקי ה-API אם יש להם גרסאות תוסף R של לפחות 2.

במקרה כזה, בדיקת גרסת התוסף יכולה לעזור לאפליקציה לספק פונקציונליות נוספת ליותר משתמשים. במאמר שמות של תוספי SDK וקבועים מפורטת רשימה של כל הקבועים שאפשר להשתמש בהם כדי לבדוק אם במכשיר מסוים יש תוספי SDK מסוימים.

תוספים לשירותי פרסום

בדומה לסט הכללי של תוספי SDK, בהפניה ל-API‏ AdServices מצוין לפעמים ש-API מסוים הוא חלק מגרסה של Ad Services Extensions. בניגוד לתוספי ה-SDK הכלליים, Ad Services Extensions משתמשים בקבוע 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;
}

במסמכי Ad Services Extensions מוסבר מהן התכונות של התוספים האלה ואיך מתחילים להשתמש בהם.

שיטות עזר

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

תמיכה בכלים

ב-Android Studio Flamingo ‏ | 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 במקרה הזה).