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 tính năng [actions.intent.GET_FOOD_OBSERVATION
][] trong ứng dụng của bạn bằng cách nói "Ok Google, hãy hỏi ExampleApp tôi đã ăn gì vào bữa trưa thứ Sáu tuần trước", Trợ lý sẽ 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 tham số BII, foodObservation.forMeal
, báo cáo cho tất cả các bữa ăn vào một ngày cụ thể, chẳng hạn như "Này Google, hãy hỏi ExampleApp tôi đã ăn gì vào 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:
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 độngandroid.intent.action.MAIN
và danh mụcandroid.intent.category.LAUNCHER
.Hãy thêm một mục tham chiếu đến
shortcuts.xml
trongAndroidManifest.xml
bằng cách sử dụng thẻ<meta-data>
trongActivity
có các bộ lọc Ý định cho cảMAIN
vàLAUNCHER
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 BIISTART_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
,shortLabel
vàlongLabel
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ộtcapability
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ố BIIexercise.name
của chức năngSTART_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ạngshortcutId
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ínhintent
,shortLabel
hoặclongLabel
, 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> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
Chỉ áp dụng cho lệnh gọi ứng dụng trên nền trước |
<parameter> |
<intent> |
|
<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ạiAction
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 trongintent
.
<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"
|
https://example.com/test?foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{&foo,bar} |
"foo": "123"
|
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ỉ được dùng để kích hoạ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 địnhcontact_name
cho tham số BIImessage.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ụngintent
tiếp theo đã xác định chocapability
.
<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> |
|
<intent> |
<shortcut> |
|
<capability-binding> |
|
|
<parameter-binding> |
<capability-binding> |
|
<extra> |
<shortcut> |
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 shortcutShortLabel
và shortcutLongLabel
đượ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ínhandroid:name
củacapability
màshortcut
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ố BIIcapability
để liên kết lối tắt này. Ví dụ:exercise.name
.android:value
: giá trịentity
. Đây có thể là mộtentity
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ị URLsameAs
Để 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
targetClass
vàtargetPackage
chointent
. Đâ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
intent
android:data
. Trường này được ghi đè bằng dữ liệu<url-template>
nếu thẻ đó cũng được xác định trongintent
.
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 bắt đầu chạy", ứng dụng sẽ nhận được một intent
gọi thành phần: targetPackage
và targetClass
. Thành phần sẽ nhận một tính năng Bổ sung với key = "exercise"
và value = "Running"
.
Sử dụng mẫu URL cho liên kết sâu trong Android
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, bắt đầu chạy bộ", ứ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.