Trang này được dịch bởi Cloud Translation API.

Tích hợp Hành động trong ứng dụng với các tiện ích Android

**Hình 1.** Triển khai một tiện ích cho `GET_EXERCISE_OBSERVATION`.

Đối với nhiều ý định, phản hồi tốt nhất là cung cấp câu trả lời đơn giản, xác nhận ngắn gọn hoặc trải nghiệm tương tác nhanh cho người dùng. Bạn có thể hiển thị tiện ích ứng dụng Android trong Trợ lý Google để thực hiện các loại ý định này.

Hướng dẫn này trình bày cách thực hiện các truy vấn của người dùng qua Trợ lý bằng tiện ích, cũng như cách cải thiện trải nghiệm của bạn khi dùng tiện ích cho Trợ lý với Thư viện mở rộng tiện ích Hành động trong ứng dụng.

Lợi ích

Tiện ích là các chế độ xem ứng dụng dưới dạng thu nhỏ, có thể nhúng được trên các nền tảng Android, chẳng hạn như trình chạy hoặc màn hình khoá. Với Hành động trong ứng dụng, bạn tăng tác động của tiện ích bằng cách khiến chúng đủ điều kiện xuất hiện trong Trợ lý:

Khám phá: Chủ động hiện các tiện ích theo truy vấn bằng ngôn ngữ tự nhiên của người dùng.
Tương tác: Hiển thị các tiện ích trong bối cảnh không dùng tay, chẳng hạn như khi Trợ lý cung cấp kết quả cá nhân trên màn hình khoá và trên Android Auto.
Lưu giữ: Cho phép người dùng ghim các tiện ích hiển thị trong Trợ lý vào trình chạy của họ. Chức năng ghim đòi hỏi phải có Thư viện mở rộng tiện ích.

Cách Trợ lý hiển thị các tiện ích

Người dùng có thể gọi các tiện ích trên Trợ lý theo 2 cách:

Yêu cầu rõ ràng tiện ích theo tên.
Nói một truy vấn với Trợ lý để kích hoạt một ý định tích hợp (BII) hoặc ý định tuỳ chỉnh được định cấu hình cho việc thực hiện tiện ích.

Lời gọi rõ ràng

Để gọi các tiện ích một cách rõ ràng cho bất kỳ ứng dụng đã cài đặt nào, người dùng có thể hỏi Trợ lý những câu đại loại như:

"Ok Google, hãy hiển thị tiện ích ExampleApp."
"Tiện ích của ExampleApp".

Trợ lý sẽ hiển thị các tiện ích này kèm phần giới thiệu chung: "ExampleApp cho biết đây là một tiện ích". Mặc dù Trợ lý trả về nguyên gốc các tiện ích được yêu cầu theo cách này mà nhà phát triển ứng dụng không cần phải làm gì, nhưng phương thức gọi này lại yêu cầu người dùng phải biết rõ về tiện ích để yêu cầu. Để đơn giản hoá quá trình khám phá tiện ích, hãy sử dụng phương thức thực hiện ý định được mô tả chi tiết trong phần sau.

Thực hiện ý định

Giúp các tiện ích của bạn dễ tìm hơn bằng cách sử dụng chúng để thực hiện những truy vấn bằng ngôn ngữ tự nhiên của người dùng trên Trợ lý. Ví dụ: bạn có thể trả về một tiện ích bất cứ khi nào người dùng kích hoạt BII GET_EXERCISE_OBSERVATION trong ứng dụng thể dục bằng cách hỏi "Ok Google, tuần này tôi chạy được bao nhiêu dặm trên ExampleApp rồi?" Ngoài việc đơn giản hoá quá trình khám phá, việc tích hợp tiện ích với Hành động trong ứng dụng cũng mang lại các lợi thế sau:

Quyền truy cập tham số: Trợ lý cung cấp các tham số ý định được trích xuất từ truy vấn của người dùng đến tiện ích của bạn, nhờ đó mà đưa ra phản hồi phù hợp.
Phần giới thiệu TTS tuỳ chỉnh: Bạn có thể cung cấp một chuỗi văn bản dưới dạng lời nói (TTS) để Trợ lý thông báo khi hiện tiện ích của bạn.
Ghim tiện ích: Trợ lý sẽ hiển thị nút Thêm tiện ích này gần tiện ích của bạn, để người dùng có thể dễ dàng ghim tiện ích đó vào trình chạy của họ.

Triển khai phương thức thực hiện tiện ích

Để triển khai phương thức thực hiện tiện ích cho ý định của bạn, hãy làm theo các bước sau:

Triển khai tiện ích Android bằng cách làm theo các bước được mô tả trong phần Tạo tiện ích đơn giản.
Trong tệp tài nguyên shortcuts.xml của ứng dụng, hãy thêm một phần tử <app-widget> vào khả năng hỗ trợ của bạn có chứa thông tin chi tiết về việc thực hiện đơn hàng cũng như thẻ BII <parameter>. Cập nhật tiện ích của bạn để xử lý các tham số.
Thêm Thư viện mở rộng tiện ích bắt buộc, để Trợ lý có thể truyền tên và tham số BII vào tiện ích của bạn. Ngoài ra, phần giới thiệu TTS tuỳ chỉnh và chức năng ghim vào tiện ích cũng sẽ được bật.

Phần sau đây mô tả giản đồ <app-widget> cho shortcuts.xml.

Giản đồ tiện ích

Phần tử <app-widget> được định nghĩa là phần tử thực hiện nhiệm vụ trong các phần tử <capability> trong shortcuts.xml. Những phần tử này bắt buộc phải có các thuộc tính sau, trừ phi được ghi chú là không bắt buộc:

Thẻ "shortcuts.xml"	Có trong	Thuộc tính
`<app-widget>`	`<capability>`	`android:identifier` `android:targetClass`
`<parameter>`	`<app-widget>`	Vui lòng xem Giản đồ hành động trong ứng dụng để biết các thuộc tính.
`<extra>`	`<app-widget>`	`android:name` (chỉ áp dụng cho TTS) `android:value` (không bắt buộc)

Mô tả giản đồ tiện ích

Phần tử của phương thức thực hiện tiện ích cấp cao nhất.

Thuộc tính:

android:identifier: giá trị nhận dạng cho phương thức thực hiện này. Giá trị này phải là duy nhất trên các phần tử của phương thức thực hiện <app-widget> và <intent> được xác định trong <capability>.
android:targetClass: tên đầy đủ của lớp AppWidgetProvider để xử lý ý định.

<parameter>

Ánh xạ một tham số BII với giá trị ý định <parameter>. Bạn có thể xác định số không hoặc nhiều tham số khác cho từng phần tử <app-widget>. Trong phương thức thực hiện, Trợ lý sẽ truyền tham số bằng cách cập nhật các ứng dụng khác cho thực thể tiện ích ở dạng cặp khoá-giá trị theo định dạng sau:

Khoá: android:key được xác định cho tham số.
Giá trị: giá trị mà BII trích xuất từ phương thức nhập bằng giọng nói của người dùng.

Bạn có thể truy cập vào các ứng dụng khác này bằng cách gọi getAppWidgetOptions() trên đối tượng AppWidgetManager được liên kết. Đối tượng này trả về Bundle chứa tên của BII kích hoạt cũng như các tham số tương ứng. Vui lòng xem phần Trích xuất giá trị tham số để biết thông tin chi tiết.

Để biết thêm thông tin về việc so khớp tham số BII, vui lòng xem bài viết Dữ liệu và so khớp tham số.

<extra>

Thẻ không bắt buộc khai báo rằng bạn nên sử dụng phần giới thiệu TTS tuỳ chỉnh cho tiện ích này. Thẻ này đòi hỏi các giá trị thuộc tính sau:

android:name: "hasTts"
android:value: "true"

Mã mẫu

Ví dụ sau đây từ tệp shortcuts.xml minh hoạ cấu hình phương thức thực hiện tiện ích cho chức năng BII GET_EXERCISE_OBSERVATION:

<capability android:name="actions.intent.GET_EXERCISE_OBSERVATION">
  <app-widget
    android:identifier="GET_EXERCISE_OBSERVATION_1"
    android:targetClass="com.exampleapp.providers.exampleAppWidgetProvider"
    android:targetPackage="com.exampleapp">
    <parameter
      android:name="exerciseObservation.aboutExercise.name"
      android:key="exercisename">
    </parameter>
    <extra android:name="hasTts" android:value="true"/>
  </app-widget>
</capability>

Bạn có thể chỉ định nhiều phần tử <app-widget> hoặc sử dụng kết hợp nhiều phần tử <app-widget> và <intent> cho từng chức năng. Phương pháp này để bạn cung cấp trải nghiệm tuỳ chỉnh dựa trên các tổ hợp tham số khác nhau do người dùng cung cấp. Ví dụ: nếu người dùng không chỉ định vị trí trả xe trong truy vấn của họ, thì bạn có thể hướng họ đến hoạt động trong ứng dụng gợi ý các tuỳ chọn để đặt vị trí nhận xe và trả xe. Vui lòng xem phần Ý định dự phòng để biết thêm thông tin chi tiết về cách xác định ý định dự phòng.

Trích xuất giá trị tham số

Trong lớp AppWidgetProvider mẫu sau đây, hàm riêng updateAppWidget() được dùng để trích xuất tên và tham số BII từ các tuỳ chọn tiện ích Bundle:

Kotlin

package com.example.exampleapp

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

/**
 * Implementation of App Widget functionality.
 */
class MyAppWidget : AppWidgetProvider() {
    override fun onUpdate(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetIds: IntArray
    ) {
        // There might be multiple widgets active, so update all of them
        for (appWidgetId in appWidgetIds) {
            updateAppWidget(context, appWidgetManager, appWidgetId)
        }
    }

    private fun updateAppWidget(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetId: Int
    ) {
        val widgetText: CharSequence = context.getString(R.string.appwidget_text)

        // Construct the RemoteViews object
        val views = RemoteViews(context.packageName, R.layout.my_app_widget)
        views.setTextViewText(R.id.appwidget_text, widgetText)

        // Extract the name and parameters of the BII from the widget options
        val optionsBundle = appWidgetManager.getAppWidgetOptions(appWidgetId)
        val bii = optionsBundle.getString(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_BII) // "actions.intent.CREATE_TAXI_RESERVATION"
        val params = optionsBundle.getBundle(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_PARAMS)
        if (params != null && params.containsKey("dropoff")) {
            val dropoffLocation = params.getString("dropoff")
            // Build your RemoteViews with the extracted BII parameter
            // ...
        }
        appWidgetManager.updateAppWidget(appWidgetId, views)
    }
}

Java

package com.example.exampleapp;

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;

/**
 * Implementation of App Widget functionality.
 */
public class MyAppWidget extends AppWidgetProvider {

    @Override
    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // There might be multiple widgets active, so update all of them
        for (int appWidgetId : appWidgetIds) {
            updateAppWidget(context, appWidgetManager, appWidgetId);
        }
    }

    private static void updateAppWidget(Context context, AppWidgetManager appWidgetManager, int appWidgetId) {

        CharSequence widgetText = context.getString(R.string.appwidget_text);

        // Construct the RemoteViews object
        RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.my_app_widget);
        views.setTextViewText(R.id.appwidget_text, widgetText);

        // Extract the name and parameters of the BII from the widget options
        Bundle optionsBundle = appWidgetManager.getAppWidgetOptions(appWidgetId);
        String bii =
                optionsBundle.getString(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_BII); // "actions.intent.CREATE_TAXI_RESERVATION"
        Bundle params =
                optionsBundle.getBundle(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_PARAMS);

        if (params != null && params.containsKey(("dropoff"))){
            String dropoffLocation = params.getString("dropoff");
            // Build your RemoteViews with the extracted BII parameter
            // ...
        }

        appWidgetManager.updateAppWidget(appWidgetId, views);
    }
}

Thư viện mở rộng tiện ích

Thư viện mở rộng tiện ích của Hành động trong ứng dụng giúp cải thiện tiện ích của bạn đối với trải nghiệm Trợ lý chuyển tiếp bằng lời nói. Thư viện này cho phép các tiện ích của bạn nhận thông tin quan trọng về phương thức thực hiện từ BII kích hoạt, bao gồm cả tên BII và mọi tham số ý định được trích xuất từ truy vấn của người dùng.

Thư viện Maven này cho phép bạn cung cấp phần giới thiệu văn bản dưới dạng lời nói (TTS) tuỳ chỉnh cho từng tiện ích, để Trợ lý có thể thông báo bản tóm tắt nội dung hiển thị trực quan với người dùng. Ngoài ra, tính năng ghim trình chạy cũng sẽ được bật, giúp người dùng dễ dàng lưu các tiện ích hiển thị trong Trợ lý vào màn hình trình chạy của họ.

Bắt đầu bằng cách thêm thư viện vào phần phụ thuộc của tệp build.gradle cho mô-đun ứng dụng của bạn:

dependencies {
    //...
    implementation "com.google.assistant.appactions:widgets:0.0.1"
}

Giới thiệu tuỳ chỉnh

Sau khi nhập Thư viện mở rộng tiện ích, bạn có thể cung cấp phần giới thiệu TTS tuỳ chỉnh cho các tiện ích của mình. Để thêm định nghĩa vào AppWidgetProvider của tiện ích, hãy mở lớp trong IDE và nhập Thư viện mở rộng tiện ích:

Kotlin

import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

Java

import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;

Tiếp theo, hãy sử dụng thư viện để xác định các chuỗi giới thiệu và cập nhật tiện ích, như minh hoạ trong "ExampleAppWidget" này:

Kotlin

package com.example.exampleapp

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

/**
 * Implementation of App Widget functionality.
 */
object MyAppWidget : AppWidgetProvider() {
    fun updateAppWidget(
        context: Context?,
        appWidgetManager: AppWidgetManager,
        appWidgetId: Int
    ) {
        val appActionsWidgetExtension = AppActionsWidgetExtension.newBuilder(appWidgetManager)
            .setResponseSpeech("Hello world") // TTS to be played back to the user
            .setResponseText("Hello world!") // Response text to be displayed in Assistant
            .build()

        // Update widget with TTS
        appActionsWidgetExtension.updateWidget(appWidgetId)

        // Update widget UI
        appWidgetManager.updateAppWidget(appWidgetId, views)
    }
}

Java

package com.example.exampleapp;

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;

/**
 * Implementation of App Widget functionality.
 */
public class MyAppWidget extends AppWidgetProvider {

  static void updateAppWidget(Context context, AppWidgetManager appWidgetManager,
    int appWidgetId) {

    AppActionsWidgetExtension appActionsWidgetExtension = AppActionsWidgetExtension.newBuilder(appWidgetManager)
      .setResponseSpeech("Hello world")  // TTS to be played back to the user
      .setResponseText("Hello world!")  // Response text to be displayed in Assistant
      .build();

      // Update widget with TTS
      appActionsWidgetExtension.updateWidget(appWidgetId);

      // Update widget UI
      appWidgetManager.updateAppWidget(appWidgetId, views);
    }

}

Nội dung đề xuất kiểu TTS

Hãy sử dụng các nội dung đề xuất kiểu sau để tối ưu hoá phần giới thiệu tiện ích tuỳ chỉnh cho lời nhắc TTS và lời nhắc được hiển thị.

Nội dung đề xuất	Nên	Không nên
Thu gọn Sử dụng tính năng thu gọn trong lời nhắc TTS. Tin nhắn không bị thu gọn nghe cứng và giống rô bốt chứ không tự nhiên và có tính đối thoại. Việc nói những từ như "không thể" và "đừng làm" nghe có vẻ trừng phạt và gay gắt.	`ResponseSpeech` (TTS) Rất tiếc, tôi không tìm thấy thông tin đặt chỗ nào. `ResponseText` Rất tiếc, tôi không tìm thấy thông tin đặt chỗ nào.	`ResponseSpeech` (TTS) Rất tiếc, tôi không thể tìm thấy thông tin đặt chỗ nào. `ResponseText` Rất tiếc, tôi không thể tìm thấy thông tin đặt chỗ nào.
Dấu phẩy Hãy trình bày rõ ràng hơn bằng cách sử dụng dấu phẩy nối tiếp trong danh sách gồm 3 mục trở lên. Nếu không có dấu phẩy nối tiếp, các mục riêng lẻ trong danh sách có thể bị nghe nhầm hoặc được đọc thành nhóm. Ví dụ: trong "hoa thuỷ tiên vàng, hoa cúc và hoa hướng dương", thì "hoa cúc và hoa hướng dương" có vẻ như đi với nhau. Trong "hoa thuỷ tiên vàng, hoa cúc, và hoa hướng dương", cả 3 loại rõ ràng là riêng biệt.	`ResponseSpeech` (TTS) Các sản phẩm phổ biến nhất của chúng tôi gồm có hoa hồng vàng, hoa thuỷ tiên vàng, hoa cúc, và hoa hướng dương. `ResponseText` Các sản phẩm phổ biến nhất của chúng tôi gồm có hoa hồng vàng, hoa thuỷ tiên vàng, hoa cúc và hoa hướng dương.	`ResponseSpeech` (TTS) Các sản phẩm phổ biến nhất của chúng tôi gồm có hoa hồng vàng, hoa thuỷ tiên vàng, hoa cúc và hoa hướng dương. `ResponseText` Các sản phẩm phổ biến nhất của chúng tôi gồm có hoa hồng vàng, hoa thuỷ tiên vàng, hoa cúc và hoa hướng dương.
Chữ số Hãy sử dụng chữ số thay vì văn bản để khiến nội dung hình ảnh dễ xem hơn.	`ResponseSpeech` (TTS) Huyết áp của bạn là 100 trên 80. `ResponseText` Huyết áp của bạn là 100/80.	`ResponseSpeech` (TTS) Huyết áp của bạn là 100/80. `ResponseText` Huyết áp của bạn là một trăm trên tám mươi.
Biểu tượng Hãy sử dụng các ký hiệu chuyên biệt thay vì văn bản để khiến nội dung hình ảnh trở nên dễ xem hơn.	`ResponseSpeech` (TTS) Giao dịch mua gần đây nhất của bạn là 24,65$. `ResponseText` Giao dịch mua gần đây nhất của bạn là 24,65 USD.	`ResponseSpeech` (TTS) Giao dịch mua gần đây nhất của bạn là 24 đô la và 65 xu. `ResponseText` Giao dịch mua gần đây nhất của bạn là 24 đô la và 65 xu.
Tránh ngôn từ khách khí Ngôn từ khách khí khiến nội dung phản hồi có vẻ xa cách và trang trọng. Đừng dùng ngôn từ khách khí mà hãy giữ cho cuộc trò chuyện thân thiện và thân mật.	`ResponseSpeech` (TTS) Đơn đặt hàng của bạn đã được giao. `ResponseText` Đơn đặt hàng của bạn đã được giao.	`ResponseSpeech` (TTS) Chắc chắn rồi, tôi có thể nói điều đó với bạn. Đơn đặt hàng của bạn đã được giao. `ResponseText` Chắc chắn rồi, tôi có thể nói điều đó với bạn. Đơn đặt hàng của bạn đã được giao.
Tránh dùng dấu chấm than Chúng tạo ra cảm giác nội dung đang được hét lên.	`ResponseSpeech` (TTS) Hôm nay, bạn đã chạy được 1,5 dặm. `ResponseText` Hôm nay, bạn đã chạy được 1,5 dặm.	`ResponseSpeech` (TTS) Hôm nay bạn đã chạy được 1,5 dặm! `ResponseText` Hôm nay, bạn đã chạy được 1,5 dặm!
Giờ Sử dụng chữ số: "5:15", thay vì "năm-mười lăm" hoặc "năm giờ mười lăm". Với đồng hồ 12 giờ, hãy dùng định dạng SA hoặc CH.	`ResponseSpeech` (TTS) Đơn hàng của bạn sẽ đến chậm nhất vào 8:15 sáng. `ResponseText` Đơn hàng của bạn sẽ đến chậm nhất vào 8:15 sáng.	`ResponseSpeech` (TTS) Đơn hàng của bạn sẽ đến chậm nhất vào 8 giờ 15 phút sáng nay. `ResponseText` Đơn hàng của bạn sẽ đến chậm nhất vào 8 giờ 15 phút sáng nay.
Đừng độc thoại Cung cấp nhiều thông tin nhưng trả lời ngắn gọn. Đừng đi vào quá chi tiết nếu không mang lại lợi ích rõ ràng cho người dùng.	`ResponseSpeech` (TTS) Tháng trước, bạn đã dùng 159 giờ năng lượng. `ResponseText` Tháng trước, bạn đã dùng 159 giờ năng lượng.	`ResponseSpeech` (TTS) Việc tiết kiệm năng lượng rất quan trọng đối với hành tinh này và môi trường. Tháng trước, bạn đã dùng 159 giờ năng lượng. Còn tháng này, bạn đã dùng 58 giờ năng lượng. `ResponseText` Việc tiết kiệm năng lượng rất quan trọng đối với hành tinh này và môi trường. Tháng trước, bạn đã dùng 159 giờ năng lượng. Còn tháng này, bạn đã dùng 58 giờ năng lượng.
Dùng từ ngắn gọn, đơn giản Ngôn từ thẳng thắn và đơn giản có sức hấp dẫn lớn nhất, giúp mọi người thuộc mọi thành phần đều có thể tiếp cận.	`ResponseSpeech` (TTS) Chỉ số đường huyết gần nhất của bạn là 126. `ResponseText` Chỉ số đường huyết gần nhất của bạn là 126 mg/dL.	`ResponseSpeech` (TTS) Giá trị chỉ nồng độ glucose có trong máu là 126. `ResponseText` Giá trị chỉ nồng độ glucose có trong máu là 126.

Ghim trình chạy

Thư viện mở rộng tiện ích cho phép hiển thị nút Thêm tiện ích này cùng với tiện ích của bạn trong Trợ lý. Để bật tính năng ghim, hãy thêm định nghĩa bộ tiếp nhận sau đây vào AndroidManifest.xml:

<application>
  <receiver android:name="com.google.assistant.appactions.widgets.pinappwidget.PinAppWidgetBroadcastReceiver"
    android:exported="false">
    <intent-filter>
      <action android:name="com.google.assistant.appactions.widgets.COMPLETE_PIN_APP_WIDGET" />
    </intent-filter>
  </receiver>
  <service
    android:name=
    "com.google.assistant.appactions.widgets.pinappwidget.PinAppWidgetService"
    android:enabled="true"
    android:exported="true">
    <intent-filter>
      <action
        android:name="com.google.assistant.appactions.widgets.PIN_APP_WIDGET" />
    </intent-filter>
  </service>
</application>

Tình trạng sẵn có của khoảng không quảng cáo

BBI hỗ trợ khoảng không quảng cáo nội tuyến hoặc khoảng không quảng cáo trên web có thể mở rộng những khoảng không quảng cáo này tới các lần thực hiện tiện ích của bạn.

Khoảng không quảng cáo nội tuyến

Mã sau đây từ tệp shortcuts.xml mẫu minh hoạ chức năng BII START_EXERCISE được định cấu hình cho khoảng không quảng cáo nội tuyến và phương thức thực hiện tiện ích:

<capability
  android:name="actions.intent.START_EXERCISE">
  <app-widget
    android:identifier="START_EXERCISE_1"
    android:targetClass="com.example.exampleapp.StartExerciseAppWidgetProvider">
    <parameter
      android:name="exercise.name"
      android:key="exerciseName"
      app:shortcutMatchRequired="true">
    </parameter>
  </app-widget>
</capability>

<shortcut android:shortcutId="RunningShortcut">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetClass="com.example.exampleapp.StartExcerciseActivity" />
  <capability-binding
    android:capability="actions.intent.START_EXERCISE"
    android:parameter="exercise.name"
    android:value="running;runs" />
</shortcut>

Trong mẫu trước đó, khi người dùng kích hoạt chức năng này bằng cách yêu cầu Trợ lý, "Bắt đầu chạy với ExampleApp", gói tuỳ chọn cho phương thức thực hiện <app-widget> chứa cặp khoá-giá trị sau:

Khoá = “exerciseName”
Giá trị = “RunningShortcut”

Khoảng không quảng cáo trên web

Mã sau đây từ tệp shortcuts.xml mẫu cho thấy một chức năng đã bật cho khoảng không quảng cáo trên web và phương thức thực hiện tiện ích:

<shortcuts>
  <capability
    android:name="actions.intent.START_EXERCISE">
    <app-widget
      android:identifier="START_EXERCISE_1"
      android:targetClass="com.example.exampleapp.CreateTaxiAppWidgetProvider">
      <parameter
        android:name="exercise.name"
        android:key="exerciseName"
        android:mimeType="text/*">
        <data android:pathPattern="https://exampleapp.com/exercise/.*" />
      </parameter>
    </app-widget>
  </capability>
</shortcuts>

Kiểm thử Hành động trong ứng dụng

Sử dụng Công cụ kiểm thử Hành động trong ứng dụng, một tính năng trong trình bổ trợ của Trợ lý Google cho Android Studio, để kiểm thử các tiện ích trên một thiết bị thực hoặc ảo. Để sử dụng công cụ này, vui lòng làm theo các bước sau:

Kết nối thiết bị thử nghiệm với ứng dụng đang chạy.
Trong Android Studio, vui lòng chọn Công cụ > Hành động trong ứng dụng > Công cụ kiểm tra hành động trong ứng dụng.
Nhấp vào Tạo bản xem trước.
Sử dụng Android Studio, chạy ứng dụng của bạn trên thiết bị kiểm thử.
Dùng ứng dụng Trợ lý trên thiết bị kiểm thử để kiểm thử Hành động trong ứng dụng. Ví dụ: bạn có thể nói những câu đại loại như "Ok Google, tuần này tôi chạy được bao nhiêu dặm trên ExampleApp rồi?"
Quan sát hành vi của ứng dụng hoặc sử dụng Trình gỡ lỗi Android Studio để xác minh kết quả của hành động mong muốn.

Nguyên tắc về chất lượng

Phần này nêu bật các yêu cầu chính và những phương pháp tốt nhất khi bạn tích hợp Hành động trong ứng dụng với các tiện ích.

Nội dung trong tiện ích

(Bắt buộc) Không hiển thị quảng cáo trong tiện ích của bạn.
Tập trung hoàn toàn vào nội dung tiện ích để thực hiện ý định. Đừng cố gắng thực hiện nhiều ý định thông qua một tiện ích hoặc thêm nội dung không liên quan.

Xử lý việc xác thực

(Bắt buộc) Khi cần xác thực người dùng để hoàn thành luồng người dùng, vui lòng trả về một tiện ích giải thích rằng người dùng cần tiếp tục trong ứng dụng. Phương thức xác thực người dùng nội tuyến trong Trợ lý Google không được hỗ trợ cho Hành động trong ứng dụng.
Nếu người dùng cho phép ứng dụng của bạn hiển thị dữ liệu bằng các tiện ích, bạn có thể trả về một tiện ích lỗi trong thời gian chạy cho người dùng trái phép.

Ý định dự phòng

(Bắt buộc) Trong shortcuts.xml, hãy luôn cung cấp tính năng dự phòng <intent> ngoài việc thực hiện tiện ích cho một khả năng nhất định. Ý định dự phòng là phần tử <intent> không có giá trị <parameter> bắt buộc.

Điều này cho phép Trợ lý thực hiện một hành động khi truy vấn của người dùng không chứa các tham số bắt buộc theo các phần tử phương thức thực hiện khác được xác định trong chức năng. Trường hợp ngoại lệ là khi không có tham số bắt buộc nào cho chức năng đó, bạn chỉ cần cung cấp phương thức thực hiện tiện ích.
Sử dụng ý định dự phòng để mở ứng dụng của bạn trên màn hình liên quan thay vì màn hình chính.

Mã sau đây từ tệp shortcuts.xml mẫu minh hoạ một <capability> có <intent> dự phòng hỗ trợ việc thực hiện <app-widget> chính:

<shortcuts>
  <capability
    android:name="actions.intent.CREATE_TAXI_RESERVATION">
    <!-- Widget with required parameter, specified using the "android:required" attribute. -->
    <app-widget
      android:identifier="CREATE_TAXI_RESERVATION_1"
      android:targetClass="com.example.myapplication.CreateTaxiAppWidgetProvider">
      <parameter
        android:name="taxiReservation.dropoffLocation.name"
        android:key="dropoff"
        android:required="true">
      </parameter>
    </app-widget>
    <!-- Fallback intent with no parameters required to successfully execute. -->
    <intent
      android:identifier="CREATE_TAXI_RESERVATION_3"
      android:action="myapplication.intent.CREATE_TAXI_RESERVATION_1"
      android:targetClass="com.example.myapplication.TaxiReservationActivity">
    </intent>
  </capability>
</shortcuts>

Tiết lộ dữ liệu trên Google Play

Phần này liệt kê các dữ liệu của người dùng cuối được thu thập qua phiên bản mới nhất của Thư viện mở rộng tiện ích.

SDK này sẽ gửi phản hồi văn bản dưới dạng lời nói (TTS) do nhà phát triển cung cấp, Trợ lý Google sẽ thông báo cho người dùng bằng công nghệ lời nói của Trợ lý. Google không lưu trữ thông tin này.

Hành động trong ứng dụng cũng có thể thu thập siêu dữ liệu của ứng dụng cho các mục đích sau:

Để theo dõi tỷ lệ sử dụng của nhiều phiên bản SDK.
Để định lượng việc sử dụng tính năng SDK trên các ứng dụng.

Tích hợp Hành động trong ứng dụng với các tiện ích Android

Lợi ích

Cách Trợ lý hiển thị các tiện ích

Lời gọi rõ ràng

Thực hiện ý định

Triển khai phương thức thực hiện tiện ích

Giản đồ tiện ích

Mô tả giản đồ tiện ích

<app-widget>

<parameter>

<extra>

Mã mẫu

Trích xuất giá trị tham số

Kotlin

Java

Thư viện mở rộng tiện ích

Giới thiệu tuỳ chỉnh

Kotlin

Java

Kotlin

Java

Nội dung đề xuất kiểu TTS

Thu gọn

Dấu phẩy

Chữ số

Biểu tượng

Tránh ngôn từ khách khí

Tránh dùng dấu chấm than

Giờ

Đừng độc thoại

Dùng từ ngắn gọn, đơn giản

Ghim trình chạy

Tình trạng sẵn có của khoảng không quảng cáo

Khoảng không quảng cáo nội tuyến

Khoảng không quảng cáo trên web

Kiểm thử Hành động trong ứng dụng

Nguyên tắc về chất lượng

Nội dung trong tiện ích

Xử lý việc xác thực

Ý định dự phòng

Tiết lộ dữ liệu trên Google Play