محدودیت در رابط های غیر SDK

با شروع Android 9 (سطح API 28)، این پلتفرم رابط‌های غیر SDK را محدود می‌کند که برنامه شما می‌تواند استفاده کند. این محدودیت‌ها زمانی اعمال می‌شوند که برنامه‌ای به یک رابط غیر SDK ارجاع می‌دهد یا سعی می‌کند با استفاده از بازتاب یا JNI، دسته آن را بدست آورد. این محدودیت‌ها برای کمک به بهبود تجربه کاربر و توسعه‌دهنده و کاهش خطرات خرابی برای کاربران و عرضه اضطراری برای توسعه‌دهندگان اعمال شد. برای اطلاعات بیشتر درباره این تصمیم، به بهبود پایداری با کاهش استفاده از رابط‌های غیر SDK مراجعه کنید.

بین رابط های SDK و غیر SDK تفاوت قائل شوید

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

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

لیست های غیر SDK API

با هر نسخه از Android، رابط های غیر SDK اضافی محدود می شوند. ما می‌دانیم که این محدودیت‌ها می‌توانند بر گردش کار انتشار شما تأثیر بگذارند، و می‌خواهیم مطمئن شویم که ابزارهایی برای تشخیص استفاده از رابط‌های غیر SDK، فرصتی برای ارائه بازخورد و زمان برای برنامه‌ریزی و تطبیق با خط‌مشی‌های جدید در اختیار دارید.

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

فهرست کنید برچسب های کد توضیحات
لیست بلاک شده
  • blocked
  • منسوخ شده: blacklist
 رابط‌های غیر SDK که نمی‌توانید بدون در نظر گرفتن سطح API هدف برنامه‌تان از آن‌ها استفاده کنید. اگر برنامه شما سعی کند به یکی از این رابط‌ها دسترسی پیدا کند، سیستم با خطا مواجه می‌شود .
مشروط مسدود شده است
  • max-target-x
  • منسوخ شده: greylist-max-x

با شروع Android 9 (سطح API 28)، هر سطح API دارای رابط های غیر SDK است که زمانی که یک برنامه آن سطح API را هدف قرار می دهد، محدود می شود.

این لیست‌ها با حداکثر سطح API ( max-target-x ) برچسب‌گذاری می‌شوند که یک برنامه می‌تواند قبل از اینکه برنامه دیگر نتواند به رابط‌های غیر SDK در آن لیست دسترسی داشته باشد، هدف قرار دهد. به عنوان مثال، یک رابط غیر SDK که در Android Pie مسدود نشده است اما اکنون در Android 10 مسدود شده است، بخشی از لیست max-target-p ( greylist-max-p ) است، جایی که "p" مخفف Pie یا Android 9 (سطح API 28) است.

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

پشتیبانی نمی شود
  • unsupported
  • منسوخ شده: greylist
 رابط های غیر SDK که نامحدود هستند و برنامه شما می تواند از آنها استفاده کند. البته توجه داشته باشید که این رابط‌ها پشتیبانی نمی‌شوند و بدون اطلاع قبلی ممکن است تغییر کنند. انتظار می رود این رابط ها به صورت مشروط در نسخه های اندروید آینده در لیست max-target-x مسدود شوند.
SDK
  • هم public-api و هم sdk
  • منسوخ شده: هم public-api و هم whitelist
 رابط‌هایی که می‌توان آزادانه از آن‌ها استفاده کرد و اکنون به‌عنوان بخشی از فهرست بسته‌بندی چارچوب Android به‌طور رسمی پشتیبانی می‌شوند.
تست API ها
  • test-api
 رابط هایی که برای آزمایش سیستم داخلی استفاده می شوند، مانند API هایی که تست را از طریق مجموعه تست سازگاری (CTS) تسهیل می کنند. APIهای آزمایشی بخشی از SDK نیستند . با شروع Android 11 (سطح API 30) ، APIهای آزمایشی در فهرست بلاک گنجانده شده‌اند، بنابراین برنامه‌ها بدون در نظر گرفتن سطح API هدفشان مجاز به استفاده از آنها نیستند. همه APIهای آزمایشی پشتیبانی نمی‌شوند و بدون توجه به سطح API پلتفرم، بدون اطلاع قبلی در معرض تغییر هستند.

در حالی که می توانید از برخی از رابط های غیر SDK (بسته به سطح API هدف برنامه خود) استفاده کنید، استفاده از هر روش یا فیلد غیر SDK همیشه خطر شکستن برنامه شما را بالا می برد. اگر برنامه شما به رابط‌های غیر SDK متکی است، باید برنامه‌ریزی برای انتقال به رابط‌های SDK یا گزینه‌های دیگر را آغاز کنید. اگر نمی توانید جایگزینی برای استفاده از یک رابط غیر SDK برای یک ویژگی در برنامه خود پیدا کنید، باید یک API عمومی جدید درخواست کنید .

تعیین کنید که یک رابط به کدام لیست تعلق دارد

لیست رابط های غیر SDK به عنوان بخشی از پلتفرم ساخته شده است. برای اطلاعات در مورد هر نسخه اندروید به بخش های زیر مراجعه کنید.

اندروید 16

برای اندروید 16 (سطح API 36)، می‌توانید فایل زیر را دانلود کنید که تمام رابط‌های غیر SDK و فهرست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: 9102af02fe6ab68b92464bdff5e5b09f3bd62c65d1130aaf85d3296f17d38074

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 16، به به روز رسانی محدودیت های رابط غیر SDK در Android 16 مراجعه کنید.

اندروید 15

برای Android 15 (سطح API 35)، می‌توانید فایل زیر را دانلود کنید که تمام رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: 40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 15، به به روز رسانی محدودیت های رابط غیر SDK در Android 15 مراجعه کنید.

اندروید 14

برای Android 14 (سطح API 34)، می‌توانید فایل زیر را دانلود کنید که تمام رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: 7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 14، به به روز رسانی محدودیت های رابط غیر SDK در Android 14 مراجعه کنید.

اندروید 13

برای Android 13 (سطح API 33)، می‌توانید فایل زیر را دانلود کنید که تمام رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: 233a277aa8ac475b6df61bffd95665d86aac6eb2ad187b90bf42a98f5f2a11a3

برای کسب اطلاعات بیشتر درباره تغییرات لیست API غیر SDK در Android 13، از جمله جایگزین‌های API عمومی پیشنهادی برای APIهایی که به طور مشروط در Android 13 مسدود شده‌اند، به به‌روزرسانی‌های محدودیت‌های رابط غیر SDK در Android 13 مراجعه کنید.

اندروید 12

برای Android 12 (سطح API 31)، می‌توانید فایل زیر را دانلود کنید که همه رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: 40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761

برای کسب اطلاعات بیشتر درباره تغییرات لیست API غیر SDK در Android 12، از جمله جایگزین‌های عمومی پیشنهادی API برای APIهایی که به طور مشروط در Android 12 مسدود شده‌اند، به فهرست تغییرات برای Android 12 مراجعه کنید.

اندروید 11

برای Android 11 (سطح API 30)، می‌توانید فایل زیر را دانلود کنید که همه رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 11، از جمله جایگزین‌های API عمومی پیشنهادی برای APIهایی که به طور مشروط در Android 11 مسدود شده‌اند، به فهرست تغییرات برای Android 11 مراجعه کنید.

اندروید 10

برای Android 10 (سطح API 29)، می‌توانید فایل زیر را دانلود کنید که تمام رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 10، از جمله جایگزین‌های API عمومی پیشنهادی برای APIهایی که به طور مشروط در Android 10 مسدود شده‌اند، به فهرست تغییرات برای Android 10 مراجعه کنید.

اندروید 9

برای Android 9 (سطح API 28)، فایل متنی زیر حاوی لیستی از APIهای غیر SDK است که محدود نیستند (فهرست خاکستری): hiddenapi-light-greylist.txt .

لیست بلاک ( blacklist ) و لیست APIهای مسدود شده مشروط (فهرست خاکستری تیره) در زمان ساخت مشتق می شوند.

ایجاد لیست از AOSP

هنگام کار با AOSP، می‌توانید یک فایل hiddenapi-flags.csv ایجاد کنید که حاوی تمام رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها است. برای انجام این کار، منبع AOSP را دانلود کنید و سپس دستور زیر را اجرا کنید:

m out/soong/hiddenapi/hiddenapi-flags.csv

سپس می توانید فایل را در مکان زیر پیدا کنید:

out/soong/hiddenapi/hiddenapi-flags.csv

رفتار مورد انتظار هنگام دسترسی به رابط‌های غیر SDK محدود

جدول زیر رفتاری را توصیف می‌کند که می‌توانید در صورت تلاش برنامه شما برای دسترسی به یک رابط غیر SDK که بخشی از فهرست مسدود است، انتظار داشته باشید.

وسیله دسترسی نتیجه
دستورالعمل دالویک به یک فیلد ارجاع می دهد NoSuchFieldError پرتاب شد
دستورالعمل دالویک به یک روش ارجاع می دهد NoSuchMethodError پرتاب شد
بازتاب با استفاده از Class.getDeclaredField() یا Class.getField() NoSuchFieldException پرتاب شد
بازتاب با استفاده از Class.getDeclaredMethod() , Class.getMethod() NoSuchMethodException پرتاب شد
بازتاب با استفاده از Class.getDeclaredFields() , Class.getFields() اعضای غیر SDK در نتایج نیستند
بازتاب با استفاده از Class.getDeclaredMethods() , Class.getMethods() اعضای غیر SDK در نتایج نیستند
JNI با استفاده از env->GetFieldID() NULL برگشت، NoSuchFieldError پرتاب شد
JNI با استفاده از env->GetMethodID() NULL برگشت، NoSuchMethodError پرتاب شد

برنامه خود را برای رابط های غیر SDK آزمایش کنید

چندین روش وجود دارد که می‌توانید از آنها برای آزمایش رابط‌های غیر SDK در برنامه خود استفاده کنید.

با استفاده از یک برنامه اشکال زدایی تست کنید

می‌توانید رابط‌های غیر SDK را با ساختن و اجرای یک برنامه قابل اشکال‌زدایی روی دستگاه یا شبیه‌ساز دارای Android 9 (سطح API 28) یا بالاتر آزمایش کنید. مطمئن شوید که دستگاه یا شبیه‌سازی که استفاده می‌کنید با سطح API هدف برنامه شما مطابقت داشته باشد.

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

  • کلاس، نام و نوع اعلان کننده (در قالبی که در زمان اجرا اندروید استفاده می شود).
  • ابزار دسترسی: یا پیوند دادن، با استفاده از بازتاب یا استفاده از JNI.
  • رابط غیر SDK به کدام لیست تعلق دارد.

می‌توانید از adb logcat برای دسترسی به این پیام‌های گزارش، که در زیر PID برنامه در حال اجرا ظاهر می‌شوند، استفاده کنید. به عنوان مثال، یک ورودی در گزارش ممکن است به صورت زیر باشد:

Accessing hidden field Landroid/os/Message;->flags:I (light greylist, JNI)

با استفاده از StrictMode API تست کنید

همچنین می‌توانید رابط‌های غیر SDK را با استفاده از StrictMode API آزمایش کنید. برای فعال کردن آن از روش detectNonSdkApiUsage استفاده کنید. پس از فعال کردن StrictMode API، می‌توانید برای هر استفاده از یک رابط غیر SDK با استفاده از penaltyListener یک تماس پاسخ دریافت کنید، جایی که می‌توانید مدیریت سفارشی را پیاده‌سازی کنید. شیء Violation ارائه شده در callback از Throwable مشتق شده است و ردیابی پشته محصور زمینه استفاده را فراهم می کند.

با استفاده از ابزار veridex تست کنید

همچنین می توانید ابزار تجزیه و تحلیل استاتیک veridex را بر روی APK خود اجرا کنید. ابزار veridex کل پایگاه کد APK از جمله کتابخانه های شخص ثالث را اسکن می کند و هرگونه استفاده از رابط های غیر SDK را که پیدا می کند گزارش می دهد.

محدودیت های ابزار veridex شامل موارد زیر است:

  • نمی‌تواند فراخوان‌ها را از طریق JNI شناسایی کند.
  • فقط می تواند زیر مجموعه ای از فراخوان ها را از طریق بازتاب تشخیص دهد.
  • تجزیه و تحلیل آن برای مسیرهای کد غیرفعال به بررسی سطح API محدود می شود.
  • فقط می‌تواند روی ماشین‌هایی اجرا شود که دستورالعمل‌های SSE4.2 و POPCNT را پشتیبانی می‌کنند.

ویندوز

باینری های بومی ویندوز ارائه نشده اند، اما می توانید ابزار veridex را با اجرای باینری های لینوکس با استفاده از زیرسیستم ویندوز برای لینوکس (WSL) در ویندوز اجرا کنید. قبل از انجام مراحل این بخش، WSL را نصب کرده و Ubuntu را به عنوان توزیع لینوکس خود انتخاب کنید.

پس از نصب اوبونتو، ترمینال اوبونتو را راه اندازی کنید و مراحل زیر را دنبال کنید:

  1. ابزار veridex را از مخزن از پیش ساخته شده در زمان اجرا اندروید دانلود کنید.
  2. محتویات فایل appcompat.tar.gz را استخراج کنید.
  3. در پوشه استخراج شده، فایل veridex-linux.zip را پیدا کرده و آن را استخراج کنید.

  4. به پوشه زیپ نشده بروید و سپس دستور زیر را اجرا کنید، جایی که your-app.apk APKی است که می خواهید آزمایش کنید:

    ./appcompat.sh --dex-file=your-app.apk

macOS

برای اجرای ابزار veridex در macOS، مراحل زیر را دنبال کنید:

  1. ابزار veridex را از مخزن از پیش ساخته شده در زمان اجرا اندروید دانلود کنید.
  2. محتویات فایل appcompat.tar.gz را استخراج کنید.
  3. در پوشه استخراج شده، فایل veridex-mac.zip را پیدا کرده و آن را استخراج کنید.

  4. به پوشه زیپ نشده بروید و سپس دستور زیر را اجرا کنید، جایی که /path-from-root/your-app.apk مسیر APK است که می خواهید آزمایش کنید، از دایرکتوری ریشه سیستم شما شروع می شود:

    ./appcompat.sh --dex-file=/path-from-root/your-app.apk

لینوکس

برای اجرای ابزار veridex در لینوکس، مراحل زیر را دنبال کنید:

  1. ابزار veridex را از مخزن از پیش ساخته شده در زمان اجرا اندروید دانلود کنید.
  2. محتویات فایل appcompat.tar.gz را استخراج کنید.
  3. در پوشه استخراج شده، فایل veridex-linux.zip را پیدا کرده و آن را استخراج کنید.

  4. به پوشه زیپ نشده بروید و سپس دستور زیر را اجرا کنید، جایی که your-app.apk APKی است که می خواهید آزمایش کنید:

    ./appcompat.sh --dex-file=your-app.apk

با استفاده از ابزار لینت اندروید استودیو تست کنید

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

همچنین می توانید ابزار lint را از خط فرمان اجرا کنید یا بازرسی ها را به صورت دستی روی یک پروژه، پوشه یا فایل خاص اجرا کنید .

با استفاده از کنسول Play تست کنید

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

برای اطلاعات بیشتر، به بخش سازگاری Android در استفاده از گزارش‌های پیش از راه‌اندازی برای شناسایی مشکلات مراجعه کنید.

درخواست یک API عمومی جدید

اگر نمی توانید جایگزینی برای استفاده از رابط غیر SDK برای یک ویژگی در برنامه خود پیدا کنید، می توانید با ایجاد یک درخواست ویژگی در ردیاب مشکل ما، یک API عمومی جدید درخواست کنید.

هنگام ایجاد یک درخواست ویژگی، اطلاعات زیر را ارائه دهید:

  • از کدام API پشتیبانی نشده استفاده می کنید، از جمله توصیفگر کامل که در پیام Accessing hidden ... دیده می شود.
  • چرا باید از این APIها استفاده کنید، از جمله جزئیات مربوط به ویژگی سطح بالایی که API برای آن ضروری است، نه فقط جزئیات سطح پایین.
  • چرا هر API SDK عمومی مرتبط برای اهداف شما کافی نیست.
  • هر جایگزین دیگری که امتحان کرده اید و چرا اینها جواب نداده اند.

وقتی این جزئیات را در درخواست ویژگی خود ارائه می کنید، احتمال اعطای یک API عمومی جدید را افزایش می دهید.

سوالات دیگر

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

سوالات عمومی

چگونه گوگل می‌تواند مطمئن باشد که می‌تواند نیازهای همه برنامه‌ها را از طریق ردیاب صادر کند؟

ما لیست های اولیه را برای Android 9 (سطح API 28) از طریق تجزیه و تحلیل استاتیک برنامه ها ایجاد کردیم که با استفاده از روش های زیر تکمیل شد:

  • تست دستی برنامه های برتر Play و غیر Play
  • گزارش های داخلی
  • جمع آوری خودکار داده ها از کاربران داخلی
  • گزارش های پیش نمایش توسعه دهندگان
  • تجزیه و تحلیل استاتیک اضافی که به گونه ای محافظه کارانه شامل موارد مثبت کاذب بیشتری طراحی شده است

همانطور که لیست ها را برای هر نسخه جدید ارزیابی می کنیم، استفاده از API و همچنین بازخورد توسعه دهندگان را از طریق ردیاب مشکل در نظر می گیریم.

چگونه می توانم دسترسی به رابط های غیر SDK را فعال کنم؟

می‌توانید با استفاده از دستورات adb برای تغییر خط‌مشی اجرای API، دسترسی به رابط‌های غیر SDK را در دستگاه‌های توسعه فعال کنید. دستوراتی که استفاده می کنید بسته به سطح API متفاوت است. این دستورات به دستگاه روت شده نیاز ندارند.

Android 10 (سطح API 29) یا بالاتر

برای فعال کردن دسترسی، از adb زیر استفاده کنید

دستور:

adb shell settings put global hidden_api_policy  1

برای بازنشانی سیاست اجرایی API به تنظیمات پیش فرض، از دستور زیر استفاده کنید:

adb shell settings delete global hidden_api_policy
Android 9 (سطح API 28)

برای فعال کردن دسترسی، از دستورات adb زیر استفاده کنید:

adb shell settings put global hidden_api_policy_pre_p_apps  1
adb shell settings put global hidden_api_policy_p_apps 1

برای بازنشانی سیاست اجرای API به تنظیمات پیش فرض، از دستورات زیر استفاده کنید: 

adb shell settings delete global hidden_api_policy_pre_p_apps
adb shell settings delete global hidden_api_policy_p_apps

می توانید عدد صحیح را در خط مشی اجرای API روی یکی از مقادیر زیر تنظیم کنید:

  • 0: همه شناسایی رابط های غیر SDK را غیرفعال کنید. استفاده از این تنظیم همه پیام‌های گزارش را برای استفاده از رابط غیر SDK غیرفعال می‌کند و از آزمایش برنامه خود با استفاده از StrictMode API جلوگیری می‌کند. این تنظیم توصیه نمی شود.
  • 1: دسترسی به تمام رابط‌های غیر SDK را فعال کنید، اما پیام‌های گزارش را با اخطار برای هر گونه استفاده از رابط غیر SDK چاپ کنید. استفاده از این تنظیم همچنین به شما امکان می‌دهد برنامه خود را با استفاده از StrictMode API آزمایش کنید.
  • 2: استفاده از واسط‌های غیر SDK را که به فهرست بلاک تعلق دارند یا به صورت مشروط برای سطح API هدف شما مسدود شده‌اند، ممنوع کنید.

سوالاتی در مورد لیست های رابط غیر SDK

از کجا می توانم لیست های غیر SDK API را در تصویر سیستم پیدا کنم؟

آنها در فیلد و بیت های پرچم دسترسی به روش در فایل های dex پلت فرم کدگذاری می شوند. هیچ فایل جداگانه ای در تصویر سیستم که حاوی این لیست ها باشد وجود ندارد.

آیا لیست‌های غیر SDK API در دستگاه‌های OEM مختلف با نسخه‌های Android یکسان یکسان هستند؟

OEM ها می توانند واسط های خود را به لیست بلاک (لیست سیاه) اضافه کنند، اما نمی توانند رابط ها را از لیست های AOSP غیر SDK API حذف کنند. CDD از چنین تغییراتی جلوگیری می‌کند و تست‌های CTS اطمینان حاصل می‌کنند که Android Runtime لیست را اجرا می‌کند.

آیا محدودیتی برای رابط های غیر NDK در کد بومی وجود دارد؟

Android SDK شامل رابط های جاوا است. این پلتفرم شروع به محدود کردن دسترسی به رابط های غیر NDK برای کدهای C/C++ در اندروید 7 (سطح API 26) کرد. برای اطلاعات بیشتر، به بهبود پایداری با محدودیت‌های نماد C/C++ خصوصی در Android N مراجعه کنید.

آیا برنامه ای برای محدود کردن دستکاری فایل های dex2oat یا DEX وجود دارد؟

ما برنامه‌های فعالی برای محدود کردن دسترسی به باینری dex2oat نداریم، اما قصد نداریم که قالب فایل DEX پایدار باشد یا یک رابط عمومی فراتر از بخش‌هایی که به طور عمومی در قالب اجرایی Dalvik مشخص شده‌اند. ما حق تغییر یا حذف dex2oat و بخش های نامشخص فرمت DEX را در هر زمان برای خود محفوظ می داریم. همچنین توجه داشته باشید که فایل های مشتق شده توسط dex2oat مانند ODEX (همچنین به عنوان OAT شناخته می شود)، VDEX و CDEX همگی فرمت های نامشخصی هستند.

اگر یک SDK شخص ثالث حیاتی (به عنوان مثال، یک مبهم) نتواند از استفاده از رابط های غیر SDK اجتناب کند، اما آیا متعهد به حفظ سازگاری با نسخه های اندروید آینده است، چه؟ آیا اندروید در این مورد می تواند از الزامات سازگاری خود چشم پوشی کند؟

ما برنامه ای برای چشم پوشی از الزامات سازگاری بر اساس هر SDK نداریم. اگر یک توسعه‌دهنده SDK فقط می‌تواند سازگاری خود را با بسته به رابط‌های موجود در لیست‌های پشتیبانی‌نشده (خاکستری سابق) حفظ کند، باید برنامه‌ریزی انتقال به رابط‌های SDK یا سایر گزینه‌ها را آغاز کند و هر زمان که نتوانست جایگزینی برای استفاده از رابط غیر SDK پیدا کند، یک API عمومی جدید درخواست کند .

آیا محدودیت‌های رابط غیر SDK برای همه برنامه‌ها از جمله برنامه‌های سیستم و شخص اول اعمال می‌شود، نه فقط برنامه‌های شخص ثالث؟

بله، با این حال، ما برنامه‌هایی را که با کلید پلتفرم امضا شده‌اند و برخی از برنامه‌های تصویر سیستم معاف می‌کنیم. توجه داشته باشید که این معافیت ها فقط برای برنامه هایی اعمال می شود که بخشی از تصویر سیستم (یا برنامه های تصویر سیستم به روز شده) هستند. این لیست فقط برای برنامه‌هایی در نظر گرفته شده است که بر اساس APIهای پلتفرم خصوصی ساخته می‌شوند، نه APIهای SDK (که در آن LOCAL_PRIVATE_PLATFORM_APIS := true ).

،

با شروع Android 9 (سطح API 28)، این پلتفرم رابط‌های غیر SDK را محدود می‌کند که برنامه شما می‌تواند استفاده کند. این محدودیت‌ها زمانی اعمال می‌شوند که برنامه‌ای به یک رابط غیر SDK ارجاع می‌دهد یا سعی می‌کند با استفاده از بازتاب یا JNI، دسته آن را بدست آورد. این محدودیت‌ها برای کمک به بهبود تجربه کاربر و توسعه‌دهنده و کاهش خطرات خرابی برای کاربران و عرضه اضطراری برای توسعه‌دهندگان اعمال شد. برای اطلاعات بیشتر درباره این تصمیم، به بهبود پایداری با کاهش استفاده از رابط‌های غیر SDK مراجعه کنید.

بین رابط های SDK و غیر SDK تفاوت قائل شوید

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

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

لیست های غیر SDK API

با هر نسخه از Android، رابط های غیر SDK اضافی محدود می شوند. ما می‌دانیم که این محدودیت‌ها می‌توانند بر گردش کار انتشار شما تأثیر بگذارند، و می‌خواهیم مطمئن شویم که ابزارهایی برای تشخیص استفاده از رابط‌های غیر SDK، فرصتی برای ارائه بازخورد و زمان برای برنامه‌ریزی و تطبیق با خط‌مشی‌های جدید در اختیار دارید.

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

فهرست کنید برچسب های کد توضیحات
لیست بلاک شده
  • blocked
  • منسوخ شده: blacklist
 رابط‌های غیر SDK که نمی‌توانید بدون در نظر گرفتن سطح API هدف برنامه‌تان از آن‌ها استفاده کنید. اگر برنامه شما سعی کند به یکی از این رابط‌ها دسترسی پیدا کند، سیستم با خطا مواجه می‌شود .
مشروط مسدود شده است
  • max-target-x
  • منسوخ شده: greylist-max-x

با شروع Android 9 (سطح API 28)، هر سطح API دارای رابط های غیر SDK است که زمانی که یک برنامه آن سطح API را هدف قرار می دهد، محدود می شود.

این لیست‌ها با حداکثر سطح API ( max-target-x ) برچسب‌گذاری می‌شوند که یک برنامه می‌تواند قبل از اینکه برنامه دیگر نتواند به رابط‌های غیر SDK در آن لیست دسترسی داشته باشد، هدف قرار دهد. به عنوان مثال، یک رابط غیر SDK که در Android Pie مسدود نشده است اما اکنون در Android 10 مسدود شده است، بخشی از لیست max-target-p ( greylist-max-p ) است، جایی که "p" مخفف Pie یا Android 9 (سطح API 28) است.

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

پشتیبانی نمی شود
  • unsupported
  • منسوخ شده: greylist
 رابط های غیر SDK که نامحدود هستند و برنامه شما می تواند از آنها استفاده کند. البته توجه داشته باشید که این رابط‌ها پشتیبانی نمی‌شوند و بدون اطلاع قبلی ممکن است تغییر کنند. انتظار می رود این رابط ها به صورت مشروط در نسخه های اندروید آینده در لیست max-target-x مسدود شوند.
SDK
  • هم public-api و هم sdk
  • منسوخ شده: هم public-api و هم whitelist
 رابط‌هایی که می‌توان آزادانه از آن‌ها استفاده کرد و اکنون به‌عنوان بخشی از فهرست بسته‌بندی چارچوب Android به‌طور رسمی پشتیبانی می‌شوند.
تست API ها
  • test-api
 رابط هایی که برای آزمایش سیستم داخلی استفاده می شوند، مانند API هایی که تست را از طریق مجموعه تست سازگاری (CTS) تسهیل می کنند. APIهای آزمایشی بخشی از SDK نیستند . با شروع Android 11 (سطح API 30) ، APIهای آزمایشی در فهرست بلاک گنجانده شده‌اند، بنابراین برنامه‌ها بدون در نظر گرفتن سطح API هدفشان مجاز به استفاده از آنها نیستند. همه APIهای آزمایشی پشتیبانی نمی‌شوند و بدون توجه به سطح API پلتفرم، بدون اطلاع قبلی در معرض تغییر هستند.

در حالی که می توانید از برخی از رابط های غیر SDK (بسته به سطح API هدف برنامه خود) استفاده کنید، استفاده از هر روش یا فیلد غیر SDK همیشه خطر شکستن برنامه شما را بالا می برد. اگر برنامه شما به رابط‌های غیر SDK متکی است، باید برنامه‌ریزی برای انتقال به رابط‌های SDK یا گزینه‌های دیگر را آغاز کنید. اگر نمی توانید جایگزینی برای استفاده از یک رابط غیر SDK برای یک ویژگی در برنامه خود پیدا کنید، باید یک API عمومی جدید درخواست کنید .

تعیین کنید که یک رابط به کدام لیست تعلق دارد

لیست رابط های غیر SDK به عنوان بخشی از پلتفرم ساخته شده است. برای اطلاعات در مورد هر نسخه اندروید به بخش های زیر مراجعه کنید.

اندروید 16

برای اندروید 16 (سطح API 36)، می‌توانید فایل زیر را دانلود کنید که تمام رابط‌های غیر SDK و فهرست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: 9102af02fe6ab68b92464bdff5e5b09f3bd62c65d1130aaf85d3296f17d38074

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 16، به به روز رسانی محدودیت های رابط غیر SDK در Android 16 مراجعه کنید.

اندروید 15

برای Android 15 (سطح API 35)، می‌توانید فایل زیر را دانلود کنید که تمام رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: 40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 15، به به روز رسانی محدودیت های رابط غیر SDK در Android 15 مراجعه کنید.

اندروید 14

برای Android 14 (سطح API 34)، می‌توانید فایل زیر را دانلود کنید که تمام رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: 7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 14، به به روز رسانی محدودیت های رابط غیر SDK در Android 14 مراجعه کنید.

اندروید 13

برای Android 13 (سطح API 33)، می‌توانید فایل زیر را دانلود کنید که تمام رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: 233a277aa8ac475b6df61bffd95665d86aac6eb2ad187b90bf42a98f5f2a11a3

برای کسب اطلاعات بیشتر درباره تغییرات لیست API غیر SDK در Android 13، از جمله جایگزین‌های API عمومی پیشنهادی برای APIهایی که به طور مشروط در Android 13 مسدود شده‌اند، به به‌روزرسانی‌های محدودیت‌های رابط غیر SDK در Android 13 مراجعه کنید.

اندروید 12

برای Android 12 (سطح API 31)، می‌توانید فایل زیر را دانلود کنید که همه رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: 40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761

برای کسب اطلاعات بیشتر درباره تغییرات لیست API غیر SDK در Android 12، از جمله جایگزین‌های عمومی پیشنهادی API برای APIهایی که به طور مشروط در Android 12 مسدود شده‌اند، به فهرست تغییرات برای Android 12 مراجعه کنید.

اندروید 11

برای Android 11 (سطح API 30)، می‌توانید فایل زیر را دانلود کنید که همه رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 11، از جمله جایگزین‌های API عمومی پیشنهادی برای APIهایی که به طور مشروط در Android 11 مسدود شده‌اند، به فهرست تغییرات برای Android 11 مراجعه کنید.

اندروید 10

برای Android 10 (سطح API 29)، می‌توانید فایل زیر را دانلود کنید که تمام رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها را توضیح می‌دهد:

فایل: hiddenapi-flags.csv

SHA-256 checksum: f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 10، از جمله جایگزین‌های API عمومی پیشنهادی برای APIهایی که به طور مشروط در Android 10 مسدود شده‌اند، به فهرست تغییرات برای Android 10 مراجعه کنید.

اندروید 9

برای Android 9 (سطح API 28)، فایل متنی زیر حاوی لیستی از APIهای غیر SDK است که محدود نیستند (فهرست خاکستری): hiddenapi-light-greylist.txt .

لیست بلاک ( blacklist ) و لیست APIهای مسدود شده مشروط (فهرست خاکستری تیره) در زمان ساخت مشتق می شوند.

ایجاد لیست از AOSP

هنگام کار با AOSP، می‌توانید یک فایل hiddenapi-flags.csv ایجاد کنید که حاوی تمام رابط‌های غیر SDK و لیست‌های مربوط به آن‌ها است. برای انجام این کار، منبع AOSP را دانلود کنید و سپس دستور زیر را اجرا کنید:

m out/soong/hiddenapi/hiddenapi-flags.csv

سپس می توانید فایل را در مکان زیر پیدا کنید:

out/soong/hiddenapi/hiddenapi-flags.csv

رفتار مورد انتظار هنگام دسترسی به رابط‌های غیر SDK محدود

جدول زیر رفتاری را توصیف می‌کند که می‌توانید در صورت تلاش برنامه شما برای دسترسی به یک رابط غیر SDK که بخشی از فهرست مسدود است، انتظار داشته باشید.

وسیله دسترسی نتیجه
دستورالعمل دالویک به یک فیلد ارجاع می دهد NoSuchFieldError پرتاب شد
دستورالعمل دالویک به یک روش ارجاع می دهد NoSuchMethodError پرتاب شد
بازتاب با استفاده از Class.getDeclaredField() یا Class.getField() NoSuchFieldException پرتاب شد
بازتاب با استفاده از Class.getDeclaredMethod() , Class.getMethod() NoSuchMethodException پرتاب شد
بازتاب با استفاده از Class.getDeclaredFields() , Class.getFields() اعضای غیر SDK در نتایج نیستند
بازتاب با استفاده از Class.getDeclaredMethods() , Class.getMethods() اعضای غیر SDK در نتایج نیستند
JNI با استفاده از env->GetFieldID() NULL برگشت، NoSuchFieldError پرتاب شد
JNI با استفاده از env->GetMethodID() NULL برگشت، NoSuchMethodError پرتاب شد

برنامه خود را برای رابط های غیر SDK آزمایش کنید

چندین روش وجود دارد که می‌توانید از آنها برای آزمایش رابط‌های غیر SDK در برنامه خود استفاده کنید.

با استفاده از یک برنامه اشکال زدایی تست کنید

می‌توانید رابط‌های غیر SDK را با ساختن و اجرای یک برنامه قابل اشکال‌زدایی روی دستگاه یا شبیه‌ساز دارای Android 9 (سطح API 28) یا بالاتر آزمایش کنید. مطمئن شوید که دستگاه یا شبیه‌سازی که استفاده می‌کنید با سطح API هدف برنامه شما مطابقت داشته باشد.

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

  • کلاس، نام و نوع اعلان کننده (در قالبی که در زمان اجرا اندروید استفاده می شود).
  • ابزار دسترسی: یا پیوند دادن، با استفاده از بازتاب یا استفاده از JNI.
  • رابط غیر SDK به کدام لیست تعلق دارد.

می‌توانید از adb logcat برای دسترسی به این پیام‌های گزارش، که در زیر PID برنامه در حال اجرا ظاهر می‌شوند، استفاده کنید. به عنوان مثال، یک ورودی در گزارش ممکن است به صورت زیر باشد:

Accessing hidden field Landroid/os/Message;->flags:I (light greylist, JNI)

با استفاده از StrictMode API تست کنید

همچنین می‌توانید رابط‌های غیر SDK را با استفاده از StrictMode API آزمایش کنید. برای فعال کردن آن از روش detectNonSdkApiUsage استفاده کنید. پس از فعال کردن StrictMode API، می‌توانید برای هر استفاده از یک رابط غیر SDK با استفاده از penaltyListener یک تماس پاسخ دریافت کنید، جایی که می‌توانید مدیریت سفارشی را پیاده‌سازی کنید. شیء Violation ارائه شده در callback از Throwable مشتق شده است و ردیابی پشته محصور زمینه استفاده را فراهم می کند.

با استفاده از ابزار veridex تست کنید

همچنین می توانید ابزار تجزیه و تحلیل استاتیک veridex را بر روی APK خود اجرا کنید. ابزار veridex کل پایگاه کد APK از جمله کتابخانه های شخص ثالث را اسکن می کند و هرگونه استفاده از رابط های غیر SDK را که پیدا می کند گزارش می دهد.

محدودیت های ابزار veridex شامل موارد زیر است:

  • نمی‌تواند فراخوان‌ها را از طریق JNI شناسایی کند.
  • فقط می تواند زیر مجموعه ای از فراخوان ها را از طریق بازتاب تشخیص دهد.
  • تجزیه و تحلیل آن برای مسیرهای کد غیرفعال به بررسی سطح API محدود می شود.
  • فقط می‌تواند روی ماشین‌هایی اجرا شود که دستورالعمل‌های SSE4.2 و POPCNT را پشتیبانی می‌کنند.

ویندوز

باینری های بومی ویندوز ارائه نشده اند، اما می توانید ابزار veridex را با اجرای باینری های لینوکس با استفاده از زیرسیستم ویندوز برای لینوکس (WSL) در ویندوز اجرا کنید. قبل از انجام مراحل این بخش، WSL را نصب کرده و Ubuntu را به عنوان توزیع لینوکس خود انتخاب کنید.

پس از نصب اوبونتو، ترمینال اوبونتو را راه اندازی کنید و مراحل زیر را دنبال کنید:

  1. ابزار veridex را از مخزن پیش ساخته Android Runtime دانلود کنید.
  2. محتویات فایل appcompat.tar.gz را استخراج کنید.
  3. در پوشه استخراج شده، فایل veridex-linux.zip را پیدا کرده و آن را استخراج کنید.

  4. به پوشه زیپ نشده بروید و سپس دستور زیر را اجرا کنید، جایی که your-app.apk APKی است که می خواهید آزمایش کنید:

    ./appcompat.sh --dex-file=your-app.apk

macOS

برای اجرای ابزار veridex در macOS، مراحل زیر را دنبال کنید:

  1. ابزار veridex را از مخزن از پیش ساخته شده در زمان اجرا اندروید دانلود کنید.
  2. محتویات فایل appcompat.tar.gz را استخراج کنید.
  3. در پوشه استخراج شده، فایل veridex-mac.zip را پیدا کرده و آن را استخراج کنید.

  4. به پوشه زیپ نشده بروید و سپس دستور زیر را اجرا کنید، جایی که /path-from-root/your-app.apk مسیر APK است که می خواهید آزمایش کنید، از دایرکتوری ریشه سیستم شما شروع می شود:

    ./appcompat.sh --dex-file=/path-from-root/your-app.apk

لینوکس

برای اجرای ابزار veridex در لینوکس، مراحل زیر را دنبال کنید:

  1. ابزار veridex را از مخزن از پیش ساخته شده در زمان اجرا اندروید دانلود کنید.
  2. محتویات فایل appcompat.tar.gz را استخراج کنید.
  3. در پوشه استخراج شده، فایل veridex-linux.zip را پیدا کرده و آن را استخراج کنید.

  4. به پوشه زیپ نشده بروید و سپس دستور زیر را اجرا کنید، جایی که your-app.apk APKی است که می خواهید آزمایش کنید:

    ./appcompat.sh --dex-file=your-app.apk

با استفاده از ابزار لینت اندروید استودیو تست کنید

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

همچنین می توانید ابزار lint را از خط فرمان اجرا کنید یا بازرسی ها را به صورت دستی روی یک پروژه، پوشه یا فایل خاص اجرا کنید .

با استفاده از کنسول Play تست کنید

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

برای اطلاعات بیشتر، به بخش سازگاری Android در استفاده از گزارش‌های پیش از راه‌اندازی برای شناسایی مشکلات مراجعه کنید.

یک API عمومی جدید درخواست کنید

اگر نمی توانید جایگزینی برای استفاده از رابط غیر SDK برای یک ویژگی در برنامه خود پیدا کنید، می توانید با ایجاد یک درخواست ویژگی در ردیاب مشکل ما، یک API عمومی جدید درخواست کنید.

هنگام ایجاد یک درخواست ویژگی، اطلاعات زیر را ارائه دهید:

  • کدام API پشتیبانی نشده شما استفاده می کنید ، از جمله توصیف کننده کامل که در پیام Accessing hidden ... LogCat مشاهده شده است.
  • چرا شما نیاز به استفاده از این API ها دارید ، از جمله جزئیات مربوط به ویژگی سطح بالا که API برای آن لازم است ، نه فقط جزئیات سطح پایین.
  • چرا هر API های SDK عمومی مرتبط برای اهداف شما کافی نیستند.
  • هر گزینه دیگری که امتحان کرده اید و چرا اینها نتیجه ای نداشته است.

هنگامی که این جزئیات را در درخواست ویژگی خود ارائه می دهید ، احتمال دریافت API عمومی جدید را افزایش می دهید.

سوالات دیگر

این بخش شامل برخی از پاسخ ها به سایر سؤالات است که توسعه دهندگان اغلب از آنها خواسته شده است:

سوالات عمومی

چگونه می تواند Google مطمئن باشد که آنها می توانند نیازهای همه برنامه ها را از طریق Ispuetracker ضبط کنند؟

ما لیست های اولیه را برای Android 9 (API سطح 28) از طریق تجزیه و تحلیل استاتیک برنامه هایی که با استفاده از روش های زیر تکمیل شده اند ایجاد کردیم:

  • تست دستی برنامه های برتر بازی و غیر بازی
  • گزارش های داخلی
  • جمع آوری خودکار داده ها از کاربران داخلی
  • گزارش های پیش نمایش توسعه دهنده
  • تجزیه و تحلیل استاتیک اضافی که برای محافظه کارانه شامل مثبت های کاذب تر است

همانطور که لیست های مربوط به هر نسخه جدید را ارزیابی می کنیم ، استفاده از API و همچنین بازخورد توسعه دهنده را از طریق ردیاب شماره در نظر می گیریم.

چگونه می توانم دسترسی به رابط های غیر SDK را فعال کنم؟

با استفاده از دستورات ADB برای تغییر سیاست اجرای API می توانید دسترسی به رابط های غیر SDK را در دستگاه های توسعه فعال کنید. دستوراتی که از آنها استفاده می کنید ، بسته به سطح API متفاوت است. این دستورات به دستگاه ریشه دار احتیاج ندارند.

Android 10 (API سطح 29) یا بالاتر

برای فعال کردن دسترسی ، از ADB زیر استفاده کنید

دستور:

adb shell settings put global hidden_api_policy  1

برای تنظیم مجدد خط مشی اجرای API در تنظیمات پیش فرض ، از دستور زیر استفاده کنید:

adb shell settings delete global hidden_api_policy
Android 9 (سطح API 28)

برای فعال کردن دسترسی ، از دستورات ADB زیر استفاده کنید:

adb shell settings put global hidden_api_policy_pre_p_apps  1
adb shell settings put global hidden_api_policy_p_apps 1

برای تنظیم مجدد خط مشی اجرای API در تنظیمات پیش فرض ، از دستورات زیر استفاده کنید: 

adb shell settings delete global hidden_api_policy_pre_p_apps
adb shell settings delete global hidden_api_policy_p_apps

شما می توانید عدد صحیح را در سیاست اجرای API بر روی یکی از مقادیر زیر تنظیم کنید:

  • 0: تمام تشخیص رابط های غیر SDK را غیرفعال کنید. با استفاده از این تنظیم ، تمام پیام های ورود به سیستم برای استفاده از رابط غیر SDK را غیرفعال می کند و از آزمایش برنامه خود با استفاده از API StrictMode جلوگیری می کند. این تنظیم توصیه نمی شود.
  • 1: دسترسی به تمام رابط های غیر SDK را فعال کنید ، اما پیام های ورود به سیستم را با هشدارهایی برای هرگونه استفاده از رابط غیر SDK چاپ کنید. استفاده از این تنظیم همچنین به شما امکان می دهد برنامه خود را با استفاده از API StrictMode تست کنید.
  • 2: استفاده از رابط های غیر SDK را که متعلق به بلوک هستند یا برای سطح API هدف شما مسدود شده اند ، مجاز نیست.

سؤالات مربوط به لیست رابط غیر SDK

از کجا می توانم لیست های API غیر SDK را در تصویر سیستم پیدا کنم؟

آنها در Field و Method Access Bits در پرونده های Platform DEX رمزگذاری شده اند. هیچ پرونده جداگانه ای در تصویر سیستم وجود ندارد که شامل این لیست ها باشد.

آیا API غیر SDK در دستگاه های مختلف OEM با همان نسخه های Android یکسان است؟

OEM ها می توانند رابط های خود را به لیست بلوک (لیست سیاه) اضافه کنند ، اما آنها نمی توانند رابط ها را از لیست API غیر SDK AOSP حذف کنند. CDD از چنین تغییراتی جلوگیری می کند و تست های CTS اطمینان حاصل می کند که زمان اجرا Android لیست را اجرا می کند.

آیا محدودیتی در رابط های غیر NDK در کد بومی وجود دارد؟

Android SDK شامل رابط های جاوا است. این پلتفرم شروع به محدود کردن دسترسی به رابط های غیر NDK برای کد C/C ++ بومی در Android 7 (API سطح 26) کرد. برای اطلاعات بیشتر ، به بهبود ثبات با محدودیت های نماد خصوصی C/C ++ در Android n مراجعه کنید.

آیا برنامه ای برای محدود کردن دستکاری پرونده dex2oat یا dex وجود دارد؟

ما برنامه های فعال برای محدود کردن دسترسی به دودویی Dex2oat نداریم ، اما ما قصد نداریم که فرمت پرونده DEX پایدار باشد یا یک رابط عمومی فراتر از بخش هایی که در قالب اجرایی Dalvik مشخص شده اند. ما این حق را داریم که Dex2oat و بخش های نامشخص از فرمت DEX را در هر زمان تغییر یا از بین ببریم. همچنین توجه داشته باشید که پرونده های مشتق شده تولید شده توسط Dex2oat مانند ODEX (همچنین به عنوان OAT نیز شناخته می شوند) ، VDEX و CDEX همه قالب های نامشخص هستند.

چه می شود اگر یک SDK شخص ثالث مهم (به عنوان مثال ، یک obfuscator) نتواند از استفاده از رابط های غیر SDK خودداری کند ، اما متعهد به حفظ سازگاری با نسخه های اندرویدی آینده است؟ آیا اندروید می تواند در این حالت از الزامات سازگاری خود چشم پوشی کند؟

ما برنامه ای نداریم که بر اساس هر SDK از الزامات سازگاری چشم پوشی کنیم. اگر یک توسعه دهنده SDK فقط بسته به رابط های موجود در لیست های پشتیبانی نشده (که قبلاً خاکستری) است ، می تواند سازگاری را حفظ کند ، آنها باید برنامه ریزی مهاجرت به رابط های SDK یا گزینه های دیگر را آغاز کنند و هر زمان که نتوانند جایگزینی برای استفاده از رابط غیر SDK پیدا کنند.

آیا محدودیت های رابط غیر SDK برای کلیه برنامه ها از جمله برنامه های سیستم و شخص اول ، نه فقط برنامه های شخص ثالث اعمال می شود؟

بله ، با این حال ، ما برنامه های امضا شده با کلید Platform و برخی از برنامه های تصویر سیستم را معاف می کنیم. توجه داشته باشید که این معافیت ها فقط در مورد برنامه هایی که بخشی از تصویر سیستم هستند (یا برنامه های به روز شده سیستم تصویر) اعمال می شود. این لیست فقط برای برنامه هایی که در برابر API های پلت فرم خصوصی ساخته می شوند ، به جای API های SDK (جایی که LOCAL_PRIVATE_PLATFORM_APIS := true ) در نظر گرفته شده است.

،

با شروع از Android 9 (API سطح 28) ، این پلتفرم محدود می کند که رابط های غیر SDK برنامه شما می تواند از آن استفاده کند. این محدودیت ها هر زمان که یک برنامه به یک رابط غیر SDK ارجاع دهد یا سعی در بدست آوردن دسته خود با استفاده از بازتاب یا JNI داشته باشد ، اعمال می شود. این محدودیت ها برای کمک به بهبود تجربه کاربر و توسعه دهنده و کاهش خطرات تصادفات برای کاربران و برنامه های اضطراری برای توسعه دهندگان به کار گرفته شد. برای کسب اطلاعات بیشتر در مورد این تصمیم ، با کاهش استفاده از رابط های غیر SDK ، به بهبود ثبات مراجعه کنید.

بین رابط های SDK و غیر SDK تمایز قائل شوید

به طور کلی ، رابط های عمومی SDK آنهایی هستند که در فهرست بسته بندی Android Framework ثبت شده اند. استفاده از رابط های غیر SDK یک جزئیات اجرای است که API را از آن جدا می کند ، بنابراین این رابط ها بدون اطلاع قبلی تغییر می کنند.

برای جلوگیری از تصادفات و رفتار غیر منتظره ، برنامه ها فقط باید از قسمت های رسمی مستند کلاس ها در SDK استفاده کنند. این همچنین بدان معنی است که شما نباید هنگام تعامل با یک کلاس با استفاده از مکانیسم هایی مانند بازتاب ، به روش ها یا زمینه هایی که در SDK ذکر نشده اند ، دسترسی پیدا کنید.

لیست های API غیر SDK

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

برای به حداقل رساندن تأثیر محدودیت های غیر SDK در گردش کار توسعه شما ، رابط های غیر SDK به لیست هایی تقسیم می شوند که بسته به اینکه سطح API مورد هدف قرار می گیرد ، چقدر استفاده آنها محدود است. در جدول زیر هر یک از این لیست ها شرح داده شده است:

فهرست کنید برچسب های کد توضیحات
لیست بلاک شده
  • blocked
  • مستهلک: blacklist
 رابط های غیر SDK که بدون توجه به سطح API هدف برنامه خود نمی توانید از آنها استفاده کنید. اگر برنامه شما سعی در دسترسی به یکی از این رابط ها دارد ، سیستم خطایی را به وجود می آورد .
به طور مشروط مسدود شده
  • max-target-x
  • کاهش یافته: greylist-max-x

با شروع Android 9 (API سطح 28) ، هر سطح API دارای رابط های غیر SDK است که وقتی یک برنامه سطح API را هدف قرار می دهد محدود می شود.

این لیست ها با حداکثر سطح API ( max-target-x ) برچسب گذاری شده اند که یک برنامه می تواند قبل از اینکه برنامه دیگر نتواند به رابط های غیر SDK در آن لیست دسترسی پیدا کند. به عنوان مثال ، یک رابط غیر SDK که در پای اندرویدی مسدود نشده است اما اکنون در Android 10 مسدود شده است ، بخشی از لیست max-target-p ( greylist-max-p ) است ، جایی که "P" مخفف پای یا Android 9 (API سطح 28) است.

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

پشتیبانی نمی شود
  • unsupported
  • کاهش یافته: greylist
 رابط های غیر SDK که بدون محدودیت هستند و برنامه شما می تواند از آن استفاده کند. توجه داشته باشید که این رابط ها پشتیبانی نشده و بدون اطلاع قبلی در معرض تغییر هستند. انتظار داشته باشید که این رابط ها در نسخه های اندرویدی آینده در یک لیست max-target-x به طور مشروط مسدود شوند.
SDK
  • هم public-api و هم sdk
  • مستهلک: هم public-api و هم whitelist
 رابط هایی که می توانند آزادانه مورد استفاده قرار گیرند و هم اکنون به عنوان بخشی از شاخص بسته بندی فریم ورک رسمی ثبت شده از آن پشتیبانی می شوند.
تست API ها
  • test-api
 رابط هایی که برای آزمایش سیستم داخلی استفاده می شوند ، مانند API هایی که آزمایش را از طریق مجموعه تست سازگاری (CTS) تسهیل می کنند. API های تست بخشی از SDK نیستند . با شروع Android 11 (API سطح 30) ، API های تست در لیست بلوک قرار می گیرند ، بنابراین برنامه ها مجاز نیستند بدون توجه به سطح API هدف خود از آنها استفاده کنند. تمام API های آزمون بدون توجه به سطح API پلتفرم ، پشتیبانی نشده و بدون اطلاع قبلی تغییر می کنند.

در حالی که می توانید از برخی از رابط های غیر SDK (بسته به سطح API هدف برنامه خود) استفاده کنید ، با استفاده از هر روش غیر SDK یا زمینه همیشه خطر بالایی برای شکستن برنامه شما دارد. اگر برنامه شما به رابط های غیر SDK متکی است ، باید برنامه ریزی مهاجرت به رابط های SDK یا گزینه های دیگر را شروع کنید. اگر نمی توانید جایگزینی برای استفاده از رابط غیر SDK برای یک ویژگی در برنامه خود پیدا کنید ، باید یک API عمومی جدید درخواست کنید .

تعیین کنید که یک رابط به کدام لیست تعلق دارد

لیست رابط های غیر SDK به عنوان بخشی از سیستم عامل ساخته شده است. برای اطلاعات در مورد هر نسخه Android به بخش های زیر مراجعه کنید.

اندروید 16

برای Android 16 (API سطح 36) ، می توانید پرونده زیر را که توصیف تمام رابط های غیر SDK و لیست های مربوطه آنها است ، بارگیری کنید:

پرونده: hiddenapi-flags.csv

SHA-256 Checksum: 9102af02fe6ab68b92464bdff5e5b09f3bd62c65d1130aaf85d3296f17d38074

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 16 ، به به روزرسانی محدودیت های رابط غیر SDK در Android 16 مراجعه کنید.

اندروید 15

برای Android 15 (API سطح 35) ، می توانید فایل زیر را که توصیف تمام رابط های غیر SDK و لیست های مربوطه آنها است ، بارگیری کنید:

پرونده: hiddenapi-flags.csv

SHA-256 Checksum: 40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 15 ، به به روزرسانی محدودیت های رابط غیر SDK در Android 15 مراجعه کنید.

اندروید 14

برای Android 14 (API سطح 34) ، می توانید پرونده زیر را که توصیف تمام رابط های غیر SDK و لیست های مربوطه آنها است ، بارگیری کنید:

پرونده: hiddenapi-flags.csv

SHA-256 Checksum: 7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 14 ، به به روزرسانی محدودیت های رابط غیر SDK در Android 14 مراجعه کنید.

اندروید 13

برای Android 13 (API سطح 33) ، می توانید پرونده زیر را که توصیف تمام رابط های غیر SDK و لیست های مربوطه آنها است ، بارگیری کنید:

پرونده: hiddenapi-flags.csv

SHA-256 Checksum: 233a277aa8ac475b6df61bffd95665d86aac6eb2ad187b90bf42a98f5f2a11a3

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 13 ، از جمله گزینه های API عمومی پیشنهادی برای API که به طور مشروط در Android 13 مسدود شده اند ، به به روزرسانی در محدودیت های رابط غیر SDK در Android 13 مراجعه کنید.

اندروید 12

برای Android 12 (API سطح 31) ، می توانید پرونده زیر را که توصیف تمام رابط های غیر SDK و لیست های مربوطه آنها است ، بارگیری کنید:

پرونده: hiddenapi-flags.csv

SHA-256 Checksum: 40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 12 ، از جمله گزینه های API عمومی پیشنهادی برای API که به طور مشروط در Android 12 مسدود شده اند ، به تغییرات لیست برای Android 12 مراجعه کنید.

اندروید 11

برای Android 11 (API سطح 30) ، می توانید پرونده زیر را که توصیف تمام رابط های غیر SDK و لیست های مربوطه آنها است ، بارگیری کنید:

پرونده: hiddenapi-flags.csv

SHA-256 Checksum: a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 11 ، از جمله گزینه های API عمومی پیشنهادی برای API که به طور مشروط در Android 11 مسدود شده اند ، به تغییرات لیست برای Android 11 مراجعه کنید.

اندروید 10

برای Android 10 (API سطح 29) ، می توانید پرونده زیر را که توصیف تمام رابط های غیر SDK و لیست های مربوطه آنها است ، بارگیری کنید:

پرونده: hiddenapi-flags.csv

SHA-256 Checksum: f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb

برای کسب اطلاعات بیشتر در مورد تغییرات لیست API غیر SDK در Android 10 ، از جمله گزینه های API عمومی پیشنهادی برای API که به طور مشروط در Android 10 مسدود شده اند ، به تغییرات لیست برای Android 10 مراجعه کنید.

اندروید 9

برای Android 9 (API سطح 28) ، پرونده متنی زیر شامل لیست API های غیر SDK است که محدود نیستند (Greylisted): hiddenapi-light-greylist.txt .

لیست بلوک ( blacklist ) و لیست API های مسدود شده مشروط (لیست Darkgrey) در زمان ساخت به دست می آیند.

لیست هایی از AOSP ایجاد کنید

هنگام کار با AOSP ، می توانید یک پرونده hiddenapi-flags.csv ایجاد کنید که شامل تمام رابط های غیر SDK و لیست های مربوطه آنها باشد. برای انجام این کار ، منبع AOSP را بارگیری کرده و سپس دستور زیر را اجرا کنید:

m out/soong/hiddenapi/hiddenapi-flags.csv

سپس می توانید پرونده را در مکان زیر پیدا کنید:

out/soong/hiddenapi/hiddenapi-flags.csv

رفتار پیش بینی شده در هنگام دسترسی به رابط های غیر SDK محدود

در جدول زیر رفتاری که می توانید انتظار داشته باشید در صورت تلاش برای دسترسی به یک رابط غیر SDK که بخشی از لیست بلوک است ، توصیف می کند.

وسیله دسترسی نتیجه
دستورالعمل Dalvik با مراجعه به یک زمینه NoSuchFieldError پرتاب شد
دستورالعمل Dalvik با مراجعه به یک روش NoSuchMethodError پرتاب شد
بازتاب با استفاده از Class.getDeclaredField() یا Class.getField() NoSuchFieldException پرتاب شد
بازتاب با استفاده از Class.getDeclaredMethod() ، Class.getMethod() NoSuchMethodException پرتاب شد
بازتاب با استفاده از Class.getDeclaredFields() ، Class.getFields() اعضای غیر SDK در نتیجه نیستند
بازتاب با استفاده از Class.getDeclaredMethods() ، Class.getMethods() اعضای غیر SDK در نتیجه نیستند
JNI با استفاده از env->GetFieldID() NULL بازگشت ، NoSuchFieldError پرتاب شد
JNI با استفاده از env->GetMethodID() NULL برگشت ، NoSuchMethodError پرتاب شد

برنامه خود را برای رابط های غیر SDK آزمایش کنید

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

با استفاده از یک برنامه اشکال زدایی تست کنید

شما می توانید با ایجاد و اجرای یک برنامه اشکال زدایی بر روی یک دستگاه یا شبیه ساز که Android 9 (API سطح 28) یا بالاتر را اجرا می کند ، برای رابط های غیر SDK آزمایش کنید. اطمینان حاصل کنید که دستگاه یا شبیه ساز که از آن استفاده می کنید با سطح API هدف برنامه خود مطابقت دارد.

در حالی که از طریق تست های روی برنامه خود اجرا می شود ، اگر برنامه شما به برخی از رابط های غیر SDK دسترسی پیدا کند ، سیستم پیام ورود به سیستم را چاپ می کند. برای یافتن جزئیات زیر می توانید پیام های ورود به سیستم خود را بازرسی کنید:

  • کلاس ، نام و نوع اعلام کننده (در فرمی که توسط زمان اجرا Android استفاده می شود).
  • وسایل دسترسی: یا پیوند دادن ، استفاده از بازتاب ، یا استفاده از JNI.
  • که لیست رابط غیر SDK متعلق به آن است.

برای دسترسی به این پیام های ورود به سیستم ، که در زیر PID برنامه در حال اجرا ظاهر می شوند ، می توانید از adb logcat استفاده کنید. به عنوان مثال ، یک ورود در ورود به سیستم ممکن است به شرح زیر باشد:

Accessing hidden field Landroid/os/Message;->flags:I (light greylist, JNI)

با استفاده از API StrictMode آزمایش کنید

همچنین می توانید با استفاده از API StrictMode برای رابط های غیر SDK تست کنید. برای فعال کردن این روش از روش detectNonSdkApiUsage استفاده کنید. پس از فعال کردن API StrictMode ، می توانید با استفاده از یک penaltyListener ، در جایی که می توانید حمل و نقل سفارشی را انجام دهید ، می توانید برای هر استفاده از یک رابط غیر SDK پاسخ دهید. شیء Violation ارائه شده در پاسخ به تماس از Throwable ناشی می شود ، و ردیابی پشته محصور زمینه استفاده را فراهم می کند.

با استفاده از ابزار Veridex آزمایش کنید

همچنین می توانید ابزار تجزیه و تحلیل استاتیک Veridex را در APK خود اجرا کنید. ابزار Veridex کل پایگاه کد APK ، از جمله هر کتابخانه شخص ثالث را اسکن می کند و از هرگونه استفاده از رابط های غیر SDK که می یابد گزارش می دهد.

محدودیت های ابزار Veridex شامل موارد زیر است:

  • این نمی تواند دعوت ها را از طریق JNI تشخیص دهد.
  • این تنها می تواند زیر مجموعه ای از دعوت ها را از طریق بازتاب تشخیص دهد.
  • تجزیه و تحلیل آن برای مسیرهای کد غیرفعال محدود به بررسی های سطح API است.
  • این فقط می تواند بر روی ماشینهایی که از دستورالعمل های SSE4.2 و POPCNT پشتیبانی می کنند ، اجرا شود.

ویندوز

باینری های بومی ویندوز ارائه نشده است ، اما می توانید با اجرای باینری های لینوکس با استفاده از زیر سیستم ویندوز برای لینوکس (WSL) ، ابزار Veridex را روی ویندوز اجرا کنید. قبل از دنبال کردن مراحل موجود در این بخش ، WSL را نصب کرده و Ubuntu را به عنوان توزیع لینوکس خود انتخاب کنید.

پس از نصب اوبونتو ، یک ترمینال اوبونتو را راه اندازی کرده و سپس این مراحل را دنبال کنید:

  1. ابزار Veridex را از مخزن Preuilts Android Runtime بارگیری کنید.
  2. محتویات پرونده appcompat.tar.gz را استخراج کنید.
  3. در پوشه استخراج شده ، پرونده veridex-linux.zip را پیدا کرده و آن را استخراج کنید.

  4. به پوشه بدون فشار بروید و سپس دستور زیر را اجرا کنید ، جایی که your-app.apk APK است که می خواهید آزمایش کنید:

    ./appcompat.sh --dex-file=your-app.apk

macOS

برای اجرای ابزار Veridex در MACOS ، این مراحل را دنبال کنید:

  1. ابزار Veridex را از مخزن Preuilts Android Runtime بارگیری کنید.
  2. محتویات پرونده appcompat.tar.gz را استخراج کنید.
  3. در پوشه استخراج شده ، پرونده veridex-mac.zip را پیدا کرده و آن را استخراج کنید.

  4. به پوشه در حالت فشرده بروید و سپس دستور زیر را اجرا کنید ، جایی که /path-from-root/your-app.apk مسیری برای APK است که می خواهید آزمایش کنید ، از فهرست اصلی سیستم خود شروع کنید:

    ./appcompat.sh --dex-file=/path-from-root/your-app.apk

لینوکس

برای اجرای ابزار Veridex در لینوکس ، این مراحل را دنبال کنید:

  1. ابزار Veridex را از مخزن Preuilts Android Runtime بارگیری کنید.
  2. محتویات پرونده appcompat.tar.gz را استخراج کنید.
  3. در پوشه استخراج شده ، پرونده veridex-linux.zip را پیدا کرده و آن را استخراج کنید.

  4. به پوشه بدون فشار بروید و سپس دستور زیر را اجرا کنید ، جایی که your-app.apk APK است که می خواهید آزمایش کنید:

    ./appcompat.sh --dex-file=your-app.apk

با استفاده از ابزار Android Studio Lint تست کنید

هر زمان که برنامه خود را در Android Studio بسازید ، ابزار LINT کد شما را برای مشکلات احتمالی بازرسی می کند. اگر برنامه شما از رابط های غیر SDK استفاده می کند ، بسته به اینکه لیست آن رابط ها به کدام لیست تعلق دارند ، ممکن است خطاها یا هشدارها را مشاهده کنید.

همچنین می توانید ابزار LINT را از خط فرمان اجرا کنید یا بازرسی ها را به صورت دستی بر روی یک پروژه ، پوشه یا پرونده خاص اجرا کنید .

با استفاده از کنسول بازی تست کنید

هنگامی که برنامه خود را در یک آهنگ تست در کنسول Play بارگذاری می کنید ، برنامه شما به طور خودکار برای مشکلات احتمالی آزمایش می شود و گزارش قبل از راه اندازی تولید می شود. اگر برنامه شما از رابط های غیر SDK استفاده می کند ، بسته به اینکه لیست آن رابط ها به کدام لیست تعلق دارند ، خطایی یا هشدار دهنده در گزارش قبل از راه اندازی.

برای اطلاعات بیشتر ، به بخش سازگاری Android در استفاده از گزارش های قبل از راه اندازی برای شناسایی مسائل مراجعه کنید.

درخواست یک API عمومی جدید

اگر نمی توانید جایگزینی برای استفاده از رابط غیر SDK برای یک ویژگی در برنامه خود پیدا کنید ، می توانید با ایجاد یک درخواست ویژگی در ردیاب شماره ما ، یک API عمومی جدید درخواست کنید.

هنگام ایجاد درخواست ویژگی ، اطلاعات زیر را ارائه دهید:

  • کدام API پشتیبانی نشده شما استفاده می کنید ، از جمله توصیف کننده کامل که در پیام Accessing hidden ... LogCat مشاهده شده است.
  • چرا شما نیاز به استفاده از این API ها دارید ، از جمله جزئیات مربوط به ویژگی سطح بالا که API برای آن لازم است ، نه فقط جزئیات سطح پایین.
  • چرا هر API های SDK عمومی مرتبط برای اهداف شما کافی نیستند.
  • هر گزینه دیگری که امتحان کرده اید و چرا اینها نتیجه ای نداشته است.

هنگامی که این جزئیات را در درخواست ویژگی خود ارائه می دهید ، احتمال دریافت API عمومی جدید را افزایش می دهید.

سوالات دیگر

این بخش شامل برخی از پاسخ ها به سایر سؤالات است که توسعه دهندگان اغلب از آنها خواسته شده است:

سوالات عمومی

چگونه می تواند Google مطمئن باشد که آنها می توانند نیازهای همه برنامه ها را از طریق Ispuetracker ضبط کنند؟

ما لیست های اولیه را برای Android 9 (API سطح 28) از طریق تجزیه و تحلیل استاتیک برنامه هایی که با استفاده از روش های زیر تکمیل شده اند ایجاد کردیم:

  • تست دستی برنامه های برتر بازی و غیر بازی
  • گزارش های داخلی
  • جمع آوری خودکار داده ها از کاربران داخلی
  • گزارش های پیش نمایش توسعه دهنده
  • تجزیه و تحلیل استاتیک اضافی که برای محافظه کارانه شامل مثبت های کاذب تر است

همانطور که لیست های مربوط به هر نسخه جدید را ارزیابی می کنیم ، استفاده از API و همچنین بازخورد توسعه دهنده را از طریق ردیاب شماره در نظر می گیریم.

چگونه می توانم دسترسی به رابط های غیر SDK را فعال کنم؟

با استفاده از دستورات ADB برای تغییر سیاست اجرای API می توانید دسترسی به رابط های غیر SDK را در دستگاه های توسعه فعال کنید. دستوراتی که از آنها استفاده می کنید ، بسته به سطح API متفاوت است. این دستورات به دستگاه ریشه دار احتیاج ندارند.

Android 10 (API سطح 29) یا بالاتر

برای فعال کردن دسترسی ، از ADB زیر استفاده کنید

دستور:

adb shell settings put global hidden_api_policy  1

برای تنظیم مجدد خط مشی اجرای API در تنظیمات پیش فرض ، از دستور زیر استفاده کنید:

adb shell settings delete global hidden_api_policy
Android 9 (سطح API 28)

برای فعال کردن دسترسی ، از دستورات ADB زیر استفاده کنید:

adb shell settings put global hidden_api_policy_pre_p_apps  1
adb shell settings put global hidden_api_policy_p_apps 1

برای تنظیم مجدد خط مشی اجرای API در تنظیمات پیش فرض ، از دستورات زیر استفاده کنید: 

adb shell settings delete global hidden_api_policy_pre_p_apps
adb shell settings delete global hidden_api_policy_p_apps

شما می توانید عدد صحیح را در سیاست اجرای API بر روی یکی از مقادیر زیر تنظیم کنید:

  • 0: تمام تشخیص رابط های غیر SDK را غیرفعال کنید. با استفاده از این تنظیم ، تمام پیام های ورود به سیستم برای استفاده از رابط غیر SDK را غیرفعال می کند و از آزمایش برنامه خود با استفاده از API StrictMode جلوگیری می کند. این تنظیم توصیه نمی شود.
  • 1: دسترسی به تمام رابط های غیر SDK را فعال کنید ، اما پیام های ورود به سیستم را با هشدارهایی برای هرگونه استفاده از رابط غیر SDK چاپ کنید. استفاده از این تنظیم همچنین به شما امکان می دهد برنامه خود را با استفاده از API StrictMode تست کنید.
  • 2: استفاده از رابط های غیر SDK را که متعلق به بلوک هستند یا برای سطح API هدف شما مسدود شده اند ، مجاز نیست.

سؤالات مربوط به لیست رابط غیر SDK

از کجا می توانم لیست های API غیر SDK را در تصویر سیستم پیدا کنم؟

آنها در Field و Method Access Bits در پرونده های Platform DEX رمزگذاری شده اند. هیچ پرونده جداگانه ای در تصویر سیستم وجود ندارد که شامل این لیست ها باشد.

آیا API غیر SDK در دستگاه های مختلف OEM با همان نسخه های Android یکسان است؟

OEM ها می توانند رابط های خود را به لیست بلوک (لیست سیاه) اضافه کنند ، اما آنها نمی توانند رابط ها را از لیست API غیر SDK AOSP حذف کنند. CDD از چنین تغییراتی جلوگیری می کند و تست های CTS اطمینان حاصل می کند که زمان اجرا Android لیست را اجرا می کند.

آیا محدودیتی در رابط های غیر NDK در کد بومی وجود دارد؟

Android SDK شامل رابط های جاوا است. این پلتفرم شروع به محدود کردن دسترسی به رابط های غیر NDK برای کد C/C ++ بومی در Android 7 (API سطح 26) کرد. برای اطلاعات بیشتر ، به بهبود ثبات با محدودیت های نماد خصوصی C/C ++ در Android n مراجعه کنید.

آیا برنامه ای برای محدود کردن دستکاری پرونده dex2oat یا dex وجود دارد؟

ما برنامه های فعال برای محدود کردن دسترسی به دودویی Dex2oat نداریم ، اما ما قصد نداریم که فرمت پرونده DEX پایدار باشد یا یک رابط عمومی فراتر از بخش هایی که در قالب اجرایی Dalvik مشخص شده اند. ما این حق را داریم که Dex2oat و بخش های نامشخص از فرمت DEX را در هر زمان تغییر یا از بین ببریم. همچنین توجه داشته باشید که پرونده های مشتق شده تولید شده توسط Dex2oat مانند ODEX (همچنین به عنوان OAT نیز شناخته می شوند) ، VDEX و CDEX همه قالب های نامشخص هستند.

چه می شود اگر یک SDK شخص ثالث مهم (به عنوان مثال ، یک obfuscator) نتواند از استفاده از رابط های غیر SDK خودداری کند ، اما متعهد به حفظ سازگاری با نسخه های اندرویدی آینده است؟ آیا اندروید می تواند در این حالت از الزامات سازگاری خود چشم پوشی کند؟

ما برنامه ای نداریم که بر اساس هر SDK از الزامات سازگاری چشم پوشی کنیم. اگر یک توسعه دهنده SDK فقط بسته به رابط های موجود در لیست های پشتیبانی نشده (که قبلاً خاکستری) است ، می تواند سازگاری را حفظ کند ، آنها باید برنامه ریزی مهاجرت به رابط های SDK یا گزینه های دیگر را آغاز کنند و هر زمان که نتوانند جایگزینی برای استفاده از رابط غیر SDK پیدا کنند.

آیا محدودیت های رابط غیر SDK برای کلیه برنامه ها از جمله برنامه های سیستم و شخص اول ، نه فقط برنامه های شخص ثالث اعمال می شود؟

بله ، با این حال ، ما برنامه های امضا شده با کلید Platform و برخی از برنامه های تصویر سیستم را معاف می کنیم. توجه داشته باشید که این معافیت ها فقط در مورد برنامه هایی که بخشی از تصویر سیستم هستند (یا برنامه های به روز شده سیستم تصویر) اعمال می شود. این لیست فقط برای برنامه هایی که در برابر API های پلت فرم خصوصی ساخته می شوند ، به جای API های SDK (جایی که LOCAL_PRIVATE_PLATFORM_APIS := true ) در نظر گرفته شده است.