Đẩy các lối tắt động tới Trợ lý

Lối tắt Android mang đến cho người dùng các phương thức nhanh chóng để thực hiện một hành động hoặc truy cập vào nội dung của một ứng dụng. Trợ lý có thể chủ động gợi ý lối tắt cho người dùng vào thời điểm thích hợp, giúp người dùng dễ dàng khám phá và phát lại chức năng có thể kích hoạt bằng giọng nói trên ứng dụng của bạn.

Ví dụ: bạn có thể đẩy một lối tắt cho mỗi ghi chú người dùng đã tạo trong ứng dụng ghi chú. Bạn có thể thêm liên kết động để những lối tắt này đủ điều kiện hiển thị trên các nền tảng của Google (chẳng hạn như Trợ lý) bằng cách thêm thư viện Tích hợp lối tắt Jetpack của Google (Google Shortcuts Integration Jetpack) vào dự án. Thư viện này cho phép Trợ lý lấy lối tắt động mà bạn đẩy lên bằng lớp ShortcutManagerCompat — trình bao bọc Jetpack cho API ShortcutManager.

Khi bạn sử dụng thư viện Tích hợp lối tắt của Google (Google Shortcuts Integration) trong ứng dụng của mình, lối tắt động mà bạn đẩy lên Google sẽ hiển thị cho người dùng dưới dạng lối tắt trong ứng dụng Trợ lý. Bạn có thể đẩy vô hạn lối tắt lên Trợ lý qua phương thức pushDynamicShortcut() từ thư viện ShortcutManagerCompat.

Định cấu hình dự án phát triển của bạn

Để thêm chức năng lối tắt động vào ứng dụng, bạn phải có thư viện Tích hợp lối tắt của Google (Google Shortcuts Integration), cũng là một thư viện Android Jetpack. Phần này mô tả cách định cấu hình dự án phát triển ứng dụng của bạn để sử dụng thư viện này.

Để thêm thư viện Jetpack này và định cấu hình dự án, hãy làm theo các bước sau:

Cập nhật tệp gradle.properties để xử lý các thư viện Jetpack:

gradle.properties

android.useAndroidX=true
# Automatically convert third-party libraries to use AndroidX
android.enableJetifier=true

Thêm các phần phụ thuộc của thư viện Jetpack vào build.gradle của bạn:

app/build.gradle
```
dependencies {
 implementation "androidx.core:core:1.6.0"
 implementation "androidx.core:core-google-shortcuts:1.0.1"
 ...
}
```
Trong mã mẫu trước đó, hãy liệt kê 2 thư viện Jetpack dưới dạng phần phụ thuộc. Thư viện androidx.core:core:1.6.0 chứa lớp ShortcutManagerCompat mà bạn dùng để đẩy các lối tắt động đến Google.

androidx.core:core-google-shortcuts:1.0.1 là Thư viện tích hợp lối tắt của Google. Thư viện này không chứa API dành cho nhà phát triển. Khi bạn thêm thư viện này dưới dạng phần phụ thuộc, Trợ lý sẽ nhận các lối tắt động bạn đã đẩy bằng cách sử dụng lớp ShortcutManagerCompat.

Lưu ý: Hãy truy cập Trình khám phá thư viện Jetpack để tìm phiên bản mới nhất của thư viện Tích hợp lối tắt của Google và Core.

Đẩy lối tắt động

Để đẩy các lối tắt động đủ điều kiện hiển thị trên Trợ lý, trước tiên, bạn phải tạo lối tắt bằng cách sử dụng lớp ShortcutInfoCompat.Builder().

Sau đó, đẩy lối tắt bằng phương thức ShortcutManagerCompat.pushDynamicShortcut(). Lối tắt sẽ được đẩy lên bất cứ khi nào người dùng hoàn tất một hành động có liên quan trong ứng dụng. Mã mẫu sau đây đẩy một lối tắt mỗi khi người dùng đặt món trong một ứng dụng giao đồ ăn:

ExampleOrderActivity

Kotlin

// Define the dynamic shortcut for a menu item
var intent = Intent(context, DisplayOrderActivity::class.java)
intent.action = Intent.ACTION_VIEW
var shortcutInfo = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Cappuccino")
    .setLongLabel("Order another cappuccino")
    .addCapabilityBinding(
        "actions.intent.ORDER_MENU_ITEM", "menuItem.name", Arrays.asList("cappuccino")
    )
    .setIntent(intent) // Push the shortcut
    .build()

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo)

Java

// Define the dynamic shortcut for a menu item
Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat.Builder shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Cappuccino")
    .setLongLabel("Order another cappuccino")
    .addCapabilityBinding(
      "actions.intent.ORDER_MENU_ITEM", "menuItem.name", Arrays.asList("cappuccino"))
    .setIntent(intent)
    .build();

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

id được tham chiếu với phương thức ShortcutInfoCompat.Builder trong mã mẫu trước đó xác định shortcutId của đối tượng lối tắt thu được. id này phải biểu thị bằng một giá trị cố định dạng chuỗi duy nhất. Để biết thông tin chi tiết, vui lòng xem Tài liệu về lối tắt trên Android.

Trong ví dụ trước, phương thức addCapabilityBinding liên kết lối tắt động với capability của cùng một android:name được xác định trong shortcuts.xml. Phương thức này cho phép bạn liên kết lối tắt với một tham số ý định tích hợp (BII) có ngữ nghĩa.

Đôi khi, bạn cũng có thể đẩy các lối tắt động mà không cần liên kết tham số BII cụ thể nào. Khi người dùng gọi, Trợ lý sẽ kích hoạt intent được xác định trong lối tắt để thực hiện hành động. Ví dụ sau đây cho thấy một phím tắt động không có mối liên kết nào với tham số:

Kotlin

var intent: Intent = Intent(context, DisplayOrderActivity::class.java)
intent.setPackage(this, "com.sample.app")
intent.setAction(Intent.ACTION_VIEW)

var shortcutInfo: ShortcutInfoCompat = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Order coffee")
    .setLongLabel("Order a cup of coffee")
    .addCapabilityBinding("actions.intent.ORDER_MENU_ITEM")
    .setIntent(intent)
    .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

Java

Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setPackage(this, "com.sample.app");
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
  .setShortLabel("Order coffee")
  .setLongLabel("Order a cup of coffee")
  .addCapabilityBinding("actions.intent.ORDER_MENU_ITEM")
  .setIntent(intent)
  .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

Kiểm thử lối tắt động bằng Trợ lý

Khi Trợ lý Google nhận được lối tắt động từ ứng dụng, lối tắt này sẽ đủ điều kiện để xuất hiện dưới dạng gợi ý khẩu lệnh nhanh trong ứng dụng Trợ lý trên Android. Ứng dụng Trợ lý sẽ gợi ý khẩu lệnh nhanh mới nhất mà ứng dụng của bạn đẩy lên.

Để thử nghiệm lối tắt động với Trợ lý, hãy làm theo các bước sau:

Tạo bản xem trước của Hành động trong ứng dụng và chuẩn bị trước thiết bị thử nghiệm hoặc trình mô phỏng cho các hành động thử nghiệm bằng cách tuân theo các yêu cầu thiết lập dưới dạng Trình bổ trợ Trợ lý Google.
Mở ứng dụng và xác định lối tắt động bạn muốn đẩy lên. Sau đó hoàn tất một hành động. Ví dụ: nếu bạn đẩy một lối tắt mỗi khi một ghi chú được trong ứng dụng ghi chú, vậy hãy tạo một ghi chú mới.
Mở lối tắt trong phần Cài đặt Trợ lý trên thiết bị của bạn. Lối tắt động sẽ xuất hiện trong danh sách cho ứng dụng của bạn.