Nachdem Sie die In-App-Funktion und den entsprechenden integrierten Intent (BII) identifiziert haben, deklarieren Sie die BIIs, die von Ihrer Funktion unterstützt werden, 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. Du könntest beispielsweise eine intent
für die Auftragsausführung definieren, für die beide BII-Parameter im obigen Beispiel erforderlich sind. Sie können dann eine zweite Absicht definieren, für die ein einzelner BII-Parameter (foodObservation.forMeal
) erforderlich ist, der Berichte zu allen Mahlzeiten an einem bestimmten Tag enthält, z. B. „Hey Google, frage BeispielApp, was ich zum Mittag 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 finden Sie 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 finden Sie 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 Entitätskürzel dienen, wie unten beschrieben. Dazu müssen Sie es mit einemcapability
über ein<capability-binding>
-Tag verknüpfen.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-Aktionen-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 Stringarray-Ressource mit Suchanfragen, die vom Nutzer für diese Absicht 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
zu erfüllen, für die alle erforderlichen Parameter angegeben sind.
Attribute:
android:action
: den Intent-TypAction
. Die Standardeinstellung istACTION_VIEW
.android:targetClass
: Zielaktivitätsklasse, z. B.:"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-Aktionen wird dieses Feld nur verwendet, um [foreground app invocation][] 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 untergeordnetes Feld des BII-Parameters 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 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 dem nächstenintent
zu erfüllen, der für diecapability
definiert ist.
<shortcut-fulfillment>
Gibt an, dass ein intent
, das in einem Inline-Inventar-Verknüpfungselement für einen bestimmten Parameter definiert ist, für die Auftragsausführung verwendet werden soll.
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 mit Kurzbefehlsabsichten.
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 finden Sie unter App-Aktionen in Android-Snippets einbinden.
Verknüpfungsschema
In der folgenden Tabelle werden die Attribute von shortcut
-Elementen beschrieben, mit denen die App-Aktionsfunktion aktiviert wird. 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> |
Nur für die Übereinstimmung von Enum-Parametern. |
Schemabeschreibung für Verknüpfungen
In diesem Abschnitt werden die shortcut
-Schemaelemente beschrieben.
<shortcut>
Eine in shortcuts.xml
definierte Android-<shortcut>
mit bestimmten Attributen, die für App-Aktionen relevant sind. Auf Stringwerte für die Felder shortcutShortLabel
und shortcutLongLabel
wird über die Stringressourcen der APK verwiesen.
Attribute:
android:shortcutId
: Kennung für diesen Verknüpfung.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
.
<parameter-binding>
Optionales Attribut, das einem shortcut
einen einzelnen Parameter einer App-Aktion capability
zuordnet. Wenn für eine shortcut
eine parameter-binding
definiert ist, kann über die Verknüpfung eine Inventar-Inline-Entität für einen BII-Parameter angegeben werden.
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 URL von sameAs 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 App-Aktionen-Ausführungsmethode.Deeplinks: Sie können App-Ziele über Android-Deeplinks starten, indem Sie im
intent
-Element das Tag<url-template>
definieren. 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 im capability
ein <url-template>
-Tag mit Platzhaltern für dynamische Parameter deklarieren. 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>
Im obigen Beispiel erhält die App bei einer Nutzeranfrage wie „Hey Google, starte meinen Lauf“ 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 Ihre App bereits App-verknüpfte URLs mit dynamischen Parametern verarbeiten kann, können Sie im Feld intent
eine <url-template>
definieren, um Android-Deeplinks für die Ausfü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>
Bei der obigen Beispielanfrage „Hey Google, starte meinen Lauf“ 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, der durch Informationen des Nutzers ersetzt werden soll. 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 einem Element ab, dessen sameAs
-Wert mit der URL des Enum-Schemas (https://schema.googleapis.com/MealTypeBreakfast
) übereinstimmt. Wenn Sie Enum-Werte für eine unterstützte entity
verknüpfen möchten, deklarieren Sie in Ihrer shortcut
eine sameAs
-Verknüpfung. Im folgenden Beispiel wird eine sameAs
-Verknüpfung für einen Inline-Entitäts-Verknüpfungs-Shortcut veranschaulicht:
<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-Aktionen
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 ähneln zwar in ihrer Funktionalität einer BII-Definition, erfordern aber zwei zusätzliche Attribute in shortcuts.xml
:
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.