App-Aktionen in Android-Widgets einbinden

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

Für viele Intents besteht die beste Reaktion darin, eine einfache Antwort zu geben, oder schnelle interaktive User Experience bieten. Sie können eine Android-App-Widget in Google Assistant für diese Art von Intents.

In diesem Leitfaden erfahren Sie, wie Assistant-Anfragen mithilfe von Widgets ausgeführt werden können und wie Sie Verbessere mit App Actions deine Widget-Nutzung für Assistant Widgets-Erweiterungsbibliothek

Vorteile

Widgets sind kleine App-Ansichten, die auf Android-Geräten eingebettet werden können. wie dem Launcher oder Sperrbildschirm. Mit App Actions können Sie die Auswirkungen Ihrer Widgets, indem Sie sie zur Anzeige in Assistant freigeben:

1. Erkennung:Widgets werden proaktiv als Reaktion auf die Abfragen in natürlicher Sprache.
2. Interaktion:Widgets werden angezeigt, wenn Nutzer die App per Sprachbefehl bedienen, z. B. wenn sie die App verwenden Assistant zeigt persönliche Ergebnisse auf dem Sperrbildschirm an und an Android Auto
3. Bindung:Lassen Sie Nutzer die Widgets anpinnen, die in Assistant zu ihrem Launcher Für die Funktion zum Anpinnen ist das Widgets-Erweiterungsbibliothek

So zeigt Assistant Widgets an

Es gibt zwei Möglichkeiten, wie Nutzer Widgets in Assistant aufrufen können:

• Ausdrückliche Anforderung eines Widgets anhand des Namens.
• Eine Anfrage an Assistant wird gesendet, Integrierter Intent (BII) oder benutzerdefinierter Intent, der für Widget-Ausführung.

Expliziter Aufruf

Um Widgets für installierte Apps explizit aufzurufen, können Nutzer Assistant fragen Dinge wie:

• „Hey Google, zeig mir das ExampleApp-Widget.“
• „Widgets aus ExampleApp.“

Assistant zeigt diese Widgets mit der allgemeinen Einführung an: „BeispielApp“ sagt: Hier ist ein Widget.“ Assistant gibt dagegen Widgets zurück, die in ohne dass der App-Entwickler etwas dafür tun muss, wird diese Aufrufmethode setzt voraus, dass der Nutzer das Widget explizit kennt, um es anfordern zu können. Bis die Widget-Erkennung zu vereinfachen, verwenden Sie die in der nächsten Abschnitt.

Intent-Ausführung

Damit Ihre Widgets leichter zu finden sind, Sprachanfragen, die Nutzer in Assistant ausführen. Sie können beispielsweise wenn ein Nutzer den BII GET_EXERCISE_OBSERVATION in Ihrem mit der Frage: „Hey Google, wie viele Kilometer bin ich diese Woche gelaufen?“ BeispielApp?“ Die Integration von Widgets mit App Actions bietet folgende Vorteile:

• Parameterzugriff:Assistant stellt die extrahierten Intent-Parameter bereit. von der Nutzeranfrage an Ihr Widget, individuelle Antworten.
• Benutzerdefinierte Einführung in Text-in-Sprache:Sie können einen Text-in-Sprache-String angeben. die Assistant bei der Anzeige deines Widgets ankündigt.
• Widget-Anpinnen:In der Nähe von Assistant wird die Schaltfläche Widget hinzufügen angezeigt. Ihr Widget, sodass Nutzer Ihre Widgets ganz einfach an ihren Launcher anpinnen können.

Widget-Ausführung implementieren

So implementieren Sie die Widget-Auftragsausführung für Ihre Intents:

1. Implementieren Sie ein Android-Widget, indem Sie die Schritte ausführen unter Erstellen Sie ein einfaches Widget.
2. Fügen Sie in der Ressourcendatei shortcuts.xml Ihrer App ein <app-widget>-Element zu Ihrer Fähigkeit, Details zur Ausführung und BII-Tags <parameter> Aktualisieren Sie Ihr um die Parameter zu handhaben.
3. Fügen Sie die erforderliche Widgets-Erweiterungsbibliothek hinzu, mit der Sie Assistant übergibt BII-Namen und -Parameter an deine Widgets. Außerdem können Sie damit individuelle Einführungen und Widget-Anpinnen Funktionalität.

Im folgenden Abschnitt wird das <app-widget>-Schema für shortcuts.xml beschrieben.

Widget-Schema

<app-widget>-Elemente sind als Ausführungen im <capability>-Elemente in shortcuts.xml. Folgende Voraussetzungen müssen erfüllt sein: , sofern nicht als optional angegeben:

Widget-Schemabeschreibung

<app-widget>

Widget-Auftragsausführungselement der obersten Ebene.

Attribute:

• android:identifier: die Kennung für diese Auftragsausführung. Dieser Wert muss darf in der Auftragsausführung von <app-widget> und <intent> eindeutig sein -Elementen, die in einem <capability> definiert sind.
• android:targetClass: der vollständige Klassenname von AppWidgetProvider für mit der Absicht umgehen.

<Parameter>

Ordnet einen BII-Parameter einem <parameter>-Wert des Intents zu. Sie können 0 oder 1 weitere Parameter für jedes <app-widget>-Element. Während der Auftragsausführung Parameter übergeben, indem die Extras für die Widget-Instanz als Schlüssel/Wert-Paare aktualisiert werden, im folgenden Format:

• Schlüssel: der für den Parameter definierte android:key
• Wert: Der Wert, den der BII aus der Spracheingabe eines Nutzers extrahiert.

Du kannst auf diese Extras zugreifen, indem du getAppWidgetOptions() auf dem zugehörigen AppWidgetManager-Objekt, das ein Bundle-Objekt mit dem Namen den auslösenden BII und seine Parameter. Weitere Informationen finden Sie unter Extrahieren Sie Parameterwerte, um Details zu erhalten.

Weitere Informationen zum BII-Parameterabgleich finden Sie unter Parameterdaten und Abgleich:

<Extra>

Optionales Tag, das angibt, dass eine benutzerdefinierte Text-in-Sprache-Einführung verwendet wird dieses Widgets. Für dieses Tag sind folgende Attributwerte erforderlich:

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

Beispielcode

Im folgenden Beispiel aus einer shortcuts.xml-Datei wird ein Widget veranschaulicht: Konfiguration der Auftragsausführung für ein BII-Funktion von 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>

Sie können mehrere <app-widget>-Elemente angeben oder eine Kombination aus <app-widget>- und <intent>-Elemente pro Funktion. Mit diesem Ansatz können Sie bieten ein individuelles Erlebnis basierend auf verschiedenen Kombinationen von Parametern die von den Nutzenden bereitgestellt werden. Beispiel: Wenn der Nutzer keinen Rückgabeort angibt können Sie sie auf die Aktivität in Ihrer App verweisen, zum Festlegen der Abhol- und Abgabeorte. Weitere Informationen finden Sie in der Weitere Informationen finden Sie im Abschnitt Fallback-Intents. Definition von Fallback-Intents.

Parameterwerte extrahieren

In der folgenden Beispielklasse AppWidgetProvider hat die private Funktion Mit updateAppWidget() werden der BII-Name und die Parameter aus dem Widget-Optionen 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>