„Verknüpfungs.xml“ erstellen

Sobald Sie die In-App-Funktionen und den entsprechenden integrierten Intent identifiziert haben (BII) zur Implementierung, deklarieren Sie die BIIs, die Ihre Funktionalität unterstützt, indem Sie Ein capability-Element in einer shortcuts.xml-Ressourcendatei 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 Natural Language Processing, um Parameter aus einem Nutzer zu extrahieren Abfrage. In der Referenz zu integrierten Intents sind die Felder aufgeführt, die jede BII aus einer zugehörigen Nutzerabfrage extrahieren kann. Wenn z. B. ein Nutzer Ruft die Funktion [actions.intent.GET_FOOD_OBSERVATION][] in Ihrer Anwendung auf, indem sagt: „Hey Google, frag ExampleApp, was habe ich letzten Freitag zu Mittag gegessen?“, Assistant extrahiert 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 in capability definierte Auftragsausführung intent. Es können ein oder mehrere intent-Elemente in einer Funktion definiert werden, die verschiedenen Möglichkeiten berücksichtigen, wie ein Nutzer einen BII aufrufen kann. Zum Beispiel haben Sie könnte eine intent der Auftragsausführung definieren, für die beide BII-Parameter in der Beispiel oben. Anschließend können Sie einen zweiten Intent definieren, für den ein einzelner BII erforderlich ist. foodObservation.forMeal, der alle Mahlzeiten an einem bestimmten Tag anzeigt, z. B. „Hey Google, frage die ExampleApp, was ich zum Mittagessen gegessen habe.“.

ausgeführt werden können.

Übersicht

App Actions werden mithilfe einer shortcuts.xml-Datei in deiner App konfiguriert Verzeichnis res/xml des Projekts und erstellen dann einen Verweis auf shortcuts.xml in Ihrem App-Manifest ein. 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 sind auf die Aktion android.intent.action.MAIN und den android.intent.category.LAUNCHER.

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 Datei xml/shortcuts.xml in das APK. Weitere Informationen zum Konfigurieren von Verknüpfungen finden Sie in der Android-Entwicklerdokumentation unter Statische Verknüpfungen erstellen.

Die Jetpack-Mediathek androidx.core:core:1.6.0 (oder höher) ist in Ihrem Android-Projekt erforderlich, um Kompilierungsfehler zu vermeiden beim Definieren von App Actions-Funktionen in shortcuts.xml. Weitere Informationen finden Sie unter Erste Schritte mit Android Jetpack

Statische Tastenkombinationen

Beim Definieren deines capability kannst du statische shortcut-Elemente in shortcuts.xml, 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 das Erstellen neuer Versionen erstellt und aktualisiert werden können, Sie sind besonders nützlich, um häufige Aktivitäten und Inhalte in Ihrer App hervorzuheben.

Sie können die folgenden App Actions-Funktionen mit statischen Tastenkombinationen aktivieren:

• Tastenkombinationen für Funktionen. Erstellen von Verknüpfungen zum Starten einer Instanz Ihres capability mit vordefinierten intent-Parameterwerten. Beispiel: könnten Sie die App-Verknüpfung „Lauf los starten“ deklarieren das den Aufruf des START_EXERCISE BII-Funktion in Ihrer Fitness-App.

  Diese Tastenkombinationen enthalten die Attribute intent, shortLabel und longLabel. Dadurch können sie proaktiv als Chips vorgeschlagen und ausgeliefert werden. Oberflächen wie Assistant oder beim langen Drücken eines App-Symbols auf Android-Geräten Launchern. Ein Tastenkürzel für Aktionen kann auch als Tastenkürzel für Entitäten dienen, unten, indem Sie es mithilfe eines capability <capability-binding>-Tag.

• Tastenkombinationen für Entitäten: Tastenkombinationen für Entitäten enthalten eine Liste der unterstützten Parameter Werte für die Auftragsausführung per Sprachbefehl für capability. Beispiel: Eine Entität mit einer Liste von Trainingsarten wie „Wandern“, „Laufen“ usw. BII-Parameter exercise.name des START_EXERCISE Wenn eine Nutzeräußerung mit einer Entität übereinstimmt, lautet die shortcutId-ID an den Intent statt an den rohen Nutzerabfragewert übergeben wird.

  Entity-Tastenkombinationen definieren intent, shortLabel oder longLabel nicht Attribute werden auf proaktiven Oberflächen nicht vorgeschlagen. Für 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 beschrieben in shortcuts.xml Beim Einbeziehen eines Tags 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 (gilt 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 Funktionsschemas

In diesem Abschnitt werden die capability-Schemaelemente beschrieben.

<capability>

Ein capability, der den von Ihrer App unterstützten App Action-Intent definiert. Jedes Das <capability>-Element in Ihrer shortcuts.xml-Datei muss mindestens eines enthalten <intent> für die Ausführung der Aktion.

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. Dieses Attribut gilt nur für benutzerdefinierten Intents, da BIIs bereits Modelle der gängige Ausdrucksweise von Nutzenden zu erledigende Aufgaben oder 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> angeben Tags in einem capability. Assistant versucht, einer Nutzeranfrage mithilfe der erste <intent> in einer capability, für die alle erforderlichen Parameter sind bereitgestellt.

Attribute:

• android:action: der 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 für Beispiel: "com.example.exercise
• android:data: Dieses Feld wird von <url-template> überschrieben, wenn dieses Tag in der intent deklariert ist.

<URL-Vorlage>

Vorlage zum Erstellen eines Deep-Link-URI zu auf dem Gerät geöffnet werden kann. Die Vorlage kann mit integriertem Intent erweitert werden Parameter, wenn alle erforderlichen Parameter für die Vorlage verfügbar sind. Für Beispiele für die HTTP-URL-Vorlage finden Sie in der Wikipedia-Artikel zu URL-Vorlagen Die Das Vorlagenformat entspricht der Spezifikation der RFC 6570-URI-Vorlage.

Im Folgenden finden Sie einige Beispiele für URL-Vorlagenwerte:

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 für die Auftragsausführung

<Extra>

Definiert zusätzliche Daten für ein intent. Bei App Actions wird dieses Feld nur für Folgendes verwendet: [App-Aufruf im Vordergrund][] für capability 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 diesem intent-Parameter verknüpft werden soll. Der Name sollte ein Feld des BII-Parameters auf Blattebene (für Beispiel: foodObservation.aboutFood.name).
• android:key: vom Entwickler definierter Schlüssel eines BII-Parameterwerts. Beispiel: können Sie contact_name für den BII 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 Folgendes enthalten muss Parameter für diesen Intent, der für die Auftragsausführung verwendet werden soll. Wenn der Parameter nicht verfügbar ist, versucht Assistant, die Nutzeranfrage mithilfe der nächsten intent definiert für capability.

<shortcut-fulfillment>

Gibt an, dass ein intent, der in einer Verknüpfung für Inline-Inventar für ein Der angegebene parameter wird für die Auftragsausführung verwendet. Weitere Informationen finden Sie unter Auftragsausführung mithilfe von Shortcut-Intents.

<Parameter> (für <shortcut-fulfillment>)

Optionales Attribut, das einen einzelnen BII-Parameter dem Inline-Inventar zuordnet Shortcut-Ausführung. Weitere Informationen finden Sie unter Auftragsausführung mithilfe von Shortcut-Intents.

Attribut:

• android:name: Name des BII-Parameters, der der Direktauslieferung von In-Line-Inventar zugeordnet werden soll. Der Name sollte ein untergeordnetes Feld des BII-Parameters sein (z. B. menuItem.name).

<slice>

Ermöglicht Assistant, das Ergebnis einer Abfrage einzubetten, die mit dieser capability übereinstimmt als ein Android-Slice erstellen. Weitere Informationen finden Sie unter App-Aktionen in Android-Snippets einbinden.

Schema der Verknüpfung

In der folgenden Tabelle werden Attribute von shortcut-Elementen beschrieben, die für Folgendes verwendet werden: um die Funktion „App Actions“ zu aktivieren. 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.

<Verknüpfung>

Ein Android-<shortcut>, das in shortcuts.xml mit bestimmten Attributen definiert ist die für App Actions relevant sind. Stringwerte für shortcutShortLabel und shortcutLongLabel wird über die String-Ressourcen.

Attribute:

• android:shortcutId: Kennung für diesen Verknüpfung.
• android:shortcutShortLabel: Stringressource, die eine kurze Verknüpfung darstellt Wortgruppe. Beispiel: "@string/callDavidShort" steht für den Wert „Call David.“
• android:shortcutLongLabel: Stringressource, die eine lange Verknüpfung darstellt Wortgruppe. Beispiel: "@string/callDavidLong" steht für den Wert „Make an Audioanruf an David.“

<intent>

Der mit dieser Verknüpfung verknüpfte Android-Intent. intent wird ausgeführt, wenn ein Nutzer startet diese Verknüpfung per Sprachbefehl oder Berührung.

shortcut-Intent-Attribute sind identisch mit capability intent Attribute.

<capability-binding>

Verknüpft eine shortcut mit einer App Actions-capability. Dieses Element wird hinzugefügt zu Ein shortcut ermöglicht die Sprachausführung mit Assistant.

Attribute:

• android:key: Das android:name-Attribut von capability. shortcut ist gebunden. Beispiel: actions.intent.START_EXERCISE.

<Parameterbindung>

Optionales Attribut, das eine shortcut mit einem einzelnen Parameter einer App verknüpft Aktionen capability. Wenn für shortcut eine parameter-binding definiert ist, kann eine Inline-Inventarentität für einen BII-Parameter verwendet werden. Weitere Informationen finden Sie unter Inline-Inventar für App-Aktionen.

Attribute:

• android:key: Der Name des BII-Parameters capability, der verknüpft werden soll zu dieser Tastenkombination hinzu. Beispiel: exercise.name.
• android:value: der Wert entity. Dies kann eine einzelne entity oder ein Ressourcenliste.

<extra>

Die extra-Bundle-Daten für die Verknüpfung. sameAs sind die einzigen Daten relevant für App Actions-shortcut-Elemente. Die URL sameAs verweist auf eine Referenzwebseite, auf der die Entität eindeutig identifiziert wird. Wird verwendet, um einen Enum-Wert nur dann, wenn der Intent-Parametertyp ein Subtyp von schema.org/Enumeration. 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 Actions ist sameAs
• android:value: der URL-Wert sameAs

Weitere Informationen finden Sie unter Übereinstimmende Werte von Aufzählungsparametern abgleichen.

Optionen für die Intent-Auftragsausführung

Du definierst intent-Elemente innerhalb einer <capability>, um zu deklarieren, wie Assistant auf Sprachbefehle von Nutzern reagiert, die dieser Fähigkeit entsprechen, oder diese ausführen. Es gibt mehrere Möglichkeiten, um zu konfigurieren, wie ein intent ein Ausführungsziel startet je nachdem, wie die App-Navigation aufgebaut ist.

Die folgenden Optionen für die Auftragsausführung sind verfügbar:

• Explizite Intents: Starten Sie eine bestimmte App-Komponente, indem Sie den Parameter targetClass- und targetPackage-Attribute für die intent Dies ist die empfohlene Methode für die Auftragsausführung von App Actions.

• Deeplinks: Richten Sie App-Ziele mit Android-Deeplinks ein, indem Sie ein <url-template>-Tag im intent-Element. 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 intentandroid:data angeben. Dieses Feld wird durch Daten vom Typ „<url-template>“ überschrieben wenn dieses Tag auch in intent definiert ist.

Parameterdaten und Abgleich

Assistant sendet standardmäßig BII-Parameter, die aus der Nutzeranfrage extrahiert wurden, an Ihren App als extra-Daten des Android-intent gemäß der Definition in capability.

Alternativ können Sie ein <url-template>-Tag im capability, die 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.

Intent-Extras verwenden

Das folgende Beispiel zeigt einen expliziten Intent, der für einen capability definiert ist Auftragsausführung:

<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 Beispiel oben wird für eine Nutzeranfrage wie „Hey Google, bestelle einen Milchkaffee bei ExampleApp" erhalten, empfängt die Anwendung ein intent, das die Komponente aufruft: targetPackage, targetClass. 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 eine <url-template> in der intent definieren, um Android Deeplinks für die Auftragsausführung. Im folgenden Beispiel wird ein <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>

Im Beispiel oben wird für eine Nutzeranfrage wie „Hey Google, bestelle einen Milchkaffee“ from ExampleApp" erhalten, erhält die App die generierte URL: „myapp://start?exercise=Running“.

Um den BII-Parameter einer Position in Ihrer URL zuzuordnen, verwenden Sie die Methode Attribut android:name des Tags <parameter>. Dieses Attribut dem Wert android:key in der URL-Vorlage entspricht, die Sie durch Informationen des Nutzers ersetzt werden. Der Wert android:key muss vorhanden sein in <url-template> und in geschweiften Klammern ({}) gesetzt.

Aufgezählte Parameterwerte abgleichen

Einige BII-Parameter stellen Aufzählungswerte für Ihren Auftragsausführungs-Intent bereit, für Beispiel: die unterstützten Textwerte des BII RECORD_FOOD_OBSERVATION. Für diese Parameter enthält, ordnet Assistant die Suchanfrage des Nutzers ("Frühstück") einer Entität, deren sameAs-Wert mit der URL des Enum-Schemas übereinstimmt (https://schema.googleapis.com/MealTypeBreakfast) Zum Verknüpfen von enum Werte für eine unterstützte entity, deklarieren Sie eine sameAs Verknüpfung in Ihr shortcut. Im folgenden Beispiel wird eine sameAs-Verknüpfung für eine Inline-Verknüpfung für Entität:

<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 einen Übereinstimmung für „Frühstück“ Art der Mahlzeit, wird das folgende Extra mit dem Auftragsausführung intent:

• 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 Tastenkombinationen zur Steuerung der Entität verwendet werden Extraktion in eine Reihe unterstützter Entitäten, die in shortcuts.xml angegeben sind, Inline-Inventar. Weitere Informationen finden Sie unter Inline-Inventar.

Benutzerdefinierte Zielgruppen mit gemeinsamer Absicht

Benutzerdefinierte Intents können in shortcuts.xml deklariert werden, um Funktionen zur Sprachaktivierung in die nicht mit den verfügbaren BIIs übereinstimmen. Obwohl ähnlich in Funktionalität einer BII-Definition kombiniert werden, sind für benutzerdefinierte Intents zwei zusätzliche Attribute in shortcuts.xml:

• app:queryPatterns: Array-Ressource, die den Parameter unterschiedliche Abfragemuster für einen benutzerdefinierten Intent.

• android:mimeType: Parametertyp eines benutzerdefinierten Intents. Dieses Feld ist nicht erforderlich für BIIs, bei denen der Parametertyp bekannt ist. Für benutzerdefinierte Zielgruppen mit gemeinsamer Absicht Parameter verwendet werden, muss ein unterstützter semantischer Typ deklariert werden.

Weitere Informationen finden Sie unter Benutzerdefinierte Intents.