Benutzerdefinierte Zielgruppen mit gemeinsamer Absicht

Jede App ist anders und nicht alle App-Funktionen stimmen mit einem verfügbaren integrierten Intent für App Actions (BII) überein. Falls es keine BII für die Funktionalität Ihrer App gibt, können Sie stattdessen einen benutzerdefinierten Intent verwenden, um Ihre App mit App Actions zu erweitern.

Wie BIIs folgen auch benutzerdefinierte Intents dem shortcuts.xml-Schema und fungieren als Verbindungspunkte zwischen Assistant und Ihren definierten Auftragsausführungen. Benutzerdefinierte Intents haben auch Intent-Parameter, die Sie den Parametern in der entsprechenden Auftragsausführung zuordnen können.

Im Gegensatz zu BIIs erfordern benutzerdefinierte Intents Abfragemuster, um Beispielabfragen des Nutzers zu beschreiben. Dieser Ansatz unterscheidet sich von integrierten Intents, die gängige Methoden von Nutzern zum Ausdrucken dieser Absicht modellieren.

Einschränkungen

Benutzerdefinierte Intents haben folgende Einschränkungen:

• Der Name eines benutzerdefinierten Intents darf nicht mit actions.intent beginnen.
• Der Name eines benutzerdefinierten Intents darf unter den Namen eines benutzerdefinierten Intents für Ihre App nur einmal vorkommen.
• Für die Parameterextraktion durch Google Assistant sind nur bestimmte Datentypen verfügbar (siehe Unterstützte Typen).
• Benutzerdefinierte Intents müssen Beispiele für verwendbare Abfragemuster enthalten (siehe Abfragemuster).
• Jede Abfrage unterstützt maximal zwei Textparameter. Diese Beschränkung gilt nicht für andere Datentypen.
• Benutzerdefinierte Intents unterstützen nur die Sprache „en-US“. Außerdem müssen die Spracheinstellungen für Gerät und Assistant übereinstimmen.

Unterstützte Typen

Benutzerdefinierte Intents unterstützen die folgenden schema.org-Typen für die Parameterextraktion:

• https://schema.org/Text
• https://schema.org/Date
• https://schema.org/Time
• https://schema.org/Number

App-Aktionen mit benutzerdefinierten Intents definieren

Wie bei anderen App-Aktionen, die BIIs verwenden, definieren Sie einen benutzerdefinierten Intent im Element <capability> in shortcuts.xml.

Funktionen werden im Stammelement <shortcuts> definiert. Schließen Sie beim Definieren des <shortcuts>-Elements die Namespaces der Attribute ein, auf die Sie zugreifen möchten, wie im folgenden Beispiel gezeigt:

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  ...
</shortcuts>

Geben Sie den Namen des benutzerdefinierten Intents im Attribut android:name an und verweisen Sie im Attribut queryPatterns auf eine Ressourcendatei mit Abfragemustern.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.EXAMPLE_INTENT"
      app:queryPatterns="@array/ExampleQueries">
    <intent ...>
      <url-template
          android:value="http://custom.com{?number_of_items,item_name}" />
      <parameter
          android:name="number_of_items"
          android:key="number_of_items"
          android:mimeType="https://schema.org/Number" />
      <parameter
          android:name="item_name"
          android:key="item_name"
          android:mimeType="https://schema.org/Text" />
    </intent>
  </capability>
  ...
</shortcuts>

Namen von benutzerdefinierten Intents dürfen nicht mit actions.intent beginnen, da dieser Namespace für BIIs reserviert ist. Verwenden Sie stattdessen beim Benennen benutzerdefinierter Intents das Präfix custom.actions.intent, um Ihre benutzerdefinierten Intents von BIIs und Android-Intents zu unterscheiden, da diese anders funktionieren.

Geben Sie für jeden Parameter den unterstützten Schema.org-Typ an, der die Bedeutung des Parameters am besten beschreibt. Mit https://schema.org/Date können Sie beispielsweise ein Datum beschreiben, das Sie erwartet:

...
<intent>
  <url-template android:value="https://example.com/appt{?apptType,date,time}" />
  <parameter
      android:name="date"
      android:key="date"
      android:mimeType="https://schema.org/Date" />
  ...
</intent>
...

Definieren Sie Verknüpfungen für benutzerdefinierte Intents in shortcuts.xml im selben Format wie Verknüpfungen für BIIs.

Im folgenden Code wird eine App-Aktion beschrieben, die die referenzierten Abfragemuster zum Auslösen des benutzerdefinierten Intents SCHEDULE_APPOINTMENT verwendet und eine definierte Gruppe von Werten (DRIVERS_LICENSE und VEHICLE_REGISTRATION) für den Parameter apptType verwendet.

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
     <url-template android:value="https://example.com/appt{?apptType,date,time}" />
       <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
       <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
       <!-- The following parameter has no type because the shortcuts are bound to it -->
       <parameter android:name="apptType" android:key="apptType" />
    </intent>
  </capability>

  <shortcut
      android:shortcutShortLabel="Driver's License"
      android:shortcutId="DRIVERS_LICENSE">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/driversLicense" />
    </capability-binding>
  </shortcut>

  <shortcut
      android:shortcutsShortLabel="Vehicle Registration"
      android:shortcutId="VEHICLE_REGISTRATION">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/vehicleRegistration" />
    </capability-binding>
  </shortcut>
</shortcuts>

Sie können benutzerdefinierte Intent-Parameter mit Inline-Inventar konfigurieren. Damit lässt sich die Entitätsextraktion auf eine Reihe von unterstützten Entitäten steuern, die in shortcuts.xml angegeben sind.

Hinweis :Webinventar wird für benutzerdefinierte Intent-Parameter nicht unterstützt.

Abfragemuster

Für jeden benutzerdefinierten Intent, den Sie verwenden, sind eine Reihe von Abfragen erforderlich, die der Nutzer für diesen Intent erwartet. Dieser Ansatz unterscheidet sich von BIIs, bei denen Abfragen bereits für gängige Methoden modelliert sind, mit denen Nutzer Aufgaben ausdrücken, die sie erledigen möchten, oder Informationen, die sie suchen.

Geben Sie in einer Android-Ressourcendatei (in der Regel /res/values/strings.xml) Abfragemuster als Elemente in einem String-Array an. Wenn Ihre App Action aufgerufen wird, gleicht Google Assistant die Nutzerabfrage mit Ihren Abfragemustern ab, um den Intent für die Auftragsausführung des Nutzers abzugleichen. Jedes von Ihnen angegebene Abfragemuster stellt eine Wortgruppe dar, die Sie für den entsprechenden benutzerdefinierten Intent als gültig betrachten.

Hinweis :Jeder benutzerdefinierten Intent kann mit bis zu 100 Abfragemustern verknüpft werden.

Wenn Sie Abfragemuster für benutzerdefinierte Intents bereitstellen, sollten Sie davon ausgehen, dass jedes Muster einem expliziten Aufruf wie „Beispiel-App öffnen und“ oder „Beispiel-App starten und“ folgt. Betrachten Sie zum Beispiel die folgenden Nutzeranfragen:

• „Hey Google, öffne die Beispiel-App und fang an, einen Kuchen zu backen.“
• „Hey Google, öffne die Beispiel-App und fang an, einen Apfelkuchen zu backen.“
• „Hey Google, starte die Beispiel-App und stelle 5 Tortenstücke zusammen.“
• „Hey Google, verwende die Beispielspiel-App, um fünfmal einen Kuchen zu backen.“

Zum Abgleichen von Nutzerabfragen geben Sie Abfragemuster an, die den Teil der Abfrage nach der Aufrufwortgruppe enthalten. Für Informationen, die Sie aus der Abfrage extrahieren möchten (z. B. Text oder eine vom Nutzer bereitgestellte Zahl), weisen Sie dem entsprechenden Intent-Parameter Werte mit Platzhaltern im Abfragemuster zu.

Hinweis: Assistant führt anhand der Abfragemuster, die Sie für benutzerdefinierte Intents angeben, genaue Übereinstimmungen aus. Der Abfragemusterabgleich enthält keine Aufrufsätze und verwendet die Spracheinstellung Assistant.

Wenn Sie auf einen Parameter in einem Abfragemuster verweisen möchten, fügen Sie dem Namen des Parameters in Ihrem Muster $ hinzu. Um beispielsweise einen Platzhalterwert für einen Parameter wie <parameter name="date1" ... (in actions.xml) oder <parameter android:name="date1" ... (in shortcuts.xml) zu erstellen, verwenden Sie $date1.

Der folgende Code beschreibt Abfragemuster, die den vorherigen Nutzerabfragen entsprechen und Werte für Elementnamen und die Anzahl der zu erstellenden Elemente extrahieren:

<resources>
  <string-array name="ExampleQueries">
    <item>start making a $text1</item>
    <item>start making an $text1</item>
    <item>craft $number1 $text1 items</item>
    <item>produce $text1 $number1 times</item>
  </string-array>
</resources>

Abfragemuster unterstützen Bedingungen. z. B. set (an)? appointment $date $time. In diesem Fall sind sowohl „Termin heute um 12:00 Uhr festlegen“ als auch „Termin heute um 12:00 Uhr festlegen“ gültige Abfragen.