כלים של מסגרת תאימות

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

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

איך מזהים אילו שינויים מופעלים

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

זיהוי שינויים שהופעלו באמצעות אפשרויות למפתחים

איור 1. המסך 'שינויים בתאימות האפליקציה' באפשרויות למפתחים.

באפשרויות למפתחים במכשיר אפשר לראות אילו שינויים מופעלים ולהפעיל או להשבית אותם. כדי לגשת לאפשרויות האלה, פועלים לפי השלבים הבאים:

1. אם האפשרויות למפתחים עדיין לא הופעלו, מפעילים אותן.
2. פותחים את אפליקציית ההגדרות במכשיר ועוברים אל מערכת > אפשרויות מתקדמות > אפשרויות למפתחים > שינויים בתאימות האפליקציות.

3. בוחרים את האפליקציה מהרשימה.

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

כל שינוי בהתנהגות שייך בדרך כלל לאחת משתי הקטגוריות הבאות:

• שינויים שמשפיעים על כל האפליקציות שפועלות בגרסה הזו של Android, בלי קשר ל-targetSdkVersion של האפליקציה.

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

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

  השינויים האלה מופעלים כברירת מחדל במסגרת התאימות אם האפליקציה שלכם מיועדת לגרסה גבוהה יותר מגרסת ה-API שמופיעה ברשימה. לדוגמה, שינוי בהתנהגות שמוגבל על ידי targetSDKVersion ב-Android 13 (רמת API 33) יופיע בממשק המשתמש בקטע שנקרא Enabled for targetSdkVersion >=33. בגרסאות ישנות יותר של Android, הקטע הזה נקרא 'הופעלה לאחר SDK API_LEVEL'.

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

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

זיהוי שינויים מופעלים באמצעות logcat

בכל שינוי בהתנהגות, בפעם הראשונה במהלך התהליך של האפליקציה שבה האפליקציה קוראת ל-API המושפע, המערכת מוציאה הודעת logcat כמו זו:

D CompatibilityChangeReporter: Compat change id reported: 194833441; UID 10265; state: ENABLED

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

כל הודעה ב-logcat כוללת את הפרטים הבאים:

שינוי מזהה

מציין איזה שינוי משפיע על האפליקציה. הערך הזה ממופה לאחד מהשינויים בהתנהגות שמופיעים במסך שינויים בתאימות האפליקציה (ראו איור 1). בדוגמה הזו, 194833441 ממופה ל-NOTIFICATION_PERM_CHANGE_ID.

UID

מציין על איזו אפליקציה השינוי משפיע.

מדינה

מציין אם השינוי משפיע על האפליקציה.

הסטטוס יכול להיות אחד מהערכים הבאים:

מדינה	משמעות
ENABLED	השינוי מופעל וישפיע על התנהגות האפליקציה אם: האפליקציה משתמשת בממשקי ה-API שהשתנו.
DISABLED	השינוי מושבת ולא ישפיע על האפליקציה. הערה: אם השינוי הזה מושבת כי targetSDKVersion של האפליקציה נמוך מהסף הנדרש, השינוי יופעל כברירת מחדל כשהאפליקציה תגדיל את targetSDKVersion שלה כדי להתאים לגרסה גבוהה יותר.
LOGGED	השינוי מתועד באמצעות מסגרת התאימות, אבל אי אפשר להפעיל או להשבית אותו. למרות שאי אפשר להפעיל או להשבית את השינוי הזה, הוא עדיין עשוי להשפיע על התנהגות האפליקציה. מידע נוסף זמין בתיאור השינוי ברשימת מסגרות התאימות לגרסת Android הזו. במקרים רבים, השינויים האלה הם ניסיוניים ואפשר להתעלם מהם.

זיהוי שינויים מופעלים באמצעות ADB

מריצים את פקודת ה-ADB הבאה כדי לראות את כל השינויים (גם אלה שהופעלו וגם אלה שהושבתו) בכל המכשיר:

adb shell dumpsys platform_compat

בפלט מפורט המידע הבא לגבי כל שינוי:

שינוי מזהה

מזהה ייחודי של שינוי ההתנהגות הזה. לדוגמה, 194833441.

שם

השם של השינוי בהתנהגות. לדוגמה, NOTIFICATION_PERM_CHANGE_ID.

קריטריונים של targetSDKVersion

התנאי שנדרש כדי שהשינוי יחול targetSDKVersion (אם יש כזה).

לדוגמה, אם השינוי הזה מופעל רק באפליקציות שמיועדות לגרסה 33 ואילך של SDK, הפלט יהיה enableAfterTargetSdk=32. אם השינוי לא מוגבל על ידי targetSDKVersion, הפלט הוא enableAfterTargetSdk=0.

שינויים בחבילות

השם של כל חבילה שבה מצב ברירת המחדל של השינוי (מופעל או מושבת) בוטל.

לדוגמה, אם מדובר בשינוי שמופעל כברירת מחדל, שם החבילה של האפליקציה יופיע אם השבתתם את השינוי באמצעות אפשרויות למפתחים או ADB. במקרה כזה, הפלט יהיה:

packageOverrides={com.my.package=false}

שינויים שמוגבלים על ידי targetSDKVersion יכולים להיות מופעלים או מושבתים כברירת מחדל, כך שרשימת החבילות יכולה לכלול מקרים של true או false, בהתאם לtargetSDKVersion של כל אחת מהאפליקציות האלה. לדוגמה:

packageOverrides={com.my.package=true, com.another.package=false}

מידע נוסף על שינויים ספציפיים

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

• ‫Android 16 (רמת API‏ 36)
• ‫Android 15 (רמת API‏ 35)
• ‫Android 14 (רמת API 34)
• ‫Android 13 (רמת API‏ 33)
• ‫Android 12 (רמות API‏ 31 ו-32)
• ‫Android 11 (רמת API‏ 30)

מתי להחליף את השינויים

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

מתי כדאי להשבית את האפשרות להחלפת שינויים

ההחלטה מתי להשבית את השינויים תלויה בדרך כלל בשאלה אם השינוי מוגבל על ידי targetSDKVersion או לא.

השינויים מופעלים לכל האפליקציות

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

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

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

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

שינויים שמוגבלים על ידי targetSDKVersion

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

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

מתי כדאי להפעיל את השינויים

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

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

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

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

הפעלה או השבתה של שינויים

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

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

החלפת המצב של השינויים באמצעות האפשרויות למפתחים

אפשר להשתמש באפשרויות למפתחים כדי להפעיל או להשבית שינויים. כדי למצוא את האפשרויות למפתחים, פועלים לפי השלבים הבאים:

1. אם האפשרויות למפתחים עדיין לא הופעלו, מפעילים אותן.
2. פותחים את אפליקציית ההגדרות במכשיר ועוברים אל מערכת > אפשרויות מתקדמות > אפשרויות למפתחים > שינויים בתאימות האפליקציות.
3. בוחרים את האפליקציה מהרשימה.
4. ברשימת השינויים, מוצאים את השינוי שרוצים להפעיל או להשבית ומקישים על המתג.

איור 2. הפעלה או השבתה של שינויים.

החלפת מצב השינויים באמצעות ADB

כדי להפעיל או להשבית שינוי באמצעות ADB, מריצים אחת מהפקודות הבאות:

adb shell am compat enable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
adb shell am compat disable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

מעבירים את CHANGE_ID (למשל, 194833441) או את CHANGE_NAME (למשל, NOTIFICATION_PERM_CHANGE_ID) ואת PACKAGE_NAME של האפליקציה.

אפשר גם להשתמש בפקודה הבאה כדי לאפס שינוי למצב ברירת המחדל שלו, ולהסיר כל שינוי שביצעתם באמצעות ADB או אפשרויות למפתחים:

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

הגבלות על החלפת שינויים

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

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

סוג build	אפליקציה שלא ניתן לנפות בה באגים	אפליקציה שאפשר לבצע בה ניפוי באגים
	כל השינויים	שינויים שמוגבלים על ידי targetSDKVersion	כל שאר השינויים
גרסת בטא או תצוגה מקדימה למפתחים	אי אפשר להפעיל או להשבית את ההגדרה	אפשר להחליף מצב	אפשר להחליף מצב
משתמש build ציבורי	אי אפשר להפעיל או להשבית את ההגדרה	אפשר להחליף מצב	אי אפשר להפעיל או להשבית את ההגדרה