Интегрируйте действия приложения с виджетами Android.

Во многих случаях лучшим ответом является предоставление пользователю простого ответа, краткого подтверждения или быстрого интерактивного взаимодействия. Вы можете отобразить виджет приложения Android в Google Assistant для реализации подобных намерений.

В этом руководстве рассказывается, как выполнять запросы пользователей Ассистента с помощью виджетов и как улучшить работу виджетов для Ассистента с помощью библиотеки расширений виджетов действий приложения.

Преимущества

Виджеты — это миниатюрные представления приложений, которые можно встроить в поверхности Android, например на панель запуска или экран блокировки. С помощью App Actions вы повышаете эффективность своих виджетов, предоставляя им возможность отображаться в Ассистенте:

1. Обнаружение: активно отображайте виджеты в ответ на запросы пользователей на естественном языке.
2. Вовлеченность: отображайте виджеты в контексте громкой связи, например, когда Ассистент предоставляет персональные результаты на экране блокировки или в Android Auto .
3. Сохранение: пользователи могут закреплять виджеты, отображаемые в Ассистенте, на своей панели запуска. Для закрепления функций требуется библиотека расширений виджетов .

Как Ассистент отображает виджеты

Пользователи могут вызывать виджеты в Ассистенте двумя способами:

• Явный запрос виджета по имени.
• Выполнение запроса Ассистенту, который запускает встроенное намерение (BII) или пользовательское намерение , настроенное для выполнения виджета.

Явный вызов

Чтобы явно вызвать виджеты для любого установленного приложения, пользователи могут задавать Ассистенту такие вопросы, как:

• «Окей, Google, покажи виджет exampleApp».
• «Виджеты из exampleApp».

Ассистент отображает эти виджеты с общим описанием: «ExampleApp говорит, вот виджет». Хотя Assistant изначально возвращает виджеты, запрошенные таким образом, без каких-либо действий со стороны разработчика приложения, этот метод вызова требует от пользователя явного знания виджета, чтобы запросить его. Чтобы упростить обнаружение виджетов, используйте метод выполнения намерений, подробно описанный в следующем разделе.

Исполнение намерения

Упростите поиск виджетов, используя их для выполнения запросов на естественном языке, которые пользователи выполняют в Ассистенте. Например, вы можете возвращать виджет всякий раз, когда пользователь запускает GET_EXERCISE_OBSERVATION BII в вашем фитнес-приложении, спрашивая: «Окей, Google, сколько миль я пробежал на этой неделе в exampleApp?» Помимо упрощения обнаружения, интеграция виджетов с действиями приложений дает следующие преимущества:

• Доступ к параметрам: Ассистент передает параметры намерений , извлеченные из пользовательского запроса, в ваш виджет, обеспечивая возможность персонализированных ответов .
• Пользовательские представления TTS: вы можете предоставить строку преобразования текста в речь (TTS), чтобы Помощник мог объявить при отображении вашего виджета.
• Закрепление виджета: Ассистент отображает кнопку «Добавить этот виджет» рядом с вашим виджетом, позволяя пользователям легко закреплять ваши виджеты на панели запуска.

Реализация виджетов

Чтобы реализовать реализацию виджета в соответствии с вашими намерениями, выполните следующие действия:

1. Реализуйте виджет Android, выполнив действия, описанные в разделе Создание простого виджета .
2. В файле ресурсов shortcuts.xml вашего приложения добавьте элемент <app-widget> к своей возможности, содержащий сведения о выполнении и теги BII <parameter> . Обновите свой виджет для обработки параметров.
3. Добавьте необходимую библиотеку расширений виджетов , которая позволит Ассистенту передавать имена и параметры BII вашим виджетам. Он также позволяет настраивать введение TTS и функцию закрепления виджетов.

В следующем разделе описывается схема <app-widget> для shortcuts.xml .

Схема виджета

Элементы <app-widget> определяются как элементы <capability> в shortcuts.xml . Для них требуются следующие атрибуты, если они не указаны как необязательные:

Описание схемы виджета

<приложение-виджет>

Элемент выполнения виджета верхнего уровня.

Атрибуты:

• android:identifier : идентификатор для этого выполнения. Это значение должно быть уникальным для элементов выполнения <app-widget> и <intent> , определенных в <capability> .
• android:targetClass : полное имя класса AppWidgetProvider для обработки намерения.

<параметр>

Сопоставляет параметр BII со значением <parameter> намерения. Вы можете определить ноль или более параметров для каждого элемента <app-widget> . Во время выполнения Ассистент передает параметры, обновляя дополнительные параметры для экземпляра виджета в виде пар ключ-значение в следующем формате:

• Ключ: ключ android:key определенный для параметра.
• Значение: значение, которое BII извлекает из голосового ввода пользователя.

Доступ к этим дополнительным функциям можно получить, вызвав метод getAppWidgetOptions() для связанного объекта AppWidgetManager , который возвращает Bundle , содержащий имя запускающего BII и его параметры. Подробности см. в разделе Извлечение значений параметров .

Дополнительную информацию о сопоставлении параметров BII см. в разделе Данные параметров и сопоставление .

<дополнительно>

Необязательный тег, объявляющий, что для этого виджета используется собственное введение TTS . Для этого тега требуются следующие значения атрибутов:

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

Пример кода

Следующий пример из файла shortcuts.xml демонстрирует конфигурацию выполнения виджета для возможности GET_EXERCISE_OBSERVATION BII:

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

Вы можете указать несколько элементов <app-widget> или использовать комбинацию элементов <app-widget> и <intent> для каждой возможности. Такой подход позволяет обеспечить индивидуальный подход на основе различных комбинаций параметров, предоставленных пользователями. Например, если пользователь не указывает место высадки в своем запросе, вы можете направить его к действию в вашем приложении, которое показывает варианты настройки мест посадки и высадки. Дополнительные сведения об определении резервных намерений см. в разделе «Намерения отката» .

Извлечение значений параметров

В следующем примере класса AppWidgetProvider частная функция updateAppWidget() используется для извлечения имени и параметров BII из параметров виджета Bundle :

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

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

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

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

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

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

}

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

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

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

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