میانبرها را مدیریت کنید

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

این صفحه این و چندین روش رایج دیگر برای مدیریت میانبرهای شما را شرح می دهد.

رفتار میانبر

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

دید میانبر

میانبرهای ایستا و میانبرهای پویا در راه‌انداز یا دستیار پشتیبانی‌شده زمانی که کاربر یک حرکت یا فرمان صوتی خاص را انجام می‌دهد ظاهر می‌شوند. در راه‌اندازهای پشتیبانی‌شده، ژست لمس و نگه‌داشتن روی نماد راه‌انداز برنامه است، اما این حرکت ممکن است در سایر برنامه‌های راه‌انداز متفاوت باشد. با Google Assistant، میانبرها را می توان در دستیار نمایش داد یا از طریق فرمان صوتی کاربر راه اندازی شد.

کلاس LauncherApps API هایی را برای برنامه های راه انداز برای دسترسی به میانبرها فراهم می کند.

از آنجا که میانبرهای پین شده در خود راه‌انداز ظاهر می‌شوند، همیشه قابل مشاهده هستند. یک میانبر پین شده فقط در شرایط زیر از راه‌انداز حذف می‌شود:

• کاربر آن را حذف می کند.
• برنامه مرتبط با میانبر حذف نصب شده است.
• کاربر با رفتن به تنظیمات > برنامه‌ها و اعلان‌ها ، انتخاب برنامه، سپس روی Storage > Clear Storage، داده‌های یک برنامه را پاک می‌کند.

اهداف اشتراک گذاری زیرمجموعه ای از میانبرهای پویا هستند که در ردیف اشتراک گذاری مستقیم برگه اشتراک اندروید ظاهر می شوند.

ترتیب نمایش میانبر

وقتی راه‌انداز میانبرهای یک برنامه را نمایش می‌دهد، باید به ترتیب زیر ظاهر شوند:

1. میانبرهای ایستا : میانبرهایی که متد isDeclaredInManifest() true را برمی گرداند.
2. میانبرهای پویا : میانبرهایی که متد ShortcutInfo.isDynamic() آنها را true برمی گرداند.

در هر نوع میانبر - ایستا و پویا - میانبرها به ترتیب افزایش رتبه طبق ShortcutInfo.getRank مرتب می شوند. Google Assistant همچنین رتبه میانبر را هنگام تعیین میانبرهای متنی برای نمایش به کاربران در نظر می گیرد.

رتبه ها اعداد صحیح غیر منفی و متوالی هستند. میانبرهای استاتیک به ترتیبی که در فایل shortcuts.xml شما ظاهر می شوند، از اولین تا آخرین رتبه بندی می شوند. برای میانبرهای پویا، با فراخوانی updateShortcuts(Context, List) ، addDynamicShortcuts(Context, List) ، pushDynamicShortcut(Context, ShortcutInfoCompat) یا setDynamicShortcuts(Context, List) می توانید رتبه بندی میانبرهای موجود را به روز کنید.

ترتیب اهداف اشتراک گذاری بر اساس عوامل مختلفی از جمله سابقه کاربر گذشته، تازگی، فرکانس، اشاره رتبه ، استفاده از برنامه و اولویت تنظیم شده در مکالمه ای است که با میانبر اشتراک گذاری مرتبط است. اهداف اشتراک‌گذاری ایجاد شده با استفاده از اشتراک‌گذاری میانبرهای API بر اهداف اشتراک‌گذاری تولید شده توسط ChooserTargetService که در Android 11 منسوخ شده بود، اولویت دارند. در Android 12 و اهداف اشتراک بالاتر تولید شده توسط ChooserTargetService منسوخ، دیگر در برگه اشتراک‌گذاری ظاهر نمی‌شوند.

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

اهداف و فعالیت های متعدد را مدیریت کنید

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

چندین هدف را اختصاص دهید

هنگام ایجاد میانبر با ShortcutInfoCompat.Builder ، می توانید به جای setIntent setIntents() از setIntent() استفاده کنید. با فراخوانی setIntents() ، می‌توانید وقتی کاربر میانبر را انتخاب می‌کند، چندین فعالیت را در برنامه خود راه‌اندازی کنید و همه فعالیت‌ها به جز آخرین فعالیت را در لیست در پشته قرار دهید. اگر کاربر سپس روی دکمه برگشت دستگاه ضربه بزند، به جای بازگشت به راه‌انداز دستگاه، فعالیت دیگری را در برنامه شما می‌بیند.

یک فعالیت را از دیگری شروع کنید

میانبرهای ایستا نمی توانند پرچم های هدف سفارشی داشته باشند. اولین هدف میانبر ایستا همیشه دارای Intent.FLAG_ACTIVITY_NEW_TASK و Intent.FLAG_ACTIVITY_CLEAR_TASK است . این بدان معناست که وقتی برنامه شما در حال اجرا است، تمام فعالیت های موجود در برنامه با راه اندازی میانبر استاتیک از بین می روند. اگر این رفتار را نمی‌خواهید، می‌توانید از یک فعالیت ترامپولین - یک فعالیت نامرئی که فعالیت دیگری را شروع می‌کند - در Activity.onCreate(Bundle) که Activity.finish() را فراخوانی می‌کند استفاده کنید:

1. در فایل AndroidManifest.xml ، تخصیص ویژگی android:taskAffinity= "" را در فعالیت ترامپولین قرار دهید.
2. در فایل منبع میانبرها، به فعالیت ترامپولین در intent داخل میانبر ثابت اشاره کنید.

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

پرچم های قصد را تنظیم کنید

می توانید میانبرهای پویا را با هر مجموعه ای از پرچم های Intent منتشر کنید. ترجیحاً Intent.FLAG_ACTIVITY_CLEAR_TASK را به همراه سایر پرچم‌های خود مشخص کنید. در غیر این صورت، اگر سعی کنید کار دیگری را در حین اجرای برنامه خود شروع کنید، ممکن است فعالیت هدف ظاهر نشود.

برای اطلاعات بیشتر درباره وظایف و پرچم‌های هدف، به Tasks و پشته پشتی مراجعه کنید.

میانبرها را به روز کنید

نماد راه‌انداز هر برنامه حداکثر می‌تواند حاوی تعدادی میانبر استاتیک و پویا باشد که برابر با مقدار بازگشتی getMaxShortcutCountPerActivity است. محدودیتی برای تعداد میانبرهای پین شده ای که یک برنامه می تواند ایجاد کند وجود ندارد.

وقتی میانبر پویا پین می شود، حتی زمانی که ناشر آن را به عنوان میانبر پویا حذف می کند، میانبر پین شده همچنان قابل مشاهده و راه اندازی است. این به برنامه اجازه می‌دهد تا تعداد میانبرهای بیشتری از getMaxShortcutCountPerActivity() داشته باشد.

مثال زیر را در نظر بگیرید، که فرض می کند مقدار بازگشتی توسط getMaxShortcutCountPerActivity() 4 است:

1. یک برنامه چت چهار میانبر پویا را منتشر می کند که نشان دهنده چهار مکالمه اخیر است: c1، c2، c3، و c4.
2. کاربر هر چهار میانبر را پین می کند.
3. بعداً کاربر سه مکالمه اضافی را شروع می کند: c5، c6 و c7. برنامه ناشر میانبرهای پویا خود را مجدداً منتشر می کند. لیست میانبرهای پویا جدید عبارتند از: c4، c5، c6 و c7.

برنامه باید c1، c2 و c3 را حذف کند، زیرا نمی تواند بیش از چهار میانبر پویا را نمایش دهد. با این حال، c1، c2 و c3 هنوز میانبرهای پین شده ای هستند که کاربر می تواند به آنها دسترسی داشته باشد و راه اندازی کند.

سپس کاربر می تواند در مجموع به هفت میانبر دسترسی داشته باشد که به فعالیت های برنامه ناشر پیوند دارند. این به این دلیل است که کل شامل حداکثر تعداد میانبرها و سه میانبر پین شده است.

1. این برنامه می تواند از updateShortcuts(Context, List) برای به روز رسانی هر یک از هفت میانبر موجود استفاده کند. برای مثال، وقتی نمادهای همتایان چت تغییر می‌کنند، ممکن است این مجموعه میانبرها را به‌روزرسانی کنید.
2. می توانید از روش های addDynamicShortcuts(Context, List) و setDynamicShortcuts(Context, List) برای به روز رسانی میانبرهای موجود با همان شناسه ها استفاده کنید. با این حال، نمی توانید از آنها برای به روز رسانی میانبرهای غیر پویا و پین شده استفاده کنید، زیرا این دو روش سعی می کنند لیست های داده شده از میانبرها را به میانبرهای پویا تبدیل کنند.

محدودیتی برای تعداد میانبرهایی که می توان برای نمایش در برنامه های دستیار مانند Google Assistant اعمال کرد، وجود ندارد. از متد pushDynamicShortcut() کتابخانه ShortcutManagerCompat Jetpack برای ایجاد و به روز رسانی میانبرها برای استفاده در برنامه های دستیار استفاده کنید. همچنین، کتابخانه Google Shortcuts Integration را به برنامه خود اضافه کنید تا پیوندهای پویا واجد شرایط ظاهر شدن در Google Assistant شوند.

برای کسب اطلاعات بیشتر درباره دستورالعمل‌های میان‌برهای برنامه، از جمله به‌روزرسانی میان‌برها، به بهترین روش‌ها برای میان‌برها مراجعه کنید.

کنترل تغییرات محلی سیستم

برنامه‌ها باید میانبرهای پویا و پین‌شده را هنگام دریافت Intent.ACTION_LOCALE_CHANGED به‌روزرسانی کنند.ACTION_LOCALE_CHANGED که نشان‌دهنده تغییر در منطقه سیستم است.

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

برای تعیین موقعیت هایی که در طی آن میانبرهای ایستا و پویا ظاهر می شوند، راه اندازی تاریخچه فعال سازی میانبرها را بررسی می کند. برای میانبرهای ایستا، می‌توانید با فراخوانی متد reportShortcutUsed() و ارسال شناسه میانبر به آن در صورت وقوع هر یک از رویدادهای زیر، ردیابی زمانی که کاربران اقدامات خاصی را در برنامه شما انجام می‌دهند:

• کاربر میانبر را با شناسه داده شده انتخاب می کند.
• در داخل برنامه، کاربر به صورت دستی عمل مربوط به همان میانبر را تکمیل می کند.

برنامه شما استفاده از میانبرهای پویا را با فراخوانی متد pushDynamicShortcut() و ارسال شناسه میانبر به آن هنگام وقوع رویداد مرتبط، ردیابی می کند. استفاده از میانبرهای پویا با این روش به برنامه‌های دستیار مانند Google Assistant اجازه می‌دهد میانبرهای مرتبط را به کاربران پیشنهاد دهند. از آنجایی که متد pushDynamicShortcut() هنگام فراخوانی میزان استفاده را گزارش می‌کند، متد reportShortcutUsed() را برای همان میان‌برها فراخوانی نکنید.

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

میانبرها را غیرفعال کنید

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

محدود کردن نرخ

وقتی از متدهای setDynamicShortcuts(), addDynamicShortcuts() یا updateShortcuts() استفاده می‌کنید، ممکن است فقط بتوانید این روش‌ها را چند بار در یک برنامه پس‌زمینه فراخوانی کنید - برنامه‌ای که هیچ فعالیت یا سرویسی در پیش‌زمینه ندارد. محدودیت تعداد مشخصی که می توانید با این روش ها تماس بگیرید، محدودیت نرخ نامیده می شود. این ویژگی از ShortcutManagerCompat از مصرف بیش از حد منابع دستگاه جلوگیری می کند.

هنگامی که نرخ محدود فعال است، isRateLimitingActive() true را برمی گرداند. با این حال، محدودیت نرخ در طول رویدادهای خاص بازنشانی می‌شود، بنابراین حتی برنامه‌های پس‌زمینه نیز می‌توانند متدهای ShortcutManager را تا رسیدن دوباره به محدودیت نرخ فراخوانی کنند. این رویدادها شامل موارد زیر است:

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

اگر در حین توسعه یا آزمایش با محدودیت نرخ مواجه شدید، می‌توانید گزینه‌های Developer > Reset ShortcutManager rate-limiting را از تنظیمات دستگاه انتخاب کنید، یا می‌توانید دستور زیر را در adb وارد کنید:

$ adb shell cmd shortcut reset-throttling [ --user your-user-id ]

پشتیبان گیری و بازیابی

می‌توانید با قرار دادن ویژگی android:allowBackup="true " در فایل مانیفست برنامه خود، به کاربران اجازه دهید هنگام تغییر دستگاه‌ها، عملیات پشتیبان‌گیری و بازیابی را در برنامه شما انجام دهند. اگر از پشتیبان گیری و بازیابی پشتیبانی می کنید، نکات زیر را در مورد میانبرهای برنامه در نظر داشته باشید:

• میانبرهای استاتیک به طور خودکار دوباره منتشر می شوند، اما تنها پس از نصب مجدد برنامه شما توسط کاربر در دستگاه جدید.
• میانبرهای پویا پشتیبان‌گیری نمی‌شوند، بنابراین منطق را در برنامه خود قرار دهید تا زمانی که کاربر برنامه شما را در دستگاه جدیدی باز می‌کند، آنها را دوباره منتشر کنید.
• میانبرهای پین شده به طور خودکار به راه‌انداز دستگاه بازیابی می‌شوند، اما سیستم از نمادهای مرتبط با میان‌برهای پین‌شده پشتیبان‌گیری نمی‌کند. بنابراین، تصاویر میانبرهای پین شده خود را در برنامه خود ذخیره کنید تا بازیابی آنها در دستگاه جدید آسان باشد.

قطعه کد زیر بهترین نحوه بازیابی میانبرهای پویا برنامه و نحوه بررسی اینکه آیا میانبرهای پین شده برنامه شما حفظ شده اند را نشان می دهد:

class MyMainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.dynamicShortcuts.size == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.pinnedShortcuts.size > 0) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}

public class MainActivity extends Activity {
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (ShortcutManagerCompat.getDynamicShortcuts().size() == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts are restored. Use pdateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}