Đối tượng có ý định tuỳ chỉnh

Mỗi ứng dụng đều khác biệt và không phải chức năng nào của ứng dụng cũng khớp với một ý định tích hợp (BII) hiện có của Hành động trong ứng dụng. Trong trường hợp không có BII cho chức năng của ứng dụng, bạn có thể dùng một đối tượng có ý định tuỳ chỉnh để mở rộng ứng dụng qua Hành động trong ứng dụng.

Giống với BII, đối tượng có ý định tuỳ chỉnh tuân theo giản đồ shortcuts.xml và đóng vai trò là các điểm kết nối giữa Trợ lý với các phương thức thực hiện mà bạn đã xác định. Đối tượng có ý định tuỳ chỉnh cũng có tham số ý định mà bạn có thể ánh xạ đến các tham số trong phương thức thực hiện tương ứng của mình.

Không giống như BII, đối tượng có ý định tuỳ chỉnh yêu cầu mẫu truy vấn để mô tả các truy vấn mẫu mà người dùng có thể nói. Phương pháp này khác với các ý định tích hợp lập mô hình những cách phổ biến để người dùng thể hiện ý định đó.

Các điểm hạn chế

Ý định tuỳ chỉnh có các giới hạn sau:

• Tên của một ý định tuỳ chỉnh không được bắt đầu bằng actions.intent.
• Tên của các đối tượng có ý định tuỳ chỉnh trong ứng dụng không được giống nhau.
• Chỉ có sẵn một số loại dữ liệu nhất định để Trợ lý Google trích xuất tham số (xem phần Các loại được hỗ trợ).
• Đối tượng có ý định tuỳ chỉnh phải chứa ví dụ về các mẫu truy vấn hữu dụng (xem phần Mẫu truy vấn).
• Mỗi truy vấn hỗ trợ tối đa 2 tham số văn bản. Hạn mức này không áp dụng cho các loại dữ liệu khác.
• Ý định tuỳ chỉnh chỉ hỗ trợ ngôn ngữ Anh – Mỹ (en-US). Ngoài ra, chế độ cài đặt ngôn ngữ cho thiết bị và Trợ lý phải khớp nhau.

Các loại được hỗ trợ

Đối tượng có ý định tuỳ chỉnh hỗ trợ các loại schema.org sau đây để trích xuất tham số:

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

Xác định Hành động trong ứng dụng bằng đối tượng có ý định tuỳ chỉnh

Giống với các Hành động trong ứng dụng khác sử dụng BII, bạn cần xác định một đối tượng có ý định tuỳ chỉnh thuộc phần tử <capability> trong shortcuts.xml.

Các khả năng được xác định trong phần tử gốc <shortcuts>. Khi bạn xác định phần tử <shortcuts>, hãy thêm không gian tên của các thuộc tính bạn muốn truy cập, như trong ví dụ sau:

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

Cung cấp tên của ý định tuỳ chỉnh trong thuộc tính android:name và tham chiếu đến tệp tài nguyên mẫu truy vấn trong thuộc tính 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>

Tên của ý định tuỳ chỉnh không được bắt đầu bằng actions.intent vì không gian tên đó dành riêng cho các BII. Thay vào đó, khi đặt tên cho ý định tuỳ chỉnh, hãy sử dụng tiền tố custom.actions.intent để phân biệt ý định tuỳ chỉnh với cả ý định BII và Android. Các ý định này có chức năng khác nhau.

Đối với mỗi tham số, hãy cung cấp loại schema.org được hỗ trợ mô tả đúng nhất ý nghĩa của tham số. Ví dụ: bạn có thể sử dụng https://schema.org/Date để mô tả ngày mà bạn dự kiến sẽ nhận được:

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

Xác định lối tắt cho các đối tượng có ý định tuỳ chỉnh trong shortcuts.xml bằng cách sử dụng cùng định dạng như các lối tắt cho BII.

Mã sau đây mô tả một Hành động trong ứng dụng dùng các mẫu truy vấn được tham chiếu để kích hoạt đối tượng có ý định tuỳ chỉnh SCHEDULE_APPOINTMENT, đồng thời sử dụng tập hợp các giá trị đã xác định (DRIVERS_LICENSE và VEHICLE_REGISTRATION) cho tham số 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>

Bạn có thể định cấu hình các tham số của đối tượng có ý định tuỳ chỉnh với khoảng không quảng cáo nội tuyến. Bạn có thể sử dụng các tham số này để hướng dẫn trích xuất thực thể đến một nhóm thực thể được hỗ trợ đã chỉ định trong shortcuts.xml.

Các mẫu truy vấn

Mỗi ý định tuỳ chỉnh mà bạn sử dụng yêu cầu một tập hợp các truy vấn dự kiến từ người dùng cho ý định đó. Phương pháp này không giống như BII, trong đó các truy vấn đã được mô hình hoá cho những cách phổ biến mà theo đó người dùng thể hiện các nhiệm vụ họ đang cố thực hiện hoặc thông tin họ tìm kiếm.

Trong tệp tài nguyên Android (thường là /res/values/strings.xml), hãy chỉ định mẫu truy vấn dưới dạng các mục trong mảng chuỗi. Khi Hành động trong ứng dụng được gọi, Trợ lý Google sẽ kiểm tra cụm từ tìm kiếm của người dùng dựa trên các mẫu truy vấn của bạn để so khớp ý định của người dùng rồi thực hiện nhiệm vụ. Mỗi mẫu truy vấn được cung cấp biểu thị một cụm từ mà bạn cho là phù hợp với ý định tuỳ chỉnh tương ứng.

Khi cung cấp các mẫu truy vấn cho ý định tuỳ chỉnh, hãy yêu cầu từng mẫu tuân theo một lời gọi rõ ràng, chẳng hạn như "mở Ứng dụng mẫu và" hoặc "bắt đầu Ứng dụng mẫu và". Ví dụ: hãy xem xét các truy vấn của người dùng sau đây:

• "Ok Google, mở Ứng dụng trò chơi mẫu và bắt đầu làm bánh."
• "Ok Google, mở Ứng dụng trò chơi mẫu và bắt đầu làm bánh táo."
• "Ok Google, khởi động Ứng dụng trò chơi mẫu và làm 5 chiếc bánh."
• "Ok Google, sử dụng Ứng dụng trò chơi mẫu để làm một chiếc bánh to gấp 5 lần."

Để khớp với truy vấn của người dùng, hãy cung cấp các mẫu truy vấn chứa phần truy vấn sau cụm từ của lời gọi. Đối với thông tin bạn muốn trích xuất từ truy vấn (chẳng hạn như văn bản hoặc số do người dùng cung cấp), bạn chỉ định giá trị cho tham số ý định tương ứng với phần giữ chỗ trong mẫu truy vấn.

Để tham chiếu một tham số trong mẫu truy vấn, vui lòng thêm $ vào tên của tham số trong mẫu đó. Ví dụ: để tạo giá trị phần giữ chỗ cho một tham số, chẳng hạn như <parameter name="date1" ... (trong actions.xml) hoặc <parameter android:name="date1" ... (trong shortcuts.xml), bạn sẽ sử dụng $date1.

Mã sau đây mô tả các mẫu truy vấn phù hợp với truy vấn người dùng ở trên và trích xuất giá trị cho tên cũng như số lượng mặt hàng cần thực hiện:

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

Mẫu truy vấn hỗ trợ tình trạng. Ví dụ: set (an)? appointment $date $time. Trong trường hợp này, cả hai nội dung "đặt cuộc hẹn cho trưa hôm nay" và "đặt một cuộc hẹn cho hôm nay vào buổi trưa" đều là các truy vấn hợp lệ.