App-Aktionen in Android-Widgets einbinden

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

}

Stilempfehlungen für Text-in-Sprache

Verwenden Sie die folgenden Stilempfehlungen, um Ihre benutzerdefinierten Widget-Einführungen für Sprachausgabe und angezeigte Aufforderungen zu optimieren.

Bildschirm anpinnen

Mit der Widgets-Erweiterungsbibliothek kann die Schaltfläche Dieses Widget hinzufügen zusammen mit deinem Widget in Assistant angezeigt werden. Fügen Sie AndroidManifest.xml die folgende Empfängerdefinition hinzu, um das Anpinnen zu aktivieren:

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

Inventarverfügbarkeit

BI-Lösungen, die Inline-Inventar oder Webinventar unterstützen, können diese Inventare auf Ihre Widget-Auftragsausführungen ausweiten.

Inline-Inventar

Der folgende Code aus einer shortcuts.xml-Beispieldatei veranschaulicht eine START_EXERCISE-BII-Funktion, die für Inline-Inventar- und Widget-Auftragsausführung konfiguriert ist:

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

Wenn ein Nutzer im vorherigen Beispiel diese Funktion auslöst, indem er Assistant "Start running with ExampleApp" fragt, enthält das Option Bundle für die <app-widget>-Auftragsausführung das folgende Schlüssel/Wert-Paar:

• Schlüssel = “exerciseName”
• Wert = “RunningShortcut”

Webinventar

Der folgende Code aus einer Beispieldatei shortcuts.xml zeigt eine Funktion, die für Webinventar und Widget-Auftragsausführung aktiviert wird:

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

Test-App-Aktionen

Mit dem App Actions-Testtool, einer Funktion des Google Assistant-Plug-ins für Android Studio, können Sie Widgets auf einem physischen oder virtuellen Gerät testen. So verwenden Sie das Testtool:

1. Verbinden Sie das Testgerät mit der ausgeführten App.
2. Rufen Sie in Android Studio Tools > App Actions > App Actions Test Tool auf.
3. Klicken Sie auf Vorschau erstellen.
4. Führen Sie Ihre App mit Android Studio auf Ihrem Testgerät aus.
5. Verwenden Sie die Assistant App auf Ihrem Testgerät, um die App-Aktion zu testen. Sie können zum Beispiel sagen: „Hey Google, wie viele Kilometer habe ich diese Woche mit der BeispielApp gelaufen?“
6. Beobachte das Verhalten deiner App oder verwende den Android Studio-Debugger, um das gewünschte Aktionsergebnis zu prüfen.

Qualitätsrichtlinien

In diesem Abschnitt werden die wichtigsten Anforderungen und Best Practices für die Einbindung von App-Aktionen in Widgets erläutert.

Inhalt in Widgets

• (Erforderlich) Schalten Sie in Ihren Widgets keine Anzeigen.
• Widget-Inhalte vollständig auf die Erfüllung des Intents konzentrieren. Versuchen Sie nicht, mehrere Intents mit einem Widget zu erfüllen oder irrelevante Inhalte hinzuzufügen.

Authentifizierung

• (Erforderlich) Wenn eine Nutzerauthentifizierung erforderlich ist, um einen Nutzerfluss abzuschließen, geben Sie ein Widget zurück, das erklärt, dass der Nutzer mit der App fortfahren muss. Die Inline-Nutzerauthentifizierung in Google Assistant wird für App-Aktionen nicht unterstützt.
• Wenn Nutzer zulassen, dass Ihre App Daten über Widgets anzeigt, können Sie zur Laufzeit ein Fehler-Widget für nicht autorisierte Nutzer zurückgeben.

Fallback-Intents

• (Erforderlich) Geben Sie in Ihrem shortcuts.xml neben der Widget-Auftragsausführung für eine bestimmte Funktion immer eine Fallback-<intent> an. Ein Fallback-Intent ist ein <intent>-Element ohne erforderliche <parameter>-Werte.

  Dadurch kann Assistant eine Aktion ausführen, wenn die Nutzerabfrage keine Parameter enthält, die von den anderen in der Funktion definierten Ausführungselementen benötigt werden. Die Ausnahme bildet, wenn für diese Funktion keine Parameter erforderlich sind. In diesem Fall wird nur die Widget-Auftragsausführung benötigt.

• Verwenden Sie den Fallback-Intent, um Ihre App auf dem relevanten Bildschirm zu öffnen, nicht auf dem Startbildschirm.

Der folgende Code aus einer shortcuts.xml-Beispieldatei veranschaulicht eine <capability> mit einem Fallback-<intent>, der eine primäre <app-widget>-Auftragsausführung unterstützt:

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

Offenlegung von Google Play-Daten

In diesem Abschnitt werden die Endnutzerdaten aufgeführt, die von der neuesten Version der Widgets-Erweiterungsbibliothek erfasst wurden.

Dieses SDK sendet vom Entwickler bereitgestellte Sprachausgabe-Antworten, die dem Nutzer von Google Assistant mithilfe der Sprachtechnologie von Assistant angesagt werden. Diese Informationen werden nicht von Google gespeichert.

App-Aktionen können Metadaten auch zu folgenden Zwecken erfassen:

• Sie können die Akzeptanzraten verschiedener SDK-Versionen im Blick behalten.
• Die Nutzung von SDK-Funktionen in Apps quantifizieren