Nachdem Sie die In-App-Funktionen und den entsprechenden integrierten Intent (BII) für die Implementierung ermittelt haben, deklarieren Sie die BIIs, die Ihre Funktionalität unterstützt. Definieren Sie dazu ein capability
-Element in einer shortcuts.xml
-Ressourcendatei. Wenn Sie eine BII als capability
deklarieren, wird die Unterstützung für diesen semantischen Intent in Ihrer App registriert und die Ausführung von Anfragen per Sprachbefehl für den Intent mit Google Assistant ermöglicht.
Assistant verwendet Natural Language Processing, um Parameter aus einer Nutzerabfrage zu extrahieren. In der Referenz zu integrierten Intents sind die Felder aufgelistet, die von jeder BII aus einer verknüpften Nutzerabfrage extrahiert werden können. Wenn ein Nutzer beispielsweise die Funktion actions.intent.ORDER_MENU_ITEM
in Ihrer App mit „Hey Google, bestell eine Pizza bei ExampleCafe in ExampleApp“ aufruft, extrahiert Assistant die folgenden BII-Parameter aus der Nutzeranfrage:
menuItem.name
= "Pizza"menuItem.inMenuSection.inMenu.forRestaurant.name
= "BeispielCafé"
Assistant übergibt BII-Parameter an die intent
für die Auftragsausführung, die in capability
definiert ist. In einer Funktion können ein oder mehrere intent
-Elemente definiert werden, die den verschiedenen Möglichkeiten zum Aufrufen einer BII entsprechen. Im obigen Beispiel könnten Sie beispielsweise eine intent
für die Auftragsausführung definieren, die beide BII-Parameter erfordert. Sie könnten dann einen zweiten Intent definieren, der einen einzelnen BII-Parameter (menuItem.name
) erfordert, der Optionen für Restaurants in der Nähe anzeigt, wenn ein Nutzer eine einfachere Anfrage stellt, z. B. „Hey Google, bestell eine Pizza mit der Beispiel-App“.
Übersicht
App Actions konfigurieren Sie mithilfe einer shortcuts.xml
-Datei im Verzeichnis res/xml
Ihres App-Projekts. Anschließend erstellen Sie in Ihrem App-Manifest einen Verweis auf shortcuts.xml
. So fügen Sie in Ihrem App-Manifest einen Verweis zu shortcuts.xml
hinzu:
Suchen Sie in der Manifestdatei (
AndroidManifest.xml
) Ihrer App nach einer Aktivität, deren Intent-Filter auf die Aktionandroid.intent.action.MAIN
und die Kategorieandroid.intent.category.LAUNCHER
festgelegt sind.Fügen Sie so einen Verweis auf
shortcuts.xml
inAndroidManifest.xml
mit einem<meta-data>
-Tag inActivity
hinzu, das Intent-Filter fürMAIN
undLAUNCHER
enthält:<meta-data android:name="android.app.shortcuts" android:resource="@xml/shortcuts" />
Im obigen Beispiel wird eine XML-Ressource für die Datei xml/shortcuts.xml
im APK deklariert. Weitere Informationen zum Konfigurieren von Tastenkombinationen finden Sie in der Android-Entwicklerdokumentation unter Statische Verknüpfungen erstellen.
Die Jetpack-Bibliothek androidx.core:core:1.6.0
(oder höher) ist in Ihrem Android-Projekt erforderlich, um Kompilierungsfehler beim Definieren von App Actions-Funktionen in shortcuts.xml
zu vermeiden. Weitere Informationen finden Sie unter Erste Schritte mit Android Jetpack.
Statische Tastenkombinationen
Beim Definieren der capability
können Sie statische shortcut
-Elemente in shortcuts.xml
deklarieren, um die Funktionalität der Funktion zu erweitern. Statische Verknüpfungen werden von Assistant aufgenommen, wenn Sie einen Release in die Google Play Console hochladen.
Da statische Verknüpfungen nur durch das Erstellen von neuen Releases erstellt und aktualisiert werden können, sind sie am nützlichsten, um gängige Aktivitäten und Inhalte in Ihrer App hervorzuheben.
Mit statischen Tastenkombinationen können Sie die folgenden App Actions-Funktionen aktivieren:
Tastenkombinationen für Funktionen: Erstellen Sie Verknüpfungen, die eine Instanz Ihrer
capability
mit vordefiniertenintent
-Parameterwerten starten. Sie können beispielsweise die App-Verknüpfung „Lauf starten“ festlegen, durch die die BII-FunktionSTART_EXERCISE
in Ihrer Fitness-App aufgerufen wird.Diese Tastenkombinationen enthalten die Attribute
intent
,shortLabel
undlongLabel
. Dadurch können sie in proaktiven Oberflächen wie Assistant oder durch langes Drücken eines App-Symbols auf Android-Launchern als Chips vorgeschlagen und ausgeführt werden. Eine Aktionsverknüpfung kann auch als Entitätsverknüpfung dienen (siehe unten), indem sie über ein<capability-binding>
-Tag mit einemcapability
verknüpft wird.Tastenkombinationen für Elemente: Entitätsverknüpfungen bieten eine Liste der unterstützten Parameterwerte für die Auftragsausführung einer
capability
-Sprachabfrage. Beispiel: Entitätsverknüpfung mit einer Liste von Trainingstypen („Wandern“, „Laufen“ usw.), die an den BII-Parameterexercise.name
der FunktionSTART_EXERCISE
gebunden ist. Wenn eine Nutzeräußerung mit einer Entität übereinstimmt, wird dieshortcutId
-ID anstelle des Rohwerts der Nutzerabfrage an den Intent übergeben.Für
Entity
werden keineintent
-,shortLabel
- oderlongLabel
-Attribute definiert. Daher werden sie auf proaktiven Oberflächen nicht empfohlen. Weitere Informationen finden Sie unter Inline-Inventar für App Actions.
Funktionsschema
In der folgenden Tabelle wird das App Actions-Schema für capability
-Elemente in shortcuts.xml
beschrieben. Wenn Sie ein Tag einfügen, sind alle Attribute erforderlich, sofern sie nicht als „optional“ gekennzeichnet sind.
Tag „Shortcuts.xml“ | Enthalten in | Merkmale |
---|---|---|
<capability> |
<shortcuts> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
Gilt nur für Aufrufe von Apps im Vordergrund |
<parameter> |
<intent> |
|
<data> |
<parameter> |
android:pathPattern (nur für Webinventar) |
<shortcut-fulfillment> |
<capability> |
Gilt nur für Inline-Inventar |
<parameter> |
<shortcut-fulfillment> |
android:name |
<slice> |
<capability> |
Gilt nur für Android-Slices |
Beschreibung des Funktionsschemas
In diesem Abschnitt werden die capability
-Schemaelemente beschrieben.
<capability>
Ein capability
, der den App Action-Intent definiert, den deine App unterstützt. Jedes <capability>
-Element in der shortcuts.xml
-Datei muss mindestens einen <intent>
für die Ausführung der Aktion bereitstellen.
Attribute:
android:name
: ID der integrierten Intent-Aktion (z. B.actions.intent.CREATE_TAXI_RESERVATION
). Eine Liste der unterstützten integrierten Intents finden Sie in der Referenz zu integrierten Intents.app:queryPatterns
: Eine String-Array-Ressource mit Abfragen, die vom Nutzer für diesen Intent erwartet werden. Dieses Attribut gilt nur für benutzerdefinierte Intents, da BIIs bereits Modelle dafür enthalten, wie Nutzer die Aufgaben, die sie ausführen möchten, oder die gesuchten Informationen ausdrücken.
<intent>
Ein Android-intent
-Element, das definiert, wie eine Nutzerabfrage mithilfe von In-App-Funktionen ausgeführt werden soll. Entwickler können mehrere <intent>
-Tags in einer capability
angeben. Assistant versucht, eine Nutzeranfrage mit dem ersten <intent>
in einer capability
auszuführen, für die alle erforderlichen Parameter angegeben sind.
Attribute:
android:action
: der Intent-TypAction
. Die Standardeinstellung istACTION_VIEW
.android:targetClass
: Zielaktivitätsklasse, z. B."com.example.food.OrderActivity"
android:targetPackage
: Paket mit der Zielaktivitätsklasse, z. B."com.example.food"
android:data
: Dieses Feld wird durch<url-template>
überschrieben, wenn das Tag inintent
deklariert ist.
<URL-Vorlage>
Vorlage zum Erstellen eines Deeplinks-URI, der auf dem Gerät geöffnet werden soll. Die Vorlage kann mit integrierten Intent-Parametern erweitert werden, wenn alle erforderlichen Parameter für die Vorlage verfügbar sind. Beispiele für die HTTP-URL-Vorlage finden Sie im Wikipedia-Artikel zu URL-Vorlagen. Das Vorlagenformat entspricht der RFC6570-URI-Vorlagenspezifikation.
Im Folgenden finden Sie einige Beispiele für URL-Vorlagenwerte:
Vorlage | Werte | Erweiterter Wert |
---|---|---|
https://example.com/test{?foo,bar} |
"foo": "123"
|
https://example.com/test?foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{&foo,bar} |
"foo": "123"
|
https://example.com/test?utm_campaign=appactions&foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{#foo} |
"foo": "123" |
https://example.com/test?utm_campaign=appactions#foo=123 |
myapp://example/{foo} |
"foo": "123" |
myapp://example/123 |
Weitere Informationen zum Konfigurieren von URL-Vorlagen finden Sie unter URL-Vorlagen in der Auftragsausführung.
<extra>
Definiert zusätzliche Daten für intent
. Bei App Actions wird dieses Feld nur verwendet, um den Aufruf von Apps im Vordergrund für eine capability
zu aktivieren.
<Parameter>
Ordnet Intent-Parameterwerten einen BII-Parameter zu. Weitere Informationen finden Sie unter Parameterdaten und Abgleich.
Attribute:
android:name
: Name des BII-Parameters, der mit diesemintent
-Parameter verknüpft werden soll. Der Name sollte ein Feld auf Blattebene des BII-Parameters sein (z. B.foodObservation.aboutFood.name
).android:key
: Vom Entwickler definierter Schlüssel eines BII-Parameterwerts. Beispielsweise können Siecontact_name
für den BII-Parametermessage.recipient.name
definieren.android:mimeType
: Der mimeType des Parameters, z. B.text/*
. Dieses Feld ist nur für Parameter von benutzerdefinierten Intents erforderlich.android:required
: Gibt an, ob die Nutzerabfrage diesen Parameter enthalten muss, damit dieser Intent für die Auftragsausführung verwendet werden kann. Wenn der Parameter nicht verfügbar ist, versucht Assistant, die Nutzeranfrage mit der nächstenintent
auszuführen, die fürcapability
definiert ist.
<Daten>
Verknüpft ein Webinventar mit einem parameter
.
Attribut:
android:pathPattern
: URL-Muster fürentity
-URLs, die mithilfe von Webinventar zurückgegeben werden sollen. Dieses Attribut unterstützt zwei Platzhalter:*
: Ein Sternchen entspricht einer Folge von null oder mehr Vorkommen des unmittelbar vorangehenden Zeichens..*
: Ein Punkt, auf den ein Sternchen folgt, entspricht einer beliebigen Folge von null oder mehr Zeichen.Escape-Zeichen werden nur für das Literal
*
und\
benötigt, das Sie als\\*
bzw.\\\\
maskieren können.
<Verknüpfung-Auftragsausführung>
Gibt an, dass ein intent
, der in einer Verknüpfung für Inline-Inventar für einen angegebenen Parameter definiert ist, für die Auftragsausführung verwendet wird.
Weitere Informationen finden Sie unter Auftragsausführung mit Verknüpfungs-Intents.
<Parameter> (für <shortcut-fulfillment>
)
Optionales Attribut, das einen einzelnen BII-Parameter der Inline-Inventar-Verknüpfungsausführung zuordnet. Weitere Informationen finden Sie unter Auftragsausführung mit Verknüpfungs-Intents.
Attribut:
android:name
: Name des BII-Parameters, der mit der Inline-Inventar-Direktauftragsausführung verknüpft werden soll. Der Name sollte ein Feld auf Blattebene des BII-Parameters sein (z. B.menuItem.name
).
<slice>
Assistant kann das Ergebnis einer Abfrage, die mit diesem capability
übereinstimmt, als Android-Slice einbetten. Weitere Informationen findest du unter App-Aktionen in Android-Slices einbinden.
Verknüpfungsschema
In der folgenden Tabelle werden Attribute von shortcut
-Elementen beschrieben, mit denen die App Actions-Funktion aktiviert wird. Wenn Sie ein Tag einfügen, sind alle Attribute erforderlich, sofern sie nicht als „optional“ gekennzeichnet sind.
Tag „Shortcuts.xml“ | Enthalten in | Merkmale |
---|---|---|
<shortcut> |
<shortcuts> |
|
<intent> |
<shortcut> |
|
<capability-binding> |
|
|
<parameter-binding> |
<capability-binding> |
|
<extra> |
<shortcut> |
Gilt nur für den Enum-Parameterabgleich. |
Beschreibung des Verknüpfungsschemas
In diesem Abschnitt werden die shortcut
-Schemaelemente beschrieben.
<Verknüpfung>
Ein Android-<shortcut>
, das in shortcuts.xml
mit bestimmten Attributen definiert ist, die für App Actions relevant sind. Stringwerte für die Felder shortcutShortLabel
und shortcutLongLabel
werden über die Stringressourcen des APKs referenziert.
Attribute:
android:shortcutId
: ID für diese Verknüpfung.android:shortcutShortLabel
: Stringressource, die eine kurze Abkürzungsformulierung darstellt. Beispiel:"@string/callDavidShort"
für den Wert „Call David“.android:shortcutLongLabel
: Stringressource, die eine lange Kurzform darstellt. Beispiel:"@string/callDavidLong"
für den Wert „Audioanruf an David“.
<intent>
Android-Intent, der mit dieser Verknüpfung verknüpft ist. Die intent
wird ausgeführt, wenn ein Nutzer diese Verknüpfung per Sprachbefehl oder Berührung startet.
shortcut
-Intent-Attribute sind mit capability
-Attributen intent
identisch.
<capability-binding>
Verknüpft eine shortcut
mit einer App Actions-capability
. Wenn Sie dieses Element zu einem shortcut
hinzufügen, wird es für die Sprachausführung mit Assistant
aktiviert.
Attribute:
android:key
: Das Attributandroid:name
dercapability
, an die dieseshortcut
gebunden ist. Beispiel:actions.intent.CREATE_TAXI_RESERVATION
.
<Parameterbindung>
Optionales Attribut, das eine shortcut
mit einem einzelnen Parameter einer App-Aktions-capability
verknüpft. Wenn für eine shortcut
eine parameter-binding
definiert ist, kann über die Verknüpfung eine Inline-Inventarentität für einen BII-Parameter bereitgestellt werden.
Weitere Informationen finden Sie unter Inline-Inventar für App Actions.
Attribute:
android:key
: Der Name des BII-Parameterscapability
, mit dem diese Verknüpfung verknüpft werden soll. z. B.foodObservation.aboutFood.name
.android:value
: der Wert vonentity
. Dies kann eine einzelneentity
oder eine Ressourcenliste sein.
<extra>
Die extra
-Bundle-Daten für die Verknüpfung. sameAs sind die einzigen Daten, die für shortcut
-Elemente von App Actions relevant sind. Die sameAs-URL verweist auf eine Referenzwebseite, auf der die Entität eindeutig identifiziert wird. Wird verwendet, um einen ENUM-Wert nur dann anzugeben, wenn der Intent-Parametertyp ein Untertyp von schema.org/Enumeration ist. Es ist für Parameterfelder erforderlich, deren Typen Untertypen von schema.org/Enumeration
sind (z. B. MealTypeBreakfast
).
Attribute:
android:key
: Der unterstützte Wert für App-Aktionen istsameAs
android:value
: der URL-WertsameAs
Weitere Informationen finden Sie unter Abgleich von aufgezählten Parameterwerten.
Optionen für die Intent-Auftragsausführung
Sie definieren intent
-Elemente in einer <capability>
, um anzugeben, wie Assistant auf Sprachbefehle von Nutzern reagiert oder diese ausführt, die dieser Funktion entsprechen. Je nach Struktur der App-Navigation gibt es mehrere Möglichkeiten zu konfigurieren, wie ein intent
ein Ausführungsziel in der App startet.
Die folgenden Optionen für die Auftragsausführung sind verfügbar:
Explizite Intents: Starten Sie eine bestimmte App-Komponente, indem Sie die Attribute
targetClass
undtargetPackage
für dieintent
definieren. Dies ist die empfohlene Auftragsausführungsmethode für App Actions.Deeplinks: Starten Sie App-Ziele mit Android-Deeplinks, indem Sie ein
<url-template>
-Tag imintent
-Element definieren. Diese Methode ist nützlich, wenn Ihre App-Navigation bereits auf Deeplinks basiert.Intent-Daten: Sie können einen Auftragsausführungs-URI im Attribut
intent
android:data
angeben. Dieses Feld wird mit<url-template>
-Daten überschrieben, wenn das Tag auch inintent
definiert ist.
Parameterdaten und Abgleich
Standardmäßig sendet Assistant BII-Parameter, die aus der Nutzerabfrage extrahiert wurden, als extra
-Daten der Android-intent
, die in der capability
definiert sind, an deine App.
Alternativ können Sie ein <url-template>
-Tag in capability
deklarieren, das Platzhalter für dynamische Parameter enthält. Diese Vorlage ist einer Ihrer Android-Aktivitäten zugeordnet. Dabei wird eine App-Link-URL, ein benutzerdefiniertes Schema oder eine Intent-basierte URL verwendet.
Intent-Extras verwenden
Das folgende Beispiel zeigt einen expliziten Intent, der für eine capability
-Auftragsausführung definiert wird:
<capability android:name="actions.intent.ORDER_MENU_ITEM">
<intent
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.OrderMenuItemActivity">
<parameter android:name="menuItem.name" android:key="menu" />
</intent>
</capability>
Anhand des Beispiels oben erhält die App für eine Nutzeranfrage wie „Hey Google, bestelle einen Latte bei ExampleApp“ ein intent
, das die Komponente targetPackage
, targetClass
aufruft. Die Komponente erhält ein Extra mit key = ”menu”
, value = ”latte”
.
URL-Vorlage für Android-Deeplinks verwenden
Wenn deine App bereits mit der App verknüpfte URLs mit dynamischen Parametern verarbeiten kann, kannst du ein <url-template>
im intent
definieren, um Android-Deeplinks für die Auftragsausführung zu generieren. Im folgenden Beispiel wird ein <url-template>
definiert:
<capability android:name="actions.intent.ORDER_MENU_ITEM">
<intent>
<url-template android:value="myapp://order{?menu}" />
<parameter android:name="menuItem.name" android:key="menu" />
</intent>
</capability>
Im obigen Beispiel erhält die App für eine Nutzeranfrage wie „Hey Google, order a Latte from ExampleApp“ die folgende generierte URL: „myapp://order?menu=latte“.
Wenn Sie den BII-Parameter einer Position in Ihrer URL zuordnen möchten, verwenden Sie das Attribut android:name
des Tags <parameter>
. Dieses Attribut entspricht dem Wert android:key
in der URL-Vorlage, den Sie durch Nutzerinformationen ersetzen möchten. Der Wert android:key
muss in der <url-template>
vorhanden sein und in geschweifte Klammern ({}
) gesetzt sein.
Aufgezählte Parameterwerte abgleichen
Einige BII-Parameter stellen Aufzählungswerte für den Auftragsausführungs-Intent bereit, z. B. die unterstützten Textwerte von RECORD_FOOD_OBSERVATION
BII. Bei diesen Parametern ordnet Assistant die Nutzeranfrage („Frühstück“) einer Entität zu, deren sameAs
-Wert der URL des enum-Schemas (https://schema.googleapis.com/MealTypeBreakfast
) entspricht. Zum Verknüpfen von Aufzählungswerten für eine unterstützte entity
müssen Sie eine sameAs
-Verknüpfung in Ihrer shortcut
deklarieren. Im folgenden Beispiel wird eine sameAs
-Verknüpfung für eine Inline-Entitätsverknüpfung dargestellt:
<shortcut android:shortcutId="meal_breakfast" >
<capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
<parameter-binding android:key="foodObservation.forMeal" />
</capability-binding>
<extra
android:key="sameAs"
android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>
<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
<intent targetPackage="com.example.app" targetClass="com.example.app.Class">
<parameter android:name="foodObservation.forMeal" android:key="for_meal" />
</intent>
</capability>
Wenn im obigen Beispiel die Funktion RECORD_FOOD_OBSERVATION
eine Übereinstimmung für den Mahlzeitentyp „Frühstück“ auslöst, wird das folgende Extra mit der Auftragsausführung intent
gesendet:
key = "for_meal"
value = "meal_breakfast"
Funktionen
Die folgenden App Actions-Funktionen sind in shortcuts.xml
verfügbar.
Inline-Inventar für App-Aktionen
Bei einigen BII-Parametern können Tastenkombinationen verwendet werden, um die Entitätsextraktion auf eine Reihe unterstützter Entitäten zu verweisen, die in shortcuts.xml
angegeben sind (Inline-Inventar). Weitere Informationen finden Sie unter Inline-Inventar.
Webinventar für App Actions
Bei einigen BIIs können Sie ein Webinventar verwenden, um URLs für die Auftragsausführung zu generieren. Webinventar verwendet Ihre Website, um URLs für die Auftragsausführung von App-Aktionen zu ermitteln. Diese Funktion ist besonders nützlich, wenn du eine starke Webpräsenz hast und deine In-App-Deeplinks um öffentlich verfügbare Webinhalte angeordnet sind.
Weitere Informationen finden Sie unter Webinventar.
Benutzerdefinierte Zielgruppen mit gemeinsamer Absicht
Benutzerdefinierte Intents können in shortcuts.xml
für Funktionen zur Sprachaktivierung in Ihrer App deklariert werden, die nicht mit den verfügbaren BIIs übereinstimmen. Benutzerdefinierte Intents haben einen ähnlichen Funktionsumfang wie eine BII-Definition, erfordern aber in shortcuts.xml
zwei zusätzliche Attribute:
app:queryPatterns
: Array-Ressource, die die verschiedenen Abfragemuster für einen benutzerdefinierten Intent deklariertandroid:mimeType
: Parametertyp eines benutzerdefinierten Intents. Dieses Feld ist für BIIs, bei denen der Parametertyp bekannt ist, nicht erforderlich. Für benutzerdefinierte Intent-Parameter muss ein unterstützter semantischer Typ deklariert werden.
Weitere Informationen finden Sie unter Benutzerdefinierte Intents.