Tạo tệp shortcuts.xml

Sau khi xác định chức năng trong ứng dụng và ý định tích hợp (BII) tương ứng để triển khai, hãy khai báo BBI mà chức năng của bạn hỗ trợ bằng cách xác định một phần tử capability trong tệp tài nguyên shortcuts.xml. Việc khai báo BII dưới dạng vùng đăng ký capability hỗ trợ về mặt ngữ nghĩa cho ý định trong ứng dụng của bạn, đồng thời cho phép thực hiện truy vấn bằng giọng nói theo ý định qua Trợ lý Google.

Trợ lý sử dụng cách xử lý ngôn ngữ tự nhiên để trích xuất các tham số từ truy vấn của người dùng. Tham chiếu ý định tích hợp sẵn liệt kê các trường mà mỗi BII có thể trích xuất từ một truy vấn của người dùng được liên kết. Ví dụ: nếu người dùng gọi chức năng [actions.intent.GET_FOOD_OBSERVATION][] trong ứng dụng của bạn bằng cách nói "Ok Google, hỏi ExampleApp tôi đã ăn gì cho bữa trưa thứ Sáu tuần trước", Trợ lý trích xuất các tham số BII sau đây từ yêu cầu của người dùng:

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

Trợ lý sẽ truyền các tham số BII đến phương thức thực hiện intent được xác định trong capability. Bạn có thể xác định một hoặc nhiều phần tử intent để hỗ trợ người dùng gọi một BII theo nhiều cách khác nhau. Chẳng hạn như bạn có thể xác định một phương thức thực hiện intent yêu cầu phải có cả hai tham số BII trong ví dụ trên. Sau đó, bạn có thể xác định ý định thứ hai yêu cầu một BII duy nhất tham số foodObservation.forMeal, giúp báo cáo về tất cả các bữa ăn trong một ngày cụ thể, chẳng hạn như "Ok Google, Hỏi ExampleApp tôi đã ăn gì cho bữa trưa".

Tổng quan

Bạn định cấu hình Hành động trong ứng dụng bằng cách sử dụng tệp shortcuts.xml đặt trong thư mục res/xml của dự án ứng dụng, sau đó tạo một tham chiếu đến shortcuts.xml trong tệp kê khai ứng dụng. Thêm một mục tham chiếu đến shortcuts.xml trong tệp kê khai ứng dụng của bạn bằng cách làm theo các bước sau:

  1. Trong tệp kê khai của ứng dụng (AndroidManifest.xml), hãy tìm một hoạt động có bộ lọc ý định được đặt thành hành động android.intent.action.MAIN và danh mục android.intent.category.LAUNCHER.

  2. Hãy thêm một mục tham chiếu đến shortcuts.xml trong AndroidManifest.xml bằng cách sử dụng thẻ <meta-data> trong Activity có các bộ lọc Ý định cho cả MAINLAUNCHER như sau:

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

Ví dụ trên khai báo tài nguyên XML cho tệp xml/shortcuts.xml trong APK. Để biết thêm thông tin chi tiết về cách định cấu hình lối tắt, vui lòng xem phần Tạo phím tắt tĩnh trong tài liệu dành cho nhà phát triển Android.

Bạn cần có thư viện Jetpack androidx.core:core:1.6.0 (trở lên) trong dự án Android để tránh lỗi biên dịch khi xác định các chức năng của Hành động trong ứng dụng trong shortcuts.xml. Để biết thông tin chi tiết, vui lòng xem phần Làm quen với Android Jetpack.

Lối tắt tĩnh

Khi xác định capability, bạn có thể khai báo các phần tử shortcut tĩnh trong shortcuts.xml để mở rộng các hỗ trợ của chức năng. Các lối tắt tĩnh sẽ được Trợ lý truyền dẫn khi bạn tải một bản phát hành lên Google Play Console. Vì bạn chỉ có thể tạo và cập nhật lối tắt tĩnh bằng cách tạo các bản phát hành mới, nên những lối tắt này sẽ hữu ích nhất khi cần làm nổi bật các hoạt động và nội dung phổ biến trong ứng dụng của bạn.

Bạn có thể bật chức năng Hành động trong ứng dụng sau đây bằng lối tắt tĩnh:

  • Lối tắt chức năng. Tạo những lối tắt để chạy một bản sao của capability chứa các giá trị tham số intent đã xác định trước. Ví dụ: bạn có thể khai báo một lối tắt ứng dụng "Bắt đầu chạy" để gọi chức năng BII START_EXERCISE trong ứng dụng thể dục của bạn.

    Các lối tắt này chứa các thuộc tính intent, shortLabellongLabel nên đủ điều kiện được đề xuất và hoàn thành nhiệm vụ dưới dạng khối (chip) trong các nền tảng chủ động, chẳng hạn như Trợ lý hoặc khi nhấn và giữ một biểu tượng ứng dụng trên trình chạy Android. Lối tắt thao tác cũng có thể đóng vai trò như một lối tắt thực thể, được nêu chi tiết dưới đây bằng cách liên kết với một capability bằng thẻ <capability-binding>.

  • Lối tắt thực thể. Lối tắt thực thể cung cấp danh sách giá trị tham số được hỗ trợ để thực hiện capability truy vấn bằng giọng nói. Ví dụ: một lối tắt thực thể với danh sách bài tập luyện ("đạp xe", "chạy", v.v.) liên kết với tham số BII exercise.name của chức năng START_EXERCISE. Nếu lời nói của người dùng khớp với một thực thể, thì mã nhận dạng shortcutId sẽ được truyền cho ý định thay vì giá trị truy vấn thô của người dùng.

    Lối tắt Entity không xác định các thuộc tính intent, shortLabel hoặc longLabel, do đó không được đề xuất trên các nền tảng chủ động. Để biết thêm thông tin chi tiết, vui lòng xem phần Khoảng không quảng cáo nội tuyến cho Hành động trong ứng dụng.

Giản đồ về chức năng

Bảng sau đây mô tả giản đồ Hành động trong ứng dụng cho các phần tử capability trong shortcuts.xml. Khi đưa một thẻ vào, bạn phải cung cấp mọi thuộc tính của thẻ đó, trừ trường hợp được đánh dấu là "không bắt buộc".

Thẻ Shortcuts.xml Có trong: Thuộc tính
<capability> <shortcuts>

android:name

app:queryPatterns (chỉ áp dụng cho đối tượng có ý định tuỳ chỉnh)

<intent> <capability>

android:action (không bắt buộc)

android:targetClass (không bắt buộc)

android:targetPackage (không bắt buộc)

android:data (không bắt buộc)

<url-template> <intent>

android:value

<extra> <intent>

android:key

android:value

Chỉ áp dụng cho lệnh gọi ứng dụng trên nền trước

<parameter> <intent>

android:name

android:key

android:mimeType (chỉ áp dụng cho đối tượng có ý định tuỳ chỉnh)

android:required (không bắt buộc)

app:shortcutMatchRequired (không bắt buộc)

<shortcut-fulfillment> <capability> Chỉ áp dụng cho khoảng không quảng cáo nội tuyến
<parameter> <shortcut-fulfillment> android:name
<slice> <capability>

Chỉ áp dụng cho Lát cắt Android

Phần mô tả giản đồ chức năng

Phần này mô tả các phần tử của giản đồ capability.

<chức năng>

capability xác định ý định của Hành động trong ứng dụng mà ứng dụng của bạn hỗ trợ. Mỗi phần tử <capability> trong tệp shortcuts.xml của bạn phải cung cấp ít nhất một <intent> để xử lý việc thực hiện hành động đó.

Thuộc tính:

  • android:name: Mã hành động theo ý định tích hợp (ví dụ: [actions.intent.GET_FOOD_OBSERVATION][]). Để biết danh sách các ý định tích hợp sẵn được hỗ trợ, vui lòng xem tài liệu tham khảo về ý định tích hợp.
  • app:queryPatterns: Tài nguyên mảng chuỗi của các truy vấn dự kiến từ người dùng cho ý định này. Thuộc tính này chỉ áp dụng cho đối tượng có ý định tuỳ chỉnh, vì BII đã bao gồm mô hình các phương thức phổ biến mà người dùng thể hiện tác vụ họ đang cố gắng thực hiện hoặc thông tin họ tìm kiếm.

<ý định>

Phần tử intent của Android xác định phương thức thực hiện truy vấn của người dùng bằng cách sử dụng chức năng trong ứng dụng. Các nhà phát triển có thể cung cấp nhiều thẻ <intent> trong một capability. Trợ lý sẽ cố gắng thực hiện truy vấn người dùng bằng cách sử dụng <intent> đầu tiên trong capability, trong đó tất cả các tham số bắt buộc đều được cung cấp.

Thuộc tính:

  • android:action: loại Action có ý định . Mặc định là ACTION_VIEW.
  • android:targetClass: Lớp hoạt động mục tiêu, chẳng hạn như "com.example.exercise.ExerciseActivity"
  • android:targetPackage: Gói chứa lớp Hoạt động mục tiêu, chẳng hạn như "com.example.exercise
  • android:data: Trường này do <url-template> ghi đè nếu thẻ đó được khai báo trong intent.

<mẫu-url>

Mẫu để tạo URI liên kết sâu được mở trên thiết bị. Bạn có thể mở rộng mẫu này bằng các tham số ý định tích hợp nếu tất cả các tham số bắt buộc cho mẫu đều có sẵn. Để biết ví dụ về mẫu URL loại HTTP, vui lòng xem nội dung Bài viết trên Wikipedia về mẫu URL. Định dạng mẫu tuân theo quy cách mẫu URI RFC6570.

Sau đây là một số ví dụ về giá trị mẫu URL:

Mẫu Giá trị Giá trị mở rộng
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

Để biết thêm thông tin về cách định cấu hình mẫu URL, vui lòng xem mẫu URL để thực hiện.

<bổ sung>

Xác định dữ liệu bổ sung cho intent. Đối với Hành động trong ứng dụng, trường này chỉ dùng để bật [lệnh gọi ứng dụng trên nền trước][] cho capability.

<tham số>

Ánh xạ một tham số BII tới các giá trị tham số ý định. Để biết thêm thông tin chi tiết, vui lòng xem nội dung Dữ liệu tham số và so khớp.

Thuộc tính:

  • android:name: Tên tham số BII để liên kết với tham số intent này. Tên tham số BII phải là một trường cấp lá xanh (chẳng hạn như foodObservation.aboutFood.name).
  • android:key: Khoá do nhà phát triển xác định của giá trị tham số BII. Ví dụ: bạn có thể xác định contact_name cho tham số BII message.recipient.name.
  • android:mimeType: mimeType của tham số, chẳng hạn như text/*. Trường này chỉ bắt buộc đối với các tham số của đối tượng có ý định tuỳ chỉnh.
  • android:required: Khai báo liệu truy vấn của người dùng có cần chứa tham số này để sử dụng cho việc thực hiện ý định hay không. Nếu không có tham số này, Trợ lý sẽ cố gắng thực hiện truy vấn của người dùng bằng cách sử dụng intent tiếp theo đã xác định cho capability.

<shortcut-fulfillment>

Chỉ định một intent đã xác định trong lối tắt của khoảng không quảng cáo nội tuyến cho một tham số được chỉ định để thực hiện nhiệm vụ. Để biết thông tin chi tiết, vui lòng xem phần Phương thức thực hiện bằng ý định của lối tắt.

<tham số> (cho <shortcut-fulfillment>)

Thuộc tính tuỳ chọn sẽ ánh xạ một tham số BII duy nhất đến phương thức thực hiện qua lối tắt của khoảng không nội tuyến. Để biết thông tin chi tiết, vui lòng xem phần Phương thức thực hiện bằng ý định của lối tắt.

Thuộc tính:

  • android:name: Tên tham số BII để liên kết với phương thức thực hiện qua lối tắt của khoảng không nội tuyến. Tên tham số BII phải là một trường cấp lá xanh (chẳng hạn như menuItem.name).

<lát cắt>

Cho phép Trợ lý nhúng kết quả của một truy vấn khớp với capability này dưới dạng một lát cắt của Android. Để biết thông tin chi tiết, vui lòng xem bài viết Tích hợp Hành động trong ứng dụng với Lát cắt Android.

Giản đồ lối tắt

Bảng sau đây mô tả các thuộc tính của các phần tử shortcut dùng để bật chức năng của Hành động trong ứng dụng. Khi đưa một thẻ vào, bạn phải cung cấp mọi thuộc tính của thẻ đó, trừ phi thuộc tính đó được đánh dấu là "không bắt buộc".

Thẻ Shortcuts.xml Có trong: Thuộc tính
<shortcut> <shortcuts>

android:shortcutId

android:shortcutShortLabel

android:shortcutLongLabel (không bắt buộc)

android:icon (không bắt buộc)

<intent> <shortcut>

android:action

android:targetClass (không bắt buộc)

android:targetPackage (không bắt buộc)

android:data (không bắt buộc)

<capability-binding> <shortcut>

android:key

<parameter-binding> <capability-binding>

android:key (không bắt buộc)

android:value

<extra> <shortcut>

android:name (không bắt buộc)

android:value

Chỉ áp dụng cho tính năng So khớp tham số Enum.

Mô tả mã schema của lối tắt

Phần này mô tả các phần tử của giản đồ shortcut.

<shortcut>

Một <shortcut> của Android được xác định trongshortcuts.xml với các thuộc tính nhất định có liên quan đến Hành động trong ứng dụng. Giá trị chuỗi cho các trường shortcutShortLabelshortcutLongLabel được tham chiếu qua tài nguyên chuỗi của tệp APK.

Thuộc tính:

  • android:shortcutId: Giá trị nhận dạng cho lối tắt này.
  • android:shortcutShortLabel: Tài nguyên chuỗi đại diện cho một cụm từ của khẩu lệnh nhanh vắn tắt này. Chẳng hạn như "@string/callDavidShort" sẽ đại diện cho giá trị "Gọi David".
  • android:shortcutLongLabel: Tài nguyên chuỗi đại diện cho một cụm từ của khẩu lệnh nhanh dài. Chẳng hạn như "@string/callDavidLong" sẽ đại diện cho giá trị "Hãy gọi điện cho David".

<ý định>

Ý định trên Android liên kết với lối tắt này. intent này sẽ được thực thi khi người dùng mở lối tắt bằng giọng nói hoặc thao tác chạm.

Các thuộc tính ý định shortcut giống hệt với các thuộc tính capability intent.

<liên kết chức năng>

Liên kết shortcut với một Hành động trong ứng dụng capability. Việc thêm phần tử này vào shortcut sẽ cho phép nó thực hiện giọng nói bằng Assistant.

Thuộc tính:

  • android:key: Thuộc tính android:name của capabilityshortcut này liên kết. Chẳng hạn như actions.intent.START_EXERCISE.

<parameter-binding>

Thuộc tính không bắt buộc liên kết shortcut với một tham số duy nhất của capability Hành động trong ứng dụng. Nếu parameter-binding được xác định cho một shortcut, bạn có thể sử dụng lối tắt để cung cấp thực thể khoảng không nội tuyến cho tham số BII. Để biết thêm thông tin chi tiết, vui lòng xem bài viết Khoảng không quảng cáo nội tuyến cho Hành động trong ứng dụng.

Thuộc tính:

  • android:key: Tên tham số BII capability để liên kết lối tắt này. Ví dụ: exercise.name.
  • android:value: giá trị entity. Đây có thể là một entity hoặc danh sách tài nguyên.

<bổ sung>

Dữ liệu gói extra cho lối tắt. sameAs là dữ liệu duy nhất liên quan đến các phần tử shortcut của Hành động trong ứng dụng. URL sameAs là một trang web tham chiếu giúp xác định rõ ràng thực thể đó. Dùng để chỉ định một giá trị enum nếu và chỉ khi tham số ý định là loại phụ của schema.org/Enumeration. Đây là yêu cầu bắt buộc đối với các trường tham số có loại phụ là schema.org/Enumeration (ví dụ: MealTypeBreakfast).

Thuộc tính:

  • android:key: Giá trị được hỗ trợ cho Hành động trong ứng dụng là: sameAs
  • android:value: Giá trị URL sameAs

Để biết thêm thông tin chi tiết, vui lòng xem bài viết So khớp các giá trị tham số được liệt kê.

Các tuỳ chọn thực hiện ý định

Bạn xác định các phần tử intent trong <capability> để khai báo cách Trợ lý phản hồi hoặc thực hiện lệnh thoại của người dùng phù hợp với chức năng đó. Có một số cách để định cấu hình phương thức intent khởi chạy một đích đến để thực hiện trong ứng dụng, tuỳ thuộc vào cách cấu trúc điều hướng ứng dụng của bạn.

Bạn có thể sử dụng các tuỳ chọn phương thức thực hiện sau:

  • Ý định tường minh: Khởi chạy một thành phần cụ thể trong ứng dụng bằng cách xác định các thuộc tính targetClasstargetPackage cho intent. Đây là phương thức thực hiện Hành động trong ứng dụng được đề xuất.

  • Liên kết sâu: Sử dụng liên kết sâu của Android để khởi chạy đích đến của ứng dụng bằng cách xác định thẻ <url-template> trong phần tử intent. Phương thức này sẽ hữu ích nếu tính năng điều hướng trong ứng dụng của bạn đã kết hợp sẵn với các đường liên kết sâu.

  • Dữ liệu ý định: Bạn có thể cung cấp URI phương thức thực hiện trong thuộc tính intentandroid:data. Trường này được ghi đè bằng dữ liệu <url-template> nếu thẻ đó cũng được xác định trong intent.

Dữ liệu tham số và so khớp

Theo mặc định, Trợ lý sẽ gửi các tham số BII trích xuất từ truy vấn của người dùng đến ứng dụng của bạn dưới dạng dữ liệu extra của intent Android được xác định trong capability.

Ngoài ra, bạn có thể khai báo thẻ <url-template> trong capability chứa phần giữ chỗ cho các tham số động. Mẫu này liên kết đến một trong các hoạt động của Android bằng một URL liên kết ứng dụng, một lược đồ tuỳ chỉnh hoặc một URL dựa trên ý định.

Sử dụng tính năng bổ sung ý định

Ví dụ sau đây minh hoạ cho một ý định rõ ràng được xác định để thực hiện 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>

Với mẫu ở trên, đối với một truy vấn của người dùng chẳng hạn như "Này Google, hãy gọi một ly latte trên ExampleApp", ứng dụng sẽ nhận được một intent gọi thành phần: targetPackagetargetClass. Thành phần sẽ nhận một tính năng Bổ sung với key = "exercise"value = "Running".

Nếu ứng dụng của bạn đã có thể xử lý các URL liên kết với ứng dụng bằng tham số động, bạn có thể xác định <url-template> trong intent để tạo liên kết sâu trên Android cho việc thực hiện đơn hàng. Mẫu sau đây xác định <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>

Với mẫu ở trên, đối với một truy vấn của người dùng chẳng hạn như “Này Google, hãy gọi một ly latte trên ExampleApp", ứng dụng sẽ nhận được URL được tạo: "myapp://start?exercise=Running".

Để ánh xạ tham số BII với một vị trí trong URL, bạn cần sử dụng thuộc tính android:name của thẻ <parameter>. Thuộc tính này tương ứng với giá trị android:key trong mẫu URL mà bạn muốn thay thế bằng thông tin của người dùng. Giá trị android:key phải có trong <url-template> của bạn và được đặt trong dấu ngoặc nhọn ({}).

Khớp với các giá trị tham số được liệt kê

Một vài tham số BII cung cấp các giá trị được liệt kê cho ý định thực hiện của bạn, chẳng hạn như giá trị văn bản được hỗ trợ của BII RECORD_FOOD_OBSERVATION. Đối với các tham số này, Trợ lý sẽ so khớp truy vấn của người dùng ("Breakfast" –"Bữa sáng") với một thực thể có giá trị sameAs khớp với URL của mã schema enum (https://schema.googleapis.com/MealTypeBreakfast). Để liên kết các giá trị enum cho entity được hỗ trợ, bạn phải khai báo một mối liên kết sameAs trong shortcut. Mẫu sau đây minh hoạ một liên kết sameAs cho lối tắt thực thể cùng dòng:

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

Trong ví dụ trên, nếu chức năng RECORD_FOOD_OBSERVATION kích hoạt kết quả phù hợp cho loại bữa ăn là "bữa sáng", thì tính năng Bổ sung sau đây sẽ được gửi cùng với intent thực hiện:

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

Tính năng

Các tính năng sau đây về Hành động trong ứng dụng có sẵn trong shortcuts.xml.

Khoảng không quảng cáo nội tuyến cho Hành động trong ứng dụng

Đối với một vài tham số BII, bạn có thể sử dụng lối tắt để 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òn được gọi là khoảng không nội tuyến. Để biết thông tin chi tiết, vui lòng xem nội dung Khoảng không quảng cáo nội tuyến.

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

Bạn có thể khai báo đối tượng có ý định tuỳ chỉnh trong shortcuts.xml để bật các tính năng bằng giọng nói trong ứng dụng không khớp với các BII có sẵn. Mặc dù có chức năng tương tự như định nghĩa BII, nhưng các ý định tuỳ chỉnh yêu cầu thêm hai thuộc tính bổ sung trong shortcuts.xml:

  • app:queryPatterns: Tài nguyên mảng khai báo các mẫu truy vấn khác nhau cho cùng một đối tượng có ý định tuỳ chỉnh.

  • android:mimeType: Loại tham số của ý định tuỳ chỉnh. Trường này không bắt buộc đối với các BII đã biết loại tham số. Đối với các tham số của đối tượng có ý định tuỳ chỉnh, bạn phải khai báo loại ngữ nghĩa được hỗ trợ.

Để biết thêm thông tin chi tiết, vui lòng xem bài viết Đối tượng có ý định tuỳ chỉnh.