„Verknüpfungs.xml“ erstellen

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:

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 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 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 Entitätskürzel dienen, wie unten beschrieben. Dazu müssen Sie es mit einem capability ü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-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-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.

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-Typ Action. Die Standardeinstellung ist ACTION_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 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:

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

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: Das android:name-Attribut der capability, an die diese shortcut 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 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 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: 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 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 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 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.