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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  השינויים האלה מופעלים כברירת מחדל במסגרת התאימות אם האפליקציה מטרגטת גרסה גבוהה יותר מגרסת ה-API שמופיעה ברשימה. לדוגמה, שינוי בהתנהגות שמוגבל על ידי targetSDKVersion ב-Android 13 (רמת API‏ 33) יופיע בממשק המשתמש בקטע שנקרא Enabled for targetSdkVersion >=33. בגרסאות ישנות יותר של Android, הקטע הזה נקרא Enabled After 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)
• thought 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 שפועל במכשיר. בטבלה הבאה מפורט מתי מותר להחליף בין סוגי השינויים השונים:

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