ابزارهای چارچوب سازگاری

اندروید 11 ابزارهای توسعه دهنده جدیدی را برای آزمایش و اشکال زدایی برنامه شما در برابر تغییرات رفتاری در نسخه های جدیدتر پلتفرم اندروید معرفی کرد. این ابزارها بخشی از یک چارچوب سازگاری هستند که به توسعه‌دهندگان برنامه اجازه می‌دهد تا با استفاده از گزینه‌های توسعه‌دهنده یا ADB، تغییرات را به‌صورت جداگانه روشن و خاموش کنند. از این انعطاف پذیری برای هدف قرار دادن آخرین نسخه API پایدار و هنگام آزمایش برنامه خود با انتشار پیش نمایش نسخه بعدی اندروید استفاده کنید.

هنگامی که از ابزارهای چارچوب سازگاری استفاده می‌کنید، پلتفرم اندروید به‌طور خودکار منطق داخلی خود را تطبیق می‌دهد، بنابراین برای انجام آزمایش اولیه نیازی به تغییر targetSDKVersion یا کامپایل مجدد برنامه خود ندارید. از آنجایی که تغییرات به‌صورت جداگانه قابل تغییر هستند، می‌توانید هر بار یک تغییر رفتار را ایزوله، آزمایش و اشکال‌زدایی کنید یا اگر نیاز به آزمایش چیز دیگری دارید، یک تغییر واحد را که باعث ایجاد مشکل می‌شود غیرفعال کنید.

نحوه تشخیص اینکه کدام تغییرات فعال هستند

وقتی یک تغییر رفتار فعال است، می‌تواند بر نحوه دسترسی برنامه شما به APIهای پلتفرمی که تحت تأثیر آن تغییر هستند تأثیر بگذارد. می توانید بررسی کنید که کدام تغییرات رفتاری با استفاده از گزینه های توسعه دهنده، logcat یا دستورات ADB فعال شده است.

با استفاده از گزینه های توسعه دهنده تغییرات فعال را شناسایی کنید

شکل 1. سازگاری برنامه صفحه را در گزینه های توسعه دهنده تغییر می دهد.

می‌توانید ببینید کدام تغییرات فعال هستند و آن تغییرات را در گزینه‌های برنامه‌نویس دستگاه روشن یا خاموش کنید . برای دسترسی به این گزینه ها، مراحل زیر را دنبال کنید:

1. اگر گزینه‌های برنامه‌نویس قبلاً فعال نشده‌اند، آن‌ها را فعال کنید .
2. برنامه تنظیمات دستگاه خود را باز کنید و به System > Advanced > Developer options > App Compatibility Changes بروید.

3. برنامه خود را از لیست انتخاب کنید.

   توجه: برای روشن و خاموش کردن تغییرات باید از یک نسخه ساخت قابل اشکال زدایی از برنامه خود استفاده کنید.

هر تغییر رفتار معمولاً به یکی از دو دسته زیر تعلق دارد:

• تغییراتی که بر همه برنامه‌هایی که در آن نسخه از Android اجرا می‌شوند، بدون توجه به targetSdkVersion برنامه تأثیر می‌گذارد.

  این تغییرات به‌طور پیش‌فرض در چارچوب سازگاری فعال هستند و در UI در قسمت 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 خواهید شد که به آن تغییرات پیش‌فرض غیرفعال می‌شود. تغییراتی که در این بخش قرار می گیرند می توانند اهداف مختلفی را دنبال کنند. قبل از فعال کردن این تغییرات، توضیحات تغییر را در لیست چارچوب سازگاری آن نسخه اندروید بخوانید.

با استفاده از 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	این تغییر از طریق چارچوب سازگاری ثبت می شود، اما نمی توان آن را روشن یا خاموش کرد. اگرچه این تغییر قابل تغییر نیست، اما همچنان ممکن است بر رفتار برنامه شما تأثیر بگذارد. برای اطلاعات بیشتر به توضیح تغییر در لیست چارچوب سازگاری آن نسخه اندروید مراجعه کنید. در بسیاری از موارد، این نوع تغییرات تجربی هستند و می توان آنها را نادیده گرفت.

با استفاده از 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 15 (سطح API 35)
• Android 14 (سطح API 34)
• Android 13 (سطح API 33)
• Android 12 (سطح API 31 و 32)
• Android 11 (سطح API 30)

چه زمانی تغییرات را تغییر دهید

هدف اصلی چارچوب سازگاری این است که هنگام آزمایش برنامه خود با نسخه های جدیدتر اندروید، کنترل و انعطاف پذیری را برای شما فراهم کند. این بخش برخی از استراتژی‌ها را توضیح می‌دهد که می‌توانید برای تعیین زمان روشن یا خاموش کردن تغییرات هنگام آزمایش و اشکال‌زدایی برنامه خود استفاده کنید.

چه زمانی باید تغییرات را خاموش کرد

تصمیم‌گیری برای خاموش کردن تغییرات معمولاً به این بستگی دارد که آیا تغییر توسط targetSDKVersion بسته شده است یا خیر.

تغییرات برای همه برنامه ها فعال شده است

تغییراتی که همه برنامه‌ها را تحت تأثیر قرار می‌دهند به‌طور پیش‌فرض برای یک نسخه پلتفرم خاص، بدون توجه به targetSDKVersion برنامه‌تان، فعال می‌شوند، بنابراین می‌توانید ببینید که آیا برنامه شما با اجرای برنامه در آن نسخه پلتفرم تحت تأثیر قرار می‌گیرد یا خیر.

به عنوان مثال، اگر در حال آماده‌سازی برای هدف قرار دادن Android 15 (سطح API 35) هستید، می‌توانید برنامه خود را روی دستگاهی که دارای Android 15 است نصب کنید و برنامه خود را با استفاده از گردش‌های کاری آزمایشی معمولی خود آزمایش کنید. اگر برنامه با مشکلاتی مواجه شد، می‌توانید تغییری که باعث این مشکل شده است را غیرفعال کنید تا بتوانید برای مشکلات دیگر به آزمایش ادامه دهید.

از آنجایی که این تغییرات می‌تواند بر همه برنامه‌ها بدون توجه به targetSDKVersion تأثیر بگذارد، معمولاً باید قبل از تغییراتی که توسط targetSDKVersion بسته می‌شوند، برنامه خود را برای این تغییرات آزمایش و به‌روزرسانی کنید. این کمک می‌کند مطمئن شوید که کاربران شما وقتی دستگاه خود را به نسخه پلتفرم جدید به‌روزرسانی می‌کنند، تجربه برنامه ضعیفی نخواهند داشت.

همچنین باید آزمایش این تغییرات را در اولویت قرار دهید زیرا نمی‌توانید هنگام استفاده از نسخه عمومی اندروید، این تغییرات را غیرفعال کنید. در حالت ایده‌آل، باید این تغییرات را برای هر نسخه از Android در حالی که آن نسخه در پیش‌نمایش است، آزمایش کنید.

تغییرات توسط targetSDKVersion

اگر برنامه شما یک targetSDKVersion خاص را هدف قرار می‌دهد، هر تغییری که توسط آن نسخه بسته می‌شود به‌طور پیش‌فرض فعال می‌شود. بنابراین، همانطور که targetSDKVersion برنامه خود را به نسخه جدید تغییر می دهید، برنامه شما به طور همزمان تحت تأثیر بسیاری از تغییرات جدید قرار می گیرد.

از آنجایی که برنامه شما ممکن است تحت تأثیر بیش از یکی از این تغییرات قرار گیرد، ممکن است لازم باشد برخی از این تغییرات را هنگام آزمایش و اشکال زدایی برنامه خود به صورت جداگانه خاموش کنید.

چه زمانی باید تغییرات را روشن کرد

تغییراتی که توسط یک targetSDKVersion مشخص ایجاد می‌شوند به‌طور پیش‌فرض غیرفعال می‌شوند، هر زمان که یک برنامه نسخه SDK پایین‌تری را نسبت به نسخه دروازه‌دار هدف قرار دهد. به طور معمول، همانطور که برای هدف قرار دادن یک targetSdkVersion جدید آماده می شوید، لیستی از تغییرات رفتاری خواهید داشت که باید برنامه خود را آزمایش و اشکال زدایی کنید.

برای مثال، ممکن است برنامه خود را در برابر یک سری تغییرات پلتفرم در targetSdkVersion بعدی آزمایش کنید. با استفاده از گزینه‌های توسعه‌دهنده یا دستورات ADB، می‌توانید هر تغییر دروازه‌دار را یک به یک فعال و آزمایش کنید، نه اینکه مانیفست برنامه‌تان را تغییر دهید و هر تغییر را به‌طور هم‌زمان انتخاب کنید. این کنترل اضافی می تواند به شما کمک کند تغییرات را به صورت مجزا آزمایش کنید و از اشکال زدایی و به روز رسانی چندین بخش برنامه خود به طور همزمان جلوگیری کنید.

پس از فعال کردن تغییر، می‌توانید برنامه خود را با استفاده از جریان‌های کاری آزمایشی معمولی خود آزمایش و اشکال‌زدایی کنید. اگر با مشکلاتی مواجه شدید، گزارش های خود را بررسی کنید تا به شما کمک کند علت مشکل را تعیین کنید. اگر مشخص نیست که آیا مشکل ناشی از تغییر پلت فرم است که فعال شده است، آن تغییر را غیرفعال کنید و سپس آن قسمت از برنامه خود را مجدداً آزمایش کنید.

تغییرات را روشن یا خاموش کنید

چارچوب سازگاری به شما امکان می دهد هر تغییر را با استفاده از گزینه های توسعه دهنده یا دستورات ADB روشن یا خاموش کنید. از آنجایی که روشن یا خاموش کردن تغییرات می‌تواند باعث از کار افتادن برنامه شما یا غیرفعال کردن تغییرات مهم امنیتی شود، محدودیت‌هایی برای تغییر وضعیت تغییرات وجود دارد.

توجه: هرگاه با استفاده از گزینه‌های توسعه‌دهنده یا دستورات ADB تغییری را برای یک برنامه تغییر دهید، برنامه حذف می‌شود تا اطمینان حاصل شود که لغو شما فوراً اعمال می‌شود.

تغییرات را با استفاده از گزینه های توسعه دهنده تغییر دهید

از گزینه های توسعه دهنده برای روشن یا خاموش کردن تغییرات استفاده کنید. برای پیدا کردن گزینه های توسعه دهنده، این مراحل را دنبال کنید:

1. اگر گزینه‌های برنامه‌نویس قبلاً فعال نشده‌اند، آن‌ها را فعال کنید .
2. برنامه تنظیمات دستگاه خود را باز کنید و به System > Advanced > Developer options > App Compatibility Changes بروید.
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 پایین‌تر از نسخه دروازه‌دار را هدف قرار می‌دهد، غیرفعال می‌شود. هنگامی که یک تغییر را روشن یا خاموش می کنید، وضعیت پیش فرض آن را لغو می کنید.

برای جلوگیری از استفاده مخرب از چارچوب سازگاری، محدودیت‌هایی در زمان تغییر تغییرات وجود دارد. اینکه آیا می‌توانید تغییری را تغییر دهید یا نه، به نوع تغییر، قابل اشکال‌زدایی برنامه شما و نوع ساختی که روی دستگاه شما اجرا می‌شود بستگی دارد. جدول زیر زمانی را توضیح می دهد که شما مجاز به تغییر انواع مختلف تغییرات هستید:

نوع ساخت	برنامه غیر قابل اشکال زدایی	برنامه قابل اشکال زدایی
	همه تغییرات	تغییرات توسط targetSDKVersion	همه تغییرات دیگر
پیش‌نمایش توسعه‌دهنده یا ساخت بتا	نمی توان تغییر داد	می تواند تغییر کند	می تواند تغییر کند
ساخت کاربر عمومی	نمی توان تغییر داد	می تواند تغییر کند	نمی توان تغییر داد