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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כל הודעה ב-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 שבו השינוי מוגבל (אם יש כזה).

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

מתי משביתים את השינויים

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

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

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

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

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

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

שינויים שמאובטחים על ידי targetSDKVersion

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

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

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

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

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

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

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

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

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

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

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

  4. ברשימת השינויים, מחפשים את השינוי שרוצים להפעיל או להשבית ומקישים על המתג.

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

החלפת מצב השינויים באמצעות 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 שינויים אחרים
גרסה זמנית למפתחים או גרסה בטא לא ניתן להחליף מצב אפשר להפעיל או להשבית אפשר להפעיל או להשבית
build של משתמש ציבורי לא ניתן להחליף מצב אפשר להפעיל או להשבית לא ניתן להחליף מצב