„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 BII deklarieren als capability die Unterstützung für diesen semantischen Intent in Ihrer App registriert und ermöglicht die Ausführung von Sprachbefehlen für den Intent mithilfe von Google Assistant.

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 für jeden BII verwendet werden. Daten aus einer verknüpften Nutzeranfrage extrahieren können. Wenn ein Nutzer z. B. Ruft die Funktion actions.intent.ORDER_MENU_ITEM in Ihrer Anwendung auf, indem sagt: „Hey Google, bestelle eine Pizza bei ExampleCafe in ExampleApp“, Assistant extrahiert die folgenden BII-Parameter aus der Nutzeranfrage:

• menuItem.name = "Pizza"
• menuItem.inMenuSection.inMenu.forRestaurant.name = "BeispielCafé"

Assistant übergibt BII-Parameter an die intent für die Auftragsausführung, die definiert ist in capability. 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. menuItem.name, der Optionen für Restaurants in der Nähe anzeigt, wenn ein Nutzer eine einfachere Anfrage wie „Hey Google, bestelle eine Pizza in ExampleApp“.

Ü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. Füge in deinem App-Manifest einen Verweis auf shortcuts.xml hinzu indem Sie die folgenden Schritte ausführen:

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. Einen Verweis zu shortcuts.xml in AndroidManifest.xml hinzufügen mithilfe eines <meta-data>-Tag in Activity mit Intent nach MAIN und LAUNCHER filtern:

   <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 Tastenkombinationen finden Sie unter Erstellen Sie statische Verknüpfungen in der Android-Entwicklerdokumentation.

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 Tastenkombinationen werden von Assistant aufgenommen, wenn Sie einen Release 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 „Laufen starten“ festlegen 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.

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: integrierte Intent-Aktions-ID, z. B. actions.intent.CREATE_TAXI_RESERVATION) Eine Liste der unterstützten Informationen zu integrierten Intents finden Sie in der Referenz zu integrierten Intents.
• 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 Nutzeranfrage aussehen soll über In-App-Funktionen erfüllt werden. 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.food.OrderActivity"
• android:targetPackage: Paket mit der Zielaktivitätsklasse für Beispiel: "com.example.food"
• android:data: Dieses Feld wird von <url-template> überschrieben. wenn dieses Tag im 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:

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 intent 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 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.

<Daten>

Verknüpft ein Webinventar mit einer parameter.

Attribut:

• android:pathPattern: URL-Muster für entity URLs, die mithilfe von Web-Inventar. Dieses Attribut unterstützt zwei Platzhalter:

  • *: Ein Sternchen entspricht einer Folge von null oder mehr Vorkommnissen des unmittelbar vorangehendes Zeichen.

  • .*: Ein Punkt gefolgt von einem Sternchen entspricht einer beliebigen Folge von Null oder mehr Zeichen.

  • Escape-Zeichen werden nur für die Literale * und \ benötigt, die Sie kann als \\* bzw. \\\\ maskiert werden.

<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 mit Inline-Inventar verknüpft werden soll Shortcut-Ausführung. Der Name sollte ein Feld des BII auf Blattebene 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 Actions in Android-Slices 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. Beim Einbinden eines Tags können all seine Attribute sind erforderlich, sofern sie nicht als optional gekennzeichnet sind.

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: ID für diese Tastenkombination.
• 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>

Mit dieser Verknüpfung verknüpfter 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 ein 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.CREATE_TAXI_RESERVATION

<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 Actions.

Attribute:

• android:key: Der Name des BII-Parameters capability, der verknüpft werden soll zu dieser Tastenkombination hinzu. Beispiel: foodObservation.aboutFood.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 sameAs-URL verweist auf einen auf eine Webseite zu verweisen, die die Entität eindeutig identifiziert. Wird verwendet, um einen Aufzählungswert nur dann, wenn der Intent-Parametertyp ein Subtyp von schema.org/Enumeration. Für Parameterfelder ist ein Pflichtfeld deren Typen Untertypen von schema.org/Enumeration sind (Beispiel: 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. Dieses ist nützlich, wenn Ihre App-Navigation bereits auf Deeplinks basiert.

• Intent-Daten: Sie können einen Ausführungs-URI in der intent angeben. android:data. 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 einer Ihrer Android-Aktivitäten mithilfe einer URL für App-Links, ein benutzerdefiniertes Schema oder eine Intent-basierte URL.

Intent-Extras verwenden

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

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name" android:key="menu" />
  </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 = ”menu”, value = ”latte”.

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.ORDER_MENU_ITEM">
  <intent>
    <url-template android:value="myapp://order{?menu}" />
    <parameter android:name="menuItem.name" android:key="menu" />
  </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://order?menu=latte“.

Um den BII-Parameter einer Position in Ihrer URL zuzuordnen, verwenden Sie die Methode android:name-Attribut des <parameter>-Tags. 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

Für einige BII-Parameter 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.

Webinventar für App Actions

Bei einigen BIIs können Sie Webinventar als Methode Generieren von URLs für die Auftragsausführung. Webinventar nutzt Ihre Website, um URLs für App Action-Ausführungen. Diese Funktion ist besonders nützlich, wenn Sie Webpräsenz und Ihre In-App-Deeplinks sind öffentlich auf verfügbaren Webinhalten.

Weitere Informationen finden Sie unter Webinventar.

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.