Membuat pintasan

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

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, konteks dalam kedua kasus tersebut dikelola oleh aplikasi Anda. Jika pengguna memilih cara aplikasi Anda menayangkan konten kepadanya, misalnya dengan pintasan yang dipasangi pin, maka konteksnya ditentukan oleh pengguna. Skenario berikut mendemonstrasikan 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 dapat menampilkan empat pintasan sekaligus, pintasan statis berguna untuk aktivitas umum. Misalnya, jika pengguna ingin melihat kalender atau emailnya dengan cara tertentu, menggunakan pintasan statis akan memastikan konsistensi pengalaman mengerjakan tugas rutin.
• 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 untuk memulai dari level saat ini ketika peluncuran, pintasan tersebut harus sering diupdate. Menggunakan pintasan dinamis memungkinkan pintasan tersebut diupdate setiap kali pengguna menyelesaikan level.
• Pintasan yang dipasangi pin digunakan untuk tindakan tertentu yang dikelola oleh pengguna. Misalnya, pengguna mungkin ingin memasang pin pada 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 tersebut harus tetap konsisten sepanjang waktu versi aplikasi saat ini. Kandidat yang cocok untuk pintasan statis mencakup melihat pesan terkirim, menyetel alarm, dan menampilkan aktivitas olahraga pengguna hari ini.

Untuk membuat pintasan statis, selesaikan rangkaian langkah berikut:

1. Dalam file manifes aplikasi Anda (AndroidManifest.xml), cari 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 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>
   

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

4. Dalam file resource baru ini, tambahkan elemen root <shortcuts> yang berisi daftar elemen <shortcut>. Setiap elemen <shortcut> berisi informasi tentang pintasan statis, termasuk ikonnya, label deskripsinya, 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 atribut yang berbeda dalam pintasan statis. Anda harus memberikan nilai untuk android:shortcutId dan android:shortcutShortLabel. Semua nilai lain bersifat opsional.

android:shortcutId

Literal string, yang mewakili pintasan saat objek ShortcutManager menjalankan operasinya.

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

android:shortcutShortLabel

Frasa singkat yang menjelaskan tujuan pintasan. Jika memungkinkan, batasi panjang "deskripsi singkat" pintasan 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, dan bukan android:shortcutShortLabel. Jika memungkinkan, batasi panjang "deskripsi panjang" pintasan 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 dalam peluncur yang didukung saat pengguna mencoba meluncurkan pintasan yang dinonaktifkan. Pesan itu harus menjelaskan kepada pengguna mengapa pintasan tersebut sekarang 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 menetapkannya ke false, Anda juga harus menetapkan android:shortcutDisabledMessage yang menjelaskan mengapa pintasan tersebut dinonaktifkan. Jika Anda merasa tidak perlu memberikan pesan semacam itu, akan sangat mudah untuk menghapus 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 bila memungkinkan untuk meningkatkan performa dan konsistensi.

Catatan: Ikon pintasan tidak boleh menyertakan tint.

Mengonfigurasikan elemen internal

File XML yang mencantumkan pintasan statis aplikasi mendukung beberapa elemen berikut di dalam setiap elemen <shortcut>. Anda harus menyertakan elemen internal intent untuk setiap pintasan statis yang ditetapkan.

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

Dalam contoh ini, pintasan ditautkan ke kemampuan yang dideklarasikan untuk CREATE_MESSAGE, yang merupakan intent bawaan Action Aplikasi. Dengan binding kemampuan khusus ini, pengguna dapat menggunakan perintah lisan dengan Asisten Google untuk memanggil pintasan ini.

Membuat pintasan dinamis

Pintasan dinamis memberikan link ke tindakan spesifik yang sensitif terhadap konteks dalam aplikasi Anda. Tindakan tersebut dapat berubah di antara penggunaan aplikasi Anda, dan bahkan dapat berubah saat aplikasi sedang berjalan. Contoh kasus 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 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.

ShorcutManagerCompat 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, semua pintasan yang dapat diubah akan diupdate.
• Hapus: Hapus sekumpulan pintasan dinamis menggunakan removeDynamicShortcuts(), atau hapus semua pintasan dinamis menggunakan removeAllDynamicShortcuts().

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

Contoh pembuatan pintasan dinamis dan pengaitannya dengan aplikasi Anda ditampilkan dalam cuplikan kode berikut:

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)

ShortcutInfo 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. Ini memungkinkan Anda mendorong pintasan dinamis yang dapat ditampilkan di platform Android (seperti peluncur) dan platform Google (seperti Asisten). Dengan library ini, pengguna dapat menemukan pintasan dengan mudah untuk mengakses konten tertentu atau memutar ulang tindakan di aplikasi. Misalnya, aplikasi pesan dapat mendorong pintasan dinamis untuk kontak "Alex" setelah pengguna mengirim pesan kepada orang tersebut. Setelah pintasan dinamis tersebut didorong, jika pengguna meminta Asisten, "Ok Google, kirim pesan ke Alex di ExampleApp", Asisten dapat meluncurkan ExampleApp dan otomatis mengonfigurasi untuk mengirim pesan ke Alex.

Pintasan dinamis yang didorong dengan library ini tidak tunduk pada batasan pintasan yang diterapkan berdasarkan perangkat, sehingga aplikasi dapat 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 didorong dari aplikasi pelacakan kebugaran yang biasanya digunakan pengguna untuk 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 untuk 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'
              ...
            }
   
         

3. Dengan dependensi library yang ditambahkan ke project Android, aplikasi Anda dapat menggunakan metode pushDynamicShortcut() dari ShortcutManagerCompat untuk mendorong pintasan dinamis yang akan memenuhi syarat untuk ditampilkan di peluncur dan platform Google yang ikut serta.

   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 memasang pin pada pintasan ke peluncur yang didukung, pengguna akan menerima dialog konfirmasi yang meminta izin untuk memasang pin pada pintasan tersebut. Jika pengguna tidak mengizinkan pintasan itu dipasangi pin, peluncur akan membatalkan permintaan tersebut.

Untuk memasang pin pada pintasan ke peluncur yang didukung menggunakan aplikasi Anda, selesaikan rangkaian 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 sudah ada atau belum:

   1. Jika pintasan sudah ada, buat objek ShortcutInfo yang hanya berisi ID pintasan yang ada. Sistem akan otomatis menemukan dan memasang pin pada semua informasi lain yang terkait dengan pintasan.
   2. Jika Anda memasang pin pada pintasan baru, buat objek ShortcutInfo yang berisi ID, intent, dan label singkat untuk pintasan baru tersebut.

   Catatan: Karena sistem otomatis menjalankan pencadangan dan pemulihan pada pintasan yang dipasangi pin, ID pintasan tersebut harus berisi string konstan yang stabil atau ID sisi server, dan bukan ID yang dihasilkan secara lokal yang mungkin tidak sesuai di perangkat lain.

3. Coba untuk memasang pin pada pintasan ke peluncur perangkat dengan memanggil requestPinShortcut(). Selama proses ini, Anda dapat meneruskan objek PendingIntent, yang akan memberi tahu aplikasi Anda hanya saat pintasan tersebut 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 informasi selengkapnya, baca Mengupdate pintasan.

Cuplikan kode berikut menunjukkan cara membuat pintasan yang dipasangi pin:

Catatan: Instance class ShortcutManager harus diperoleh menggunakan Context.getSystemService(Class) dengan argumen ShortcutManager.class atau Context.getSystemService(String) dengan argumen Context.SHORTCUT_SERVICE.

val shortcutManager = getSystemService(ShortcutManager::class.java)

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Assumes there's already a shortcut with the ID "my-shortcut".
    // The shortcut must be enabled.
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user allowed the shortcut to be pinned. Note that, if the
    // pinning operation fails, your app isn't notified. We assume here that the
    // app has implemented 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)
}

ShortcutManager shortcutManager =
        context.getSystemService(ShortcutManager.class);

if (shortcutManager.isRequestPinShortcutSupported()) {
    // Assumes there's already a shortcut with the ID "my-shortcut".
    // The shortcut must be enabled.
    ShortcutInfo pinShortcutInfo =
            new ShortcutInfo.Builder(context, "my-shortcut").build();

    // Create the PendingIntent object only if your app needs to be notified
    // that the user allowed the shortcut to be pinned. Note that, if the
    // pinning operation fails, your app isn't notified. We assume here that the
    // app has implemented 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());
}

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

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.

Menguji pintasan

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

• Ketuk lama pada ikon peluncur aplikasi Anda untuk melihat pintasan yang telah Anda tentukan untuk aplikasi tersebut.
• Ketuk dan tarik pintasan untuk memasang pin pada pintasan tersebut ke peluncur perangkat.