Mengelola pintasan

Setelah membuat pintasan, Anda mungkin perlu mengelolanya selama aplikasi Anda. Misalnya, Anda mungkin ingin mengoptimalkan aplikasi dengan menentukan cara sering kali pengguna menyelesaikan tindakan tertentu dengan pintasan Anda. Dalam kasus lain, Anda mungkin memutuskan untuk menonaktifkan pintasan yang dipasangi pin untuk mencegah aplikasi Anda melakukan tindakan yang usang atau tidak ada. Untuk pintasan yang dirujuk di percakapan, Anda mungkin ingin melacak penggunaan untuk memberikan sinyal yang meningkatkan peringkat pintasan.

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

Perilaku pintasan

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

Visibilitas pintasan

Penting: Semua informasi pintasan disimpan dalam kredensial yang dienkripsi penyimpanan, sehingga aplikasi Anda tidak dapat mengakses pintasan pengguna sampai mereka membuka kunci perangkat.

Pintasan statis dan dinamis muncul pada peluncur yang didukung atau asisten saat pengguna melakukan {i>gesture <i}atau perintah suara tertentu. Aktif peluncur yang didukung, gesturnya adalah sentuhan & tahan ikon peluncur aplikasi, tetapi {i>gesture <i}tersebut mungkin berbeda di aplikasi peluncur lainnya. Dengan Google Asisten, pintasan dapat ditampilkan dalam Asisten atau diluncurkan dari pengguna perintah suara.

Class LauncherApps menyediakan API yang dapat diakses oleh aplikasi peluncur 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 merupakan subkumpulan pintasan dinamis yang muncul di baris berbagi langsung pada Sheet berbagi Android.

Gambar 1. Android Sharesheet. Target berbagi langsung muncul di baris pertama, diikuti oleh aplikasi yang diberi peringkat, lalu daftar Aplikasi.

Urutan tampilan pintasan

Saat peluncur menampilkan pintasan aplikasi, pintasan harus muncul sebagai berikut berikut:

1. Pintasan statis: pintasan dengan metode isDeclaredInManifest() menampilkan true.
2. Pintasan dinamis: pintasan dengan ShortcutInfo.isDynamic() akan menampilkan true.

Dalam setiap jenis pintasan—statis dan dinamis—pintasan diurutkan dalam urutan meningkatkan peringkat menurut ShortcutInfo.getRank. Asisten Google juga mempertimbangkan peringkat pintasan saat menentukan pintasan kontekstual yang akan ditampilkan pelanggan.

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

Urutan target berbagi didasarkan pada berbagai faktor, termasuk pengguna lama sejarah, keterkinian, frekuensi, petunjuk peringkat, penggunaan aplikasi, dan prioritas yang ditetapkan pada percakapan yang terkait dengan untuk berbagi pintasan. Bagikan target yang dibuat menggunakan Berbagi Shortcuts API 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 spreadsheet.

Sebagian besar peluncur menampilkan maksimum 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 secara terprogram membuat tiga pintasan dinamis pintasan, peluncur akan menampilkan dua pintasan statis pertama, dan dua pintasan dinamis yang memiliki peringkat tinggi.

Catatan: Peringkat disesuaikan secara otomatis sehingga bersifat unik untuk setiap jenis pintasan—statis atau dinamis. Misalnya, jika ada tiga pintasan dinamis dengan peringkat 0, 1, dan 2, menambahkan pintasan dinamis lainnya dengan peringkat 1 mewakili permintaan untuk menempatkan pintasan ini di posisi kedua. Sebagai respons, peringkat pintasan yang sebelumnya peringkat 1 dan 2 berubah menjadi 2 dan 3, masing-masing.

Mengelola beberapa intent dan aktivitas

Jika Anda ingin aplikasi melakukan beberapa operasi saat pengguna mengaktifkan , Anda dapat mengonfigurasinya untuk memicu aktivitas berurutan. Anda dapat melakukan ini dengan menetapkan beberapa intent, memulai satu aktivitas dari yang lain, atau menetapkan flag intent, tergantung pada jenis pintasan.

Menetapkan beberapa intent

Saat membuat pintasan dengan ShortcutInfoCompat.Builder, Anda dapat menggunakan setIntents(), bukan setIntent(). Dengan memanggil setIntents(), Anda bisa meluncurkan beberapa aktivitas dalam aplikasi Anda saat pengguna memilih pintasan, menempatkan semua kecuali aktivitas terakhir dalam daftar di stack sebelumnya. Jika lalu pengguna mengetuk tombol kembali di perangkat. Mereka akan melihat aktivitas lain di aplikasi Anda alih-alih kembali ke peluncur perangkat.

Catatan: Saat pengguna memilih pintasan lalu mengetuk tombol kembali, aplikasi meluncurkan aktivitas yang sesuai dengan intent kedua hingga terakhir yang tercantum dalam file resource pintasan. Pola perilaku ini berlanjut selama pengguna terus mengetuk tombol kembali sampai pengguna menghapus {i>back stack<i} yang dibuat pintasan. Kemudian, jika pengguna mengetuk tombol kembali lagi, sistem mengarahkan mereka kembali ke peluncur.

Memulai suatu aktivitas dari aktivitas lainnya

Pintasan statis tidak boleh memiliki flag intent kustom. Intent pertama dari suatu pintasan selalu memiliki Intent.FLAG_ACTIVITY_NEW_TASK dan Intent.FLAG_ACTIVITY_CLEAR_TASK ditetapkan. Ini berarti bahwa ketika aplikasi Anda berjalan, semua aktivitas yang ada di aplikasi dihancurkan ketika pintasan diluncurkan. Jika Anda tidak menginginkan perilaku ini, Anda dapat menggunakan trampolin aktivitas —aktivitas tak terlihat yang memulai aktivitas lain—di Activity.onCreate(Bundle) yang memanggil Activity.finish():

1. Di dalam file AndroidManifest.xml, sertakan penetapan atribut android:taskAffinity=" dalam aktivitas trampolin.
2. Dalam file resource pintasan, rujuk aktivitas trampolin di bagian intent dalam pintasan statis.

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

Menetapkan flag intent

Anda dapat memublikasikan pintasan dinamis dengan kumpulan tanda Intent apa pun. Sebaiknya, tentukan Intent.FLAG_ACTIVITY_CLEAR_TASK beserta atribut lainnya penanda. Atau, jika Anda mencoba memulai tugas lain saat aplikasi Anda berjalan, aktivitas target mungkin tidak muncul.

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

Memperbarui pintasan

Setiap ikon peluncur aplikasi dapat berisi, paling banyak, sejumlah pintasan yang sama dengan nilai yang ditampilkan oleh getMaxShortcutCountPerActivity Tidak ada batasan jumlah pintasan yang disematkan yang dapat dibuat oleh sebuah aplikasi.

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

Pertimbangkan contoh berikut, yang mengasumsikan bahwa nilai yang ditampilkan oleh getMaxShortcutCountPerActivity() adalah 4:

1. Aplikasi chat memublikasikan empat pintasan dinamis, yang mewakili empat pintasan 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. Tujuan aplikasi penayang memublikasikan ulang pintasan dinamisnya. Pintasan dinamis 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.

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

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

Tidak ada batasan jumlah pintasan yang dapat didorong untuk ditampilkan di aplikasi Google Assistant seperti Asisten Google. Menggunakan pushDynamicShortcut() library Jetpack ShortcutManagerCompat untuk membuat dan mengupdate untuk digunakan di aplikasi asisten. Selain itu, tambahkan Integrasi Pintasan Google library ke aplikasi Anda agar link dinamis memenuhi syarat untuk muncul di Google Google.

Untuk mempelajari lebih lanjut panduan untuk 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 sistem lokalitas.

Melacak penggunaan pintasan

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

• Pengguna memilih pintasan dengan ID yang diberikan.
• Di dalam aplikasi, pengguna menyelesaikan tindakan yang sesuai dengan pintasan yang sama.

Aplikasi Anda melacak penggunaan pintasan dinamis dengan memanggil pushDynamicShortcut() dan meneruskan ID pintasan ke sini saat peristiwa yang relevan. 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 untuk panggilan keluar dan pesan masuk. Untuk mengetahui detailnya, lihat praktik terbaik untuk pengguna dan percakapan.

Catatan: Library Integrasi Pintasan Google diperlukan untuk mengaktifkan link dinamis yang didorong aplikasi Anda agar memenuhi syarat untuk muncul di platform Google seperti Google Assistant. Dengan menambahkan koleksi ini ke aplikasi, Anda mengizinkan Asisten mengambil link dinamis dan menyarankannya kepada pengguna dari aplikasi Asisten.

Menonaktifkan pintasan

Karena aplikasi Anda dan penggunanya dapat menyematkan pintasan ke peluncur perangkat, mungkin pintasan yang dipasangi pin ini dapat mengarahkan pengguna ke tindakan dalam aplikasi Anda yang usang atau tidak ada lagi. Untuk mengelola situasi ini, Anda dapat menonaktifkan pintasan yang tidak boleh dipilih pengguna dengan memanggil disableShortcuts, yang menghapus pintasan yang ditentukan dari pintasan statis serta daftar pintasan dinamis dan menonaktifkan salinan yang disematkan dari pintasan tersebut. Anda juga dapat menggunakan versi kelebihan beban dari metode ini yang menerima CharSequence sebagai pesan error kustom. Pesan {i>error<i} tersebut kemudian muncul saat pengguna mencoba meluncurkan pintasan yang dinonaktifkan.

Catatan: Jika Anda menghapus beberapa pintasan statis aplikasi saat mengupdate sistem, sistem akan otomatis menonaktifkan pintasan ini.

Pembatasan kapasitas

Saat menggunakan setDynamicShortcuts(), addDynamicShortcuts(), atau updateShortcuts(), Anda mungkin hanya dapat memanggil metode ini frekuensi tertentu dalam aplikasi latar belakang —aplikasi tanpa aktivitas atau berjalan di latar depan. Batas berapa kali Anda dapat memanggil metode ini disebut pembatasan kapasitas. Fitur ini mencegah ShortcutManagerCompat dari penggunaan resource perangkat yang berlebihan.

Saat pembatasan kapasitas diaktifkan, isRateLimitingActive() menampilkan nilai benar. Namun, pembatasan kapasitas direset selama peristiwa tertentu, sehingga bahkan aplikasi latar belakang dapat memanggil metode ShortcutManager sampai batas kapasitas tercapai lagi. Ini peristiwa tersebut meliputi:

• 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 perangkat setelan, 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 mengubah perangkat dengan menyertakan android:allowBackup="true" atribut dalam file manifes aplikasi Anda. Jika Anda mendukung pencadangan dan pemulihan, simpan poin-poin 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 dipublikasikan ulang mereka ketika pengguna membuka aplikasi Anda di perangkat baru.
• Pintasan yang disematkan dipulihkan ke peluncur perangkat secara otomatis, tetapi Google tidak mencadangkan ikon yang terkait dengan pintasan yang dipasangi pin. Oleh karena itu, simpan pintasan Anda yang disematkan' gambar di aplikasi Anda sehingga mudah untuk dipulihkan sebuah perangkat baru.

Cuplikan kode berikut menunjukkan cara terbaik untuk memulihkan fungsi dinamis aplikasi Anda dan cara memeriksa apakah pintasan yang dipasangi pin di 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.
            }
        }
    }
    // ...
}