Android-Apps mit App Actions auf Google Assistant erweitern

1. Übersicht

Mit App Actions können Sie Google Assistant verwenden, um direkt zu App-Funktionen zu springen und Aufgaben per Sprachbefehl zu erledigen. Als Android-Entwickler implementieren Sie Capability-Elemente, um App Actions hinzuzufügen. Mithilfe von Funktionen kann Assistant erkennen, welche App-Funktionen Sprachbefehle von Nutzern unterstützen und wie diese Befehle ausgeführt werden sollen.

In diesem Codelab werden Konzepte für Anfänger für die Entwicklung mit App Actions behandelt. Für dieses Codelab sollten Sie bereits Erfahrung mit der Entwicklung von Android-Apps und Android-Intents haben. Wenn Sie neu bei Android sind, sollten Sie stattdessen mit einem der Codelabs für Android-Entwicklergrundlagen beginnen.

Aufgaben

In diesem Codelab fügen Sie einer Beispiel-Fitness-App für Android zwei integrierte Intents (Built-in Intents, BIIs) für App Actions hinzu, damit Nutzer einen Trainingstimer per Sprachbefehl starten und stoppen können.

Lerninhalte

Sie erfahren, wie Sie BIIs aus der Kategorie Gesundheit und Fitness verwenden, um Assistant auf eine Android-App auszuweiten. Außerdem lernen Sie, wie Sie das Google Assistant-Plug‑in für Android Studio verwenden, um Ihre BIIs zu testen.

Vorbereitung

Bevor Sie fortfahren, müssen Sie sicherstellen, dass die folgenden Tools in Ihrer Umgebung verfügbar sind:

  • Ein Terminal zum Ausführen von Shell-Befehlen mit installiertem git.
  • Die aktuelle Version von Android Studio.
  • Ein Google-Konto mit Zugriff auf die [Google Play Console][].
  • Ein physisches oder virtuelles Android-Gerät mit Internetzugang zum Play Store.

Bevor du fortfährst, musst du sicherstellen, dass du in Android Studio und der Google App auf deinem Testgerät mit demselben Google-Konto angemeldet bist.

2. Funktionsweise

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

Wenn ein Nutzer Assistant bittet, eine Aufgabe mit Ihrer App auszuführen, vergleicht Assistant seine Anfrage mit einem App Action-capability, das in der XML-Ressource shortcuts.xml Ihrer App definiert ist.

Ein Flussdiagramm, das zeigt, wie Google Assistant eine Sprachanfrage für App Actions verarbeitet

Abbildung 1. Ein Flussdiagramm, das zeigt, wie Assistant eine Sprachabfrage für App Actions verarbeitet.

Jedes Capability-Element definiert:

  • Ein Intent: Der Voice-Intent für App Actions, der die Funktion auslösen soll.
  • Mindestens eine Ausführung: Android-Intents oder Deeplinks, die Assistant generiert, um die App zu starten und die Sprachanfrage des Nutzers auszuführen. In Fulfillment-Definitionen wird angegeben, welche Parameter von der Nutzeranfrage erwartet werden und wie diese Parameter in die Startanweisungen codiert werden sollen.

Intents

In Natural Language Understanding (NLU) ist ein Intent eine Gruppe von Nutzerformulierungen mit ähnlicher Bedeutung. Google hat Dutzende von integrierten Intents (Built-in Intents, BIIs) für App Actions entwickelt, die eine Vielzahl von Anfragetypen abdecken. Assistant ist beispielsweise darauf trainiert, die Formulierungen „Bestell eine Pizza“ oder „Zeig mir die Dessertkarte“ mit dem BII ORDER_MENU_ITEM zu verknüpfen. Mit App Actions können Sie diese BIIs nutzen, um häufige Sprachanfragen schnell auf App-Funktionen zu erweitern.

Auftragsausführungen

Wenn eine Nutzeranfrage eine App Action in shortcuts.xml auslöst, muss Ihre Android-Aktivität den eingehenden Android-Intent oder Deeplink erkennen und verarbeiten und dem Nutzer die gewünschte Funktion bereitstellen. Das Ergebnis ist eine sprachgesteuerte Benutzeroberfläche, bei der Assistant Ihre App als Reaktion auf die Anfrage eines Nutzers aufruft.

3. Bereiten Sie Ihre Entwicklungsumgebung vor

In diesem Codelab wird die Fitness-Beispiel-App für Android verwendet. Mit dieser App können Nutzer einen Trainingstimer starten und beenden und Statistiken zu ihren Trainingsroutinen ansehen.

Basisdateien herunterladen

Wenn Sie die Basisdateien für dieses Codelab abrufen möchten, führen Sie den folgenden Befehl aus, um das GitHub-Repository zu klonen:

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

Nachdem Sie das Repository geklont haben, öffnen Sie es in Android Studio:

  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.

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.

App auf Ihrem Gerät ausprobieren

Bevor Sie weitere Änderungen am Code der App vornehmen, sollten Sie sich einen Überblick über die Funktionen der Beispiel-App verschaffen. Das Testen der App in Ihrer Entwicklungsumgebung umfasst die folgenden Schritte:

  1. Öffnen Sie Ihr virtuelles oder physisches Android-Testgerät.
  2. Prüfen, ob die Assistant App funktioniert
  3. Die Beispiel-App mit Android Studio auf Ihrem Gerät bereitstellen und ausführen

So testen Sie Ihre App:

  1. Wählen Sie in Android Studio Run > Run app (Ausführen > App ausführen) aus oder klicken Sie in der Symbolleiste auf Runacabcb8f8634af20.png.
  2. Wenn Sie ein virtuelles Gerät verwenden, wählen Sie im Dialogfeld Select Deployment Target (Bereitstellungsziel auswählen) ein virtuelles Gerät aus und klicken Sie auf OK. Die empfohlene Betriebssystemversion ist Android 8 (API‑Level 26) oder höher. Actions können aber auch auf Geräten mit Android 5 (API‑Level 21) ausgeführt werden.
  3. Halte nach dem Öffnen der App den Home-Button gedrückt, um Assistant einzurichten und zu prüfen, ob sie funktioniert. Melden Sie sich bei Assistant an, falls Sie das noch nicht getan haben.
  4. Öffnen Sie die App noch einmal.

Smartphone mit geöffneter Fit Actions App, auf dem Trainingsstatistiken angezeigt werden.

Abbildung 2: Die Fit Actions-Beispiel-App mit Trainingsstatistiken.

Sehen Sie sich die App kurz an, um zu sehen, was sie kann. Wenn Sie auf das Symbol „Laufen“ tippen, wird ein Trainingstimer gestartet. Wenn Sie dann auf das Symbol „X“ tippen, wird der Timer angehalten. Das sind die Aufgaben, die Sie für die Sprachsteuerung mit App Actions aktivieren.

Google Assistant-Plug-in installieren

Mit dem Google Assistant-Plug-in können Sie Ihre App Actions auf einem Testgerät testen. So fügen Sie es Android Studio hinzu:

  1. Klicken Sie auf Datei > Einstellungen (unter MacOS Android Studio > Einstellungen).
  2. Gehen Sie im Bereich „Plug‑ins“ zum Marketplace und suchen Sie nach „Google Assistant“.
  3. Installieren Sie das Tool und starten Sie Android Studio neu.

4. Füge die BII-Funktion „Start Exercise“ hinzu.

Mit dem actions.intent.START_EXERCISE BII können Nutzer eine App öffnen und ein Training per Sprachbefehl starten. In diesem Schritt implementieren Sie eine Funktion für dieses BII, mit der Nutzer Assistant bitten können, einen Lauf in der Fitness-App zu starten.

Funktion definieren

Assistant verwendet capability-Elemente, die in shortcuts.xml definiert sind, um Sprachbefehle mit den folgenden Schritten zu verarbeiten:

  1. Assistant ordnet die Sprachanfrage des Nutzers einem BII zu, der in den Funktionen Ihrer App definiert ist.
  2. Assistant extrahiert Werte aus der Anfrage in BII-Parameter. Jeder Parameter wird einem Bundle hinzugefügt, der an ein generiertes Intent angehängt ist.
  3. Assistant verwendet Intent, um die App zu starten und ihr Zugriff auf die gebündelten Parameter zu gewähren.

Das START_EXERCISE-BII unterstützt den BII-Parameter exercise.name. Mit diesem Parameter können Nutzer die Art des Trainings angeben, das in der App erfasst werden soll.

Fügen Sie Ihrer App das BII START_EXERCISE hinzu, indem Sie shortcuts.xml in app/src/main/res/xml, das sich im Beispielprojektverzeichnis capability befindet, Folgendes hinzufügen:

<!-- shortcuts.xml -->

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <parameter
      android:name="exercise.name"
      android:key="exerciseType"/>
  </intent>
</capability>

Ersetzen Sie PUT_YOUR_APPLICATION_ID_HERE durch die eindeutige applicationId, die Sie im vorherigen Schritt definiert haben.

Die oben gezeigte Beispiel-XML:

  • Deklariert eine Funktion für die START_EXERCISE-BII.
  • Gibt die Android-intent an, die von Assistant generiert wird, um die App zu starten:
    • Die Attribute targetPackage und targetClass geben die empfangende Aktivität an.
    • Das Attribut parameter ordnet den BII-Parameter exercise.name dem Parameter exerciseType in den von der Aktivität empfangenen Bundle-Extras zu.

BII-Parameter mit einem Inline-Inventar verarbeiten

BII-Parameter stellen die Elemente dar, die aus einer Nutzeranfrage an Assistant extrahiert werden. Wenn ein Nutzer beispielsweise „Hey Google, starte einen Lauf in Beispiel-App“ sagt, extrahiert Assistant „Lauf“ in den BII-Parameter exercise.name schema.org. Bei einigen BIIs können Sie Assistant anweisen, BII-Parameter mit einer Reihe von Kennungen abzugleichen, die von Ihrer App erwartet werden.

Dazu binden Sie Inline-Inventar-Elemente an den BII-Parameter. Ein Inline-Inventar ist eine Reihe unterstützter BII-Parameterwerte wie „run“, „hike“ und „jog“ sowie die entsprechende Shortcut-ID, z. B. EXERCISE_RUN. Durch diese Inventarbindung kann Assistant die Shortcut-ID für übereinstimmende Parameter anstelle des Rohabfragewerts an Ihre Auftragsausführungsaktivität übergeben.

Für einige BII-Parameter wie exercise.name ist ein Inline-Inventar erforderlich. Fügen Sie die folgenden shortcut-Inventarelemente zu shortcuts.xml hinzu, um diesen Parameter zu verarbeiten:

<!-- shortcuts.xml -->

<shortcuts>
  <shortcut
    android:shortcutId="running"
    android:shortcutShortLabel="@string/activity_running">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/runningSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="walking"
    android:shortcutShortLabel="@string/activity_walking">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/walkingSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="cycling"
    android:shortcutShortLabel="@string/activity_cycling">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/cyclingSynonyms"/>
    </capability-binding>
  </shortcut>

  <capability> ... </capability>
</shortcuts>

Im vorherigen Code haben Sie drei Verknüpfungen definiert, die ein Inline-Inventar für die unterstützten Trainingstypen der App darstellen: Laufen, Gehen und Radfahren. Jede Verknüpfung ist auf folgende Weise an die Funktion gebunden:

  • Das Attribut android:key jedes capability-binding-Elements verweist auf dieselbe START_EXCERCISE-BII, die für die Funktion definiert ist.
  • Das parameter-binding-Element jeder Tastenkombination wird dem BII-Parameter exercise.name zugeordnet.

Synonyme für Inline-Inventar hinzufügen

Die Attribute android:value des Elements parameter-binding in den vorangegangenen Inventarkürzeln verweisen auf eine Array-Ressource mit Synonymen für jedes Inventarelement. Mit Synonymen können Varianten eines Elementtyps wie „Laufen“, „Joggen“ und „Sprinten“ auf dieselbe shortcutId verweisen. Fügen Sie der array.xml-Ressource des Projekts die folgenden Synonymeinträge hinzu:

<!-- array.xml -->
<array name="runningSynonyms">
  <item>Run</item>
  <item>Jog</item>
  <item>Jogging</item>
  <item>Sprint</item>
</array>

<array name="walkingSynonyms">
  <item>Walk</item>
  <item>Hike</item>
  <item>Hiking</item>
</array>

<array name="cyclingSynonyms">
  <item>Biking</item>
  <item>Riding</item>
  <item>Pedaling</item>
</array>

Eingehende Android-Intents ausführen

Android-Intents sind Messaging-Objekte, mit denen Android eine Aktion von einer anderen App anfordert. Assistant erfüllt die Sprachanfragen von Nutzern, indem ein Intent aus den Konfigurationsdetails in der ausgelösten Funktion generiert wird. Wenn Sie Intents für die Funktion START_EXERCISE ausführen möchten, aktualisieren Sie die Zielklasse FitMainActivity, um den eingehenden Intent und die BII-Parameter zu verarbeiten.

Ersetzen Sie zuerst die Funktion Intent.handleIntent durch den folgenden Code:

//FitMainActivity.kt

private fun Intent.handleIntent() {
  when (action) {
    // When the BII is matched, Intent.Action_VIEW will be used
    Intent.ACTION_VIEW -> handleIntent(data)
    // Otherwise start the app as you would normally do.
    else -> showDefaultView()
  }
}

Fügen Sie als Nächstes der Klasse mit dem folgenden Code eine neue handleIntent-Funktion hinzu:

//FitMainActivity.kt

/**
 * Use extras provided by the intent to handle the different BIIs
 */

private fun handleIntent(data: Uri?) {
  // path is normally used to indicate which view should be displayed
  // i.e https://fit-actions.firebaseapp.com/start?exerciseType="Running" -> path = "start"
  var actionHandled = true

  val startExercise = intent?.extras?.getString(START_EXERCISE)
  // Add stopExercise variable here

  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  else{
   // path is not supported or invalid, start normal flow.
   showDefaultView()

   // Unknown or invalid action
   actionHandled = false
  }
  notifyActionSuccess(actionHandled)
}

In der oben genannten Funktion Intent.handleIntent werden die Intent-Daten der App Action an die Funktion handleIntent übergeben, wenn ACTION_VIEW ausgelöst wird. Auf die im Intent START_EXERCISE gebündelten BII-Parameter wird über intent?.extras?.getString(START_EXERCISE) zugegriffen. Im restlichen Teil der Funktion wird FitTrackingFragment aktualisiert, um den ausgewählten startExercise-Fitnesstyp anzuzeigen.

App Action testen

Während der Entwicklung von App Actions verwenden Sie das Google Assistant-Plug‑in, um sich eine Vorschau Ihrer Actions auf einem Testgerät anzusehen. Sie können das Plug-in auch verwenden, um die Intent-Parameterwerte einer Aktion anzupassen und so zu testen, wie Ihre App die verschiedenen Formulierungen einer Assistant-Anfrage für Ihre App verarbeitet.

So testen Sie Ihre App Action mit dem Plug-in:

  1. Führen Sie Ihre App in Android Studio aus, indem Sie Run > Run App auswählen oder in der oberen Symbolleiste auf das Symbol Run klicken.
  2. Klicken Sie auf Tools > App Actions > Google Assistant > App Actions Test Tool.
  3. Klicken Sie auf Vorschau erstellen. Lesen und akzeptieren Sie die Richtlinien und Nutzungsbedingungen für App Actions, wenn Sie dazu aufgefordert werden.
  4. Wählen Sie den integrierten Intent actions.intent.START_EXERCISE aus.
  5. Übernehmen Sie im Feld exercise (Training) den Standardwert running (Laufen).
  6. Klicken Sie auf App-Aktion ausführen. Prüfe, ob Assistant einen Deeplink zum Trainingstimer der App erstellt hat und ob der Timer ein Lauftraining gestartet hat.

Sie haben Ihre ersten App Actions mit dem BII START_EXERCISE implementiert. Glückwunsch! Als Nächstes ermöglichen wir Nutzern, ein laufendes Training in Ihrer App zu beenden.

5. Funktion „Training beenden“ für BII hinzufügen

Mit dem BII actions.intent.STOP_EXERCISE können Nutzer ein Training beenden, indem sie z. B. ;Hey Google, beende meinen Lauf in Beispiel-App sagen. Implementieren Sie dieses BII in der Fitness-App, indem Sie shortcuts.xml ein zweites capability hinzufügen:

<!-- shortcuts.xml -->

<capability android:name="actions.intent.STOP_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <!-- Eg. name = "Running" -->
    <parameter
        android:name="exercise.name"
        android:key="stopExercise"/>
  </intent>
</capability>

Ersetzen Sie PUT_YOUR_APPLICATION_ID_HERE durch Ihre eindeutige applicationId.

BII-Parameter mit einem Inline-Inventar verarbeiten

Dieses BII unterstützt denselben exercise.name-Parameter wie das BII START_EXERCISE. Nutzer können also angeben, welches aktive Training sie beenden möchten. Fügen Sie dazu shortcuts.xml eine zweite Gruppe von Elementen für Inventarkürzel hinzu:

<!-- shortcuts.xml -->

<shortcut
  android:shortcutId="running"
  android:shortcutShortLabel="@string/activity_running">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/runningSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="walking"
  android:shortcutShortLabel="@string/activity_walking">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/walkingSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="cycling"
  android:shortcutShortLabel="@string/activity_cycling">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/cyclingSynonyms"/>
  </capability-binding>
</shortcut>

Eingehende Android-Intents ausführen

Aktualisieren Sie die Klasse FitMainActivity, damit die App eingehende Android-Intents vom Typ STOP_EXERCISE verarbeiten kann. Fügen Sie zuerst der Funktion handleIntent eine Variable hinzu, um die Intent-Daten STOP_EXERCISE zu speichern:

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  val stopExercise = intent?.extras?.getString(STOP_EXERCISE)
  //...
}

Aktualisieren Sie als Nächstes die bedingte Logik der Funktion handleIntent, um STOP_EXERCISE-Intents zu verarbeiten:

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  //...
  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  <strong>
  } else if(stopExercise != null){
    // Stop the tracking service if any and return to home screen.
    stopService(Intent(this, FitTrackingService::class.java))
    updateView(FitStatsFragment::class.java)
  }
  </strong>
  //...
}

Im vorherigen Code haben Sie die Funktion handleIntent aktualisiert, um im eingehenden Android-Intent nach dem BII STOP_EXERCISE zu suchen. Wenn ein aktiver Timer gefunden wird, wird er beendet und der Nutzer wird zum Startbildschirm zurückgebracht.

App Action testen

So testen Sie Ihre App Action mit dem Google Assistant-Plug-in:

  1. Führen Sie Ihre App in Android Studio aus, indem Sie Run > Run App auswählen oder in der oberen Symbolleiste auf das Symbol Run klicken.
  2. Starte in der App ein neues Training vom Typ „Laufen“.
  3. Öffnen Sie das Plug-in in Android Studio: Gehen Sie zu Tools > App Actions > Google Assistant > App Actions Test Tool.
  4. Klicken Sie auf Vorschau erstellen.
  5. Wählen Sie den integrierten Intent actions.intent.STOP_EXERCISE aus.
  6. Übernehmen Sie im Feld exercise (Training) den Standardwert running (Laufen).
  7. Klicken Sie auf App-Aktion ausführen. Prüfe, ob Assistant das Training beendet und du zum Startbildschirm zurückkehrst.

6. Nächste Schritte

Das wars!

Sie wissen jetzt, wie Sie eine Android-App mithilfe von integrierten Assistant-Intents für die Sprachsteuerung optimieren. In diesem Codelab haben Sie Folgendes gelernt:

  • Nutzern ermöglichen, mit Assistant bestimmte App-Funktionen zu nutzen
  • Inline-Inventar verwenden
  • So testen Sie BIIs mit dem Google Assistant-Plug-in.

Nächste Schritte

Von hier aus können Sie weitere Optimierungen an Ihrer Fitness-App vornehmen. Das fertige Projekt finden Sie auf GitHub im Hauptzweig.

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

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

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

Feedback-Umfrage

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