Membuat pintasan

Pintasan menayangkan jenis konten tertentu kepada pengguna dengan membantunya mengakses berbagai bagian aplikasi dengan cepat.

Gambar 1. Pintasan aplikasi dan pintasan yang dipasangi pin.

Cara Anda menayangkan konten dengan pintasan bergantung pada kasus penggunaan Anda dan apakah konteks pintasan dikelola aplikasi atau pengguna. Meskipun konteks pintasan statis tidak berubah dan konteks pintasan dinamis terus berubah, aplikasi Anda mendorong konteks dalam kedua kasus tersebut. Dalam kasus saat pengguna memilih cara aplikasi Anda menayangkan konten kepada mereka, seperti dengan pintasan yang disematkan, konteks ditentukan oleh pengguna. Skenario berikut menjelaskan beberapa kasus penggunaan untuk setiap jenis pintasan:

• Pintasan statis paling cocok untuk aplikasi yang menautkan konten menggunakan struktur konsisten sepanjang waktu interaksi pengguna dengan aplikasi. Karena sebagian besar peluncur hanya menampilkan empat pintasan sekaligus, pintasan statis berguna untuk melakukan tugas rutin secara konsisten, seperti jika pengguna ingin melihat kalender atau emailnya dengan cara tertentu.
• Pintasan dinamis digunakan untuk tindakan dalam aplikasi yang sensitif terhadap konteks. Pintasan yang sensitif terhadap konteks disesuaikan dengan tindakan yang dilakukan pengguna di aplikasi. Misalnya, jika Anda membuat game yang memungkinkan pengguna memulai dari level saat ini saat peluncuran, Anda harus sering mengupdate pintasan tersebut. Dengan menggunakan pintasan dinamis, Anda dapat memperbarui pintasan setiap kali pengguna menyelesaikan level.
• Pintasan yang dipasangi pin digunakan untuk tindakan tertentu yang dikelola oleh pengguna. Misalnya, pengguna mungkin ingin menyematkan situs tertentu ke peluncur. Hal ini menguntungkan karena pengguna dapat melakukan tindakan kustom, seperti bernavigasi ke 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 sepanjang waktu versi aplikasi saat ini. Opsi yang baik untuk pintasan statis mencakup melihat pesan terkirim, menyetel alarm, dan menampilkan aktivitas olahraga pengguna hari ini.

Untuk membuat pintasan statis, lakukan hal berikut:

1. Dalam file AndroidManifest.xml aplikasi Anda, temukan aktivitas yang filter intent-nya ditetapkan ke tindakan android.intent.action.MAIN dan kategori android.intent.category.LAUNCHER.

2. Tambahkan elemen <meta-data> ke aktivitas ini yang mereferensikan file resource tempat pintasan aplikasi 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>
   

   Catatan: Jika menggunakan activity-alias, tentukan metadata dalam activity-alias, bukan aktivitas yang ditargetkan menggunakan atribut targetActivity.

3. Buat file resource baru bernama res/xml/shortcuts.xml.

4. Dalam file resource baru, tambahkan elemen root <shortcuts> yang berisi daftar elemen <shortcut>. Di setiap elemen <shortcut>, sertakan informasi tentang pintasan statis, termasuk ikon, 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.Main" />
       <!-- 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 lainnya bersifat opsional.

android:shortcutId

Literal string yang mewakili pintasan saat objek ShortcutManager menjalankan operasi di atasnya.

Catatan: Anda tidak dapat menetapkan nilai atribut ini ke string resource, seperti @string/shortcut_id.

android:shortcutShortLabel

Frasa singkat yang menjelaskan tujuan pintasan. Jika memungkinkan, batasi deskripsi singkat ini hingga 10 karakter.

Untuk informasi selengkapnya, lihat setShortLabel().

Catatan: Nilai atribut ini harus berupa string resource, seperti @string/shortcut_short_label.

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().

Catatan: Nilai atribut ini harus berupa string resource, seperti @string/shortcut_long_label.

android:shortcutDisabledMessage

Pesan yang muncul di peluncur yang didukung saat pengguna mencoba meluncurkan pintasan yang dinonaktifkan. Pesan harus menjelaskan kepada pengguna alasan pintasan dinonaktifkan. Nilai atribut ini tidak berpengaruh jika android:enabled adalah true.

Catatan: Nilai atribut ini harus berupa string resource, seperti @string/shortcut_disabled_message.

android:enabled

Menentukan apakah pengguna dapat berinteraksi dengan pintasan dari peluncur yang didukung. Nilai default android:enabled adalah true. Jika Anda menetapkannya ke false, tetapkan android:shortcutDisabledMessage yang menjelaskan alasan Anda menonaktifkan pintasan. Jika Anda merasa tidak perlu memberikan pesan semacam itu, hapus pintasan tersebut dari file XML secara keseluruhan.

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.

Catatan: Ikon pintasan tidak boleh menyertakan tint.

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 tetapkan.

intent

Tindakan yang akan diluncurkan sistem saat pengguna memilih pintasan. Intent ini harus memberikan nilai untuk atribut android:action.

Catatan: Elemen intent ini tidak dapat menyertakan resource string.

Anda dapat memberikan beberapa intent untuk satu pintasan. Lihat Mengelola beberapa intent dan aktivitas, Menetapkan intent, dan referensi class TaskStackBuilder untuk mengetahui detailnya.

categories

Memberikan pengelompokan untuk jenis tindakan yang dijalankan 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.

Dalam contoh sebelumnya, pintasan ditautkan ke kemampuan yang dideklarasikan untuk CREATE_MESSAGE, yang merupakan intent bawaan Action Aplikasi. Binding kemampuan ini memungkinkan pengguna 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 Anda dan saat aplikasi Anda sedang berjalan. Penggunaan yang baik untuk pintasan dinamis mencakup menelepon orang tertentu, menavigasi ke lokasi tertentu, dan memuat game dari titik simpan terakhir pengguna. Anda juga dapat menggunakan pintasan dinamis untuk membuka percakapan.

Library Jetpack ShortcutManagerCompat adalah bantuan untuk ShortcutManager API, yang memungkinkan Anda mengelola pintasan dinamis di aplikasi. Penggunaan library ShortcutManagerCompat mengurangi kode boilerplate dan membantu memastikan 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.

ShortcutManagerCompat API memungkinkan aplikasi Anda melakukan operasi berikut dengan pintasan dinamis:

• Push dan update: gunakan pushDynamicShortcut() untuk memublikasikan dan mengupdate pintasan dinamis Anda. Jika sudah ada pintasan dinamis atau yang dipasangi pin dengan ID yang sama, setiap pintasan yang dapat diubah akan diupdate.
• Hapus: hapus sekumpulan pintasan dinamis menggunakan removeDynamicShortcuts(). Hapus semua pintasan dinamis menggunakan removeAllDynamicShortcuts().

Untuk informasi selengkapnya tentang menjalankan operasi di pintasan, lihat Mengelola pintasan dan referensi ShortcutManagerCompat.

Berikut contoh pembuatan pintasan dinamis dan pengaitannya dengan aplikasi Anda:

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)

Menambahkan Library Integrasi Pintasan Google

Library Integrasi Pintasan Google adalah library Jetpack opsional. Library ini memungkinkan Anda mendorong pintasan dinamis yang dapat ditampilkan di platform Android, seperti peluncur, dan platform Google. Dengan library ini, pengguna dapat menemukan pintasan Anda untuk mengakses konten tertentu atau memutar ulang tindakan di aplikasi dengan cepat.

Pintasan dinamis yang didorong dengan library ini tidak tunduk pada batas pintasan yang diterapkan berdasarkan per perangkat. Dengan demikian, aplikasi Anda dapat mengirimkan pintasan setiap kali pengguna menyelesaikan tindakan terkait di aplikasi Anda. Dengan mengirimkan pintasan yang sering digunakan dengan cara ini, Google dapat memahami pola penggunaan pengguna Anda dan menyarankan pintasan yang relevan secara kontekstual kepada mereka.

Misalnya, Asisten dapat belajar dari pintasan yang didorong dari aplikasi pelacakan kebugaran Anda bahwa pengguna biasanya berlari setiap pagi dan secara proaktif menyarankan pintasan "mulai lari" saat pengguna mengangkat ponselnya di pagi hari.

Library Integrasi Pintasan Google tidak menawarkan fungsi yang dapat membuat alamat sendiri. Menambahkan library ini ke aplikasi Anda memungkinkan platform Google menyerap pintasan yang didorong aplikasi Anda menggunakan ShortcutManagerCompat.

Untuk menggunakan library ini di aplikasi Anda, ikuti langkah-langkah berikut:

1. Update file gradle.properties Anda untuk mendukung library AndroidX:

   android.useAndroidX=true
   # Automatically convert third-party libraries to use AndroidX
   android.enableJetifier=true
   

2. Di app/build.gradle, tambahkan dependensi untuk Library Integrasi Pintasan Google dan ShortcutManagerCompat:

   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.

Catatan: Sebaiknya gunakan pushDynamicShortcut untuk menerapkan pintasan dinamis menggunakan Library Integrasi Pintasan Google. Aplikasi Anda dapat menggunakan metode lain untuk memublikasikan pintasan, tetapi pintasan tersebut mungkin gagal jika mencapai batas pintasan maksimum.

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 dipasangi pin akan terlihat di peluncur yang didukung sebagai ikon terpisah. Gambar 1 menunjukkan perbedaan antara kedua jenis pintasan ini.

Catatan: Saat Anda mencoba menyematkan pintasan ke peluncur yang didukung, pengguna akan menerima dialog konfirmasi yang meminta izin untuk menyematkan pintasan tersebut. Jika pengguna tidak mengizinkan pintasan dipasangi pin, peluncur akan membatalkan permintaan.

Untuk menyematkan pintasan ke peluncur yang didukung menggunakan aplikasi Anda, selesaikan langkah-langkah berikut:

1. Gunakan isRequestPinShortcutSupported() untuk memverifikasi bahwa peluncur default perangkat mendukung penyematan pintasan dalam aplikasi.

2. Buat objek ShortcutInfo dengan salah satu dari dua cara, bergantung pada apakah pintasan ada atau tidak:

   1. 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.
   2. Jika Anda menyematkan pintasan baru, buat objek ShortcutInfo yang berisi ID, intent, dan label singkat untuk pintasan baru tersebut.
   Catatan: Karena sistem melakukan pencadangan dan pemulihan pada pintasan yang dipasangi pin secara otomatis, ID pintasan ini harus berisi string yang stabil dan konstan atau ID sisi server, bukan ID yang dibuat secara lokal yang mungkin tidak masuk akal di perangkat lain.

3. Pasang pin pintasan ke peluncur perangkat dengan memanggil requestPinShortcut(). Selama proses ini, Anda dapat meneruskan objek PendingIntent, yang akan memberi tahu aplikasi Anda hanya saat pintasan berhasil dipasangi pin.

   Catatan: Jika pengguna tidak mengizinkan pintasan dipasangi pin ke peluncur, aplikasi Anda tidak akan menerima callback.

   Setelah pintasan dipasangi pin, aplikasi Anda dapat mengupdate kontennya menggunakan metode updateShortcuts(). Untuk mengetahui informasi selengkapnya, baca Mengupdate pintasan.

Cuplikan kode berikut menunjukkan cara membuat pintasan yang dipasangi pin.

Catatan: Dapatkan instance class ShortcutManager dengan memanggil getSystemService() dengan class ShortcutManager.

val shortcutManager = getSystemService<ShortcutManager>()

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)
}

Catatan: Lihat juga API Support Library isRequestPinShortcutSupported() dan requestPinShortcut(), yang berfungsi di Android 7.1 (API level 25) dan yang lebih rendah. Support Library akan menggunakan kembali tambahan EXTRA_SHORTCUT_INTENT yang tidak digunakan lagi untuk mencoba proses pemasangan pin.

Membuat aktivitas pintasan kustom

Gambar 2. Contoh aktivitas dialog pintasan aplikasi kustom.

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 akan menyiapkan perilaku berikut saat pengguna mencoba membuat pintasan:

1. Sistem memulai aktivitas khusus aplikasi Anda.
2. Pengguna menetapkan opsi untuk pintasan tersebut.
3. Pengguna memilih tombol konfirmasi.
4. Aplikasi Anda membuat pintasan menggunakan metode createShortcutResultIntent(). Metode ini menampilkan Intent, yang akan digunakan oleh aplikasi Anda untuk kembali ke aktivitas yang dijalankan sebelumnya menggunakan setResult().
5. Aplikasi Anda memanggil finish() di aktivitas yang digunakan untuk membuat pintasan yang disesuaikan.

Demikian pula, aplikasi Anda dapat meminta pengguna untuk menambahkan pintasan yang dipasangi pin ke layar utama setelah penginstalan atau saat pertama kali aplikasi diluncurkan. Metode ini efektif karena membantu pengguna membuat pintasan sebagai bagian dari alur kerja umum mereka.

Menguji pintasan

Untuk menguji pintasan aplikasi Anda, instal aplikasi Anda di perangkat dengan peluncur yang mendukung pintasan. Kemudian, jalankan beberapa tindakan berikut:

• Sentuh lama ikon peluncur aplikasi Anda untuk melihat pintasan yang Anda tentukan untuk aplikasi Anda.
• Tarik pintasan untuk menyematkannya ke peluncur perangkat.