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

ב-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'.

בנוסף, שימו לב לקטע Default Disabled Changes (שינויים מושבתים כברירת מחדל) שמוצג באיור 1. שינויים שנכללים בקטע הזה יכולים לשמש למגוון מטרות. לפני שמפעילים את השינויים האלה, כדאי לקרוא את תיאור השינוי ברשימת מסגרת התאימות לגרסת 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 של גרסת בטא לא ניתן להחליף מצב אפשר להפעיל או להשבית אפשר להפעיל או להשבית
build של משתמש ציבורי לא ניתן להחליף מצב אפשר להפעיל או להשבית לא ניתן להחליף מצב