Ý định tuỳ chỉnh

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

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

Giống với BII, ý đị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 hoạt động mà bạn đã xác định. Ý định tuỳ chỉnh cũng có tham số ý định mà bạn có thể ánh xạ đến các tham số trong quá trình thực hiện tương ứng của mình.

Không giống như BII, ý đị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 sẵn, mỗi mô hình đều 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 ý định tuỳ chỉnh trong ứng dụng không được giống nhau.
  • Chỉ có một số loại dữ liệu nhất định có sẵn để trích xuất tham số của Trợ lý Google. Vui lòng xem nội dung phần Các loại được hỗ trợ để biết danh sách các loại được hỗ trợ.
  • Hệ thống hỗ trợ tối đa hai tham số văn bản cho mỗi truy vấn. Hạn mức này không áp dụng cho các loại dữ liệu khác.
  • Chỉ ngôn ngữ Tiếng Anh – Mỹ mới được hỗ trợ cho các ý định tuỳ chỉnh (cài đặt ngôn ngữ cho thiết bị và Trợ lý phải khớp nhau).

Các kiểu được hỗ trợ

Ý đị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 ý định tuỳ chỉnh

Giống với các Hành động trong ứng dụng khác sử dụng ý định tích hợp, bạn cần xác định một ý đị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 xác định phần tử <shortcuts>, bạn phải kèm không gian tên của các thuộc tính mà bạn muốn truy cập.

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

Khi đặt tên cho ý định tuỳ chỉnh, bạn nên sử dụng tiền tố custom.actions.intent để phân biệt ý định tuỳ chỉnh với cả ý định tích hợp và các ý định trong Android (vì chúng có chức năng khác nhau). 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 ý định tích hợp.

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

Định nghĩa về lối tắt trong shortcuts.xml sử dụng cùng định dạng với ý định tuỳ chỉnh giống như đối với ý định tích hợp. Mã sau đây mô tả một Hành động trong ứng dụng sử dụng các mẫu truy vấn được tham chiếu để kích hoạt ý định tuỳ chỉnh SCHEDULE_APPOINTMENT và tập hợp các giá trị đã xác định, DRIVERS_LICENSEVEHICLE_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 ý đị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ư các ý định tích hợp sẵn, trong đó các cụm từ tìm kiếm đã được mô hình hoá theo những cách phổ biến mà người dùng thể hiện các nhiệm vụ mà họ đang cố gắng 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ở ExampleApp và" hoặc "bắt đầu ExampleApp và". Ví dụ: hãy xem xét các truy vấn của người dùng sau đây:

  • "Ok Google, hãy mở ExamplegameApp và bắt đầu làm bánh."
  • "Ok Google, hãy mở ExampleGameApp và bắt đầu làm bánh táo."
  • "Ok Google, hãy khởi động ExampleGameApp và làm 5 chiếc bánh."
  • "Ok Google, hãy sử dụng ExampleGameApp để làm bánh 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" ... (actions.xml) hoặc <parameter android:name="date1" ... (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ụ: "đặt (một)? cuộc hẹn $ngày $giờ”. 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ệ.