将与应用有关的 Action 与 Android widget 集成

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 的自定义 widget 简介，以及所显示的提示。

启动器固定

借助 widget Extension 库，可以在 Google 助理中与 widget 一起显示添加此 widget 按钮。如需启用固定功能，请将以下接收器定义添加到 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 可以将这两种目录扩展到您的 widget 执行方式。

内嵌目录

示例 shortcuts.xml 文件中的以下代码演示了为内嵌目录和 widget 执行方式配置的 START_EXERCISE BII capability：

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

在上述示例中，当用户通过向 Google 助理发出“Start running with ExampleApp”请求来触发此 capability 时，<app-widget> 执行方式的选项 bundle 就会包含以下键值对：

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

网站目录

示例 shortcuts.xml 文件中的以下代码显示了为网站目录和 widget 执行方式启用的 capability：

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

测试与应用有关的 Action

与应用有关的 Action 测试工具是适用于 Android Studio 的 Google 助理插件的一项功能，可用于在实体设备或虚拟设备上测试 widget。如要使用该测试工具，请按以下步骤操作：

1. 连接运行您的应用的测试设备。
2. 在 Android Studio 中，依次点击 Tools > App Actions > App Actions Test Tool。
3. 点击 Create preview。
4. 使用 Android Studio，在测试设备上运行您的应用。
5. 使用测试设备上的 Google 助理应用测试与应用有关的 Action。例如，您可以这样说：“Hey Google, how many miles have I run this week on ExampleApp?”。
6. 观察应用的行为，或使用 Android Studio 调试程序来验证是否取得了所需的操作结果。

质量指南

本部分重点介绍将与应用有关的 Action 与 widget 集成的关键要求和最佳实践。

widget 中的内容

• （必需）不得在 widget 中展示广告。
• 让 widget 内容完全专注于执行 intent。不要试图用一个 widget 执行多个 intent，也不要添加不相关的内容。

处理身份验证

• （必需）如果需要对用户进行身份验证才能完成用户流，则应返回一个 widget，用于说明用户需要在应用中继续操作。与应用有关的 Action 不支持 Google 助理中的内嵌用户身份验证。
• 如果用户允许您的应用使用 widget 显示数据，您可以在运行时为未经授权的用户返回错误 widget。

回退 intent

• （必需）在 shortcuts.xml 中，除 widget 执行方式外，还应始终为给定 capability 提供一个回退 <intent>。回退 intent 是不含必需的 <parameter> 值的 <intent> 元素。

  这样一来，当用户查询中不包含该 capability 中定义的其他执行方式元素所需的参数时，Google 助理仍可执行操作。对此有一个例外，那就是该 capability 没有必需的参数，在这种情况下，只要有 widget 执行方式就够了。

• 使用回退 intent 在您的应用中打开相关屏幕，而不是主屏幕。

示例 shortcuts.xml 文件中的以下代码展示了一个 <capability>，其回退 <intent> 支持主要 <app-widget> 执行方式：

<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 Extension 库会收集的最终用户数据。

此 SDK 会发送开发者提供的文字转语音 (TTS) 响应，这些响应将由 Google 助理使用 Google 助理的语音技术向用户读出。Google 不会存储这些信息。

与应用有关的 Action 也可能会出于以下目的收集客户端应用元数据：

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