App Actions erstellen

Mit App Actions können Nutzer Funktionen in deiner Android-App starten, indem sie Google Assistant dazu auffordern oder von Assistant vorgeschlagene Android-Verknüpfungen verwenden. Folgendes sind die wichtigsten Schritte, um deine Android-App durch App Actions zu ergänzen:

Identifiziere die auszulösende In‑App-Funktion und den entsprechenden integrierten Intent (Built-In Intent, BII).
Gib Details zur Ausführung für den BII an.
Sende Verknüpfungen für die App Action an Assistant.
Sieh dir die Vorschau deiner App Actions auf einem Testgerät an.
Erstelle einen Testrelease deiner App.
Beantrage die Überprüfung und Bereitstellung der App Actions.

Optional kannst du dynamische Verknüpfungen definieren, die für Assistant zur Verfügung gestellt werden sollen, damit er sie den Nutzern vorschlagen kann. Erstelle eine App Action mit einer Beispiel-App. Folge dazu dem Codelab für App Actions.

Anforderungen

Prüfe vor der Entwicklung von App Actions, ob deine App die folgenden Anforderungen erfüllt:

Du musst ein Google-Konto mit Zugriff auf die Google Play Console haben.
Deine App muss im Google Play Store veröffentlicht sein, da App Actions nur für dort veröffentlichte Apps verfügbar sind. Achte außerdem darauf, dass deine App nicht für die Verwendung in einem Arbeitsprofil vorgesehen ist, da App Actions von Managed Google Play nicht unterstützt werden.
Du musst ein physisches oder virtuelles Gerät haben, auf dem du deine App Actions testen kannst.
Du benötigst die neueste Version von Android Studio.
Du musst dasselbe Google-Konto verwenden, um dich in Android Studio, der Google App auf deinem Testgerät und der Google Play Console anzumelden.
Du musst Assistant auf dem Testgerät einrichten und testen, indem du die Startbildschirmtaste berührst und hältst.

Integrierte Intents mit App-Funktionen abgleichen

Ermittle die Funktionen in deiner Android-App, zu denen Nutzer möglicherweise mit einem Sprachbefehl wechseln möchten, und sieh dir die Referenz zu integrierten Intents an, um geeignete BIIs für deine Anwendungsfälle zu finden. BIIs modellieren Nutzeranfragen für Aufgaben, die ausgeführt werden sollen. Suche also nach BIIs, die wichtigen Funktionen und Aufrufabfolgen in deiner App entsprechen.

Es gibt gängige BIIs, die in fast jeder Android-App verwendet werden können. Beispielsweise kann die native In‑App-Suche mit dem BII actions.intent.GET_THING auf Assistant erweitert werden oder du kannst den BII actions.intent.OPEN_APP_FEATURE implementieren, damit Nutzer bestimmte App-Funktionen per Sprachbefehl starten können.

Es gibt auch BIIs, die branchenspezifische oder kategoriespezifische Anwendungsfälle ermöglichen. In einer App zur Essensbestellung könnte beispielsweise der BII actions.intent.ORDER_MENU_ITEM verwendet werden.

Achte darauf, dass jeder von dir implementierte BII für deine In‑App-Funktionen relevant ist, um für optimale Nutzerfreundlichkeit zu sorgen und potenzielle Verzögerungen bei der Genehmigung zu vermeiden.

Bei App Actions werden über die Assistant-App Android-Intents gestartet, um Nutzer direkt zu bestimmten Inhalten in deiner App weiterzuleiten. Du kannst Intents so definieren, dass eine Aktivität explizit gestartet wird. Gib dazu die Felder targetClass und targetPackage an. Wenn in deiner App bereits Android-Deeplinks implementiert sind, kannst du den Intent so konfigurieren, dass für die Ausführung ein Deeplink verwendet wird. Weitere Informationen findest du im Abschnitt Aktivitäts-Deeplinks testen.

Details zur Ausführung für integrierte Intents angeben

Die Erstellung einer App Action besteht hauptsächlich darin, in der Ressourcendatei shortcuts.xml deiner Android-App eine Funktion zu deklarieren, mit der du den ausgewählten BII und die entsprechende Ausführung deklarierst. Ein BII modelliert die Nutzeranfrage für eine Aufgabe und ein Ausführungs-Intent gibt Assistant Informationen darüber, wie die Aufgabe ausgeführt werden soll.

In der Datei shortcuts.xml werden BIIs als <capability>-Elemente und jede Ausführung als <intent>-Element dargestellt:

<shortcuts>
    <capability android:name="actions.intent.ORDER_MENU_ITEM">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.example.app"
            android:targetClass="com.example.app.browse">
            <parameter
                android:name="menuItem.name"
                android:key="query">
            </parameter>
        </intent>
    </capability>

Bei den meisten BIIs extrahierst du Intent-Parameter aus der Nutzeranfrage basierend auf schema.org-Entitäten. Deine App verwendet diese BII-Parameter dann, um Nutzer zur gewünschten Funktion zu leiten. Der vorherige Code ordnet beispielsweise den BII-Parameter menuItem.name dem Android-intent-Parameter query zu.

Wenn du Aktionen über Deeplinks ausführen lässt, kannst du im Feld urlTemplate festlegen, welche Deeplink-URL Assistant generiert:

<shortcuts>
    <capability android:name="actions.intent.ORDER_MENU_ITEM">
        <intent android:action="android.intent.action.VIEW">
            <url-template android:value="myfoodapp://browse{?query}" />
            <parameter android:name="menuItem.name"
                android:key="query"
                android:mimeType="text/*">
            </parameter>
        </intent>
    </capability>
</shortcuts>

Tipp: Wenn deine App mehrere auszuführende Intents für einen einzigen BII anbietet, versucht Assistant, sie in der Reihenfolge zu erledigen, in der sie im capability-Element aufgeführt sind.

Wichtige Informationen zum Hinzufügen von App Actions zur Datei shortcuts.xml findest du unter shortcuts.xml erstellen. Dort wird auch beschrieben, wie du die Parameterwerte angibst, die deine App erwartet.

Integrierten Intent GET_THING implementieren

Wenn deine App eine Suchfunktion hat, musst du für diese Funktion den BII actions.intent.GET_THING implementieren. Assistant kann Nutzer dann zur Suchfunktion deiner App weiterleiten, damit sie In‑App-Ergebnisse erhalten, wenn sie Anfragen wie „Hey Google, suche in Beispiel-App nach Beispielsache“ stellen.

Implementiere in der Datei shortcuts.xml ein <capability>-Element für den BII actions.intent.GET_THING so, wie du auch andere BIIs implementierst. Du kannst mehrere Ausführungen für GET_THING verwenden, solange du mindestens eine Ausführung anbietest, die die Nutzeranfrage an die Suchfunktion deiner App weiterleitet.

Hier ist ein Beispiel für das Hinzufügen des BII actions.intent.GET_THING in shortcuts.xml:

  <capability android:name="actions.intent.GET_THING">
    <intent
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.MySearchActivity">
      <parameter android:name="thing.name" android:key="query" />
    </intent>
  </capability>

Extrahiere in der Activity für die Suche die Suchanfrage aus den zusätzlichen Daten des intent und leite sie an die Suchfunktion deiner App weiter. Im vorherigen Code wird die als query-Schlüssel übergebene Suchanfrage dem BII-Parameter "thing.name" zugeordnet. Führe dann eine Suche mit der Anfrage durch und zeige die Ergebnisse auf der Benutzeroberfläche an.

Optional: Verknüpfungen für App Actions an Assistant senden

Nachdem du eine Funktion für deine Aktion definiert hast, können Nutzer deine Aktion starten, indem sie z. B. „Hey Google, bestelle eine Pizza über Beispiel-App“ sagen. Assistant kann Nutzern zu geeigneter Zeit Android-Verknüpfungen für deine Aktionen vorschlagen, damit sie deine Aktionen finden und verwenden können. Assistant kann sowohl dynamische als auch statische Verknüpfungen vorschlagen.

Wenn du dynamische Verknüpfungen an Assistant senden möchtest, verwende die Bibliothek „Google Shortcuts Integration“. Mit dieser Jetpack-Bibliothek kann Assistant deine Verknüpfungen berücksichtigen und Nutzern zu geeigneter Zeit vorschlagen.

Weitere Informationen findest du unter Dynamische Verknüpfungen an Assistant senden.

Vorschau deiner App Actions ansehen

Verwende während der Entwicklung und beim Testen das Google Assistant-Plug‑in für Android Studio, um zu testen, ob App Actions für deine App funktionieren. Das Plug‑in erstellt für dein Google-Konto eine Vorschau deiner App Actions in Assistant. Mit dem Testtool kannst du die Ausführungen auf einem physischen Testgerät oder Emulator prüfen. Stelle dazu BIIs mit Eingabeparametern bereit, die du von Nutzern erwartest.

Während der Vorschau deiner App Actions kannst du auf dem Gerät Anfragen per Sprachbefehl auslösen. Diese Funktion ist nur für Anfragen verfügbar, die in der BII-Referenz für App Actions aufgeführt sind. Verwende das Auslösen per Sprachbefehl nur zu Demonstrationszwecken und nicht für normale Tests.

Teste deine App mit den Entwicklertools für die Google Play Console im Entwurfsmodus, bevor du sie zur Überprüfung einreichst. Weitere Informationen zur Bereitstellung eines App-Entwurfs über die Google Play Console findest du unter Release vorbereiten und einführen.

Testrelease erstellen

Wenn du bereit bist, deine App Actions mit weiteren Testern zu prüfen, erstelle einen Release deiner App für interne oder geschlossene Tests. Standardmäßig können deine Tester für den internen bzw. geschlossenen Release auf App Actions zugreifen, die bereits überprüft und genehmigt wurden.

Um den Testzugriff auf alle App Actions zu ermöglichen, einschließlich nicht genehmigter Aktionen, müssen deine Tester der Google-Gruppe App Actions Development Program beitreten. Mitglieder dieser Gruppe haben Zugriff auf alle App Actions in Releases für interne oder geschlossene Tests, ohne eine Vorschau mit dem App Actions-Testtool erstellen zu müssen. Nach dem Beitritt zur Gruppe kann es bis zu drei Stunden dauern, bis der Zugriff möglich ist.

Überprüfung und Bereitstellung von App Actions beantragen

App Actions sind für Nutzer deiner veröffentlichten Apps oder deiner Releases für offene Tests erst verfügbar, nachdem sie überprüft und genehmigt wurden. Die Überprüfung von App Actions hat keine Auswirkungen auf den Überprüfungs- und Bereitstellungsstatus deiner Android-App bei Google Play. Auch wenn deine eingereichte App genehmigt und im Play Store veröffentlicht wurde, kann die Überprüfung der Datei shortcuts.xml durch Google noch ausstehen. App Actions funktionieren für deine Endnutzer erst, nachdem auch diese Überprüfung erfolgreich abgeschlossen wurde.

Wenn du deine App bereitstellst, bleiben App Actions aktiviert. Noch einmal bereitgestellte Versionen müssen jedoch von Google überprüft werden. Wenn die neue Version nicht richtig funktioniert oder Richtlinienverstöße enthält, behält sich Google das Recht vor, App Actions für deine App zu deaktivieren.

So reichst du App Actions zur Überprüfung ein:

Akzeptiere in der Google Play Console die Nutzungsbedingungen von Actions on Google (Erweiterte Einstellungen > Actions on Google):
Lade deine App, einschließlich shortcuts.xml, wie gewohnt in der Google Play Console zur Veröffentlichung hoch.
Nachdem du deine App in der Play Console hochgeladen hast, sendet Google dir unter der E‑Mail-Adresse, die in deinem Play Console-Konto angegeben ist, weitere Informationen zum Status der App Actions-Überprüfung. Du kannst dich bei Fragen zum Überprüfungsstatus deiner App Actions auch an den Actions on Google-Entwicklersupport wenden. Gib im Kontaktformular deine App-Paket-ID an und wähle im Feld How can we help you? (Wie können wir Ihnen helfen?) die Option App Action review (App Action-Überprüfung) aus.

Optional: Aktivitäts-Deeplinks testen

Wenn du einen Deeplink verwenden möchtest, um eine Activity mit einer App Action zu starten, müssen für die Activity Deeplink-URLs eingerichtet sein und sie muss im Manifest der Android-App einen entsprechenden Intent-Filter haben.

Führe den folgenden adb-Befehl aus, um zu testen, ob deine Aktivitäten zugänglich sind und mit Deeplinks über App Actions ausgelöst werden können:

$ adb shell am start -a android.intent.action.VIEW -d "AppLinksURL"

Beispiel:

$ adb shell am start -a android.intent.action.VIEW -d "https://www.example.com/deeplink"

Wenn deine Aktivität mit dem adb-Befehl nicht korrekt gestartet wird, prüfe Folgendes:

In der Manifestdatei deiner App muss für die Aktivität android:exported=true festgelegt sein, damit sie über Google Assistant mit Intents gestartet werden.
Wenn du App-Link-URLs verwendest, folge der Anleitung unter Umgang mit Android-App-Links.

App Actions-Richtlinien

App Actions müssen bestimmten Richtlinien entsprechen, damit sie bei Nutzern, die sie auslösen, wie gewünscht funktionieren. Mache dich mit diesen Richtlinien vertraut, bevor du deine Apps einreichst. So kannst du für optimale Nutzerfreundlichkeit sorgen und Verzögerungen bei der Play Store-Überprüfung oder gar eine Ablehnung vermeiden.

Nutzer zu von ihnen gewünschten Inhalten weiterleiten

BIIs und Parameter für App Actions dürfen Nutzer nur zur relevanten, von ihnen gewünschten Aktionen weiterleiten. Dazu können auch In‑App-Inhalte, Websiteinhalte sowie in Slices oder Widgets angezeigte Informationen gehören, sofern dies vom Nutzer gewünscht ist.

Implementierungen des BII ORDER_MENU_ITEM helfen Nutzern beispielsweise, eine Bestellung für ein Gericht auf einer Speisekarte oder eine bestimmte Art von Essen aufzugeben. Die einzige Ausnahme von dieser Richtlinie ist, wenn Nutzer durch deinen BII OPEN_APP_FEATURE zum Startbildschirm deiner App weitergeleitet werden.
Nutzer zu relevanten Webinhalten weiterleiten

Wenn Nutzer zum Inhalt einer Webseite weitergeleitet werden, muss die Website für die von ihnen gewünschte Aktion relevant sein und der Marke gehören.

Beispielsweise ist es nicht erlaubt, Nutzer, die deinen BII GET_RESERVATION auslösen, zu google.com/travel weiterzuleiten, das nicht zur Marke exampledomain.com deiner App gehört. Ein Verstoß wäre es auch, wenn Nutzer, die deinen BII GET_CALL_HISTORY auslösen, zu exampledomain.com/payment weitergeleitet und zu einem Kauf aufgefordert werden.
Relevante App Actions-BIIs implementieren

Implementierte BIIs müssen sich direkt auf den Inhalt und die Funktionen der App beziehen.

Wenn deine App beispielsweise zur Play Store-Kategorie „Kommunikation“ gehört, solltest du nicht den BII ORDER_MENU_ITEM implementieren, der für Apps in der Kategorie „Essen & Trinken“ empfohlen wird.
Relevante benutzerdefinierte Intents implementieren

Definierte Anfragen für benutzerdefinierten Intents beziehen sich auf den Inhalt und die Funktionen der App. Ein Beispiel für einen möglichen Verstoß gegen diese Richtlinie ist das Erstellen des Intents custom.action.intent.GET_RECIPE mit dem zugehörigen Anfragemuster „Zeig mir Burrito-Rezepte“ für eine App in der Play Store-Kategorie „Karten & Navigation“.