Nachdem Sie die In-App-Funktion und den entsprechenden zu implementierenden integrierten Intent (integrierte Intents) identifiziert haben, müssen Sie die von der Funktion unterstützten BIIs deklarieren, indem Sie ein capability
-Element in einer shortcuts.xml
-Ressourcendatei definieren. Wenn Sie einen BII als capability
deklarieren, wird die Unterstützung für diesen semantischen Intent in Ihrer App registriert und die Ausführung der Sprachabfrage für den Intent über Google Assistant ermöglicht.
Assistant verwendet die Verarbeitung natürlicher Sprache, um Parameter aus einer Nutzerabfrage zu extrahieren. In der Referenz zu integrierten Intents sind die Felder aufgeführt, die jede BII aus einer zugehörigen Nutzerabfrage extrahieren kann. Wenn ein Nutzer beispielsweise die Funktion [actions.intent.GET_FOOD_OBSERVATION
][] in Ihrer App aufruft, indem er sagt: „Hey Google, frage BeispielApp, was ich letzten Freitag zum Mittag gegessen habe“, extrahiert Assistant die folgenden BII-Parameter aus der Nutzeranfrage:
foodObservation.forMeal
= "https://schema.googleapis.com/MealTypeLunch"foodObservation.startTime
= "2024-09-06T00:00:00"foodObservation.endTime
= „2024-09-06T23:59:59“
Assistant übergibt BII-Parameter an die im capability
definierte Auftragsausführung intent
. In einer Funktion können ein oder mehrere intent
-Elemente definiert werden, um die verschiedenen Möglichkeiten zu berücksichtigen, wie ein Nutzer eine BII aufrufen kann. Sie könnten beispielsweise eine Auftragsausführung intent
definieren, für die im obigen Beispiel beide BII-Parameter erforderlich sind. Sie können dann einen zweiten Intent definieren, der einen einzigen BII-Parameter, foodObservation.forMeal
, der alle Mahlzeiten an einem bestimmten Tag erfordert, z. B. „Hey Google, Ask ExampleApp, was habe ich zum Mittagessen gegessen habe“.
Übersicht
Sie konfigurieren App-Aktionen mit einer shortcuts.xml
-Datei, die Sie im Verzeichnis res/xml
Ihres App-Projekts platzieren. Anschließend erstellen Sie im App-Manifest einen Verweis auf shortcuts.xml
. So fügen Sie Ihrem App-Manifest eine Referenz auf shortcuts.xml
hinzu:
Suchen Sie in der Manifestdatei Ihrer App (
AndroidManifest.xml
) nach einer Aktivität, deren Intent-Filter auf die Aktionandroid.intent.action.MAIN
und die Kategorieandroid.intent.category.LAUNCHER
festgelegt sind.Fügen Sie in
AndroidManifest.xml
einen Verweis aufshortcuts.xml
hinzu. Verwenden Sie dazu ein<meta-data>
-Tag inActivity
mit Intent-Filtern fürMAIN
undLAUNCHER
:<meta-data android:name="android.app.shortcuts" android:resource="@xml/shortcuts" />
Im obigen Beispiel wird eine XML-Ressource für die xml/shortcuts.xml
-Datei im APK deklariert. Weitere Informationen zum Konfigurieren von Verknüpfungen findest du in der Android-Entwicklerdokumentation unter Statische Verknüpfungen erstellen.
In Ihrem Android-Projekt ist die Jetpack-Bibliothek androidx.core:core:1.6.0
(oder höher) erforderlich, um Kompilierungsfehler beim Definieren von App Actions-Funktionen in shortcuts.xml
zu vermeiden. Weitere Informationen findest du unter Erste Schritte mit Android Jetpack.
Statische Tastenkombinationen
Wenn Sie capability
definieren, 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 eine Version in die Google Play Console hochladen.
Da statische Verknüpfungen nur durch Erstellen neuer Releases erstellt und aktualisiert werden können, eignen sie sich am besten, um häufige Aktivitäten und Inhalte in Ihrer App hervorzuheben.
Sie können die folgenden App-Aktionsfunktionen mit statischen Verknüpfungen aktivieren:
Tastenkürzel für Funktionen Erstellen Sie Verknüpfungen, die eine Instanz von
capability
mit vordefiniertenintent
-Parameterwerten starten. Sie können beispielsweise einen App-Shortcut „Laufen starten“ deklarieren, der die BII-FunktionSTART_EXERCISE
in Ihrer Fitness-App aufruft.Diese Verknüpfungen enthalten die Attribute
intent
,shortLabel
undlongLabel
. Sie können daher in proaktiven Oberflächen wie Assistant oder beim langen Drücken auf ein App-Symbol in Android-Launchern als Chips vorgeschlagen und ausgeführt werden. Ein Aktionskürzel kann auch als Verknüpfung für Entitäten dienen (siehe unten). Dazu wird es mithilfe eines<capability-binding>
-Tags mit einercapability
verknüpft.Entitätskürzel Entitätsverknüpfungen enthalten eine Liste der unterstützten Parameterwerte für die Ausführung von Sprachabfragen für eine
capability
. Beispiel: Ein Entitäts-Shortcut mit einer Liste von Trainingstypen („Wandern“, „Laufen“ usw.), der an den BII-Parameterexercise.name
der FunktionSTART_EXERCISE
gebunden ist. Wenn eine Nutzeräußerung mit einer Entität übereinstimmt, wird dieshortcutId
-ID an den Intent übergeben, anstatt der Rohwert der Nutzerabfrage.Für
Entity
-Verknüpfungen werden keineintent
-,shortLabel
- oderlongLabel
-Attribute definiert. Daher werden sie auf proaktiven Oberflächen nicht vorgeschlagen. Weitere Informationen finden Sie unter Inline-Inventar für App-Aktionen.
Schema für Fähigkeiten
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 zugehörigen Attribute erforderlich, sofern sie nicht als „optional“ gekennzeichnet sind.
Shortcuts.xml-Tag | Enthalten in | Attribute |
---|---|---|
<capability> |
<shortcuts> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
Gilt nur für die Aufrufung von Apps im Vordergrund |
<parameter> |
<intent> |
|
<shortcut-fulfillment> |
<capability> |
Gilt nur für Inline-Inventar |
<parameter> |
<shortcut-fulfillment> |
android:name |
<slice> |
<capability> |
Gilt nur für Android Slices |
Beschreibung des Schemas für Fähigkeiten
In diesem Abschnitt werden die capability
-Schemaelemente beschrieben.
<capability>
Ein capability
, das die App-Aktionsabsicht definiert, die von Ihrer App unterstützt wird. Jedes <capability>
-Element in Ihrer shortcuts.xml
-Datei muss mindestens ein <intent>
enthalten, um die Ausführung der Aktion zu steuern.
Attribute:
android:name
: Aktions-ID der integrierten Absicht (z. B. [actions.intent.GET_FOOD_OBSERVATION
][]). Eine Liste der unterstützten integrierten Absichten finden Sie in der Referenz zu integrierten Absichten.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 der gängigen Ausdrucksweisen von Nutzern für die Aufgaben enthalten, die sie ausführen möchten, oder die Informationen, nach denen sie suchen.
<intent>
Android-Element intent
, das festlegt, wie eine Nutzerabfrage mithilfe von In-App-Funktionen erfüllt werden soll. Entwickler können mehrere <intent>
-Tags in einem 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, zum Beispiel:"com.example.exercise.ExerciseActivity"
android:targetPackage
: Paket mit der Zielaktivitätsklasse, z. B."com.example.exercise
android:data
: Dieses Feld wird von<url-template>
überschrieben, wenn dieses Tag in derintent
deklariert ist.
<url-template>
Vorlage zum Erstellen eines Deeplink-URIs, 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 URI-Vorlagenspezifikation RFC6570.
Im Folgenden finden Sie einige Beispiele für Werte für URL-Vorlagen:
Vorlage | Werte | Maximierter 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 bei der Auftragsausführung.
<extra>
Definiert zusätzliche Daten für eine intent
. Bei App Actions wird dieses Feld nur verwendet, um den [App-Aufruf im Vordergrund][] für eine capability
zu aktivieren.
<Parameter>
Ordnet einen BII-Parameter Intent-Parameterwerten 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 des BII-Parameters auf Blattebene sein (z. B.foodObservation.aboutFood.name
).android:key
: Vom Entwickler definierter Schlüssel eines BII-Parameterwerts. Sie können beispielsweisecontact_name
für den BII-Parametermessage.recipient.name
definieren.android:mimeType
: Der MIME-Typ 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 dem nächstenintent
zu erfüllen, der für diecapability
definiert ist.
<shortcut-fulfillment>
Gibt an, dass eine in einer Verknüpfung für Inline-Inventar definierte intent
für einen angegebenen Parameter für die Auftragsausführung verwendet wird.
Weitere Informationen finden Sie unter Auftragsausführung mit Kurzbefehlsabsichten.
<parameter> (für <shortcut-fulfillment>
)
Optionales Attribut, das einen einzelnen BII-Parameter der Direktausführung für Inventar-Shortcuts zuordnet. Weitere Informationen finden Sie unter Auftragsausführung mithilfe von Shortcut-Intents.
Attribut:
android:name
: Name des BII-Parameters, der der Direktausführung für Inline-Inventar zugeordnet werden soll. Der Name sollte ein untergeordnetes Feld des BII-Parameters sein (z. B.menuItem.name
).
<slice>
Ermöglicht es Assistant, das Ergebnis einer Abfrage, die mit dieser capability
übereinstimmt, als Android-Snippet einzubetten. Weitere Informationen findest du unter App Actions in Android-Slices einbinden.
Verknüpfungsschema
In der folgenden Tabelle werden Attribute von shortcut
-Elementen beschrieben, mit denen App Actions-Funktionen aktiviert werden. Wenn Sie ein Tag einfügen, sind alle zugehörigen Attribute erforderlich, sofern sie nicht als „optional“ gekennzeichnet sind.
Shortcuts.xml-Tag | Enthalten in | Attribute |
---|---|---|
<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.
<shortcut>
Ein in shortcuts.xml
definiertes Android-<shortcut>
mit bestimmten Attributen, die für App Actions relevant sind. Auf Stringwerte für die Felder shortcutShortLabel
und shortcutLongLabel
wird über die Stringressourcen der APK verwiesen.
Attribute:
android:shortcutId
: ID für diese Tastenkombination.android:shortcutShortLabel
: Stringressource, die eine kurze Tastenkombination darstellt. Beispiel:"@string/callDavidShort"
steht für den Wert „David anrufen“.android:shortcutLongLabel
: Stringressource, die eine lange Tastenkombination darstellt. Beispiel:"@string/callDavidLong"
steht für den Wert „David anrufen“.
<intent>
Der mit dieser Verknüpfung verknüpfte Android-Intent. Diese intent
wird ausgeführt, wenn ein Nutzer diese Verknüpfung per Sprachbefehl oder Berührung startet.
shortcut
-Intent-Attribute sind mit capability
-intent
-Attributen identisch.
<capability-binding>
Ordnet eine shortcut
einer capability
für App Actions zu. Wenn Sie dieses Element einem shortcut
hinzufügen, kann es per Sprachbefehl mit Assistant
ausgeführt werden.
Attribute:
android:key
: Dasandroid:name
-Attribut dercapability
, an die dieseshortcut
gebunden ist. Beispiel:actions.intent.START_EXERCISE
.
<Parameterbindung>
Optionales Attribut, das einem shortcut
einen einzelnen Parameter einer App-Aktion capability
zuordnet. Wenn eine parameter-binding
für eine shortcut
definiert ist, kann die Verknüpfung verwendet werden, um eine Inline-Inventarentität für einen BII-Parameter anzugeben.
Weitere Informationen finden Sie unter Inline-Inventar für App-Aktionen.
Attribute:
android:key
: Der Name descapability
-BII-Parameters, dem diese Verknüpfung zugewiesen werden soll. Beispiel:exercise.name
.android:value
: der Wertentity
. Dies kann eine einzelneentity
oder eine Ressourcenliste sein.
<Extra>
Die extra
-Bundle-Daten für den Shortcut. sameAs ist das einzige Datenelement, das für shortcut
-Elemente von App-Aktionen relevant ist. Die sameAs-URL verweist auf eine Referenzwebseite, auf der die Entität eindeutig identifiziert wird. Wird verwendet, um einen Wertebereich anzugeben, wenn und nur wenn der Typ des Intent-Parameters ein Untertyp von schema.org/Enumeration ist. Er 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 ist:sameAs
android:value
: DersameAs
-URL-Wert
Weitere Informationen finden Sie unter Abgleich von Parameterwerten mit einer Aufzählung.
Optionen für die Intent-Ausführung
Sie definieren intent
-Elemente in einem <capability>
, um anzugeben, wie Assistant auf Sprachbefehle von Nutzern reagiert oder diese erfüllt, die mit dieser Funktion übereinstimmen. Je nachdem, wie die Navigation in Ihrer App strukturiert ist, gibt es mehrere Möglichkeiten, die Ausführung eines intent
-Auftrags in Ihrer App zu konfigurieren.
Folgende Optionen für die Auftragsausführung sind verfügbar:
Explizite Intents: Sie können eine bestimmte App-Komponente starten, indem Sie die Attribute
targetClass
undtargetPackage
für dieintent
definieren. Dies ist die empfohlene Methode für die Auftragsausführung von App Actions.Deeplinks: Wenn Sie ein
<url-template>
-Tag im Elementintent
definieren, können Sie App-Ziele mit Android-Deeplinks aufrufen. Diese Methode ist nützlich, wenn die Navigation in Ihrer App bereits auf Deeplinks basiert.Intent-Daten: Sie können einen Ausführungs-URI im Attribut
intent
android:data
angeben. Dieses Feld wird von<url-template>
-Daten überschrieben, wenn dieses Tag auch imintent
definiert ist.
Parameterdaten und Abgleich
Standardmäßig sendet Assistant BII-Parameter, die aus der Nutzeranfrage extrahiert wurden, als extra
-Daten der im capability
definierten Android-intent
an Ihre App.
Alternativ können Sie ein <url-template>
-Tag in capability
deklarieren, das Platzhalter für dynamische Parameter enthält. Diese Vorlage wird einer Ihrer Android-Aktivitäten mithilfe einer App-Links-URL, eines benutzerdefinierten Schemas oder einer Intent-basierten URL zugeordnet.
Zusatzoptionen für Intents verwenden
Das folgende Beispiel zeigt einen expliziten Intent, der für die Ausführung einer capability
-Aufgabe definiert ist:
<capability android:name="actions.intent.START_EXERCISE">
<intent
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.ExerciseActivity">
<parameter android:name="exercise.name" android:key="exercise" />
</intent>
</capability>
Angenommen, ein Nutzer sagt Hey Google, bestelle einen Latte über die Beispiel-App. In diesem Fall erhält die App eine intent
, die die Komponente targetPackage
, targetClass
aufruft. Die Komponente erhält ein Extra mit key = "exercise"
, value = "Running"
.
URL-Vorlage für Android-Deeplinks verwenden
Wenn deine App bereits über Apps verknüpfte URLs mit dynamischen Parametern verarbeiten kann, kannst du in der intent
eine <url-template>
definieren, um Android-Deeplinks für die Auftragsausführung zu generieren. Im folgenden Beispiel wird eine <url-template>
definiert:
<capability android:name="actions.intent.START_EXERCISE">
<intent>
<url-template android:value="myapp://start{?exercise}" />
<parameter android:name="exercise.name" android:key="exercise" />
</intent>
</capability>
Angenommen, ein Nutzer sagt „Hey Google, bestelle einen Latte bei Beispiel-App“. In diesem Fall erhält die App die generierte URL „myapp://start?exercise=Running“.
Um den BII-Parameter einer Position in Ihrer URL zuzuordnen, verwenden Sie das android:name
-Attribut des <parameter>
-Tags. Dieses Attribut entspricht dem Wert android:key
in der URL-Vorlage, den du durch Informationen des Nutzers ersetzen möchtest. Der Wert android:key
muss in <url-template>
vorhanden sein und in geschweifte Klammern ({}
) gesetzt werden.
Aufzählungswerte mit Parameterwerten abgleichen
Einige BII-Parameter stellen für Ihre Auftragsabsicht aufgezählte Werte bereit, z. B. die unterstützten Textwerte des BII RECORD_FOOD_OBSERVATION
. Bei diesen Parametern gleicht Assistant die Suchanfrage des Nutzers ("Frühstück") mit einer Entität ab, deren sameAs
-Wert mit der URL des Enum-Schemas (https://schema.googleapis.com/MealTypeBreakfast
) übereinstimmt. Zum Verknüpfen von Enum-Werten für eine unterstützte entity
deklarieren Sie eine sameAs
-Verknüpfung in Ihrer shortcut
. Das folgende Beispiel zeigt eine sameAs
-Verknüpfung für eine Inline-Entitätsverknüpfung:
<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 Beispiel oben die Funktion RECORD_FOOD_OBSERVATION
eine Übereinstimmung für den Essenstyp „Frühstück“ auslöst, wird das folgende Extra mit der Ausfü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 Actions
Bei einigen BII-Parametern können Verknüpfungen verwendet werden, um die Entitätsextraktion auf eine Reihe von unterstützten Entitäten in shortcuts.xml
zu lenken, die als „Inline-Inventar“ bezeichnet werden. Weitere Informationen finden Sie unter Inline-Inventar.
Benutzerdefinierte Zielgruppen mit gemeinsamer Absicht
Benutzerdefinierte Intents können in shortcuts.xml
deklariert werden, um Funktionen in Ihrer App per Sprachbefehl zu aktivieren, die nicht mit verfügbaren BII-Konten übereinstimmen. Benutzerdefinierte Intents haben zwar ähnliche Funktionen wie eine BII-Definition, erfordern aber in shortcuts.xml
zwei zusätzliche Attribute:
app:queryPatterns
: Arrayressource, in der die verschiedenen Abfragemuster für eine benutzerdefinierte Absicht deklariert werden.android:mimeType
: Parametertyp einer benutzerdefinierten Intent-Definition. Dieses Feld ist für BIIs nicht erforderlich, bei denen der Parametertyp bekannt ist. Für benutzerdefinierte Intent-Parameter muss ein unterstützter semantischer Typ deklariert werden.
Weitere Informationen finden Sie unter Benutzerdefinierte Intents.