Setelah membuat pintasan, Anda mungkin perlu mengelolanya selama masa aktif aplikasi Anda. 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 agar aplikasi tidak 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 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 pada aplikasi peluncur lainnya. Dengan Asisten Google, pintasan dapat ditampilkan dalam Asisten atau diluncurkan dari perintah suara pengguna.
Class LauncherApps
menyediakan API untuk aplikasi peluncur agar dapat 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 sheet berbagi Android.
![Screenshot Android Sharesheet](https://developer.android.com/static/images/guide/topics/ui/shortcuts/sharesheet.png?authuser=19&hl=id)
Urutan tampilan pintasan
Saat peluncur menampilkan pintasan aplikasi, pintasan tersebut harus muncul dalam urutan berikut:
- Pintasan statis: pintasan yang metode
isDeclaredInManifest()
-nya menampilkantrue
. - Pintasan dinamis: pintasan yang metode
ShortcutInfo.isDynamic()
-nya menampilkantrue
.
Dalam setiap jenis pintasan—statis dan dinamis—pintasan diurutkan dalam urutan
peningkatan peringkat sesuai dengan ShortcutInfo.getRank
. Asisten Google
juga mempertimbangkan peringkat pintasan saat menentukan pintasan kontekstual untuk ditampilkan kepada
pengguna.
Peringkat adalah bilangan bulat non-negatif yang berurutan. Pintasan statis diberi peringkat dari
pertama ke terakhir sesuai urutan kemunculannya di file shortcuts.xml
Anda. 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
Shared Shortcuts API
lebih diprioritaskan daripada target berbagi yang dihasilkan oleh
ChooserTargetService
yang tidak digunakan lagi di Android 11. Di Android 12 dan target berbagi yang lebih tinggi
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 dinamis yang ditentukan, peluncur akan menampilkan maksimum dua pintasan statis dan dua pintasan dinamis. Misalnya, jika Anda menentukan empat pintasan statis dan secara terprogram membuat tiga pintasan dinamis, peluncur akan menampilkan dua pintasan statis pertama, dan dua pintasan dinamis dengan peringkat tinggi.
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 lainnya, atau menetapkan flag intent, bergantung pada jenis pintasan.
Menetapkan beberapa intent
Saat membuat pintasan dengan ShortcutInfoCompat.Builder
, Anda dapat menggunakan
setIntents()
, bukan setIntent()
. Dengan memanggil setIntents()
, Anda
dapat meluncurkan beberapa aktivitas dalam aplikasi saat pengguna memilih pintasan,
menempatkan semua aktivitas kecuali aktivitas terakhir dalam daftar di data sebelumnya. Jika
kemudian pengguna mengetuk tombol kembali di perangkat, mereka akan melihat aktivitas lain di aplikasi Anda,
bukan kembali ke peluncur perangkat.
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
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 tak terlihat yang memulai aktivitas lain—di
Activity.onCreate(Bundle)
yang memanggil Activity.finish()
:
- Dalam file
AndroidManifest.xml
, sertakan penetapan atributandroid:taskAffinity=
"" dalam aktivitas trampolin. - Dalam file resource pintasan, rujuk aktivitas trampolin pada intent dalam pintasan statis.
Untuk informasi selengkapnya tentang aktivitas trampolin, lihat Memulai satu aktivitas dari aktivitas lain.
Menetapkan flag intent
Anda dapat memublikasikan pintasan dinamis dengan kumpulan tanda Intent
mana pun.
Sebaiknya, tentukan Intent.FLAG_ACTIVITY_CLEAR_TASK
bersama dengan flag
Anda yang lain. Jika tidak, jika Anda mencoba memulai tugas lain saat aplikasi sedang
berjalan, aktivitas target mungkin tidak muncul.
Untuk mempelajari tugas dan tanda intent lebih lanjut, lihat Tugas dan data sebelumnya.
Memperbarui pintasan
Setiap ikon peluncur aplikasi dapat berisi maksimal jumlah pintasan statis dan dinamis
yang digabungkan yang sama dengan nilai yang ditampilkan oleh
getMaxShortcutCountPerActivity
. Tidak ada batasan jumlah
pintasan yang disematkan yang dapat dibuat aplikasi.
Saat pintasan dinamis disematkan, meskipun penayang menghapusnya sebagai
pintasan dinamis, pintasan yang disematkan masih terlihat dan dapat diluncurkan. Ini memungkinkan
aplikasi memiliki lebih dari jumlah getMaxShortcutCountPerActivity()
pintasan.
Perhatikan contoh berikut, yang mengasumsikan bahwa nilai yang ditampilkan oleh
getMaxShortcutCountPerActivity()
adalah 4
:
- Aplikasi chat memublikasikan empat pintasan dinamis, yang mewakili empat percakapan terbaru: c1, c2, c3, dan c4.
- Pengguna memasang pin pada keempat pintasan tersebut.
- 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 tetap 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. Ini karena totalnya mencakup jumlah maksimum pintasan dan tiga pintasan yang disematkan.
- 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. - Anda dapat menggunakan metode
addDynamicShortcuts(Context, List)
dansetDynamicShortcuts(Context, List)
untuk memperbarui pintasan yang ada dengan ID yang sama. Namun, Anda tidak dapat menggunakannya untuk memperbarui pintasan non-dinamis yang disematkan, karena kedua metode ini mencoba mengonversi daftar pintasan tertentu menjadi pintasan dinamis.
Tidak ada batasan jumlah pintasan yang bisa dikirim untuk ditampilkan di
aplikasi asisten seperti Asisten Google. Gunakan metode pushDynamicShortcut()
dari library Jetpack ShortcutManagerCompat
untuk membuat dan memperbarui
pintasan untuk digunakan pada 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 memperbarui pintasan dinamis dan yang disematkan saat menerima
siaran Intent.ACTION_LOCALE_CHANGED
yang menunjukkan perubahan pada lokal
sistem.
Melacak penggunaan pintasan
Untuk menentukan situasi di mana pintasan statis dan dinamis muncul,
peluncur 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 berkaitan 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 asisten 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 Anda dan penggunanya dapat menyematkan pintasan ke peluncur perangkat, pintasan
yang disematkan ini mungkin dapat mengarahkan pengguna ke tindakan dalam aplikasi Anda
yang tidak berlaku lagi atau sudah tidak ada lagi. Untuk mengelola situasi ini, Anda dapat
menonaktifkan pintasan yang tidak Anda inginkan untuk dipilih pengguna dengan memanggil
disableShortcuts
, yang menghapus pintasan tertentu dari daftar pintasan
statis dan dinamis serta menonaktifkan salinan pintasan yang disematkan ini. Anda
juga dapat menggunakan versi overload dari metode ini yang menerima
CharSequence
sebagai pesan error kustom. Pesan error tersebut kemudian muncul
saat pengguna mencoba meluncurkan pintasan yang dinonaktifkan.
Pembatasan kapasitas
Saat menggunakan metode setDynamicShortcuts(), addDynamicShortcuts()
, atau
updateShortcuts()
, Anda mungkin hanya dapat memanggil metode ini
dalam jumlah tertentu di aplikasi latar belakang—aplikasi tanpa aktivitas atau
layanan di latar depan. Batas berapa kali Anda dapat memanggil metode ini disebut pembatasan kapasitas. Fitur ini mencegah
ShortcutManagerCompat
menggunakan resource perangkat secara berlebihan.
Saat pembatasan kapasitas diaktifkan, isRateLimitingActive()
akan menampilkan nilai benar (true).
Namun, pembatasan kapasitas akan direset selama peristiwa tertentu, sehingga aplikasi latar belakang
dapat memanggil metode ShortcutManager
sampai batas kapasitas kembali tercapai. Peristiwa
ini mencakup:
- Aplikasi muncul di latar depan.
- Perubahan lokal sistem.
- Pengguna melakukan tindakan balasan inline pada notifikasi.
Jika 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 pada aplikasi Anda saat
mengganti perangkat dengan menyertakan penetapan atribut
android:allowBackup="true
" dalam file manifes aplikasi. Jika Anda mendukung pencadangan dan pemulihan, perhatikan
hal-hal berikut tentang pintasan aplikasi:
- Pintasan statis otomatis dipublikasikan ulang, tetapi hanya setelah pengguna menginstal ulang aplikasi Anda di perangkat baru.
- Pintasan dinamis tidak dicadangkan, jadi sertakan logika di aplikasi Anda untuk memublikasikannya ulang saat pengguna membuka aplikasi di perangkat baru.
- Pintasan yang disematkan dipulihkan ke peluncur perangkat secara otomatis, tetapi sistem tidak mencadangkan ikon yang terkait dengan pintasan yang disematkan. Oleh karena itu, simpan image pintasan yang disematkan di aplikasi Anda agar mudah memulihkannya di perangkat baru.
Cuplikan kode berikut menunjukkan cara terbaik untuk memulihkan pintasan dinamis aplikasi Anda dan cara memeriksa apakah pintasan yang disematkan aplikasi Anda dipertahankan:
Kotlin
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. } } } // ... }
Java
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. } } } // ... }