Intent kustom

Setiap aplikasi berbeda, dan tidak semua fungsi aplikasi cocok dengan intent bawaan Action Aplikasi (BII) yang tersedia. Jika tidak ada BII untuk fungsi aplikasi, Anda dapat menggunakan intent kustom untuk memperluas aplikasi dengan Action Aplikasi.

Seperti BII, intent kustom mengikuti skema shortcuts.xml dan bertindak sebagai titik koneksi antara Asisten dan fulfillment yang Anda tetapkan. Intent kustom juga memiliki parameter intent, yang dapat Anda petakan ke parameter dalam fulfillment yang sesuai.

Tidak seperti BII, intent kustom memerlukan pola kueri untuk mendeskripsikan kueri contoh yang mungkin diucapkan pengguna. Pendekatan ini berbeda dengan intent bawaan, yang mencontohkan cara umum pengguna mengekspresikan intent tersebut.

Batasan

Intent kustom memiliki batasan berikut:

  • Nama intent kustom tidak boleh diawali dengan actions.intent.
  • Nama intent kustom harus unik di antara nama intent kustom untuk aplikasi Anda.
  • Hanya jenis data tertentu yang tersedia untuk ekstraksi parameter oleh Asisten Google (lihat Jenis yang didukung).
  • Intent kustom harus berisi contoh pola kueri yang dapat digunakan (lihat Pola kueri).
  • Setiap kueri mendukung maksimum dua parameter teks. Batas ini tidak berlaku untuk jenis data lainnya.
  • Intent kustom hanya mendukung lokalitas en-US. Selain itu, setelan bahasa perangkat dan Asisten harus cocok.

Jenis yang didukung

Intent kustom mendukung jenis schema.org berikut untuk ekstraksi parameter:

  • https://schema.org/Text
  • https://schema.org/Date
  • https://schema.org/Time
  • https://schema.org/Number

Menentukan Action Aplikasi dengan intent kustom

Seperti Action Aplikasi lainnya yang menggunakan BII, Anda menentukan intent kustom dalam elemen <capability> di shortcuts.xml.

Kemampuan ditentukan dalam elemen root <shortcuts>. Saat menentukan elemen <shortcuts>, sertakan namespace atribut yang ingin diakses, seperti yang ditunjukkan pada contoh berikut ini:

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  ...
</shortcuts>

Masukkan nama intent kustom dalam atribut android:name, dan referensikan file resource pola kueri dalam atribut queryPatterns.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.EXAMPLE_INTENT"
      app:queryPatterns="@array/ExampleQueries">
    <intent ...>
      <url-template
          android:value="http://custom.com{?number_of_items,item_name}" />
      <parameter
          android:name="number_of_items"
          android:key="number_of_items"
          android:mimeType="https://schema.org/Number" />
      <parameter
          android:name="item_name"
          android:key="item_name"
          android:mimeType="https://schema.org/Text" />
    </intent>
  </capability>
  ...
</shortcuts>

Nama intent kustom tidak boleh diawali dengan actions.intent, karena namespace tersebut dicadangkan untuk BII. Sebagai gantinya, saat memberi nama intent kustom Anda, gunakan awalan custom.actions.intent untuk membedakan intent kustom dari BII dan intent Android, yang berfungsi secara berbeda.

Untuk setiap parameter, berikan jenis schema.org yang didukung yang paling menjelaskan arti parameter. Misalnya, Anda dapat menggunakan https://schema.org/Date untuk mendeskripsikan tanggal yang diperkirakan akan diterima:

...
<intent>
  <url-template android:value="https://example.com/appt{?apptType,date,time}" />
  <parameter
      android:name="date"
      android:key="date"
      android:mimeType="https://schema.org/Date" />
  ...
</intent>
...

Menentukan pintasan untuk intent kustom di shortcuts.xml menggunakan format yang sama dengan pintasan untuk BII.

Kode berikut menjelaskan Action Aplikasi yang menggunakan pola kueri yang direferensikan untuk memicu intent kustom SCHEDULE_APPOINTMENT dan menggunakan kumpulan nilai yang ditetapkan, DRIVERS_LICENSE dan VEHICLE_REGISTRATION, untuk parameter apptType.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
     <url-template android:value="https://example.com/appt{?apptType,date,time}" />
       <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
       <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
       <!-- The following parameter has no type because the shortcuts are bound to it -->
       <parameter android:name="apptType" android:key="apptType" />
    </intent>
  </capability>

  <shortcut
      android:shortcutShortLabel="Driver's License"
      android:shortcutId="DRIVERS_LICENSE">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/driversLicense" />
    </capability-binding>
  </shortcut>

  <shortcut
      android:shortcutsShortLabel="Vehicle Registration"
      android:shortcutId="VEHICLE_REGISTRATION">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/vehicleRegistration" />
    </capability-binding>
  </shortcut>
</shortcuts>

Anda dapat mengonfigurasi parameter intent kustom dengan inventaris inline, yang dapat digunakan untuk memandu ekstraksi entitas ke kumpulan entitas yang didukung yang ditentukan dalam shortcuts.xml.

Pola kueri

Setiap intent kustom yang Anda gunakan memerlukan serangkaian kueri yang diharapkan dari pengguna untuk intent tersebut. Pendekatan ini tidak seperti BII, ketika kueri yang sudah dimodelkan untuk cara umum bagi pengguna untuk mengekspresikan tugas yang akan mereka coba lakukan atau informasi yang mereka cari.

Dalam file resource Android (biasanya /res/values/strings.xml), tentukan pola kueri sebagai item dalam array string. Saat Action Aplikasi Anda dipanggil, Asisten Google akan memeriksa kueri pengguna terhadap pola kueri Anda sebagai bagian dari mencocokkan intent pengguna untuk fulfillment. Setiap pola kueri yang Anda berikan mewakili frasa yang Anda anggap valid untuk intent kustom yang sesuai.

Saat memberikan pola kueri untuk intent kustom, setiap pola harus mengikuti panggilan eksplisit seperti "buka Aplikasi Contoh" atau "mulai Aplikasi Contoh lalu". Misalnya, pertimbangkan kueri pengguna berikut:

  • "Ok Google, buka Aplikasi Game Contoh lalu mulai buat kue".
  • "Ok Google, buka Aplikasi Game Contoh lalu mulai buat pai apel".
  • "Ok Google, mulai Aplikasi Game Contoh lalu buat 5 item kue".
  • "Ok Google, gunakan Aplikasi Game Contoh untuk membuat kue 5 kali".

Untuk mencocokkan kueri pengguna, berikan pola kueri yang berisi bagian kueri setelah frasa pemanggilan. Untuk informasi yang ingin Anda ekstrak dari kueri (seperti teks atau angka yang diberikan oleh pengguna), Anda perlu menetapkan nilai ke parameter intent yang sesuai dengan placeholder dalam pola kueri.

Untuk mereferensikan parameter dalam pola kueri, tambahkan $ ke nama parameter dalam pola Anda. Misalnya, untuk membuat nilai placeholder untuk parameter seperti <parameter name="date1" ... (dalam actions.xml) atau <parameter android:name="date1" ... (dalam shortcuts.xml), gunakan $date1.

Kode berikut menjelaskan pola kueri yang cocok dengan kueri pengguna sebelumnya dan mengekstrak nilai untuk nama item dan jumlah item yang akan dibuat:

<resources>
  <string-array name="ExampleQueries">
    <item>start making a $text1</item>
    <item>start making an $text1</item>
    <item>craft $number1 $text1 items</item>
    <item>produce $text1 $number1 times</item>
  </string-array>
</resources>

Pola kueri mendukung kondisional. Misalnya, set (an)? appointment $date $time. Dalam hal ini, "setel janji temu hari ini pada siang hari" dan "setel satu janji temu hari ini pada siang hari" merupakan kueri yang valid.