Membuat shortcuts.xml

Setelah Anda mengidentifikasi fungsi aplikasi dan intent bawaan (BII) bawaan yang sesuai untuk diimplementasikan, deklarasikan BII yang didukung fungsi Anda dengan menentukan elemen capability dalam file resource shortcuts.xml. Mendeklarasikan BII sebagai capability akan mendaftarkan dukungan untuk intent semantik tersebut di aplikasi Anda, dan memungkinkan fulfillment kueri suara untuk intent tersebut menggunakan Asisten Google.

Asisten menggunakan natural language processing untuk mengekstrak parameter dari kueri pengguna. Referensi intent bawaan mencantumkan kolom yang dapat diekstrak oleh setiap BII dari kueri pengguna yang terkait. Misalnya, jika pengguna memanggil kemampuan [actions.intent.GET_FOOD_OBSERVATION][] di aplikasi Anda dengan mengucapkan, "Ok Google, Tanyakan kepada ExampleApp apa yang saya makan untuk Makan Siang Jumat lalu", Asisten mengekstrak parameter BII berikut dari permintaan pengguna:

• foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
• foodObservation.startTime = "2024-09-06T00:00:00"
• foodObservation.endTime = "2024-09-06T23:59:59"

Asisten meneruskan parameter BII ke intent fulfillment yang ditentukan dalam capability. Satu atau beberapa elemen intent dapat ditentukan dalam kemampuan untuk mengakomodasi berbagai cara yang mungkin digunakan pengguna untuk memanggil BII. Misalnya, Anda dapat menentukan intent fulfillment yang memerlukan kedua parameter BII dalam contoh di atas. Anda kemudian dapat menentukan intent kedua yang memerlukan satu parameter BII, foodObservation.forMeal, yang melaporkan semua makanan pada hari tertentu, seperti "Ok Google, Tanyakan kepada ExampleApp apa yang saya makan untuk Makan Siang".

Catatan: Penggantian intent yang tidak memerlukan parameter agar dapat memenuhi permintaan pengguna diperlukan untuk setiap capability. Intent penggantian ini meningkatkan pengalaman pengguna dengan memungkinkan tindakan agar berhasil, bahkan untuk kueri pengguna yang tidak jelas seperti "Ok Google, Tanyakan kepada ExampleApp apa yang saya makan".

Ringkasan

Anda mengonfigurasi Action Aplikasi menggunakan file shortcuts.xml yang ditempatkan di direktori res/xml project aplikasi, lalu membuat referensi ke shortcuts.xml dalam manifes aplikasi Anda. Tambahkan referensi ke shortcuts.xml di manifes aplikasi Anda dengan mengikuti langkah-langkah ini:

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 referensi ke shortcuts.xml di AndroidManifest.xml menggunakan tag <meta-data> di Activity yang memiliki filter intent untuk MAIN dan LAUNCHER, sebagai berikut:

   <meta-data
      android:name="android.app.shortcuts"
      android:resource="@xml/shortcuts" />
   

Contoh di atas mendeklarasikan resource XML untuk file xml/shortcuts.xml dalam APK. Untuk detail selengkapnya tentang cara mengonfigurasi pintasan, lihat Membuat pintasan statis di dokumentasi developer Android.

Catatan: Jika Anda menggunakan alat obfuscation untuk APK rilis, nonaktifkan obfuscation untuk file shortcuts.xml aplikasi Anda menggunakan daftar yang diizinkan. Jika tidak, Anda kemungkinan akan mengalami error saat mengupload APK ke Konsol Google Play.

Library Jetpack androidx.core:core:1.6.0 (atau yang lebih baru) diperlukan dalam project Android Anda untuk menghindari error kompilasi saat menentukan kemampuan Action Aplikasi di shortcuts.xml. Untuk mengetahui detailnya, lihat Mulai menggunakan Android Jetpack.

Pintasan statis

Saat menentukan capability, Anda dapat mendeklarasikan elemen shortcut statis di shortcuts.xml untuk memperluas fungsi kemampuan. Pintasan statis diserap oleh Asisten saat Anda mengupload rilis ke Konsol Google Play. Karena pintasan statis hanya dapat dibuat dan diupdate dengan membuat rilis baru, pintasan tersebut paling berguna untuk menyoroti aktivitas dan konten umum dalam aplikasi Anda.

Catatan: Asisten juga dapat menampilkan pintasan dinamis kepada pengguna. Pintasan dinamis disesuaikan untuk pengguna Anda, serta dapat dibuat dan diperbarui pada waktu proses. Untuk mengetahui detailnya, lihat Mendorong pintasan dinamis ke Asisten.

Anda dapat mengaktifkan fungsi Action Aplikasi berikut dengan pintasan statis:

• Pintasan kemampuan. Buat pintasan yang meluncurkan instance capability Anda yang berisi nilai parameter intent yang telah ditetapkan. Misalnya, Anda dapat mendeklarasikan pintasan aplikasi "Mulai lari" yang memanggil kemampuan BII START_EXERCISE di aplikasi kebugaran Anda.

  Pintasan ini berisi atribut intent, shortLabel, dan longLabel, sehingga memenuhi syarat untuk disarankan dan terpenuhi sebagai chip di platform proaktif, seperti Asisten atau saat menekan lama ikon aplikasi di peluncur Android. Pintasan tindakan juga dapat berfungsi sebagai pintasan entitas, yang dijelaskan di bawah, dengan mengaitkannya ke capability menggunakan tag <capability-binding>.

• Pintasan entitas. Pintasan entity memberikan daftar parameter value yang didukung untuk fulfillment kueri suara capability. Misalnya, pintasan entity dengan daftar jenis olahraga ("gerak jalan", "berlari", dll.) yang terikat ke parameter BII exercise.name dari kemampuan START_EXERCISE. Jika ucapan pengguna cocok dengan entity, ID shortcutId diteruskan ke intent, bukan nilai kueri pengguna yang mentah.

  Pintasan Entity tidak menentukan atribut intent, shortLabel, atau longLabel, dan oleh karena itu tidak disarankan pada platform proaktif. Untuk mengetahui detailnya, lihat Inventaris inline untuk Action Aplikasi.

  Catatan: Pintasan statis yang dideklarasikan sebagai pintasan entitas dihapus oleh LauncherApps API, artinya fitur tersebut tersedia untuk peluncur Android.

Skema Kemampuan

Tabel berikut menjelaskan skema Action Aplikasi untuk elemen capability di shortcuts.xml. Saat menyertakan tag, semua atributnya wajib kecuali ditandai "opsional".

Tag shortcuts.xml	Ada dalam	Atribut
<capability>	<shortcuts>	android:name app:queryPatterns (hanya berlaku untuk intent kustom)
<intent>	<capability>	android:action (opsional) android:targetClass (opsional) android:targetPackage (opsional) android:data (opsional)
<url-template>	<intent>	android:value
<extra>	<intent>	android:key android:value Hanya berlaku untuk pemanggilan aplikasi latar depan
<parameter>	<intent>	android:name android:key android:mimeType (hanya berlaku untuk intent kustom) android:required (opsional) app:shortcutMatchRequired (opsional)
<shortcut-fulfillment>	<capability>	Hanya berlaku untuk inventaris inline
<parameter>	<shortcut-fulfillment>	android:name
<slice>	<capability>	Hanya berlaku untuk Android Slice

Deskripsi skema kemampuan

Bagian ini menjelaskan elemen skema capability.

<capability>

capability yang menentukan intent Action Aplikasi yang didukung aplikasi Anda. Setiap elemen <capability> dalam file shortcuts.xml Anda harus menyediakan setidaknya satu <intent> untuk menangani fulfillment tindakan.

Atribut:

• android:name: ID Tindakan intent bawaan (misalnya, [actions.intent.GET_FOOD_OBSERVATION][]). Untuk daftar intent bawaan yang didukung, lihat referensi intent bawaan.
• app:queryPatterns: Resource array string dari kueri yang diharapkan dari pengguna untuk intent ini. Atribut ini hanya berlaku untuk intent kustom, karena BII sudah menyertakan model cara umum yang digunakan pengguna untuk mengekspresikan tugas yang berusaha mereka lakukan, atau informasi yang mereka cari.

Catatan: Intent bawaan Action Aplikasi berbeda dengan intent Android. BII membuat model kueri pengguna untuk tugas yang ingin dilakukan pengguna di aplikasi Anda. Sebaliknya, intent Android meluncurkan tujuan di aplikasi Anda dengan konteks yang disertakan. Anda mendeklarasikan tag capability untuk memetakan BII ke intent Android yang sesuai, sehingga memungkinkan pengguna meluncurkan fungsi dalam aplikasi dengan memanggil BII dengan Asisten.

<intent>

Elemen intent Android yang menentukan cara kueri pengguna harus diisi menggunakan fungsi dalam aplikasi. Developer dapat menyediakan beberapa tag <intent> dalam capability. Asisten berupaya memenuhi kueri pengguna menggunakan <intent> pertama di capability yang menyediakan semua parameter yang diperlukan.

Atribut:

• android:action: jenis Action intent. Default-nya adalah ACTION_VIEW.
• android:targetClass: Class Aktivitas Target, misalnya: "com.example.exercise.ExerciseActivity"
• android:targetPackage: Paket yang berisi class Aktivitas target, misalnya: "com.example.exercise
• android:data: Kolom ini ditimpa oleh <url-template> jika tag tersebut dideklarasikan di intent.

Catatan: android:targetClass dan android:targetPackage diperlukan untuk intent yang secara eksplisit menargetkan Aktivitas. Atribut android:data juga dapat digunakan untuk menentukan Aktivitas target. Untuk mengetahui detailnya, lihat Opsi fulfillment intent.

<url-template>

Template untuk membuat URI deep link yang akan dibuka di perangkat. Template dapat diluaskan dengan parameter intent bawaan jika semua parameter yang diperlukan untuk template tersedia. Untuk contoh template URL HTTP, lihat artikel Wikipedia tentang template URL. Format template mengikuti spesifikasi template URI RFC6570.

Berikut adalah beberapa contoh nilai template URL:

Template	Nilai	Nilai yang diperluas
https://example.com/test{?foo,bar}	"foo": "123" "bar": "456"	https://example.com/test?foo=123&bar=456
https://example.com/test?utm_campaign=appactions{&foo,bar}	"foo": "123" "bar": "456"	https://example.com/test?utm_campaign=appactions&foo=123&bar=456
https://example.com/test?utm_campaign=appactions{#foo}	"foo": "123"	https://example.com/test?utm_campaign=appactions#foo=123
myapp://example/{foo}	"foo": "123"	myapp://example/123

Untuk informasi selengkapnya tentang cara mengonfigurasi template URL, lihat Template URL dalam fulfillment.

Catatan: <url-template> adalah metode opsional untuk menargetkan Aktivitas dalam intent. Untuk mengetahui detailnya, lihat Opsi fulfillment intent.

<extra>

Menentukan data tambahan untuk intent. Untuk Action Aplikasi, kolom ini hanya digunakan untuk mengaktifkan [pemanggilan aplikasi latar depan][] untuk capability.

<parameter>

Memetakan parameter BII ke parameter value intent. Untuk informasi selengkapnya, lihat Data dan pencocokan parameter.

Atribut:

• android:name: Nama parameter BII yang akan dikaitkan dengan parameter intent ini. Nama harus berupa kolom tingkat ikon daun nest dari parameter BII (misalnya, foodObservation.aboutFood.name).
• android:key: Kunci yang ditentukan developer untuk parameter value BII. Misalnya, Anda dapat menentukan contact_name untuk parameter BII message.recipient.name.
• android:mimeType: mimeType parameter, seperti text/*. Kolom ini hanya diperlukan untuk parameter intent kustom.
• android:required: Mendeklarasikan apakah kueri pengguna perlu menyertakan parameter ini agar intent ini digunakan untuk fulfillment. Jika parameter tidak tersedia, Asisten akan mencoba memenuhi kueri pengguna menggunakan intent berikutnya yang ditentukan untuk capability.

<shortcut-fulfillment>

Menentukan bahwa intent yang ditentukan dalam pintasan inventaris inline untuk parameter yang ditentukan akan digunakan untuk fulfillment. Untuk mengetahui detailnya, lihat Fulfillment menggunakan intent pintasan.

<parameter> (untuk <shortcut-fulfillment>)

Atribut opsional yang memetakan satu parameter BII ke fulfillment pintasan inventaris inline. Untuk mengetahui detailnya, lihat Fulfillment menggunakan intent pintasan.

Atribut:

• android:name: Nama parameter BII yang akan dikaitkan dengan fulfillment pintasan inventaris inline. Nama harus berupa kolom tingkat ikon daun nest dari parameter BII (misalnya, menuItem.name).

<slice>

Memungkinkan Asisten menyematkan hasil kueri yang cocok dengan capability ini sebagai Android Slice. Untuk mengetahui detailnya, lihat Mengintegrasikan Action Aplikasi dengan Android Slice.

Skema pintasan

Tabel berikut menjelaskan atribut elemen shortcut yang digunakan untuk mengaktifkan fungsionalitas Action Aplikasi. Saat menyertakan tag, semua atributnya wajib ada kecuali jika ditandai "opsional".

Tag shortcuts.xml	Ada dalam	Atribut
<shortcut>	<shortcuts>	android:shortcutId android:shortcutShortLabel android:shortcutLongLabel (opsional) android:icon (opsional)
<intent>	<shortcut>	android:action android:targetClass (opsional) android:targetPackage (opsional) android:data (opsional)
<capability-binding>	<shortcut>	android:key
<parameter-binding>	<capability-binding>	android:key (opsional) android:value
<extra>	<shortcut>	android:name (opsional) android:value Hanya berlaku untuk Pencocokan parameter enum.

Deskripsi skema pintasan

Bagian ini menjelaskan elemen skema shortcut.

<shortcut>

<shortcut> Android yang ditentukan di shortcuts.xml dengan atribut tertentu yang relevan untuk Action Aplikasi. Nilai string untuk kolom shortcutShortLabel dan shortcutLongLabel direferensikan melalui resource string APK.

Atribut:

• android:shortcutId: ID untuk pintasan ini.
• android:shortcutShortLabel: Resource string yang menampilkan frasa pintasan singkat. Misalnya, "@string/callDavidShort" yang menampilkan nilai "Telepon David".
• android:shortcutLongLabel: Resource string yang menampilkan frasa pintasan yang panjang. Misalnya, "@string/callDavidLong" yang menampilkan nilai "Lakukan panggilan audio ke David".

<intent>

Intent Android yang terkait dengan pintasan ini. intent ini dijalankan saat pengguna meluncurkan pintasan ini menggunakan suara atau sentuhan.

Atribut intent shortcut identik dengan atribut capability intent.

<capability-binding>

Mengaitkan shortcut ke capability Action Aplikasi. Menambahkan elemen ini ke shortcut memungkinkannya untuk fulfillment suara menggunakan Assistant.

Atribut:

• android:key: Atribut android:name dari capability yang terikat dengan shortcut ini. Misalnya, actions.intent.START_EXERCISE.

<parameter-binding>

Atribut opsional yang mengaitkan shortcut ke satu parameter Action Aplikasi capability. Jika parameter-binding ditentukan untuk shortcut, pintasan dapat digunakan untuk memberikan entity inventaris inline ke parameter BII. Untuk mengetahui detail, lihat Inventaris inline untuk Action Aplikasi.

Atribut:

• android:key: Nama parameter BII capability yang akan dikaitkan dengan pintasan ini. Misalnya, exercise.name.
• android:value: nilai entity. Ini dapat berupa satu entity atau daftar resource.

<extra>

Data paket extra untuk pintasan. sameAs adalah satu-satunya data yang relevan dengan elemen shortcut Action Aplikasi. URL sameAs merujuk pada halaman web referensi yang secara jelas mengidentifikasi entitas. Digunakan untuk menentukan nilai enum jika dan hanya jika jenis parameter intent adalah subjenis schema.org/Enumeration. Kolom ini wajib ada untuk kolom parameter yang jenisnya adalah subjenis schema.org/Enumeration (misalnya: MealTypeBreakfast).

Atribut:

• android:key: Nilai yang didukung untuk Action Aplikasi adalah: sameAs
• android:value: Nilai URL sameAs

Untuk detail selengkapnya, lihat Mencocokkan parameter value yang di-enumerasi.

Opsi fulfillment intent

Anda menentukan elemen intent dalam <capability> untuk mendeklarasikan cara Asisten merespons, atau memenuhi, perintah suara pengguna yang cocok dengan kemampuan tersebut. Ada beberapa cara untuk mengonfigurasi cara intent meluncurkan tujuan fulfillment di aplikasi Anda, bergantung pada cara navigasi aplikasi Anda disusun.

Opsi fulfillment berikut tersedia:

• Intent eksplisit: Meluncurkan komponen aplikasi tertentu dengan menentukan atribut targetClass dan targetPackage untuk intent. Ini adalah metode fulfillment Action Aplikasi yang direkomendasikan.

• Deep link: Meluncurkan tujuan aplikasi menggunakan deep link Android dengan menentukan tag <url-template> dalam elemen intent. Metode ini berguna jika navigasi aplikasi Anda sudah mengandalkan deep link.

• Data intent: Anda dapat menyediakan URI fulfillment di atribut android:data intent. Kolom ini ditimpa oleh data <url-template> jika tag tersebut juga ditentukan dalam intent.

Catatan: Opsi fulfillment ini saling eksklusif. Misalnya, jika Anda menentukan intent eksplisit dengan menggunakan atribut targetClass dan targetPackage, Anda tidak perlu menentukan <url-template>.

Data dan pencocokan parameter

Secara default, Asisten mengirimkan parameter BII yang diekstrak dari kueri pengguna ke aplikasi Anda sebagai data extra dari intent Android yang ditentukan dalam capability.

Atau, Anda dapat mendeklarasikan tag <url-template> dalam capability yang berisi placeholder untuk parameter dinamis. Template ini memetakan ke salah satu aktivitas Android Anda menggunakan URL Link Aplikasi, skema kustom, atau URL berbasis Intent.

Menggunakan Tambahan intent

Contoh berikut menunjukkan intent eksplisit yang ditentukan untuk fulfillment capability:

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Dengan contoh di atas, untuk kueri pengguna seperti, "Ok Google, mulai sesi lari saya", aplikasi menerima intent yang memanggil komponen: targetPackage, targetClass. Komponen ini menerima Tambahan dengan key = "exercise", value = "Running".

Menggunakan template URL untuk deep link Android

Jika aplikasi Anda sudah dapat menangani URL yang tertaut ke aplikasi, dengan parameter dinamis, Anda dapat menentukan <url-template> dalam intent untuk menghasilkan deep link Android untuk fulfillment. Contoh berikut menentukan <url-template>:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Berdasarkan contoh di atas, untuk kueri pengguna seperti, “Ok Google, mulai sesi lari saya", aplikasi akan menerima URL yang dibuat: "myapp://start?exercise=Running".

Catatan: Jika URL yang dihasilkan untuk intent menggunakan <url-template> untuk fulfillment ditautkan ke aplikasi, dan ada filter intent yang relevan yang ditambahkan di file resource AndroidManifest.xml, atribut targetClass dan targetActivity tidak perlu ditentukan di intent.

Untuk memetakan parameter BII ke posisi di URL, Anda harus menggunakan atribut android:name pada tag <parameter>. Atribut ini sesuai dengan nilai android:key di template URL yang ingin Anda ganti dengan informasi dari pengguna. Nilai android:key harus ada di <url-template> dan diapit oleh tanda kurung kurawal ({}).

Mencocokkan parameter value yang dienumerasi

Beberapa parameter BII memberikan nilai terenumerasi untuk intent fulfillment Anda, misalnya, nilai teks yang didukung dari BII RECORD_FOOD_OBSERVATION. Untuk parameter ini, Asisten mencocokkan kueri pengguna ("Sarapan") dengan entity yang nilai sameAs-nya cocok dengan URL skema enum (https://schema.googleapis.com/MealTypeBreakfast). Guna mengaitkan nilai enum untuk entity yang didukung, Anda mendeklarasikan pengaitan sameAs dalam shortcut. Contoh berikut menunjukkan objek atribusi sameAs untuk pintasan entitas inline:

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

Pada contoh di atas, jika kemampuan RECORD_FOOD_OBSERVATION memicu kecocokan untuk jenis makanan "sarapan", Tambahan berikut akan dikirim dengan intent fulfillment:

• key = "for_meal"
• value = "meal_breakfast"

Fitur

Fitur Action Aplikasi berikut tersedia di shortcuts.xml.

Inventaris inline untuk Action Aplikasi

Untuk beberapa parameter BII, pintasan dapat digunakan untuk memandu ekstraksi entity ke serangkaian entity yang didukung dan ditentukan dalam shortcuts.xml, yang dikenal sebagai inventaris inline. Untuk mengetahui detailnya, lihat Inventaris inline.

Intent kustom

Intent kustom dapat dideklarasikan di shortcuts.xml untuk mengaktifkan fitur suara di aplikasi Anda yang tidak cocok dengan BII yang tersedia. Meskipun mirip dengan fungsi BII, intent kustom memerlukan dua atribut tambahan dalam shortcuts.xml:

• app:queryPatterns: Resource array yang mendeklarasikan berbagai pola kueri untuk intent kustom.

• android:mimeType: Jenis parameter intent kustom. Kolom ini tidak wajib untuk BII, tempat jenis parameter diketahui. Untuk parameter intent kustom, jenis semantik yang didukung harus dideklarasikan.

Untuk detail selengkapnya, lihat Intent kustom.