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

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

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

چگونه تشخیص دهیم کدام تغییرات فعال شده‌اند

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

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

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

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

1. اگر گزینه‌های توسعه‌دهنده از قبل فعال نیستند، آن‌ها را فعال کنید .
2. برنامه تنظیمات دستگاه خود را باز کنید و به سیستم > پیشرفته > گزینه‌های توسعه‌دهنده > تغییرات سازگاری برنامه بروید.

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

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

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

  این تغییرات به طور پیش‌فرض در چارچوب سازگاری فعال هستند و در رابط کاربری در بخش تغییرات پیش‌فرض فعال فهرست شده‌اند.

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

  این تغییرات به طور پیش‌فرض در چارچوب سازگاری فعال می‌شوند اگر برنامه شما نسخه‌ای بالاتر از نسخه API ذکر شده را هدف قرار دهد. به عنوان مثال، یک تغییر رفتاری که توسط targetSDKVersion در اندروید ۱۳ (سطح API ۳۳) مسدود شده باشد، در رابط کاربری در بخشی با عنوان Enabled for targetSdkVersion >=۳۳ فهرست می‌شود. در برخی از نسخه‌های پایین‌تر اندروید، این بخش به جای آن "Enabled After SDK API_LEVEL " نامگذاری شده است.

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

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

برای هر تغییر رفتار، اولین باری که در طول فرآیند برنامه شما، برنامه API آسیب‌دیده را فراخوانی می‌کند، سیستم یک پیام logcat مانند این را خروجی می‌دهد:

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

هر پیام logcat شامل اطلاعات زیر است:

تغییر شناسه

نشان می‌دهد که کدام تغییر بر برنامه تأثیر می‌گذارد. این مقدار به یکی از تغییرات رفتاری که در صفحه تغییرات سازگاری برنامه فهرست شده‌اند (شکل 1 را ببینید) نگاشت می‌شود. در این مثال، 194833441 به NOTIFICATION_PERM_CHANGE_ID نگاشت می‌شود.

شناسه کاربری

نشان می‌دهد که کدام برنامه تحت تأثیر تغییر قرار گرفته است.

ایالت

نشان می‌دهد که آیا تغییر روی برنامه تأثیر می‌گذارد یا خیر.

حالت می‌تواند یکی از این مقادیر باشد:

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

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

دستور ADB زیر را اجرا کنید تا مجموعه کامل تغییرات (اعم از فعال و غیرفعال) را در کل دستگاه مشاهده کنید:

adb shell dumpsys platform_compat

خروجی، اطلاعات زیر را برای هر تغییر فهرست می‌کند:

تغییر شناسه

یک شناسه منحصر به فرد برای این تغییر رفتار. به عنوان مثال، 194833441 .

نام

نام این رفتار تغییر می‌کند. برای مثال، NOTIFICATION_PERM_CHANGE_ID .

معیارهای targetSDKversion

کدام targetSDKVersion تغییر را محدود می‌کند (در صورت وجود).

برای مثال، اگر این تغییر فقط برای برنامه‌هایی که 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}

درباره تغییرات خاص بیشتر بدانید

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

• اندروید ۱۶ (سطح API ۳۶)
• اندروید ۱۵ (سطح API ۳۵)
• اندروید ۱۴ (سطح API ۳۴)
• اندروید ۱۳ (سطح API ۳۳)
• اندروید ۱۲ (سطح API 31 و 32)
• اندروید ۱۱ (سطح API 30)

چه زمانی تغییرات را فعال/غیرفعال کنیم

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

چه زمانی تغییرات را غیرفعال کنیم؟

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

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

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

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

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

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