将 App Actions 与 Android 小部件集成

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

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);
    }

}

TTS 样式建议

使用以下样式建议来优化您的自定义小部件简介，以用于 TTS 和显示的提示。

启动器固定

小部件扩展库使“添加此小部件”按钮可以与您的小部件一起在助理中显示。要启用固定，请将以下接收器定义添加到 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>

库存可用性

支持 内联库存 或 网页库存 的 BII 可以将这些库存扩展到您的应用小部件完成。

内联库存

以下来自示例 shortcuts.xml 文件的代码演示了为内联库存和小部件完成配置的 START_EXERCISE BII 功能。

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

在前面的示例中，当用户通过询问助理“使用 ExampleApp 开始跑步”来触发此功能时，<app-widget> 完成的选项包将包含以下键值对：

• 键 = “exerciseName”
• 值 = “RunningShortcut”

网页库存

以下来自示例 shortcuts.xml 文件的代码显示了为网页库存和小部件完成启用的功能。

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

测试应用操作

使用应用操作测试工具（Android Studio 的 Google 助理插件 的一项功能）在物理设备或虚拟设备上测试小部件。要使用该测试工具，请执行以下步骤

1. 将您的测试设备连接到运行您的应用的设备。
2. 在 Android Studio 中，转到工具 > 应用操作 > 应用操作测试工具。
3. 单击创建预览。
4. 使用 Android Studio，在您的测试设备上运行您的应用。
5. 使用测试设备上的助理应用来测试您的应用操作。例如，您可以说“嘿 Google，本周我在 ExampleApp 上跑了多少英里？”
6. 观察应用的行为，或使用 Android Studio 调试器 来验证所需的操作结果。

质量指南

本节重点介绍将应用操作与小部件集成时的关键要求和最佳实践。

小部件中的内容

• （必需）不要在您的应用小部件中显示广告。
• 使小部件内容完全专注于完成意图。不要尝试用一个小部件完成多个意图，也不要添加无关的内容。

处理身份验证

• （必需）在需要用户身份验证才能完成用户流程的地方，返回一个小部件，说明用户需要在应用中继续。Google 助理中不支持应用操作的内联用户身份验证。
• 如果用户允许您的应用使用小部件显示数据，则可以在运行时为未经授权的用户返回错误小部件。

回退意图

• （必需）在您的 shortcuts.xml 中，始终为给定功能提供回退 <intent> 以及您的应用小部件完成。回退意图是一个没有必需 <parameter> 值的 <intent> 元素。

  这使助理能够在用户查询不包含功能中定义的其他完成元素所需的参数时完成操作。唯一的例外是，当该功能没有必需参数时，在这种情况下，只需要应用小部件完成。

• 使用回退意图打开应用的相应屏幕，而不是主屏幕。

以下来自示例 shortcuts.xml 文件的代码演示了具有支持主要 <app-widget> 完成的回退 <intent> 的 <capability>。

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

Google Play 数据披露

本节列出了最新版 Widgets 扩展库收集的最终用户数据。

此 SDK 发送开发人员提供的文本转语音 (TTS) 响应，这些响应由 Google 助理使用其语音技术宣布给用户。 Google 不会存储此信息。

应用操作 还可能收集客户端应用元数据，用于以下目的：

• 监控不同 SDK 版本的采用率。
• 量化应用中的 SDK 功能使用情况。