پس‌از ایجاد میان‌برها، ممکن است لازم باشد آن‌ها را در طول عمر برنامه‌تان مدیریت کنید. برای مثال، ممکن است بخواهید با تعیین اینکه کاربران شما چند وقت یک‌بار کنش‌های خاصی را با میان‌برهای شما تکمیل می‌کنند، برنامه‌تان را بهینه‌سازی کنید. در موردی دیگر، ممکن است تصمیم بگیرید میان‌بر سنجاق‌شده‌ای را غیرفعال کنید تا از انجام کنش‌های قدیمی یا مفقودشده توسط برنامه‌تان جلوگیری کنید. برای میان‌برهای ارجاع‌شده در مکالمه‌ها، شاید بخواهید استفاده را ردیابی کنید تا سیگنال‌هایی ارائه دهید که رتبه‌بندی میان‌بر را بهبود می‌بخشد.
این صفحه این روش‌ها و چند روش رایج دیگر را برای مدیریت میان‌برها شرح می‌دهد.
رفتار میان‌بر
بخش‌های زیر حاوی اطلاعات کلی درباره رفتار میان‌بر، ازجمله نمایان بودن، ترتیب نمایش، و رتبه‌بندی است.
نمایان بودن میان‌بر
میان‌برهای ایستا و میان‌برهای پویا در راه‌انداز یا دستیار پشتیبانی‌شده ظاهر می‌شوند وقتی کاربر اشاره یا فرمان صوتی خاصی را اجرا می‌کند. در راه‌اندازهای پشتیبانی‌شده، اشاره به‌صورت لمس کردن و نگه داشتن نماد راه‌انداز برنامه است، اما این اشاره ممکن است در دیگر برنامه‌های راه‌انداز متفاوت باشد. با «دستیار Google»، میان‌برها می‌توانند در «دستیار» نمایش داده شوند یا ازطریق فرمان صوتی کاربر راه‌اندازی شوند.
کلاس LauncherApps میاناهای برنامه‌سازی کاربردی را برای برنامه‌های راه‌انداز فراهم می‌کند تا به میان‌برها دسترسی داشته باشند.
چون میان‌برهای سنجاق‌شده در خود راه‌انداز نشان داده می‌شوند، همیشه قابل‌مشاهده هستند. میان‌بر سنجاق‌شده فقط در شرایط زیر از راه‌انداز برداشته می‌شود:
- کاربر آن را بردارد.
- برنامه مرتبط با میان‌بر حذف نصب شده است.
- کاربر با رفتن به تنظیمات > برنامه‌ها و اعلان‌ها، انتخاب برنامه، و سپس تک‌ضرب زدن روی فضای ذخیره‌سازی > پاک کردن فضای ذخیره‌سازی، داده‌های برنامه را پاک می‌کند.
هدف‌های هم‌رسانی زیرمجموعه‌ای از میان‌برهای پویا هستند که در ردیف هم‌رسانی مستقیم در برگه هم‌رسانی Android نشان داده می‌شوند.
ترتیب نمایش میان‌بر
وقتی راه‌انداز میان‌برهای برنامه را نمایش می‌دهد، این میان‌برها باید به‌ترتیب زیر نشان داده شوند:
- میان‌برهای ایستا: میان‌برهایی که روش
isDeclaredInManifest()آن‌هاtrueرا برمی‌گرداند. - میان‌برهای پویا: میان‌برهایی که روش
ShortcutInfo.isDynamic()آن‌هاtrueرا برمی‌گرداند.
در هر نوع میان‌بر (ایستا و پویا)، میان‌برها به‌ترتیب افزایش رتبه براساس ShortcutInfo.getRank مرتب می‌شوند. «دستیار Google»
هنگام تعیین میان‌برهای زمینه‌ای برای نمایش به کاربران،
رتبه میان‌بر را نیز درنظر می‌گیرد.
رتبه‌ها اعداد صحیح غیرمنفی و متوالی هستند. میان‌برهای ایستا از اول به آخر به‌ترتیبی که در فایل shortcuts.xml شما نشان داده می‌شوند رتبه‌بندی می‌شوند. برای میان‌برهای پویا، می‌توانید هنگام فراخوانی updateShortcuts(Context, List)، addDynamicShortcuts(Context,
List)، pushDynamicShortcut(Context, ShortcutInfoCompat)، یا setDynamicShortcuts(Context, List)، رتبه‌های میان‌برهای موجود را به‌روز کنید.
ترتیب هدف‌های هم‌رسانی براساس عوامل مختلفی ازجمله سابقه کاربر در گذشته،
تازگی، فراوانی، نکته رتبه‌بندی، استفاده از برنامه، و اولویت تنظیم‌شده در
مکالمه‌ای که با میان‌بر هم‌رسانی مرتبط است تعیین می‌شود. هدف‌های هم‌رسانی ایجادشده بااستفاده از Sharing Shortcuts API نسبت‌به هدف‌های هم‌رسانی تولیدشده توسط ChooserTargetService که در Android 11 منسوخ شده است اولویت دارند. در Android 12 و نسخه‌های بالاتر، هدف‌های هم‌رسانی تولیدشده توسط
ChooserTargetService منسوخ‌شده دیگر در برگه هم‌رسانی نشان داده نخواهد شد.
اکثر راه‌اندازها حداکثر چهار میان‌بر را نمایش می‌دهند. برای هر ترکیبی از میان‌برهای ایستا و میان‌برهای پویای تعریف‌شده، راه‌انداز حداکثر دو میان‌بر ایستا و دو میان‌بر پویا را نمایش می‌دهد. برای مثال، اگر چهار میان‌بر ایستا تعریف کنید و به‌صورت برنامه‌نویسی‌شده سه میان‌بر پویا ایجاد کنید، راه‌انداز دو میان‌بر ایستای اول و دو میان‌بر پویای دارای بالاترین رتبه را نمایش می‌دهد.
مدیریت چندین هدف و فعالیت
اگر می‌خواهید برنامه‌تان وقتی کاربر میان‌بری را فعال می‌کند چندین عملیات انجام دهد، می‌توانید آن را برای راه‌اندازی فعالیت‌های متوالی پیکربندی کنید. بسته به نوع میان‌بر، می‌توانید این کار را با اختصاص دادن چند هدف، شروع کردن یک فعالیت از فعالیتی دیگر، یا تنظیم پرچم‌های هدف انجام دهید.
شروع کردن یک فعالیت از فعالیتی دیگر
میان‌برهای ایستا نمی‌توانند پرچم‌های قصد سفارشی داشته باشند. اولین هدف میان‌بر ایستا همیشه دارای Intent.FLAG_ACTIVITY_NEW_TASK و Intent.FLAG_ACTIVITY_CLEAR_TASK است. این یعنی وقتی برنامه‌تان درحال اجرا است، همه فعالیت‌های موجود در برنامه هنگام راه‌اندازی میان‌بر ایستا ازبین می‌روند. اگر این رفتار را نمی‌خواهید، می‌توانید از فعالیت ترامپولین (فعالیت نامرئی که فعالیت دیگری را شروع می‌کند) با فراخوانی finish در بلوک راه‌اندازی یا onCreate قبل‌از تنظیم محتوای Compose استفاده کنید:
در
AndroidManifest.xml file، واگذاری مشخصهandroid:taskAffinity=""را در فعالیت جَستانه اضافه کنید.در فایل منبع میان‌برها، به فعالیت جَستانه در قصد درون میان‌بر ایستا ارجاع دهید.
برای اطلاعات بیشتر درباره فعالیت‌های ترامپولین، به شروع کردن یک فعالیت از فعالیتی دیگر مراجعه کنید.
تنظیم پرچم‌های هدف
می‌توانید میان‌برهای پویا را با هر مجموعه‌ای از پرچم‌های Intent منتشر کنید.
ترجیحاً، ترکیب Intent.FLAG_ACTIVITY_SINGLE_TOP و
Intent.FLAG_ACTIVITY_CLEAR_TOP را در قصد میان‌بر مشخص کنید. این کار تضمین می‌کند که اگر
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» ارسال شوند وجود ندارد. از روش pushDynamicShortcut
کتابخانه ShortcutManagerCompat Jetpack برای ایجاد و به‌روزرسانی
میان‌برها برای استفاده در برنامه‌های همیار استفاده کنید. همچنین، کتابخانه ادغام میان‌برهای Google را به برنامه‌تان اضافه کنید تا پیوندهای پویا واجدشرایط نمایش در «دستیار Google» شوند.
برای آشنایی بیشتر با دستورالعمل‌های میان‌برهای برنامه، ازجمله به‌روزرسانی میان‌برها، روال‌های مطلوب برای میان‌برها را ببینید.
مدیریت تغییرات منطقه زبانی سیستم
برنامه‌ها باید میان‌برهای پویا و سنجاق‌شده را هنگام دریافت
Intent.ACTION_LOCALE_CHANGED همه‌فرستی که نشان‌دهنده تغییر در زبان سیستم است، به‌روز کنند.
ردیابی استفاده از میان‌بر
برای تعیین موقعیت‌هایی که میان‌برهای پویا و ایستا در آن‌ها ظاهر می‌شوند،
راه‌انداز سابقه فعال‌سازی میان‌برها را بررسی می‌کند. برای میان‌برهای ایستا،
می‌توانید با فراخوانی روش reportShortcutUsed و ارسال شناسه میان‌بر به آن،
زمان تکمیل کنش‌های خاص توسط کاربران در برنامه‌تان را پیگیری کنید
وقتی یکی از رویدادهای زیر رخ می‌دهد:
- کاربر میان‌بر را با شناسه ارائه‌شده انتخاب می‌کند.
- درون برنامه، کاربر به‌طور دستی کنش مربوط به همان میان‌بر را تکمیل می‌کند.
برنامه شما با فراخوانی روش pushDynamicShortcut
و ارسال شناسه میان‌بر به آن درصورت وقوع رویداد مربوطه، استفاده از میان‌برهای پویا را ردیابی می‌کند.
بااستفاده از این روش، ارسال استفاده از میان‌بر پویا به برنامه‌های همیار مانند
«دستیار Google» امکان می‌دهد میان‌برهای مرتبط را به کاربران پیشنهاد دهند. چون
روش pushDynamicShortcut هنگام فراخوانی، استفاده را گزارش می‌کند،
روش reportShortcutUsed را برای همان میان‌برها فراخوانی نکنید.
برای میان‌برهای مربوط به مکالمه، مهم است که استفاده از پیام‌های ارسالی و دریافتی را ردیابی کنید. برای جزئیات، روال‌های مطلوب برای افراد و مکالمه‌ها را ببینید.
غیرفعال کردن میان‌برها
چون برنامه شما و کاربران آن می‌توانند میان‌برها را به راه‌انداز دستگاه سنجاق کنند،
ممکن است این میان‌برهای سنجاق‌شده کاربران را به کنش‌هایی در برنامه‌تان هدایت کنند
که قدیمی هستند یا دیگر وجود ندارند. برای مدیریت این وضعیت، می‌توانید
میان‌برهایی را که نمی‌خواهید کاربران انتخاب کنند با فراخوانی
disableShortcuts غیرفعال کنید، که میان‌برهای مشخص‌شده را از فهرست میان‌برهای ایستا
و پویا برمی‌دارد و نسخه‌های سنجاق‌شده این میان‌برها را غیرفعال می‌کند. همچنین می‌توانید از نسخه سربارگذاری‌شده این روش استفاده کنید که CharSequence را به‌عنوان پیام خطای سفارشی می‌پذیرد. سپس وقتی کاربران سعی می‌کنند میان‌بر غیرفعال‌شده‌ای را راه‌اندازی کنند،
آن پیام خطا نشان داده می‌شود.
محدودیت نرخ
هنگام استفاده از روش‌های setDynamicShortcuts, addDynamicShortcuts یا updateShortcuts، ممکن است فقط بتوانید این روش‌ها را تعداد دفعات مشخصی در یک برنامه پس‌زمینه (برنامه‌ای بدون فعالیت یا سرویس در پیش‌زمینه) فراخوانی کنید.
محدودیت تعداد دفعات مشخصی که می‌توانید این روش‌ها را فراخوانی کنید
محدودیت نرخ نامیده می‌شود. این ویژگی از مصرف بیش‌ازحد منابع دستگاه توسط ShortcutManagerCompat جلوگیری می‌کند.
وقتی محدودیت نرخ فعال باشد، isRateLimitingActive مقدار true را برمی‌گرداند.
بااین‌حال، محدودیت نرخ درطول رویدادهای خاصی بازنشانی می‌شود، بنابراین حتی برنامه‌های پس‌زمینه
می‌توانند روش‌های ShortcutManager را تا زمانی که محدودیت نرخ دوباره حاصل شود فراخوانی کنند. این
رویدادها شامل موارد زیر است:
- برنامه‌ای به پیش‌زمینه می‌آید.
- منطقه سیستم تغییر می‌کند.
- کاربر کنش پاسخ به‌خط را در اعلان انجام می‌دهد.
اگر درطول توسعه یا آزمایش با محدودیت نرخ مواجه شدید، می‌توانید
گزینه‌های توسعه‌دهندگان > بازنشانی محدودیت نرخ ShortcutManager را از تنظیمات
دستگاه انتخاب کنید، یا می‌توانید فرمان زیر را در adb وارد کنید:
adb shell cmd shortcut reset-throttling [ --user your-user-id ]
پشتیبان‌گیری و بازیابی
با گنجاندن تخصیص مشخصه 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.getShortcuts(this, ShortcutManagerCompat.FLAG_MATCH_PINNED).isNotEmpty()) { // Pinned shortcuts are restored. Use updateShortcuts() to make // sure they contain up-to-date information. } } } // ... }