پس از ایجاد میانبرها، ممکن است لازم باشد آنها را در طول عمر برنامه خود مدیریت کنید. به عنوان مثال، ممکن است بخواهید با تعیین اینکه کاربران شما چند وقت یکبار اقدامات خاصی را با میانبرهای شما انجام میدهند، برنامه خود را بهینه کنید. در مورد دیگر، ممکن است تصمیم بگیرید یک میانبر پین شده را غیرفعال کنید تا از انجام اقدامات قدیمی یا از دست رفته برنامه خود جلوگیری کنید. برای میانبرهایی که در مکالمات به آنها اشاره شده است، ممکن است بخواهید میزان استفاده را پیگیری کنید تا سیگنالهایی ارائه دهید که رتبهبندی میانبرها را بهبود بخشد.
این صفحه این روشها و چندین روش رایج دیگر برای مدیریت میانبرها را شرح میدهد.
رفتار میانبر
بخشهای زیر شامل اطلاعات کلی در مورد رفتار میانبرها، از جمله میزان دیده شدن، ترتیب نمایش و رتبهبندیها است.
قابلیت مشاهده میانبر
میانبرهای ایستا و پویا در یک لانچر یا دستیار پشتیبانیشده، زمانی ظاهر میشوند که کاربر یک حرکت یا فرمان صوتی خاص را انجام دهد. در لانچرهای پشتیبانیشده، این حرکت با لمس و نگهداشتن آیکون لانچر برنامه انجام میشود، اما این حرکت ممکن است در سایر برنامههای لانچر متفاوت باشد. با دستیار گوگل، میانبرها میتوانند در داخل دستیار نمایش داده شوند یا از طریق فرمان صوتی کاربر اجرا شوند.
کلاس LauncherApps رابطهای برنامهنویسی کاربردی (API) را برای دسترسی برنامههای لانچر به میانبرها فراهم میکند.
از آنجا که میانبرهای پین شده در خود لانچر ظاهر میشوند، همیشه قابل مشاهده هستند. یک میانبر پین شده فقط در شرایط زیر از لانچر حذف میشود:
- کاربر آن را حذف میکند.
- برنامه مرتبط با میانبر حذف نصب شده است.
- کاربر با رفتن به تنظیمات > برنامهها و اعلانها ، انتخاب برنامه و سپس ضربه زدن روی ذخیرهسازی > پاک کردن فضای ذخیرهسازی ، دادههای برنامه را پاک میکند.
اهداف اشتراکگذاری زیرمجموعهای از میانبرهای پویا هستند که در ردیف اشتراکگذاری مستقیم در برگه اشتراکگذاری اندروید ظاهر میشوند.
ترتیب نمایش میانبرها
وقتی لانچر میانبرهای یک برنامه را نمایش میدهد، آنها باید به ترتیب زیر ظاهر شوند:
- میانبرهای استاتیک : میانبرهایی که متد
isDeclaredInManifest()آنهاtrueرا برمیگرداند. - میانبرهای پویا : میانبرهایی که متد
ShortcutInfo.isDynamic()آنهاtrueرا برمیگرداند.
در هر نوع میانبر - استاتیک و پویا - میانبرها به ترتیب افزایش رتبه بر اساس ShortcutInfo.getRank مرتب میشوند. دستیار گوگل همچنین هنگام تعیین میانبرهای متنی برای نمایش به کاربران، رتبه میانبر را در نظر میگیرد.
رتبهها اعداد صحیح غیر منفی و متوالی هستند. میانبرهای استاتیک از اولین تا آخرین به ترتیبی که در فایل shortcuts.xml شما ظاهر میشوند، رتبهبندی میشوند. برای میانبرهای پویا، میتوانید رتبههای میانبرهای موجود را با فراخوانی updateShortcuts(Context, List) ، addDynamicShortcuts(Context, List) ، pushDynamicShortcut(Context, ShortcutInfoCompat) یا setDynamicShortcuts(Context, List) بهروزرسانی کنید.
ترتیب اهداف اشتراکگذاری بر اساس عوامل مختلفی از جمله سابقه کاربر قبلی، تازگی، فراوانی، اشاره به رتبه ، میزان استفاده از برنامه و اولویت تعیینشده برای مکالمه مرتبط با یک میانبر اشتراکگذاری است. اهداف اشتراکگذاری ایجاد شده با استفاده از API میانبرهای اشتراکگذاری نسبت به اهداف اشتراکگذاری تولید شده توسط ChooserTargetService که در اندروید ۱۱ منسوخ شده است، اولویتبندی میشوند. در اندروید ۱۲ و بالاتر، اهداف اشتراکگذاری تولید شده توسط ChooserTargetService منسوخ شده دیگر در برگه اشتراکگذاری ظاهر نمیشوند.
اکثر لانچرها حداکثر چهار میانبر نمایش میدهند. برای هر ترکیبی از میانبرهای ایستا و میانبرهای پویا که تعریف شدهاند، لانچر حداکثر دو میانبر ایستا و دو میانبر پویا نمایش میدهد. برای مثال، اگر چهار میانبر ایستا تعریف کنید و به صورت برنامهنویسی سه میانبر پویا ایجاد کنید، لانچر دو میانبر ایستا اول و دو میانبر پویا با رتبهبندی بالا را نمایش میدهد.
مدیریت چندین هدف و فعالیت
اگر میخواهید برنامه شما هنگام فعال کردن یک میانبر توسط کاربر، چندین عملیات را انجام دهد، میتوانید آن را طوری پیکربندی کنید که فعالیتهای متوالی را آغاز کند. میتوانید این کار را با اختصاص چندین اینتنت، شروع یک فعالیت از فعالیت دیگر یا تنظیم پرچمهای اینتنت، بسته به نوع میانبر، انجام دهید.
شروع یک فعالیت از فعالیت دیگر
میانبرهای ایستا نمیتوانند پرچمهای اینتنت سفارشی داشته باشند. اولین اینتنت یک میانبر ایستا همیشه دارای Intent.FLAG_ACTIVITY_NEW_TASK و Intent.FLAG_ACTIVITY_CLEAR_TASK است. این بدان معناست که وقتی برنامه شما در حال اجرا است، تمام اکتیویتیهای موجود در برنامه با راهاندازی یک میانبر ایستا از بین میروند. اگر این رفتار را نمیخواهید، میتوانید از یک اکتیویتی ترامپولین - یک اکتیویتی نامرئی که اکتیویتی دیگری را شروع میکند - با فراخوانی finish درون یک بلوک راهاندازی یا onCreate قبل از تنظیم محتوای Compose استفاده کنید:
در
AndroidManifest.xml file، به activity مربوط به trampoline، ویژگیandroid:taskAffinity=""را اختصاص دهید.در فایل منبع میانبرها، اکتیویتی ترامپولین را در اینتنت درون میانبر استاتیک ارجاع دهید.
برای اطلاعات بیشتر در مورد فعالیتهای ترامپولین، به بخش شروع یک فعالیت از فعالیت دیگر مراجعه کنید.
پرچمهای هدف را تنظیم کنید
شما میتوانید میانبرهای پویا را با هر مجموعهای از پرچمهای Intent منتشر کنید. ترجیحاً، ترکیب Intent.FLAG_ACTIVITY_SINGLE_TOP و Intent.FLAG_ACTIVITY_CLEAR_TOP را در intent میانبر مشخص کنید. این تضمین میکند که اگر ComponentActivity شما از قبل فعال باشد، به پیشزمینه آورده شده و بدون از بین رفتن، دوباره استفاده میشود و به معماری تکفعالیتی شما اجازه میدهد تا رویداد میانبر را از طریق onNewIntent() به طرز شایستهای مدیریت کند.
برای کسب اطلاعات بیشتر در مورد وظایف و پرچمهای اینتنت، به بخش وظایف و پشته پشتی مراجعه کنید.
بهروزرسانی میانبرها
آیکون لانچر هر برنامه حداکثر میتواند شامل تعدادی میانبر استاتیک و دینامیک باشد که با مقداری که getMaxShortcutCountPerActivity برمیگرداند، برابر است. هیچ محدودیتی برای تعداد میانبرهای پینشدهای که یک برنامه میتواند ایجاد کند، وجود ندارد.
وقتی یک میانبر پویا پین میشود، حتی وقتی ناشر آن را به عنوان یک میانبر پویا حذف میکند، میانبر پین شده همچنان قابل مشاهده و اجرا است. این به یک برنامه اجازه میدهد تا تعداد میانبرهای بیشتری از getMaxShortcutCountPerActivity داشته باشد.
مثال زیر را در نظر بگیرید که فرض میکند مقدار برگردانده شده توسط getMaxShortcutCountPerActivity 4 است:
- یک برنامه چت چهار میانبر پویا منتشر میکند که نشاندهنده چهار مکالمه اخیر است: c1، c2، c3 و c4.
- کاربر هر چهار میانبر را پین میکند.
- بعداً، کاربر سه مکالمه اضافی را شروع میکند: c5، c6 و c7. برنامه ناشر میانبرهای پویای خود را دوباره منتشر میکند. لیست میانبرهای پویای جدید عبارتند از: c4، c5، c6 و c7.
این برنامه باید c1، c2 و c3 را حذف کند، زیرا نمیتواند بیش از چهار میانبر پویا را نمایش دهد. با این حال، c1، c2 و c3 هنوز میانبرهای پین شدهای هستند که کاربر میتواند به آنها دسترسی پیدا کرده و آنها را اجرا کند.
سپس کاربر میتواند در مجموع به هفت میانبر که به فعالیتهای موجود در برنامه ناشر پیوند دارند، دسترسی داشته باشد. دلیل این امر این است که این مجموع شامل حداکثر تعداد میانبرها و سه میانبر پین شده است.
- این برنامه میتواند از
updateShortcuts(Context, List)برای بهروزرسانی هر یک از هفت میانبر موجود استفاده کند. برای مثال، میتوانید این مجموعه از میانبرها را هنگامی که آیکونهای همتایان چت تغییر میکنند، بهروزرسانی کنید. - شما میتوانید از متدهای
addDynamicShortcuts(Context, List)وsetDynamicShortcuts(Context, List)برای بهروزرسانی میانبرهای موجود با شناسههای یکسان استفاده کنید. با این حال، نمیتوانید از آنها برای بهروزرسانی میانبرهای غیرپویا و پینشده استفاده کنید، زیرا این دو متد سعی میکنند لیستهای دادهشده از میانبرها را به میانبرهای پویا تبدیل کنند.
محدودیتی برای تعداد میانبرهایی که میتوانند برای نمایش در برنامههای دستیار مانند دستیار گوگل (Google Assistant) نمایش داده شوند، وجود ندارد. از متد pushDynamicShortcut از کتابخانه ShortcutManagerCompat Jetpack برای ایجاد و بهروزرسانی میانبرها برای استفاده در برنامههای دستیار استفاده کنید. همچنین، کتابخانه Google Shortcuts Integration را به برنامه خود اضافه کنید تا پیوندهای پویا برای نمایش در دستیار گوگل واجد شرایط شوند.
برای کسب اطلاعات بیشتر در مورد دستورالعملهای مربوط به میانبرهای برنامه، از جمله بهروزرسانی میانبرها، به بهترین شیوهها برای میانبرها مراجعه کنید.
مدیریت تغییرات محلی سیستم
برنامهها باید میانبرهای پویا و پینشده را هنگام دریافت اعلان Intent.ACTION_LOCALE_CHANGED که نشاندهنده تغییر در زبان سیستم است، بهروزرسانی کنند.
پیگیری استفاده از میانبرها
برای تعیین موقعیتهایی که میانبرهای ایستا و پویا در آنها ظاهر میشوند، لانچر تاریخچهی فعالسازی میانبرها را بررسی میکند. برای میانبرهای ایستا، میتوانید با فراخوانی متد reportShortcutUsed و ارسال شناسهی یک میانبر به آن، در صورت وقوع هر یک از رویدادهای زیر، پیگیری کنید که کاربران چه زمانی اقدامات خاصی را در برنامهی شما انجام میدهند:
- کاربر میانبری را با شناسه داده شده انتخاب میکند.
- در داخل برنامه، کاربر به صورت دستی عمل مربوط به همان میانبر را انجام میدهد.
برنامه شما با فراخوانی متد pushDynamicShortcut و ارسال شناسه میانبر به آن، میزان استفاده از میانبرهای پویا را هنگام وقوع یک رویداد مرتبط، ردیابی میکند. ارسال میزان استفاده از میانبرهای پویا با این متد، به برنامههای دستیار مانند دستیار گوگل اجازه میدهد تا میانبرهای مرتبط را به کاربران پیشنهاد دهند. از آنجایی که متد pushDynamicShortcut هنگام فراخوانی، میزان استفاده را گزارش میدهد، متد reportShortcutUsed برای همان میانبرها فراخوانی نکنید.
برای میانبرهای مربوط به مکالمه، پیگیری میزان استفاده از آنها برای پیامهای خروجی و ورودی مهم است. برای جزئیات بیشتر، به بهترین شیوهها برای افراد و مکالمات مراجعه کنید.
غیرفعال کردن میانبرها
از آنجا که برنامه شما و کاربران آن میتوانند میانبرها را به لانچر دستگاه پین کنند، این امکان وجود دارد که این میانبرهای پین شده، کاربران را به سمت اقداماتی در برنامه شما که قدیمی هستند یا دیگر وجود ندارند، هدایت کنند. برای مدیریت این وضعیت، میتوانید میانبرهایی را که نمیخواهید کاربران انتخاب کنند، با فراخوانی disableShortcuts غیرفعال کنید، که میانبرهای مشخص شده را از لیست میانبرهای ایستا و پویا حذف کرده و کپیهای پین شده از این میانبرها را غیرفعال میکند. همچنین میتوانید از یک نسخه بارگذاری شده از این روش استفاده کنید که CharSequence به عنوان یک پیام خطای سفارشی میپذیرد. سپس این پیام خطا هنگامی که کاربران سعی میکنند هر میانبر غیرفعال شدهای را اجرا کنند، ظاهر میشود.
محدود کردن نرخ
هنگام استفاده از متدهای setDynamicShortcuts, addDynamicShortcuts یا updateShortcuts ، ممکن است فقط بتوانید تعداد دفعات مشخصی این متدها را در یک برنامه پسزمینه - برنامهای که هیچ فعالیت یا سرویسی در پیشزمینه ندارد - فراخوانی کنید. محدودیت تعداد دفعات مشخصی که میتوانید این متدها را فراخوانی کنید، محدودیت نرخ (rate limiting) نامیده میشود. این ویژگی از مصرف بیش از حد منابع دستگاه ShortcutManagerCompat جلوگیری میکند.
وقتی محدودیت نرخ فعال باشد، isRateLimitingActive مقدار true را برمیگرداند. با این حال، محدودیت نرخ در طول رویدادهای خاصی مجدداً تنظیم میشود، بنابراین حتی برنامههای پسزمینه نیز میتوانند تا رسیدن دوباره به محدودیت نرخ، متدهای ShortcutManager را فراخوانی کنند. این رویدادها شامل موارد زیر هستند:
- یک برنامه به پیش زمینه می آید.
- محل سیستم تغییر میکند.
- کاربر عمل پاسخ درونخطی را روی یک اعلان انجام میدهد.
اگر در حین توسعه یا آزمایش با محدودیت سرعت مواجه شدید، میتوانید از تنظیمات دستگاه، گزینه Developer Options > Reset ShortcutManager rate-limiting را انتخاب کنید، یا میتوانید دستور زیر را در adb وارد کنید:
$ adb shell cmd shortcut reset-throttling [ --user <var>your-user-id</var> ]
پشتیبان گیری و بازیابی
شما میتوانید با اضافه کردن ویژگی android:allowBackup="true" به فایل مانیفست برنامهتان، به کاربران اجازه دهید هنگام تغییر دستگاه، عملیات پشتیبانگیری و بازیابی را در برنامهتان انجام دهند. اگر از پشتیبانگیری و بازیابی پشتیبانی میکنید، نکات زیر را در مورد میانبرهای برنامه در نظر داشته باشید:
- میانبرهای استاتیک به طور خودکار دوباره منتشر میشوند، اما تنها پس از اینکه کاربر برنامه شما را دوباره روی دستگاه جدید نصب کند.
- میانبرهای پویا پشتیبانگیری نمیشوند، بنابراین منطقی را در برنامه خود بگنجانید تا وقتی کاربری برنامه شما را در دستگاه جدیدی باز میکند، آنها را دوباره منتشر کند.
- میانبرهای پینشده بهطور خودکار در لانچر دستگاه بازیابی میشوند، اما سیستم از آیکونهای مرتبط با میانبرهای پینشده پشتیبانگیری نمیکند. بنابراین، تصاویر میانبرهای پینشده خود را در برنامه خود ذخیره کنید تا بازیابی آنها در دستگاه جدید سریع باشد.
قطعه کد زیر نشان میدهد که چگونه میتوان میانبرهای پویای برنامه خود را بازیابی کرد و چگونه بررسی کرد که آیا میانبرهای پین شده برنامه شما حفظ شدهاند یا خیر:
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
if (ShortcutManagerCompat.getDynamicShortcuts(this).isEmpty()) {
// Application restored. Re-publish dynamic shortcuts.
if (ShortcutManagerCompat.getPinnedShortcuts(this).isNotEmpty()) {
// Pinned shortcuts are restored. Use updateShortcuts() to make
// sure they contain up-to-date information.
}
}
}
// ...
}