Pintasan mengirimkan jenis konten tertentu kepada pengguna dengan membantu mereka mengakses bagian aplikasi Anda dengan cepat.
![Gambar yang menunjukkan kontras antara pintasan aplikasi dan pintasan yang disematkan](https://developer.android.com/static/images/guide/topics/ui/shortcuts/pinned-shortcuts.png?authuser=6&hl=id)
Cara Anda menayangkan konten dengan pintasan bergantung pada kasus penggunaan Anda dan apakah konteks pintasan berbasis aplikasi atau berbasis pengguna. Meskipun konteks pintasan statis tidak berubah dan konteks pintasan dinamis terus berubah, aplikasi Anda mendorong konteks dalam kedua kasus tersebut. Jika pengguna memilih cara aplikasi Anda mengirimkan konten kepada mereka, seperti dengan pintasan yang disematkan, konteksnya akan ditentukan oleh pengguna. Skenario berikut menjelaskan beberapa kasus penggunaan untuk setiap jenis pintasan:
- Pintasan statis paling cocok untuk aplikasi yang menautkan ke konten menggunakan struktur yang konsisten sepanjang waktu interaksi pengguna dengan aplikasi. Karena sebagian besar peluncur hanya menampilkan empat pintasan sekaligus, pintasan statis berguna untuk menjalankan tugas rutin secara konsisten, seperti jika pengguna ingin melihat kalender atau emailnya dengan cara tertentu .
- Pintasan dinamis digunakan untuk tindakan di aplikasi yang sensitif terhadap konteks. Pintasan yang sensitif terhadap konteks disesuaikan dengan tindakan yang dilakukan pengguna dalam aplikasi. Misalnya, jika Anda membuat game yang memungkinkan pengguna memulai dari level saat ini ketika peluncuran, Anda harus sering mengupdate pintasan tersebut. Menggunakan pintasan dinamis memungkinkan Anda mengupdate pintasan setiap kali pengguna menyelesaikan level.
- Pintasan yang disematkan digunakan untuk tindakan tertentu yang dikelola pengguna. Misalnya, pengguna mungkin ingin menyematkan situs tertentu ke peluncur. Hal ini bermanfaat karena memungkinkan pengguna melakukan tindakan kustom—seperti membuka situs dalam satu langkah, lebih cepat daripada menggunakan instance default browser.
Membuat pintasan statis
Pintasan statis memberikan link ke tindakan umum dalam aplikasi Anda, dan tindakan ini harus tetap konsisten selama masa aktif versi aplikasi saat ini. Opsi yang tepat untuk pintasan statis mencakup melihat pesan terkirim, menyetel alarm, dan menampilkan aktivitas olahraga pengguna untuk hari itu.
Untuk membuat pintasan statis, lakukan hal berikut:
-
Dalam file
AndroidManifest.xml
aplikasi Anda, temukan aktivitas yang filter intent-nya ditetapkan ke tindakanandroid.intent.action.MAIN
dan kategoriandroid.intent.category.LAUNCHER
. -
Tambahkan elemen
<meta-data>
ke aktivitas ini yang mereferensikan file resource tempat pintasan aplikasi akan ditentukan:<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.myapplication"> <application ... > <activity android:name="Main"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> <meta-data android:name="android.app.shortcuts" android:resource="@xml/shortcuts" /> </activity> </application> </manifest>
-
Buat file resource baru bernama
res/xml/shortcuts.xml
. -
Dalam file resource baru, tambahkan elemen root
<shortcuts>
yang berisi daftar elemen<shortcut>
. Pada setiap elemen<shortcut>
, sertakan informasi tentang pintasan statis termasuk ikonnya, label deskripsi, dan intent yang diluncurkan dalam aplikasi:<shortcuts xmlns:android="http://schemas.android.com/apk/res/android"> <shortcut android:shortcutId="compose" android:enabled="true" android:icon="@drawable/compose_icon" android:shortcutShortLabel="@string/compose_shortcut_short_label1" android:shortcutLongLabel="@string/compose_shortcut_long_label1" android:shortcutDisabledMessage="@string/compose_disabled_message1"> <intent android:action="android.intent.action.VIEW" android:targetPackage="com.example.myapplication" android:targetClass="com.example.myapplication.ComposeActivity" /> <!-- If your shortcut is associated with multiple intents, include them here. The last intent in the list determines what the user sees when they launch this shortcut. --> <categories android:name="android.shortcut.conversation" /> <capability-binding android:key="actions.intent.CREATE_MESSAGE" /> </shortcut> <!-- Specify more shortcuts here. --> </shortcuts>
Menyesuaikan nilai atribut
Daftar berikut menyertakan deskripsi untuk berbagai atribut dalam
pintasan statis. Berikan nilai untuk android:shortcutId
dan
android:shortcutShortLabel
. Semua nilai lain bersifat opsional.
-
android:shortcutId
-
Literal string yang mewakili pintasan saat objek
ShortcutManager
menjalankan operasi pada objek tersebut. -
android:shortcutShortLabel
-
Frasa singkat yang menjelaskan tujuan pintasan. Jika memungkinkan, batasi deskripsi singkat ini hingga 10 karakter.
Untuk informasi selengkapnya, lihat
setShortLabel()
. -
android:shortcutLongLabel
-
Frasa lebih panjang yang menjelaskan tujuan pintasan. Jika ada cukup ruang, peluncur akan menampilkan nilai ini, bukan
android:shortcutShortLabel
. Jika memungkinkan, batasi deskripsi panjang ini hingga 25 karakter.Untuk informasi selengkapnya, lihat
setLongLabel()
. -
android:shortcutDisabledMessage
-
Pesan yang muncul dalam peluncur yang didukung saat pengguna mencoba meluncurkan pintasan yang dinonaktifkan. Pesan tersebut harus menjelaskan kepada pengguna mengapa pintasan dinonaktifkan. Nilai atribut ini tidak berpengaruh jika
android:enabled
adalahtrue
. -
android:enabled
-
Menentukan apakah pengguna dapat berinteraksi dengan pintasan dari peluncur yang didukung. Nilai default
android:enabled
adalahtrue
. Jika menetapkannya kefalse
, setelandroid:shortcutDisabledMessage
yang menjelaskan alasan Anda menonaktifkan pintasan tersebut. Jika Anda merasa tidak perlu memberikan pesan seperti itu, hapus pintasan dari file XML sepenuhnya. -
android:icon
-
bitmap atau ikon adaptif yang digunakan peluncur saat menampilkan pintasan kepada pengguna. Nilai ini dapat berupa jalur ke gambar atau file resource yang berisi gambar. Gunakan ikon adaptif jika memungkinkan untuk meningkatkan performa dan konsistensi.
Mengonfigurasikan elemen internal
File XML yang mencantumkan pintasan statis aplikasi mendukung elemen
berikut di dalam setiap elemen <shortcut>
. Anda
harus menyertakan elemen dalam intent
untuk setiap
pintasan statis yang Anda tentukan.
-
intent
-
Tindakan yang akan diluncurkan sistem saat pengguna memilih pintasan. Intent ini harus memberikan nilai untuk atribut
android:action
.Anda dapat memberikan beberapa intent untuk satu pintasan. Lihat Mengelola beberapa intent dan aktivitas, Menetapkan intent, dan referensi class
TaskStackBuilder
untuk detailnya. -
categories
-
Memberikan pengelompokan untuk jenis tindakan yang dilakukan pintasan aplikasi Anda, seperti membuat pesan chat baru.
Untuk daftar kategori pintasan yang didukung, lihat referensi class
ShortcutInfo
. -
capability-binding
-
Mendeklarasikan kemampuan yang ditautkan dengan pintasan.
Pada contoh sebelumnya, pintasan ditautkan ke kemampuan yang dideklarasikan untuk
CREATE_MESSAGE
, yang merupakan intent bawaan Action Aplikasi. Dengan binding kemampuan ini, pengguna dapat menggunakan perintah lisan dengan Asisten Google untuk memanggil pintasan.
Membuat pintasan dinamis
Pintasan dinamis memberikan link ke tindakan spesifik yang sensitif terhadap konteks dalam aplikasi Anda. Tindakan ini dapat berubah di antara penggunaan aplikasi dan saat aplikasi berjalan. Penggunaan yang baik untuk pintasan dinamis mencakup memanggil orang tertentu, membuka lokasi tertentu, dan memuat game dari titik simpan terakhir pengguna. Anda juga dapat menggunakan pintasan dinamis untuk membuka percakapan.
Library Jetpack
ShortcutManagerCompat
adalah helper untuk
ShortcutManager
API, yang memungkinkan Anda mengelola pintasan dinamis di aplikasi. Penggunaan
library ShortcutManagerCompat
akan mengurangi kode boilerplate dan membantu
memastikan bahwa pintasan Anda berfungsi secara konsisten di seluruh versi Android. Library
ini juga diperlukan untuk mendorong pintasan dinamis agar memenuhi syarat
untuk muncul di platform Google, seperti Asisten, dengan
Library Integrasi Pintasan Google.
API ShortcutManagerCompat
memungkinkan aplikasi Anda melakukan operasi berikut
dengan pintasan dinamis:
-
Push dan update: gunakan
pushDynamicShortcut()
untuk memublikasikan dan memperbarui pintasan dinamis Anda. Jika sudah ada pintasan dinamis atau yang disematkan dengan ID yang sama, setiap pintasan yang dapat diubah akan diperbarui. -
Remove: menghapus sekumpulan pintasan dinamis menggunakan
removeDynamicShortcuts()
. Hapus semua pintasan dinamis menggunakanremoveAllDynamicShortcuts()
.
Untuk mengetahui informasi selengkapnya tentang menjalankan operasi di pintasan, lihat
Mengelola pintasan
dan
referensi
ShortcutManagerCompat
.
Berikut contoh pembuatan pintasan dinamis dan mengaitkannya dengan aplikasi Anda:
Kotlin
val shortcut = ShortcutInfoCompat.Builder(context, "id1") .setShortLabel("Website") .setLongLabel("Open the website") .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website)) .setIntent(Intent(Intent.ACTION_VIEW, Uri.parse("https://www.mysite.example.com/"))) .build() ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)
Java
ShortcutInfoCompat shortcut = new ShortcutInfoCompat.Builder(context, "id1") .setShortLabel("Website") .setLongLabel("Open the website") .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website)) .setIntent(new Intent(Intent.ACTION_VIEW, Uri.parse("https://www.mysite.example.com/"))) .build(); ShortcutManagerCompat.pushDynamicShortcut(context, shortcut);
Menambahkan Library Integrasi Pintasan Google
Library Integrasi Pintasan Google adalah library Jetpack opsional. Hal ini memungkinkan Anda mendorong pintasan dinamis yang dapat ditampilkan di platform Android, seperti peluncur, dan platform Google, seperti Asisten. Penggunaan library ini membantu pengguna menemukan pintasan Anda untuk mengakses konten tertentu atau tindakan replay di aplikasi dengan cepat.
Misalnya, aplikasi pesan mungkin mendorong pintasan dinamis untuk kontak bernama "Alex" setelah pengguna mengirim pesan ke orang tersebut. Setelah pintasan dinamis didorong, jika pengguna meminta Asisten, "Ok Google, kirim pesan ke Alex di ExampleApp", Asisten dapat meluncurkan ExampleApp dan otomatis mengonfigurasinya untuk mengirim pesan ke Alex.
Pintasan dinamis yang dikirim dengan library ini tidak tunduk pada batas pintasan yang diterapkan per perangkat. Hal ini memungkinkan aplikasi Anda mendorong pintasan setiap kali pengguna menyelesaikan tindakan terkait di aplikasi Anda. Mendorong pintasan yang sering digunakan dengan cara ini memungkinkan Google memahami pola penggunaan pengguna dan menyarankan pintasan yang relevan secara kontekstual kepada mereka.
Misalnya, Asisten dapat belajar dari pintasan yang dikirim dari aplikasi pelacakan kebugaran yang biasanya dijalankan pengguna setiap pagi dan secara proaktif menyarankan pintasan "mulai lari" saat pengguna mengangkat ponsel di pagi hari.
Library Integrasi Pintasan Google tidak menawarkan fungsi yang dapat dialamatkan
itu sendiri. Menambahkan library ini ke aplikasi Anda memungkinkan platform Google menggunakan
pintasan yang dikirim aplikasi Anda menggunakan ShortcutManagerCompat
.
Untuk menggunakan library ini di aplikasi Anda, ikuti langkah-langkah berikut:
-
Update file
gradle.properties
Anda untuk mendukung library AndroidX:android.useAndroidX=true # Automatically convert third-party libraries to use AndroidX android.enableJetifier=true
-
Di
app/build.gradle
, tambahkan dependensi untuk Library Integrasi Pintasan Google danShortcutManagerCompat
:dependencies { implementation "androidx.core:core:1.6.0" implementation 'androidx.core:core-google-shortcuts:1.0.0' ... }
Dengan dependensi library yang ditambahkan ke project Android, aplikasi Anda dapat menggunakan
metode pushDynamicShortcut()
dari
ShortcutManagerCompat
untuk mendorong pintasan dinamis yang memenuhi syarat
untuk ditampilkan di peluncur dan platform Google yang berpartisipasi.
Membuat pintasan yang dipasangi pin
Di Android 8.0 (API level 26) dan yang lebih tinggi, Anda dapat membuat pintasan yang dipasangi pin. Tidak seperti pintasan statis dan dinamis, pintasan yang disematkan akan muncul di peluncur yang didukung sebagai ikon terpisah. Gambar 1 menunjukkan perbedaan antara kedua jenis pintasan ini.
Untuk menyematkan pintasan ke peluncur yang didukung menggunakan aplikasi Anda, selesaikan langkah-langkah berikut:
-
Gunakan
isRequestPinShortcutSupported()
untuk memverifikasi bahwa peluncur default perangkat mendukung penyematan pintasan dalam aplikasi. -
Buat objek
ShortcutInfo
dengan salah satu dari dua cara, bergantung pada apakah pintasan ada:-
Jika pintasan ada, buat objek
ShortcutInfo
yang hanya berisi ID pintasan yang ada. Sistem akan otomatis menemukan dan menyematkan semua informasi lain yang terkait dengan pintasan. -
Jika Anda menyematkan pintasan baru, buat objek
ShortcutInfo
yang berisi ID, intent, dan label singkat untuk pintasan baru tersebut.
-
Jika pintasan ada, buat objek
-
Sematkan pintasan ke peluncur perangkat dengan memanggil
requestPinShortcut()
. Selama proses ini, Anda dapat meneruskan objekPendingIntent
, yang memberi tahu aplikasi Anda hanya saat pintasan berhasil disematkan.Setelah pintasan disematkan, aplikasi Anda dapat memperbarui kontennya menggunakan metode
updateShortcuts()
. Untuk informasi selengkapnya, baca Memperbarui pintasan.
Cuplikan kode berikut menunjukkan cara membuat pintasan yang disematkan.
Kotlin
val shortcutManager = getSystemService(ShortcutManager::class.java) if (shortcutManager!!.isRequestPinShortcutSupported) { // Enable the existing shortcut with the ID "my-shortcut". val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build() // Create the PendingIntent object only if your app needs to be notified // that the user let the shortcut be pinned. If the pinning operation fails, // your app isn't notified. Assume here that the app implements a method // called createShortcutResultIntent() that returns a broadcast intent. val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo) // Configure the intent so that your app's broadcast receiver gets the // callback successfully. For details, see PendingIntent.getBroadcast(). val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0, pinnedShortcutCallbackIntent, /* flags */ 0) shortcutManager.requestPinShortcut(pinShortcutInfo, successCallback.intentSender) }
Java
ShortcutManager shortcutManager = context.getSystemService(ShortcutManager.class); if (shortcutManager.isRequestPinShortcutSupported()) { // Enable the existing shortcut with the ID "my-shortcut". ShortcutInfo pinShortcutInfo = new ShortcutInfo.Builder(context, "my-shortcut").build(); // Create the PendingIntent object only if your app needs to be notified // that the user let the shortcut be pinned. If the pinning operation fails, // your app isn't notified. Assume here that the app implements a method // called createShortcutResultIntent() that returns a broadcast intent. Intent pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo); // Configure the intent so that your app's broadcast receiver gets the // callback successfully. For details, see PendingIntent.getBroadcast(). PendingIntent successCallback = PendingIntent.getBroadcast(context, /* request code */ 0, pinnedShortcutCallbackIntent, /* flags */ 0); shortcutManager.requestPinShortcut(pinShortcutInfo, successCallback.getIntentSender()); }
Membuat aktivitas pintasan kustom
![Gambar yang menampilkan aktivitas dialog kustom yang menampilkan perintah 'Apakah
Anda ingin menambahkan ikon peluncur Gmail ke layar utama?' Opsi
kustomnya adalah 'Lain kali' dan 'Tambahkan ikon'.](https://developer.android.com/static/images/guide/topics/ui/shortcuts/pinned-shortcuts-dialog.png?authuser=6&hl=id)
Anda juga dapat membuat aktivitas khusus yang membantu pengguna membuat pintasan, lengkap dengan opsi kustom dan tombol konfirmasi. Gambar 2 menunjukkan contoh jenis aktivitas ini di aplikasi Gmail.
Dalam file manifes aplikasi Anda, tambahkan
ACTION_CREATE_SHORTCUT
ke elemen
<intent-filter>
aktivitas. Deklarasi ini menyiapkan perilaku berikut saat pengguna mencoba
membuat pintasan:
- Sistem memulai aktivitas khusus aplikasi Anda.
- Pengguna menetapkan opsi untuk pintasan tersebut.
- Pengguna memilih tombol konfirmasi.
-
Aplikasi Anda membuat pintasan menggunakan
metode
createShortcutResultIntent()
. Metode ini menampilkanIntent
, yang akan diteruskan kembali oleh aplikasi Anda ke aktivitas yang dijalankan sebelumnya menggunakansetResult()
. -
Aplikasi Anda memanggil
finish()
pada aktivitas yang digunakan untuk membuat pintasan yang disesuaikan.
Demikian pula, aplikasi Anda dapat meminta pengguna untuk menambahkan pintasan yang disematkan ke layar utama setelah penginstalan atau saat pertama kali aplikasi diluncurkan. Metode ini efektif karena membantu pengguna membuat pintasan sebagai bagian dari alur kerja biasa mereka.
Menguji pintasan
Untuk menguji pintasan aplikasi Anda, instal aplikasi di perangkat dengan peluncur yang mendukung pintasan. Kemudian, jalankan beberapa tindakan berikut:
- Sentuh lama ikon peluncur aplikasi untuk melihat pintasan yang Anda tetapkan untuk aplikasi.
- Tarik pintasan untuk menyematkannya ke peluncur perangkat.