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. 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 suatu 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" />
     </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.

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. Kandidat yang cocok untuk pintasan dinamis mencakup menelepon orang tertentu, menavigasi ke lokasi tertentu, dan memuat game dari titik simpan terakhir pengguna.

API ShortcutManager memungkinkan Anda menyelesaikan beberapa operasi berikut di pintasan dinamis:

• Publikasi: Gunakan setDynamicShortcuts() untuk menentukan ulang seluruh daftar pintasan dinamis, atau gunakan addDynamicShortcuts() untuk menambah daftar pintasan dinamis yang ada.
• Update: Gunakan metode updateShortcuts().
• 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 ShortcutManager.

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

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>(ShortcutManager::class.java)

val shortcut = ShortcutInfo.Builder(context, "id1")
        .setShortLabel("Website")
        .setLongLabel("Open the website")
        .setIcon(Icon.createWithResource(context, R.drawable.icon_website))
        .setIntent(Intent(Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")))
        .build()

shortcutManager!!.dynamicShortcuts = Arrays.asList(shortcut)

ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);

ShortcutInfo shortcut = new ShortcutInfo.Builder(context, "id1")
    .setShortLabel("Website")
    .setLongLabel("Open the website")
    .setIcon(Icon.createWithResource(context, R.drawable.icon_website))
    .setIntent(new Intent(Intent.ACTION_VIEW,
                   Uri.parse("https://www.mysite.example.com/")))
    .build();

shortcutManager.setDynamicShortcuts(Arrays.asList(shortcut));

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 pemasangan pin pada 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.