„Verknüpfungs.xml“ erstellen

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:

  1. Suchen Sie in der Manifestdatei Ihrer App (AndroidManifest.xml) nach einer Aktivität, deren Intent-Filter auf die Aktion android.intent.action.MAIN und die Kategorie android.intent.category.LAUNCHER festgelegt sind.

  2. Fügen Sie in AndroidManifest.xml einen Verweis auf shortcuts.xml hinzu. Verwenden Sie dazu ein <meta-data>-Tag in Activity mit Intent-Filtern für MAIN und LAUNCHER:

    <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 vordefinierten intent-Parameterwerten starten. Sie können beispielsweise einen App-Shortcut „Laufen starten“ deklarieren, der die BII-Funktion START_EXERCISE in Ihrer Fitness-App aufruft.

    Diese Verknüpfungen enthalten die Attribute intent, shortLabel und longLabel. 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 einer capability 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-Parameter exercise.name der Funktion START_EXERCISE gebunden ist. Wenn eine Nutzeräußerung mit einer Entität übereinstimmt, wird die shortcutId-ID an den Intent übergeben, anstatt der Rohwert der Nutzerabfrage.

    Für Entity-Verknüpfungen werden keine intent-, shortLabel- oder longLabel-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>

android:name

app:queryPatterns (nur für benutzerdefinierte Intents)

<intent> <capability>

android:action (optional)

android:targetClass (optional)

android:targetPackage (optional)

android:data (optional)

<url-template> <intent>

android:value

<extra> <intent>

android:key

android:value

Gilt nur für die Aufrufung von Apps im Vordergrund

<parameter> <intent>

android:name

android:key

android:mimeType (gilt nur für benutzerdefinierte Intents)

android:required (optional)

app:shortcutMatchRequired (optional)

<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-Typ Action. Die Standardeinstellung ist ACTION_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 der intent 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"

"bar": "456"

https://example.com/test?foo=123&bar=456
https://example.com/test?utm_campaign=appactions{&foo,bar} "foo": "123"

"bar": "456"

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 diesem intent-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 beispielsweise contact_name für den BII-Parameter message.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ächsten intent zu erfüllen, der für die capability 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>

android:shortcutId

android:shortcutShortLabel

android:shortcutLongLabel (optional)

android:icon (optional)

<intent> <shortcut>

android:action

android:targetClass (optional)

android:targetPackage (optional)

android:data (optional)

<capability-binding> <shortcut>

android:key

<parameter-binding> <capability-binding>

android:key (optional)

android:value

<extra> <shortcut>

android:name (optional)

android:value

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: Das android:name-Attribut der capability, an die diese shortcut 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 des capability-BII-Parameters, dem diese Verknüpfung zugewiesen werden soll. Beispiel: exercise.name.
  • android:value: der Wert entity. Dies kann eine einzelne entity 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: Der sameAs-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 und targetPackage für die intent definieren. Dies ist die empfohlene Methode für die Auftragsausführung von App Actions.

  • Deeplinks: Wenn Sie ein <url-template>-Tag im Element intent 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 im intent 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".

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.