Diese Seite wurde von der Cloud Translation API übersetzt.

Android-Apps mit App Actions auf Google Assistant erweitern

1. Übersicht

Mit App Actions kannst du mit Google Assistant direkt per Sprachbefehl App-Funktionen aufrufen und Aufgaben erledigen. Als Android-Entwickler implementieren Sie Funktionselemente, um App Actions hinzuzufügen. Mithilfe von Funktionen kann Assistant mitteilen, welche App-Funktionen Sprachanfragen von Nutzern unterstützen und wie diese Anfragen ausgeführt werden sollen.

In diesem Codelab werden Konzepte für Einsteiger zum Entwickeln mit App Actions behandelt. Sie sollten Erfahrung mit der Entwicklung von Android-Apps und Android-Intents haben, um diesem Codelab zu folgen. Wenn Sie neu bei Android sind, können Sie mit einem der Codelabs für Grundlagen für Android-Entwickler beginnen.

Aufgaben

In diesem Codelab fügen Sie einer Beispiel-Fitness-Android-App zwei integrierte App Actions-Intents (BIIs) hinzu, mit denen Nutzer einen Trainings-Timer per Sprachbefehl starten und stoppen können.

Lerninhalte

Du erfährst, wie du BIIs aus der Kategorie Gesundheit und Fitness verwendest, um Assistant auf eine Android-App auszuweiten. Außerdem lernen Sie, wie Sie Ihre BIIs mit dem Google Assistant-Plug-in für Android Studio testen.

Vorbereitung

Bevor Sie fortfahren, benötigen Sie die folgenden Tools in Ihrer Umgebung:

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

Bevor Sie fortfahren, achten Sie darauf, dass Sie im selben Google-Konto in Android Studio und in der Google App auf Ihrem Testgerät angemeldet sind.

2. Funktionsweise

Mit App Actions werden Nutzer über Google Assistant mit deiner Android-App verbunden. Funktionsweise

Wenn ein Nutzer Assistant bittet, eine Aufgabe mit deiner App auszuführen, ordnet Assistant seine Anfrage einer App Actions-capability zu, die in der XML-Ressource shortcuts.xml deiner App definiert ist.

Ein Flussdiagramm, das zeigt, wie Google Assistant eine App Actions-Sprachanfrage verarbeitet

Abbildung 1. Ein Flussdiagramm, das zeigt, wie Assistant eine App Actions-Sprachanfrage verarbeitet.

Jedes Capability-Element definiert Folgendes:

Intent: Der App Actions-Sprach-Intent, der die Funktion auslösen soll.
Eine oder mehrere Auftragsausführungen: Android-Intents oder Deeplinks, die Assistant generiert, um die App zu starten und die Sprachanfrage des Nutzers auszuführen. In den Ausführungsdefinitionen wird angegeben, welche Parameter von der Nutzeranfrage erwartet werden und wie diese Parameter in den Startanweisungen codiert werden sollen.

Intents

Beim Natural Language Understanding (NLU) ist ein Intent eine Gruppe von Wortgruppen mit ähnlichen Bedeutungen. Google hat Dutzende von „integrierten“ Intents (BIIs) decken eine Vielzahl von Anfragetypen ab, die mit App Actions verfügbar sind. Assistant wurde beispielsweise dafür trainiert, die Formulierungen „Pizza bestellen“ oder „Zeig mir das Dessertmenü“ mit dem BII ORDER_MENU_ITEM zu verknüpfen. Mit App Actions kannst du diese BIIs nutzen, um häufige Sprachbefehle schnell auf App-Funktionen auszuweiten.

Auftragsausführungen

Wenn eine Nutzeranfrage eine App Action in shortcuts.xml auslöst, muss deine Android-Aktivität den eingehenden Android-Intent oder Deeplink erkennen und verarbeiten sowie dem Nutzer die gewünschten Funktionen bereitstellen. Das Ergebnis ist eine sprachgesteuerte Nutzererfahrung, bei der Assistant Ihre App als Antwort 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 Trainings-Timer starten und stoppen und Statistiken zu ihren Trainingsroutinen ansehen.

Basisdateien herunterladen

Um die Basisdateien für dieses Codelab abzurufen, 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:

Klicken Sie im Dialogfeld Welcome to Android Studio (Willkommen bei Android Studio) auf Import project (Projekt importieren).
Wählen Sie den Ordner aus, in den Sie das Repository geklont haben.

Android-App-ID aktualisieren

Durch die Aktualisierung der App-ID wird die App auf Ihrem Testgerät eindeutig identifiziert. „Doppelte Paketnamen“ werden vermieden. wenn die App in die Play Console hochgeladen wird. Öffnen Sie app/build.gradle, um die Anwendungs-ID zu aktualisieren:

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

Ersetzen Sie "MYUNIQUENAME". im Feld applicationId in ein für Sie einzigartiges Feld ein.

Probiere die App auf deinem Gerät aus

Bevor Sie weitere Änderungen am Anwendungscode vornehmen, sollten Sie sich ein Bild davon machen, was die Beispiel-App leisten kann. Zum Testen der Anwendung in Ihrer Entwicklungsumgebung sind folgende Schritte erforderlich:

Ihr virtuelles oder physisches Android-Testgerät wird geöffnet.
Es wird geprüft, ob die Assistant-App funktioniert.
Beispiel-App mit Android Studio bereitstellen und auf Ihrem Gerät ausführen

So testen Sie Ihre App:

Wählen Sie in Android Studio Run > (Ausführen >) aus. App ausführen oder in der Symbolleiste auf Ausführen klicken
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 jedoch auch auf Geräten ab Android 5 (API-Level 21) ausgeführt werden.
Halten Sie nach dem Öffnen der App die Startbildschirmtaste lange gedrückt, um Assistant einzurichten und zu prüfen, ob er funktioniert. Melden Sie sich in Assistant an, falls noch nicht geschehen.
Öffnen Sie die App wieder.

Smartphone mit geöffneter Fit Actions-App und Anzeige von Trainingsstatistiken.

Abbildung 2: Die Fit Actions-Beispiel-App, die Trainingsstatistiken anzeigt.

Sehen Sie sich kurz die App an, um zu sehen, was sie alles kann. Tippe auf das Lauf-Symbol, um einen Trainings-Timer zu starten, und tippe auf das X-Symbol, um den Timer zu stoppen. Dies sind die Aufgaben, die du für die Sprachsteuerung mit App Actions aktivierst.

Google Assistant-Plug-in installieren

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

Gehen Sie zu Datei > Einstellungen (Android Studio > Einstellungen unter macOS)
Rufen Sie im Abschnitt „Plug-ins“ den Marketplace auf und suchen Sie nach „Google Assistant“.
Installieren Sie das Tool und starten Sie Android Studio neu.

4. Funktion „Training starten“-BII hinzufügen

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

Fähigkeit definieren

Assistant verwendet in shortcuts.xml definierte capability-Elemente, um Sprachbefehle so zu verarbeiten:

Assistant ordnet die Stimme des Nutzers einem BII zu, der in den Funktionen deiner App definiert ist.
Der Assistent extrahiert Werte aus der Abfrage in BII-Parameter. Jeder Parameter wird einem Bundle hinzugefügt, der an ein generiertes Intent angehängt ist.
Assistant verwendet die Intent, um die App zu starten, und gibt der App Zugriff auf die gebündelten Parameter.

Der BII START_EXERCISE unterstützt den BII-Parameter exercise.name. Mit diesem Parameter können Nutzer festlegen, welche Art von Training in der App erfasst werden soll.

Fügen Sie Ihrer Anwendung den BII START_EXERCISE hinzu, indem Sie diesen capability in shortcuts.xml im Verzeichnis app/src/main/res/xml des Beispielprojekts einfü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 vorherige Beispiel-XML-Datei hat folgende Auswirkungen:

Deklariert eine Funktion für den BII START_EXERCISE.
Gibt die Android-intent an, die Assistant zum Starten der App generiert:
- Die Attribute targetPackage und targetClass geben die Empfangsaktivität an.
- Das Attribut parameter ordnet den BII-Parameter exercise.name in den Bundle-Extras, die von der Aktivität empfangen werden, exerciseType zu.

BII-Parameter mit Inline-Inventar verarbeiten

BII-Parameter stehen für die Elemente, die aus einer Assistant-Nutzeranfrage extrahiert wurden. Wenn ein Nutzer beispielsweise „Hey Google, starte ein Lauftraining in ExampleApp“ sagt, extrahiert Assistant „Lauf“. in den BII-Parameter exercise.name schema.org ein. 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-Inventarelemente an den BII-Parameter. Ein Inline-Inventar besteht aus einer Reihe unterstützter BII-Parameterwerte wie „Laufen“, „Wandern“ und „Laufen“ sowie der zugehörigen Verknüpfungs-ID, z. B. EXERCISE_RUN. Mit dieser Inventarbindung kann Assistant die Verknüpfungs-ID für übereinstimmende Parameter anstelle des Rohabfragewerts an Ihre Auftragsausführungsaktivität übergeben.

Einige BII-Parameter wie exercise.name erfordern ein Inline-Inventar, damit sie funktionieren. Fügen Sie shortcuts.xml die folgenden shortcut-Inventarelemente 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 hast du drei Verknüpfungen definiert, die ein Inline-Inventar für die von der App unterstützten Trainingstypen darstellen: Laufen, Gehen und Radfahren. Jede Tastenkombination ist auf folgende Weise an die Capability gebunden:

Das android:key-Attribut jedes capability-binding-Elements bezieht sich auf denselben START_EXCERCISE-BII, der für die Capability definiert ist.
Das parameter-binding-Element der einzelnen Tastenkombinationen für den BII-Parameter exercise.name.

Synonyme für Inline-Inventar hinzufügen

Die android:value-Attribute des Elements parameter-binding in den vorherigen Inventarverknüpfungen beziehen sich auf eine Array-Ressource mit Synonymen für jedes Inventarelement. Mit Synonymen können Varianten eines Elementtyps wie „Laufen“, „Joggen“ und „Sprint“ verwendet werden. auf dieselbe shortcutId verweisen. Fügen Sie der Ressource array.xml 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 Nachrichtenobjekte, die Android verwendet, um eine Aktion von einer anderen App anzufordern. Assistant erfüllt Nutzer*innen Sprachabfragen durch Generieren eines Intents aus den Konfigurationsdetails in der ausgelösten Funktion. Damit Intents für die Funktion START_EXERCISE erfüllt werden können, müssen Sie die Zielklasse FitMainActivity so aktualisieren, dass der eingehende Intent und die BII-Parameter verarbeitet werden.

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

Als Nächstes fügen Sie der Klasse eine neue handleIntent-Funktion mit dem folgenden Code 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)
}

Wenn in der vorherigen Intent.handleIntent-Funktion ACTION_VIEW ausgelöst wird, werden die App Action-Intent-Daten an die handleIntent-Funktion übergeben. Der Zugriff auf die im Intent START_EXERCISE gebündelten BII-Parameter erfolgt über intent?.extras?.getString(START_EXERCISE). Der Rest der Funktion aktualisiert FitTrackingFragment, sodass der ausgewählte Fitnesstyp startExercise angezeigt wird.

App Action testen

Bei der Entwicklung von App Actions verwendest du das Google Assistant-Plug-in, um dir eine Vorschau deiner Actions auf einem Testgerät anzusehen. Du kannst das Plug-in auch verwenden, um die Intent-Parameterwerte einer Aktion anzupassen, um zu testen, wie deine App die verschiedenen Möglichkeiten verarbeitet, wie Nutzer eine Assistant-Anfrage für deine App formulieren können.

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

Führen Sie Ihre App in Android Studio aus, indem Sie Ausführen > Run App (App ausführen) oder in der oberen Symbolleiste auf das Symbol Run (Ausführen) klicken
Klicken Sie auf Tools > App Actions > Google Assistant > App Actions-Testtool
Klicken Sie auf Vorschau erstellen. Wenn du dazu aufgefordert wirst, lies und akzeptiere die Richtlinien und Nutzungsbedingungen für App Actions.
Wählen Sie den integrierten Intent actions.intent.START_EXERCISE aus.
Übernehmen Sie im Feld train (Training) den Standardwert running (wird ausgeführt).
Klicken Sie auf Run App Action (App-Aktion ausführen). Prüfe, ob Assistant Deeplinks zum Trainings-Timer der App enthält und ob der Timer ein Lauftraining gestartet hat.

Du hast deine ersten App Actions mit dem BII START_EXERCISE implementiert. Glückwunsch! Als Nächstes ermöglichen wir Benutzern, ein Lauftraining in deiner App zu stoppen.

5. Funktion „Training starten“-BII hinzufügen

Mit dem BII actions.intent.STOP_EXERCISE können Nutzer eine Trainingseinheit beenden, indem sie beispielsweise sagen: „Hey Google, stoppe meinen Lauf in ExampleApp.“ Implementiere diesen BII in der Fitness-App, indem du shortcuts.xml eine zweite capability hinzufügst:

<!-- 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 Inline-Inventar verarbeiten

Dieser BII unterstützt denselben exercise.name-Parameter wie der BII START_EXERCISE, sodass Nutzer angeben können, welches aktive Training sie beenden möchten. Dazu fügen Sie shortcuts.xml einen zweiten Satz von Inventarverknüpfungselementen 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

Aktivieren Sie die App, um eingehende STOP_EXERCISE-Android-Intents zu verarbeiten, indem Sie die Klasse FitMainActivity aktualisieren. Fügen Sie der Funktion handleIntent zuerst eine Variable für die Intent-Daten STOP_EXERCISE hinzu:

// 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. Wird der Timer gefunden, stoppt die Funktion den aktiven Timer und kehrt zum Startbildschirm zurück.

App Action testen

So kannst du deine App Action mit dem Google Assistant-Plug-in testen:

Führen Sie Ihre App in Android Studio aus, indem Sie Ausführen > Run App (App ausführen) oder in der oberen Symbolleiste auf das Symbol Run (Ausführen) klicken
Starten Sie in der App einen neuen „Laufen“ Übung.
Öffnen Sie das Plug-in in Android Studio: Gehen Sie zu Tools > App Actions > Google Assistant > App Actions-Testtool
Klicken Sie auf Vorschau erstellen.
Wählen Sie den integrierten Intent actions.intent.STOP_EXERCISE aus.
Übernehmen Sie im Feld train (Training) den Standardwert running (wird ausgeführt).
Klicken Sie auf Run App Action (App-Aktion ausführen). Prüfe, ob Assistant das Training beendet und dich zum Startbildschirm zurückkehrt.

6. Nächste Schritte

Glückwunsch!

Jetzt wissen Sie, wie Sie Android-Apps mithilfe der integrierten Assistant-Intents per Sprachbefehl aktivieren. In diesem Codelab haben Sie Folgendes gelernt:

Hier erfahren Sie, wie Sie Nutzern mithilfe von Assistant bestimmte App-Funktionen näherbringen können.
Inline-Inventar verwenden
BIIs mit dem Google Assistant-Plug-in testen

Nächste Schritte

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

Hier sind einige Vorschläge, wie du diese App mit App Actions erweitern kannst:

Dann sieh dir unsere anderen App Actions-Codelabs an.
In der Referenz zu integrierten Intents für App Actions findest du weitere BIIs, mit denen du deine Apps auf Assistant erweitern kannst.

Wenn Sie Actions on Google weiter nutzen möchten, sollten Sie sich die folgenden Ressourcen ansehen:

developers.google.com/assistant: Offizielle Dokumentationswebsite für Actions on Google
Beispielindex für App Actions: Beispiel-Apps und Code zum Ausprobieren 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.

Folge uns auf Twitter (@ActionsOnGoogle), um dich über unsere neuesten Ankündigungen zu informieren, und twittere unter #appactions, um deine Arbeit mit anderen zu teilen.

Feedback-Umfrage

Bitte nimm abschließend an dieser Umfrage teil, um uns Feedback zu deinen Erfahrungen mit diesem Codelab zu geben.