Mengelola pintasan

Setelah membuat pintasan, Anda mungkin perlu mengelolanya selama masa aktif aplikasi. Misalnya, Anda mungkin ingin mengoptimalkan aplikasi dengan menentukan seberapa sering pengguna menyelesaikan tindakan tertentu dengan pintasan Anda. Dalam kasus lain, Anda mungkin memutuskan untuk menonaktifkan pintasan yang disematkan untuk mencegah aplikasi melakukan tindakan yang sudah tidak berlaku atau tidak ada. Untuk pintasan yang dirujuk dalam percakapan, Anda mungkin ingin melacak penggunaan untuk memberikan sinyal yang meningkatkan peringkat pintasan.

Halaman ini menjelaskan cara ini dan beberapa cara umum lainnya untuk mengelola pintasan Anda.

Perilaku pintasan

Bagian berikut berisi informasi umum tentang perilaku pintasan, termasuk visibilitas, urutan tampilan, dan peringkat.

Visibilitas pintasan

Pintasan statis dan pintasan dinamis muncul di peluncur atau asisten yang didukung saat pengguna melakukan gestur atau perintah suara tertentu. Pada peluncur yang didukung, gesturnya adalah sentuh lama pada ikon peluncur aplikasi, tetapi gesturnya mungkin berbeda di aplikasi peluncur lainnya. Dengan Asisten Google, pintasan dapat ditampilkan dalam Asisten atau diluncurkan dari perintah suara pengguna.

Class LauncherApps menyediakan API untuk aplikasi peluncur guna mengakses pintasan.

Karena pintasan yang dipasangi pin muncul di peluncur tersebut, pintasan itu selalu terlihat. Pintasan yang dipasangi pin akan dihapus dari peluncur hanya dalam situasi berikut:

• Pengguna menghapusnya.
• Aplikasi yang dikaitkan dengan pintasan tersebut di-uninstal.
• Pengguna menghapus data aplikasi dengan membuka Setelan > Aplikasi & notifikasi, memilih aplikasi, lalu mengetuk Penyimpanan > Hapus penyimpanan.

Target berbagi adalah subset pintasan dinamis yang muncul di baris berbagi langsung pada sharesheet Android.

Urutan tampilan pintasan

Saat peluncur menampilkan pintasan aplikasi, pintasan tersebut harus muncul dalam urutan berikut:

1. Pintasan statis: pintasan yang metode isDeclaredInManifest()-nya menampilkan true.
2. Pintasan dinamis: pintasan yang metode ShortcutInfo.isDynamic()-nya menampilkan true.

Dalam setiap jenis pintasan—statis dan dinamis—pintasan diurutkan berdasarkan peringkat yang meningkat sesuai dengan ShortcutInfo.getRank. Asisten Google juga mempertimbangkan peringkat pintasan saat menentukan pintasan kontekstual yang akan ditampilkan kepada pengguna.

Peringkat adalah bilangan bulat non-negatif yang berurutan. Pintasan statis diberi peringkat dari pertama hingga terakhir sesuai urutan kemunculannya dalam file shortcuts.xml. Untuk pintasan dinamis, Anda dapat memperbarui peringkat pintasan yang ada saat memanggil updateShortcuts(Context, List), addDynamicShortcuts(Context, List), pushDynamicShortcut(Context, ShortcutInfoCompat), atau setDynamicShortcuts(Context, List).

Urutan target berbagi didasarkan pada berbagai faktor, termasuk histori pengguna sebelumnya, keterkinian, frekuensi, petunjuk peringkat, penggunaan aplikasi, dan prioritas yang ditetapkan pada percakapan yang terkait dengan pintasan berbagi. Target berbagi yang dibuat menggunakan Sharing Shortcuts API diprioritaskan daripada target berbagi yang dihasilkan oleh ChooserTargetService yang tidak digunakan lagi di Android 11. Di Android 12 dan yang lebih baru, target berbagi yang dihasilkan oleh ChooserTargetService yang tidak digunakan lagi tidak akan muncul lagi di sheet berbagi.

Sebagian besar peluncur menampilkan maksimal empat pintasan. Untuk kombinasi pintasan statis dan pintasan dinamis yang ditentukan, peluncur akan menampilkan maksimum dua pintasan statis dan dua pintasan dinamis. Misalnya, jika Anda menentukan empat pintasan statis dan membuat tiga pintasan dinamis secara terprogram, peluncur akan menampilkan dua pintasan statis pertama, dan dua pintasan dinamis dengan peringkat tertinggi.

Mengelola beberapa intent dan aktivitas

Jika ingin aplikasi melakukan beberapa operasi saat pengguna mengaktifkan pintasan, Anda dapat mengonfigurasinya untuk memicu aktivitas berturut-turut. Anda dapat melakukannya dengan menetapkan beberapa intent, memulai satu aktivitas dari aktivitas lain, atau menetapkan flag intent, bergantung pada jenis pintasan.

Memulai suatu aktivitas dari aktivitas lainnya

Pintasan statis tidak boleh memiliki flag intent kustom. Intent pertama dari pintasan statis selalu memiliki Intent.FLAG_ACTIVITY_NEW_TASK dan Intent.FLAG_ACTIVITY_CLEAR_TASK yang ditetapkan. Artinya, saat aplikasi Anda berjalan, semua aktivitas yang ada di aplikasi akan dihancurkan saat pintasan statis diluncurkan. Jika tidak menginginkan perilaku ini, Anda dapat menggunakan aktivitas trampolin—aktivitas tidak terlihat yang memulai aktivitas lain—dengan memanggil finish di dalam blok peluncuran atau onCreate sebelum konten Compose ditetapkan:

1. Di AndroidManifest.xml file, sertakan penetapan atribut android:taskAffinity="" dalam aktivitas trampolin.

2. Dalam file resource pintasan, referensikan aktivitas trampolin dalam intent dalam pintasan statis.

Untuk mengetahui informasi selengkapnya tentang aktivitas trampolin, lihat Memulai satu aktivitas dari aktivitas lain.

Menetapkan flag intent

Anda dapat memublikasikan pintasan dinamis dengan kumpulan flag Intent apa pun. Sebaiknya, tentukan kombinasi Intent.FLAG_ACTIVITY_SINGLE_TOP dan Intent.FLAG_ACTIVITY_CLEAR_TOP dalam intent pintasan. Hal ini memastikan bahwa jika ComponentActivity Anda sudah aktif, aktivitas tersebut akan ditampilkan ke latar depan dan digunakan kembali tanpa dihancurkan, sehingga arsitektur aktivitas tunggal Anda dapat menangani peristiwa pintasan dengan baik melalui onNewIntent().

Untuk mempelajari lebih lanjut tugas dan flag intent, lihat Tugas dan data sebelumnya.

Memperbarui pintasan

Setiap ikon peluncur aplikasi dapat berisi, maksimal, sejumlah pintasan statis dan dinamis yang digabungkan yang sama dengan nilai yang ditampilkan oleh getMaxShortcutCountPerActivity. Tidak ada batasan jumlah pintasan yang disematkan yang dapat dibuat oleh aplikasi.

Saat pintasan dinamis disematkan, meskipun penayang menghapusnya sebagai pintasan dinamis, pintasan yang disematkan masih terlihat dan dapat diluncurkan. Hal ini memungkinkan aplikasi memiliki lebih dari getMaxShortcutCountPerActivity pintasan.

Perhatikan contoh berikut, yang mengasumsikan bahwa nilai yang ditampilkan oleh getMaxShortcutCountPerActivity adalah 4:

1. Aplikasi chat memublikasikan empat pintasan dinamis, yang mewakili empat percakapan terbaru: c1, c2, c3, dan c4.
2. Pengguna memasang pin pada keempat pintasan tersebut.
3. Kemudian, pengguna memulai tiga percakapan tambahan: c5, c6, dan c7. Aplikasi penayang memublikasikan ulang pintasan dinamisnya. Daftar pintasan dinamis yang baru adalah: c4, c5, c6, dan c7.

Aplikasi harus menghapus c1, c2, dan c3, karena tidak dapat menampilkan lebih dari empat pintasan dinamis. Namun, c1, c2, dan c3 masih merupakan pintasan yang disematkan yang dapat diakses dan diluncurkan oleh pengguna.

Pengguna kemudian dapat mengakses total tujuh pintasan yang tertaut ke aktivitas di aplikasi penayang. Hal ini karena totalnya mencakup jumlah maksimum pintasan dan tiga pintasan yang disematkan.

1. Aplikasi dapat menggunakan updateShortcuts(Context, List) untuk memperbarui salah satu dari tujuh pintasan yang ada. Misalnya, Anda dapat memperbarui kumpulan pintasan ini saat ikon rekan chat berubah.
2. Anda dapat menggunakan metode addDynamicShortcuts(Context, List) dan setDynamicShortcuts(Context, List) untuk memperbarui pintasan yang ada dengan ID yang sama. Namun, Anda tidak dapat menggunakannya untuk memperbarui pintasan yang disematkan dan non-dinamis, karena kedua metode ini mencoba mengonversi daftar pintasan yang diberikan menjadi pintasan dinamis.

Tidak ada batasan jumlah pintasan yang dapat dikirim untuk ditampilkan di aplikasi asisten seperti Asisten Google. Gunakan metode pushDynamicShortcut dari library Jetpack ShortcutManagerCompat untuk membuat dan memperbarui pintasan yang akan digunakan di aplikasi asisten. Selain itu, tambahkan library Integrasi Pintasan Google ke aplikasi Anda agar link dinamis memenuhi syarat untuk muncul di Asisten Google.

Untuk mempelajari lebih lanjut panduan pintasan aplikasi, termasuk memperbarui pintasan, lihat Praktik terbaik untuk pintasan.

Menangani perubahan lokal sistem

Aplikasi harus mengupdate pintasan dinamis dan yang disematkan saat menerima siaran Intent.ACTION_LOCALE_CHANGED yang menunjukkan perubahan pada lokalitas sistem.

Melacak penggunaan pintasan

Untuk menentukan situasi saat pintasan statis dan dinamis muncul, peluncur akan memeriksa histori aktivasi pintasan. Untuk pintasan statis, Anda dapat melacak kapan pengguna menyelesaikan tindakan tertentu dalam aplikasi dengan memanggil metode reportShortcutUsed dan meneruskan ID pintasan saat salah satu peristiwa berikut terjadi:

• Pengguna memilih pintasan dengan ID yang diberikan.
• Dalam aplikasi, pengguna menyelesaikan tindakan yang sesuai dengan pintasan yang sama secara manual.

Aplikasi Anda melacak penggunaan pintasan dinamis dengan memanggil metode pushDynamicShortcut dan meneruskan ID pintasan saat peristiwa yang relevan terjadi. Mendorong penggunaan pintasan dinamis dengan metode ini memungkinkan aplikasi bantuan seperti Asisten Google menyarankan pintasan yang relevan kepada pengguna. Karena metode pushDynamicShortcut melaporkan penggunaan saat dipanggil, jangan panggil metode reportShortcutUsed untuk pintasan yang sama.

Untuk pintasan terkait percakapan, penting untuk melacak penggunaan pesan keluar dan masuk. Untuk mengetahui detailnya, lihat praktik terbaik untuk orang dan percakapan.

Menonaktifkan pintasan

Karena aplikasi dan pengguna Anda dapat menyematkan pintasan ke peluncur perangkat, mungkin saja pintasan yang disematkan ini dapat mengarahkan pengguna ke tindakan dalam aplikasi Anda yang sudah tidak berlaku atau tidak ada lagi. Untuk mengelola situasi ini, Anda dapat menonaktifkan pintasan yang tidak ingin dipilih pengguna dengan memanggil disableShortcuts, yang akan menghapus pintasan yang ditentukan dari daftar pintasan statis dan dinamis serta menonaktifkan salinan yang disematkan dari pintasan ini. Anda juga dapat menggunakan versi overload dari metode ini yang menerima CharSequence sebagai pesan error kustom. Pesan error tersebut kemudian akan muncul saat pengguna mencoba meluncurkan pintasan yang dinonaktifkan.

Pembatasan kapasitas

Saat menggunakan metode setDynamicShortcuts, addDynamicShortcuts, atau updateShortcuts, Anda mungkin hanya dapat memanggil metode ini beberapa kali di aplikasi latar belakang—aplikasi tanpa aktivitas atau layanan di latar depan. Batas jumlah spesifik frekuensi Anda dapat memanggil metode ini disebut pembatasan kapasitas. Fitur ini mencegah ShortcutManagerCompat menggunakan resource perangkat secara berlebihan.

Saat pembatasan kapasitas aktif, isRateLimitingActive akan menampilkan nilai true. Namun, pembatasan kapasitas direset selama peristiwa tertentu, sehingga aplikasi latar belakang pun dapat memanggil metode ShortcutManager hingga batas kapasitas tercapai lagi. Peristiwa ini mencakup:

• Aplikasi muncul di latar depan.
• Perubahan lokal sistem.
• Pengguna melakukan tindakan balasan inline pada notifikasi.

Jika Anda mengalami pembatasan kapasitas selama pengembangan atau pengujian, Anda dapat memilih Opsi Developer > Reset pembatasan kapasitas ShortcutManager dari setelan perangkat, atau Anda dapat memasukkan perintah berikut di adb:

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

Pencadangan dan pemulihan

Anda dapat mengizinkan pengguna melakukan operasi pencadangan dan pemulihan di aplikasi Anda saat mengganti perangkat dengan menyertakan penetapan atribut android:allowBackup="true" dalam file manifes aplikasi Anda. Jika Anda mendukung pencadangan dan pemulihan, perhatikan hal-hal berikut tentang pintasan aplikasi:

• Pintasan statis dipublikasikan ulang secara otomatis, tetapi hanya setelah pengguna menginstal ulang aplikasi Anda di perangkat baru.
• Pintasan dinamis tidak dicadangkan, jadi sertakan logika di aplikasi Anda untuk memublikasikannya kembali saat pengguna membuka aplikasi Anda di perangkat baru.
• Pintasan yang disematkan akan otomatis dipulihkan ke peluncur perangkat, tetapi sistem tidak mencadangkan ikon yang terkait dengan pintasan yang disematkan. Oleh karena itu, simpan gambar pintasan yang disematkan di aplikasi Anda agar dapat dipulihkan dengan cepat di perangkat baru.

Cuplikan kode berikut menunjukkan cara terbaik untuk memulihkan pintasan dinamis aplikasi dan cara memeriksa apakah pintasan yang disematkan di aplikasi dipertahankan:

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.
            }
        }
    }
    // ...
}
ShortcutsSnippets.kt