Как интегрировать действия в приложении с виджетами Android

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

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

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

Виджеты – это миниатюрные представления приложений, которые можно встраивать в интерфейс Android, например на главный или заблокированный экран. Действия в приложениях повышают эффективность виджетов, позволяя показывать их в Ассистенте.

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

Как Ассистент показывает виджеты

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

• Явный запрос виджета по названию.
• Пользователь произносит запрос, который активирует встроенное или специальное намерение, настроенное для выполнения виджета.

Явный вызов

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

• "Окей, Google, покажи виджет ExampleApp".
• "Виджеты из ExampleApp".

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

Выполнение намерения

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

• Доступ к параметрам. Ассистент передает виджету параметры намерения, извлеченные из запроса пользователя, что позволяет персонализировать ответы.
• Собственные вступления TTS. Вы можете указать строку преобразования текста в речь, которую Ассистент будет озвучивать при показе виджета.
• Закрепление виджетов. Рядом с вашим виджетом Ассистент показывает кнопку Добавить этот виджет, чтобы пользователи могли легко закрепить его на панели запуска.

Как реализовать выполнение виджета

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

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

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

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

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

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

<app-widget>

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

Атрибуты:

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

<parameter>

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

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

Чтобы получить доступ к этим дополнительным данным, вызовите getAppWidgetOptions() для связанного объекта AppWidgetManager. Это вернет Bundle с названием встроенного намерения, которое активировало действие, и его параметрами. Подробнее о том, как извлекать значения параметров…

Подробнее о сопоставлении параметров встроенных намерений…

<extra>

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

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

Пример кода

В следующем примере из файла shortcuts.xml показана конфигурация выполнения виджета для функции 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>

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

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

В следующем примере класса AppWidgetProvider закрытая функция updateAppWidget() используется для извлечения названия и параметров встроенного намерения из параметров виджета 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>