תוספי SDK

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

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

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

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

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

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

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

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

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

כדי להשתמש ב-SDK של תוסף, יש לפעול לפי השלבים הבאים:

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

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

    מגניב

    android {
    compileSdk 33
    compileSdkExtension 4
    ...
}

    Kotlin

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

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

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

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

תוספים לשירותי מודעות

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

למידע נוסף על התכונות של 'תוספים לשירותי מודעות' ועל כדי להתחיל, ראו תוספים לשירותי מודעות תיעוד.

שיטות שירות

במקרים מסוימים, לתוספי SDK יש שיטות לשימוש ב-Jetpack לבדיקה של הזמינות של ממשקי ה-API של תוספי SDK. לדוגמה, אפשר להשתמש ב-Jetpack את הפונקציה של 'ספרייה' שצריך לבדוק כדי להשתמש ב-PhotoPhotoer availability [זמינות], שמפשט את בדיקות הגרסה המותנית.

תמיכה בכלים

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

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

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

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