Zintegruj akcje w aplikacji z widżetami na Androida

W przypadku wielu intencji najlepsza odpowiedź to prosta, zwięzła odpowiedź, lub szybki, interaktywny interfejs. Możesz w niej wyświetlać widżet aplikacji na Androida w Asystencie Google do realizacji tego typu intencji.

Z tego przewodnika dowiesz się, jak odpowiadać na pytania użytkowników Asystenta za pomocą widżetów oraz jak ulepszyć działanie widżetów Asystenta dzięki akcjom w aplikacji Biblioteka rozszerzeń widżetów.

Zalety

Widżety to miniaturowe widoki aplikacji, które można umieszczać na urządzeniach z Androidem. takich jak Menu z aplikacjami czy ekran blokady. Dzięki akcjom w aplikacji wpływ widżetów, umożliwiając ich wyświetlanie w Asystencie:

1. Wykrywalność: proaktywnie wyświetlaj widżety w odpowiedzi na żądania użytkowników zapytań w języku naturalnym.
2. Zaangażowanie: wyświetlaj widżety bez użycia rąk, na przykład podczas wyświetlania Asystent podaje Twoje wyniki na ekranie blokady i gdy jest włączony Android Auto
3. Utrzymanie: zezwalaj użytkownikom na przypinanie widżetów wyświetlanych w Asystenta do programu uruchamiającego. Funkcja przypinania wymaga: Biblioteka rozszerzeń widżetów.

Jak Asystent wyświetla widżety

Użytkownicy mogą wywoływać widżety w Asystencie na 2 sposoby:

• Bezpośrednie żądanie widżetu według nazwy.
• Wypowiedzenie do Asystenta zapytania, które aktywuje intencje wbudowane (BII) lub intencje niestandardowe skonfigurowane dla na potrzeby realizacji widżetu.

Jednoznaczne wywołanie

Aby jawnie wywołać widżety dla dowolnej zainstalowanej aplikacji, użytkownicy mogą poprosić Asystenta na przykład:

• „OK Google, pokaż widżet PrzykładowaAplikacja”.
• „Widżety z aplikacji ExampleApp”.

Asystent wyświetla te widżety wraz z ogólnym wprowadzeniem: „PrzykładowaAplikacja oto widżet”. Asystent natywnie zwraca widżety żądane w w ten sposób bez konieczności wykonywania przez dewelopera aplikacji żadnych działań, ta metoda wywołania wymaga od użytkownika wyraźnej wiedzy na temat widżetu, aby można było go wysłać. Do uprość wykrywanie widżetów, użyj metody realizacji intencji omówionej w w następnej sekcji.

Realizacja intencji

Ułatw znalezienie widżetów, używając ich do zapytań, których język użytkownik używa w Asystencie. Możesz na przykład zwrócić zapytanie za każdym razem, gdy użytkownik wywoła GET_EXERCISE_OBSERVATION BII w Twoim do fitnessu, pytając: „OK Google, ile mil udało mi się przebiec w tym tygodniu PrzykładowaAplikacja? Poza uproszczeniem odkrywania treści integrujemy widżety z Akcje w aplikacji oferują te zalety:

• Dostęp do parametrów: Asystent udostępnia wyodrębnione parametry intencji. z zapytania użytkownika do widżetu, dostosowanych odpowiedzi.
• Niestandardowe wprowadzenie do zamiany tekstu na mowę: możesz dodać ciąg tekstowy do zamiany tekstu na mowę. aby Asystent informował o tym podczas wyświetlania widżetu.
• Przypinanie widżetu: Asystent wyświetla przycisk Dodaj ten widżet obok widżet, dzięki czemu użytkownicy mogą je łatwo przypiąć do programu uruchamiającego.

Wdrażanie realizacji widżetów

Aby wdrożyć realizację widżetów na potrzeby intencji, wykonaj te czynności:

1. Zaimplementuj widżet na Androida, wykonując czynności opisane w Utwórz prosty widżet.
2. W pliku zasobów shortcuts.xml aplikacji dodaj komponent <app-widget> do możliwości zawierających szczegóły realizacji i tagi BII <parameter>. Zaktualizuj widżet do obsługi parametrów.
3. Dodaj wymaganą bibliotekę rozszerzeń widżetów, która umożliwia Asystent przekazuje do widżetów nazwy i parametry BII. Umożliwia też wprowadzenie niestandardowych funkcji zamiany tekstu na mowę i przypinanie widżetów funkcji.

W poniższej sekcji opisano schemat <app-widget> dla shortcuts.xml.

Schemat widżetu

Elementy <app-widget> są zdefiniowane jako zrealizowane w obrębie kategorii elementy <capability> w elemencie shortcuts.xml. Wymagają: atrybutów, chyba że oznaczono je jako opcjonalne:

Opis schematu widżetu

<widżet-aplikacji>

Element realizacji widżetu najwyższego poziomu.

Atrybuty:

• android:identifier: identyfikator realizacji. Ta wartość musi musi być niepowtarzalna w całej realizacji <app-widget> i <intent> elementów zdefiniowanych w obrębie <capability>.
• android:targetClass: pełna nazwa zajęć związanych z zajęciami AppWidgetProvider na do obsługi intencji.

<parametr>

Mapuje parametr BII na wartość intencji <parameter>. Możesz zdefiniować zero lub więcej parametrów dla każdego elementu <app-widget>. Podczas realizacji zamówienia Asystent przekazuje parametry, aktualizując dodatki instancji widżetu w postaci par klucz-wartość, w tym formacie:

• Klucz: android:key zdefiniowany dla parametru.
• Wartość: wartość, którą BII wyodrębnia z poleceń głosowych użytkownika.

Aby uzyskać dostęp do tych dodatkowych treści, zadzwoń pod numer getAppWidgetOptions() na powiązanym AppWidgetManager, który zwraca obiekt Bundle zawierający nazwę wyzwalający BII i jego parametry. Zobacz Wyodrębnij wartości parametrów, aby uzyskać szczegóły.

Więcej informacji o dopasowywaniu parametrów BII znajdziesz tutaj Dane i dopasowanie parametrów

<ekstra>

Opcjonalny tag deklarujący, że używane jest niestandardowe wprowadzenie do zamiany tekstu na mowę ten widżet. Ten tag wymaga następujących wartości atrybutów:

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

Kod demonstracyjny

Poniższy przykład z pliku shortcuts.xml przedstawia widżet dla konfiguracji realizacji zamówienia Zdolność 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>

Możesz określić wiele elementów <app-widget> lub użyć ich kombinacji <app-widget> i <intent> elementów na możliwość. Takie podejście pozwala zapewniają spersonalizowane wrażenia na podstawie różnych kombinacji parametrów; udostępniane przez użytkowników. Na przykład jeśli użytkownik nie wskaże lokalizacji wyjazdu w zapytaniu, możesz skierować tę osobę do aktywności w aplikacji, która pokazuje: ustawień miejsc odbioru i dostawy. Zobacz Intencje zastępcze. o definiowaniu intencji zastępczych.

Wyodrębnianie wartości parametrów

W poniższej przykładowej klasie AppWidgetProvider funkcja prywatna updateAppWidget() służy do wyodrębniania nazwy i parametrów BII z opcje widżetu 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>