Android-Apps mit App Actions auf Google Assistant erweitern (Level 2)

1. Übersicht

Mit App Actions können Nutzer direkt über Google Assistant bestimmte App-Funktionen starten. So können Sie die Reichweite Ihrer Android-App erhöhen. Als Android-Entwickler können Sie Funktionen implementieren, mit denen Google Assistant weiß, welche Art von Funktionen für Nutzer verfügbar sind und wie Sie diese Anfragen erfüllen möchten.

Im ersten App Actions-Codelab haben Sie gelernt, wie Sie Google Assistant auf eine Beispiel-Fitness-App ausweiten, indem Sie integrierte Intents (BIIs) aus der BII-Kategorie „Gesundheit und Fitness“ implementieren. BIIs sind in Kategorien unterteilt, die die Arten von Aufgaben darstellen, die Nutzer häufig vom Assistant ausführen lassen.

Schlüsselbegriff: Ein integrierter Assistant-Intent, kurz BII, ist ein vordefinierter Trigger für eine bestimmte Art von Funktion, die der Nutzer ausführen möchte. Google entwickelt und pflegt die Sprachmodelle für BIIs, damit eine Vielzahl von Anfragen, die sich auf diesen bestimmten Intent beziehen, verstanden werden können.

In diesem Codelab erfahren Sie, wie Sie einer App App Actions hinzufügen. Dazu verwenden Sie BIIs aus der BII-Kategorie „Common“, die für häufige App-Aufgaben steht, die in fast jeder Android-App ausgeführt werden können.

In diesem Codelab werden Konzepte für die Entwicklung mit App Actions für Fortgeschrittene behandelt. Sie sollten bereits Erfahrung mit der Entwicklung von Android-Apps und der Implementierung von Android-Intents haben.

Aufgaben

In diesem Codelab fügen Sie einer Beispiel-App für To-do-Listen zwei Common BIIs hinzu, damit Nutzer Assistant bitten können, Folgendes zu tun:

• Mit dem BII actions.intent.OPEN_APP_FEATURE können Sie in der App zu Funktionen navigieren.
• Mit dem BII actions.intent.GET_THING können Nutzer in Ihrer App nach Inhalten suchen.

Hinweis:Apps mit Suchfunktion müssen den BII actions.intent.GET_THING implementieren. Weitere Informationen zu den Bereitstellungsanforderungen für App Actions

Abbildung 1. Drei progressive Bildschirme, auf denen Google Assistant aktive Aufgaben in einer App anzeigt.

Lerninhalte

Sie erfahren, wie Sie BIIs für allgemeine Kategorien verwenden, um Assistant auf die meisten Android-Apps auszuweiten. Außerdem erfahren Sie, wie Sie allgemeine BIIs mit dem Google Assistant-Plug-in für Android Studio testen.

Vorbereitung

• Ein Terminal zum Ausführen von Shell-Befehlen mit installiertem Git.
• Die aktuelle stabile Version von Android Studio.
• Ein physisches oder virtuelles Android-Gerät mit Internetzugang zum Google Play Store, um Ihre Aktionen zu testen.
• Sie müssen mit demselben Google-Konto in Android Studio und sowohl in der Google App als auch in der Google Assistant App auf Ihrem Testgerät angemeldet sein.

Hinweis:Sie können die in diesem Codelab beschriebenen App Actions mit Google Assistant in einer begrenzten Anzahl von Sprachen testen. In der Referenzdokumentation zu allgemeinen BIIs finden Sie Informationen dazu, welche Intents je nach Sprache verfügbar sind.

In diesem Codelab verwenden Sie ein Android-Gerät (physisch oder virtuell), um Ihre Aktionen zu testen. Wenn Sie ein physisches Gerät verwenden, muss es mit Ihrem lokalen Entwicklungscomputer verbunden sein. Außerdem müssen Sie auf dem Gerät in der Google App und in Android Studio mit demselben Google-Konto angemeldet sein. Auf dem Gerät muss außerdem die Google Assistant App installiert sein.

2. Funktionsweise

Mit App Actions werden Nutzer von Google Assistant zu Ihrer Android-App weitergeleitet. Aber wie funktioniert das?

Wenn ein Nutzer Assistant mitteilt, dass er Ihre App verwenden möchte, sucht Assistant in einer shortcuts.xml-Datei nach App Actions, die für Ihre App registriert sind. Diese Datei enthält die Funktionen der App, die eine integrierte oder benutzerdefinierte Assistant-Intention mit einer Android-Intention oder einem Deeplink verknüpfen.

Schlüsselbegriff: Funktionen sind Vorlagen, die Sie in shortcuts.xml definieren, um die Arten von Aktionen zu deklarieren, mit denen Nutzer Ihre App starten und direkt zu einer bestimmten Aufgabe springen können. Weitere Informationen finden Sie in der Android-Dokumentation zu Funktionen.

Wenn ein Nutzer eine Anfrage an Assistant richtet, wird die Eingabe des Nutzers von Assistant analysiert und einem App Actions-Intent zugeordnet (in diesem Codelab ist das ein integrierter Intent). Assistant weiß anhand der shortcuts.xml-Datei in Ihrer Android-App, welche Funktionen Sie unterstützen. Mit dem Intent-Abgleich enthält die Funktion mit diesem BII Informationen dazu, wie Sie diese Anfrage erfüllen möchten. In diesem Codelab ist die Ausführung ein Android-Intent, der eine Aktivität in Ihrer App startet.

Das folgende Diagramm zeigt diesen Assistant-Ablauf:

Abbildung 2. Ein Ablauf, der beschreibt, wie Google Assistant eine gesprochene Anfrage verarbeitet.

Die Projektdatei shortcuts.xml enthält die folgenden Informationen für jede App Action:

• Welchen integrierten oder benutzerdefinierten Intent die App Action verwendet
• Welche Android-Aktivität oder welcher Deeplink für den Nutzer bereitgestellt werden soll
• Wie Parameter für den integrierten Intent Informationen zuordnen, die der Nutzer Assistant zur Verfügung stellt

Ihre Android-Aktivität filtert dann nach dem bereitgestellten Android-Intent oder Deeplink und verarbeitet ihn, um dem Nutzer die gewünschte Funktion bereitzustellen. Das Ergebnis ist eine Nutzererfahrung, bei der Assistant die Funktionen Ihrer App als Reaktion auf die Anfrage eines Nutzers aufruft.

3. Bereiten Sie Ihre Entwicklungsumgebung vor

In diesem Codelab wird die Beispiel-App „To-do list“ für Android verwendet. Mit dieser Beispiel-App können Sie Elemente zu To-do-Listen hinzufügen, nach Elementen nach Kategorie suchen und Informationen zu erledigten Aufgaben aufrufen.

Basisdateien herunterladen

Führen Sie den folgenden Befehl aus, um das GitHub-Repository der Beispiel-App zu klonen:

git clone --branch codelab-start https://github.com/actions-on-google/appactions-common-biis-kotlin.git

Nachdem Sie das Repository geklont haben, gehen Sie so vor, um es in Android Studio zu öffnen:

1. Klicken Sie im Dialogfeld Welcome to Android Studio auf Import project.
2. Suchen Sie den Ordner, in den Sie das Repository geklont haben, und wählen Sie ihn aus.

Wenn Sie eine Version der App sehen möchten, die dem abgeschlossenen Codelab entspricht, klonen Sie das Beispiel-App-Repository mit dem Flag --branch master.

Android-App-ID aktualisieren

Durch das Aktualisieren der Anwendungs-ID der App wird die App auf Ihrem Testgerät eindeutig identifiziert. Außerdem wird der Fehler „Doppelter Paketname“ vermieden, wenn die App in die Play Console hochgeladen wird. So aktualisieren Sie die Anwendungs-ID:app/build.gradle

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

Ersetzen Sie „MYUNIQUENAME“ im Feld applicationId durch einen eindeutigen Namen.

Hinweis: Nach dem Aktualisieren von applicationId wird in Android Studio die Warnung „Gradle files have changed since last project sync...“ (Gradle-Dateien haben sich seit der letzten Projektsynchronisierung geändert) angezeigt. Klicken Sie auf Jetzt synchronisieren, um Probleme beim Hochladen Ihrer App zu vermeiden.

App auf Ihrem Gerät testen

Bevor Sie weitere Änderungen an der App vornehmen, sollten Sie sich ansehen, was die Beispiel-App kann. So führen Sie die App auf Ihrem Emulator aus:

1. Wählen Sie in Android Studio Run > Run app (Ausführen > App ausführen) aus oder klicken Sie in der Symbolleiste auf Run.
2. Wählen Sie im Dialogfeld Bereitstellungsziel auswählen ein Gerät aus und klicken Sie auf OK. Die empfohlene Betriebssystemversion ist Android 10 (API-Level 30) oder höher. Aktionen werden jedoch auch auf Geräten mit Android 5 (API-Level 21) ausgeführt.
3. Halte die Startbildschirmtaste gedrückt, um Assistant einzurichten und zu prüfen, ob sie funktioniert. Sie müssen sich auf Ihrem Gerät in Assistant anmelden, falls Sie das noch nicht getan haben.

Weitere Informationen zu virtuellen Android-Geräten finden Sie unter Virtuelle Geräte erstellen und verwalten.

Abbildung 3: Eine Animation, die die Beispiel-App für To‑do-Listen zeigt.

Sehen Sie sich die App kurz an, um zu sehen, was sie kann. Wenn Sie auf das Pluszeichen tippen, wird ein neues Aufgabenelement erstellt. Über die Menüelemente oben rechts können Sie nach Aufgabenelementen suchen und sie nach Abschlussstatus filtern.

Test-Plug-in installieren

Mit dem Google Assistant-Plug-in können Sie Ihre App Actions auf einem Testgerät testen. Wenn Sie das Testtool noch nicht haben, installieren Sie es so:

1. Klicken Sie auf Datei > Einstellungen (unter MacOS auf Android Studio > Einstellungen).
2. Rufen Sie im Bereich „Plugins“ den Marketplace auf und suchen Sie nach „Google Assistant“. Sie können das Testtool auch manuell herunterladen und installieren.
   • Wenn Sie das Plug-in nicht im Marketplace finden, können Sie es manuell herunterladen und der Anleitung unter Plug-in von der Festplatte installieren folgen.
3. Installieren Sie das Tool und starten Sie Android Studio neu.

Hinweis:Das Test-Plug-in sendet Informationen über die Google App auf Ihrem Android-Gerät an Assistant.

4. BII-Funktion „Get Thing“ hinzufügen

Mit dem BII actions.intent.GET_THING wird die In‑App-Suchfunktion auf Google Assistant ausgeweitet. In diesem Schritt implementieren und testen Sie den BII GET_THING, damit Nutzer in der Beispiel-App nach bestimmten Aufgaben suchen können.

Tipp:Mit dem BII GET_THING wird in einer App mit der standardmäßigen In‑App-Suchfunktion nach Inhalten oder Einheiten gesucht. Füllen Sie die Suchkriterien mit dem Namen des Inhalts oder der Einheit mithilfe des Intent-Parameters thing.name aus und präsentieren Sie dem Nutzer die relevantesten Suchergebnisse.

„Get Thing“-Funktion definieren

Bei einer suchbezogenen App Action extrahiert Assistant Suchbegriffe aus der Nutzeranfrage in den BII-Parameter thing.name und übergibt diesen Wert dann an die Android-Anwendung.

Wenn Sie das GET_THING-BII in Ihre App einfügen möchten, aktualisieren Sie shortcuts.xml im Beispielprojektverzeichnis app/src/main/res/xml mit einem <capability>-Element innerhalb des <shortcuts>-Tags der obersten Ebene:

shortcuts.xml

<shortcuts ....>
    <capability android:name="actions.intent.GET_THING">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.yourApplicationId.appaction"
            android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
            <parameter
                android:name="thing.name"
                android:key="q"/>
        </intent>
    </capability>
</shortcuts>

Die obige Konfiguration:

1. Gibt an, dass die App auf die BII GET_THING reagiert.
2. Gibt an, wie ein Android-Intent erstellt wird, der die App als Reaktion auf diesen BII startet.
   • Die Aktivität wird anhand von targetPackage und targetClass identifiziert.
   • Der BII-Parameter thing.name wird dem Intent Extra mit dem Namen q zugeordnet.

Die benannte Aktivität muss im Manifest der App vorhanden und exportiert sein.

Die bereitgestellte Android-Anwendung enthält Metadaten, sodass die shortcuts.xml-Datei in der AndroidManifest-Datei angegeben ist:

<meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />

App Action testen

So testen Sie die In-App-Suche für Ihre App über Assistant:

1. Achte darauf, dass dein Android-Gerät verbunden ist.
2. Klicken Sie auf Tools > Google Assistant > App Actions Test Tool (Tools > Google Assistant > App Actions Test Tool).
3. Klicken Sie auf Vorschau erstellen, um die Standardwerte für App-Name und Gebietsschema zu übernehmen. Lesen und akzeptieren Sie die Richtlinien und Nutzungsbedingungen für App Actions, wenn Sie dazu aufgefordert werden.
4. Wählen Sie im ersten Schritt, in dem Sie aufgefordert werden, ein BII auszuwählen und zu konfigurieren, actions.intent.GET_THING aus. Ändern Sie den Wert name von running shoes in milk.
5. Klicken Sie auf App-Aktion ausführen.

In diesem Test verwendet die GET_THING-BII das Attribut name, um in der App nach Aufgaben zu suchen, die „Milch“ enthalten. Wie bei der vorherigen App Action können Sie Ihre Action mit dem Testtool testen oder auf Ihrem Testgerät einfach Hey Google, suche in der Aufgabenliste nach Backmischung oder andere Suchanfragen sagen.

Tipp:Wenn beim Ausführen des Testtools Probleme auftreten, finden Sie hier eine Anleitung zur Fehlerbehebung.

5. BII-Funktion „App öffnen“ hinzufügen

In diesem Schritt implementieren Sie den Open app feature BII, damit Nutzer sich ihre aktiven und erledigten Aufgaben über Assistant ansehen können. Führen Sie dazu die Funktion in shortcuts.xml aus. Dort finden Sie Informationen dazu, wie die Funktion ausgelöst wird, wie Parameter übergeben werden und welche Android-Intents aufgerufen werden. In diesem Codelab verwenden Sie OPEN_APP_FEATURE BII. Nachdem Sie dieses BII implementiert haben, testen Sie die Aktion auf Ihrem Gerät.

Hinweis:Mit diesem BII wird eine Funktion der App gestartet. Dieser Intent ist besonders nützlich, um Nutzern zu helfen, zu Funktionen in Ihrer App zu navigieren, die sonst schwer zu finden sind oder mehrere Tippvorgänge erfordern. Sie müssen inline inventory für den Funktionsparameter angeben.

Funktion „App öffnen“ hinzufügen

Fügen Sie unter dem Element „Get Thing Capability“ eine zweite Funktion für das Feature „App öffnen“ in shortcuts.xml hinzu:

shortcuts.xml

<capability android:name="actions.intent.OPEN_APP_FEATURE">
   <intent
       android:action="android.intent.action.VIEW"
       android:targetPackage="yourApplicationId"
       android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
       <parameter
           android:name="feature"
           android:key="feature"/>
   </intent>
</capability>

Diese Funktion ordnet den BII für die Funktion „App öffnen“ und den Android-Intent einander zu. Wenn die Funktion „App öffnen“ ausgelöst wird, wird also auch der Android-Intent ausgelöst.

Bevor der Android-Intent ausgelöst wird, werden unterstützte Parameter aus der Eingabe des Nutzers abgerufen. Das OPEN_APP_FEATURE-BII unterstützt einen Parameter, feature, der die aus der Nutzeranfrage extrahierte App-Funktion darstellt. Diese Anwendung unterstützt zwei Arten von Funktionen: „Aktive Aufgabe“ und „Abgeschlossene Aufgabe“. Mit diesen Funktionen können Nutzer die App mit einer gefilterten Ansicht ihrer Aufgabenliste öffnen. Sie müssen Inline-Inventar verwenden, um diese Funktionen zu unterstützen.

Schlüsselbegriff: Ein Inline-Inventar führt die Extraktion von Entitäten für BIIs an, indem es eine Reihe von Entitäten für einen BII-Parameter bereitstellt, der Inline-Inventar unterstützt. Weitere Informationen finden Sie unter Inline-Inventar für App Actions.

Intent-Parameter mit Inline-Inventar verarbeiten

Intent-Parameter stellen die Elemente dar, die aus einer Nutzeranfrage extrahiert werden. Wenn ein Nutzer beispielsweise Hey Google, bestelle eine Pizza über Beispiel-App sagt, extrahiert Assistant „Pizza“ in einen food.item-Intent-Parameter des schema.org-Schemas und übergibt den Parameter an Ihre Aktion zur Verarbeitung.

Das BII für die Funktion „App öffnen“ unterstützt einen Parameter, feature, der die aus der Nutzeranfrage extrahierte App-Funktion darstellt. Für diesen Parameter ist ein Inline-Inventar erforderlich, das Assistant eine Reihe unterstützter App-Funktionsnamen zur Verfügung stellt, mit denen der Parameterwert abgeglichen werden kann.

Wenn Sie den Intent-Parameter feature verarbeiten möchten, fügen Sie Ihrem shortcuts.xml mit dem folgenden Code über der Funktion „App öffnen“ eine Verknüpfung hinzu:

shortcuts.xml

<shortcut
   android:shortcutId="active_tasks"
   android:shortcutShortLabel="@string/label_active"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/active_tasks_synonyms" />
   </capability-binding>
</shortcut>

<shortcut
   android:shortcutId="completed_tasks"
   android:shortcutShortLabel="@string/label_completed"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/completed_tasks_synonyms" />
   </capability-binding>
</shortcut>

Im obigen Code haben Sie ein Inline-Inventar definiert, das als shortcut-Elemente mit Funktions- und Parameterbindungen dargestellt wird. Tastenkombinationen können als Inventar für BII-Parameter verwendet werden. Google Assistant gleicht die Nutzeranfrage mit den Werten in der Parameterbindung von Shortcuts ab. Bei einem übereinstimmenden Parameterwert wird der shortcutId dem Intent für die Auftragsausführung hinzugefügt. Wenn ein Nutzer den BII OPEN_APP_FEATURE mit einer Anfrage aktiviert, gleicht Assistant den Wert des Funktionsparameters mit dem Wertattribut einer Verknüpfung ab und übergibt den Wert als parameter in Extra an targetClass.

Wenn ein Nutzer beispielsweise Hey Google, zeig mir meine erledigten Aufgaben in BeispielApp sagt, gleicht Assistant den Parameterwert des Feature-Intents „erledigte Aufgaben“ mit der entsprechenden Inventarkürzel ab und übergibt diesen Wert an die OPEN_APP_FEATURE-Funktion. Assistant löst dann den Android-Intent aus.

App Action testen

Während der Entwicklung und beim Testen verwenden Sie das Google Assistant-Plug‑in, um sich eine Vorschau Ihrer App Action in Assistant auf einem Testgerät anzusehen. Sie können das Tool auch verwenden, um Intent-Parameter für eine App Action anzupassen und zu testen, wie Ihre Action die verschiedenen Möglichkeiten verarbeitet, mit denen ein Nutzer Assistant auffordern kann, sie auszuführen.

So testen Sie Ihre App Action mit dem Testtool:

1. Schließen Sie Ihr physisches Android-Testgerät an oder starten Sie Ihren Android-Emulator.
2. Wenn das Testtool nicht angezeigt wird, öffnen Sie es über Tools > Google Assistant > App Actions Test Tool (Tools > Google Assistant > App Actions Test Tool).
3. Klicken Sie auf die Schaltfläche Aktualisieren, um die Vorschau zu aktualisieren.
4. Wählen Sie im ersten Schritt, in dem Sie aufgefordert werden, ein BII auszuwählen und zu konfigurieren, actions.intent.OPEN_APP_FEATURE aus.
5. Aktualisieren Sie im Feld feature den Standardwert History mit Completed tasks.
6. Klicken Sie auf App-Aktion ausführen.

Tipp:Wenn beim Ausführen des Testtools Probleme auftreten, finden Sie hier eine Anleitung zur Fehlerbehebung.

Alternativ können Sie den Aufrufnamen direkt in der Assistant App auf Ihrem Gerät verwenden, um Ihre App Action auszuprobieren. Sie können zum Beispiel sagen: Hey Google, zeige erledigte Aufgaben in der Aufgabenliste an.

6. Nächste Schritte

Das wars!

Sie können jetzt fast jede Android-App mit Google Assistant verwenden, indem Sie gängige BIIs nutzen.

Behandelte Themen

In diesem Codelab haben Sie Folgendes gelernt:

• Nutzern ermöglichen, mit Assistant bestimmte App-Funktionen zu nutzen
• So können Nutzer über Assistant auf die In-App-Suche zugreifen.
• So testen Sie häufige BIIs mit dem Google Assistant-Plug-in.

Nächste Schritte

Von hier aus können Sie weitere Verbesserungen an Ihrer To-do-Liste vornehmen. Das fertige Projekt finden Sie auf GitHub im –master-Branch.

Hier sind einige Vorschläge, wie Sie diese App mit App Actions erweitern können:

• Beispiel für eine To-do-Liste mit Google Analytics for Firebase
• In der Referenz für integrierte Intents für App Actions finden Sie weitere Möglichkeiten, Ihre Apps für Assistant zu erweitern.

Wenn Sie Ihre Reise mit Actions on Google fortsetzen möchten, sehen Sie sich diese Ressourcen an:

• developers.google.com/assistant: Offizielle Dokumentationswebsite für Actions on Google.
• Beispielindex für App Actions: Beispiel-Apps und Code zum Erkunden der App Actions-Funktionen.
• Actions on Google-GitHub-Repository: Beispielcode und Bibliotheken.
• r/GoogleAssistantDev: Offizielle Reddit-Community für Entwickler, die mit Google Assistant arbeiten.

Folgen Sie uns auf Twitter unter @ActionsOnGoogle, um über unsere neuesten Ankündigungen auf dem Laufenden zu bleiben, und twittern Sie mit #AoGDevs, um zu teilen, was Sie entwickelt haben.

Feedbackumfrage

Füllen Sie zum Schluss bitte diese Umfrage aus, um Feedback zu diesem Codelab zu geben.