תוספי SDK

התוספים ל-SDK מתבססים על רכיבי מערכת מודולריים כדי להוסיף ממשקי API ל-SDK הציבורי לרמות API מסוימות שפורסמו בעבר. ממשקי ה-API האלה מועברים למכשירים כשמשתמשי הקצה מקבלים עדכוני מודולים דרך עדכוני המערכת של 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 Extensions. שמות של תוספים ל-SDK תואמים למשתנה קבוע שלם – משתנה קבוע מ-Build.VERSION_CODES או משתנה קבוע שהוגדר בכיתה SdkExtensions (למשל SdkExtensions.AD_SERVICES).

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

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

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

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

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

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

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

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

   Groovy

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }
   

   Kotlin

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

בדיקה אם יש תוספים ל-SDK

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

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

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

Kotlin

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.
}

Java

public static final boolean isPhotoPickerAvailable() {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2;
}

הבדיקה הזו דומה לבדיקה שמבוססת על Build.VERSION.SDK_INT:

Kotlin

fun isPhotoPickerAvailable(): Boolean {
    return Build.VERSION.SDK_INT >= 33
}

Java

public static final boolean isPhotoPickerAvailable() {
    return Build.VERSION.SDK_INT >= 33;
}

בדיקת SDK_INT עדיין בטוחה ותקפה, אבל הפונקציה isPhotoPickerAvailable תחזיר את הערך false במכשירים מסוימים, למרות ש-Extension API זמין. כתוצאה מכך, הבדיקה של SDK_INT לא אופטימלית, ובדיקה של גרסת התוסף היא דרך טובה יותר לבדוק את הזמינות של ה-API. בכל המכשירים עם SDK_INT שגדול מ-33 או שווה לו (Android 13 ואילך) יש את ממשקי ה-API של בורר התמונות ב-SDK הציבורי, אבל יש מכשירים עם SDK_INT שקטן מ-33 (כמו Android 11,‏ 12 ו-12L) שיכולים לגשת גם לממשקי ה-API אם יש להם גרסאות של התוסף R עם 2 לפחות.

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

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

בדומה לקבוצה הכללית של תוספים ל-SDK, לפעמים ההפניה ל-API‏ AdServices מציינת ש-API הוא חלק מגרסה של 'תוספים לשירותי מודעות'. בניגוד לתוספים הכלליים של SDK, בתוספים של Ad Services נעשה שימוש בערך הקבוע SdkExtensions.AD_SERVICES כדי לקבוע איזו גרסה מותקנת במכשיר:

Kotlin

fun isAdServicesAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4
}

Java

public static final boolean isAdServicesAvailable() {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4;
}

למידע נוסף על התכונות של התוספים של Ad Services ועל תחילת העבודה, אפשר לעיין במסמכי העזרה של התוספים של Ad Services.

שיטות שירות

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

תמיכה בכלים

ב-Android Studio Flamingo | 2022.2.1 ואילך, כלי ה-lint יכול לסרוק בעיות בגרסאות של SDK Extension כחלק מהבדיקה של NewAPI. בנוסף, Android Studio יכול ליצור באופן אוטומטי את בדיקות הגרסאות הנכונות לממשקי API שמופעלים באמצעות תוספים ל-SDK.

כלי ה-lint מסמנים מקרים שבהם לא צוינה הגרסה המינימלית של SDK Extensions שנדרשת כדי לבצע קריאה ל-API.

שמות ומשתני קבועים של תוסף SDK

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

שם התוסף ל-SDK	קבוע	מכשירים שעומדים בתנאים
תוספים ל-R	VERSION_CODES.R	Android מגרסה 11 (רמת API 30) ואילך
תוספים מסוג S	VERSION_CODES.S	Android מגרסה 12 (רמת API 31) ואילך
תוספים מסוג T	VERSION_CODES.TIRAMISU	Android מגרסה 13 (רמת API ‏33) ואילך
תוספים מסוג U	VERSION_CODES.UPSIDE_DOWN_CAKE	Android מגרסה 14 (API ברמה 34) ואילך
תוספים מסוג V	VERSION_CODES.VANILLA_ICE_CREAM	Android מגרסה 15 (רמת API ‏35) ואילך
תוספים של שירותי פרסום	SdkExtensions.AD_SERVICES	Android מגרסה 13 (רמת API ‏33) ואילך

בדיקה באמצעות 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 במקרה הזה).