Пользовательские намерения

Каждое приложение отличается, и не все функции приложения соответствуют доступному встроенному намерению App Actions (BII). В тех случаях, когда для функциональности вашего приложения нет BII, вместо этого вы можете использовать собственное намерение, чтобы расширить свое приложение с помощью действий приложения.

Как и BII, пользовательские намерения следуют схеме shortcuts.xml и действуют как точки соединения между Ассистентом и определенными вами действиями. Пользовательские намерения также имеют параметры намерений, которые вы можете сопоставить с параметрами соответствующего выполнения.

В отличие от BII, пользовательские намерения требуют шаблонов запросов для описания примеров запросов, которые может произнести пользователь. Этот подход отличается от встроенных намерений, которые моделируют общие способы выражения этих намерений пользователями.

Ограничения

Пользовательские намерения имеют следующие ограничения:

  • Имя специального намерения не может начинаться с actions.intent .
  • Имя специального намерения должно быть уникальным среди имен пользовательских намерений вашего приложения.
  • Только определенные типы данных доступны для извлечения параметров с помощью Google Assistant (см. Поддерживаемые типы ).
  • Пользовательские намерения должны содержать примеры полезных шаблонов запросов (см. Шаблоны запросов ).
  • Каждый запрос поддерживает максимум два текстовых параметра. Это ограничение не распространяется на другие типы данных.
  • Пользовательские намерения поддерживают только локаль en-US. Кроме того, языковые настройки устройства и Ассистента должны совпадать.

Поддерживаемые типы

Пользовательские намерения поддерживают следующие типы Schema.org для извлечения параметров:

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

Определите действия приложения с настраиваемыми намерениями

Как и в случае с другими действиями приложения, использующими BII, пользовательское намерение определяется в элементе <capability> в shortcuts.xml .

Возможности определяются в корневом элементе <shortcuts> . При определении элемента <shortcuts> включите пространства имен атрибутов, к которым вы хотите получить доступ, как показано в следующем примере:

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

Укажите имя пользовательского намерения в атрибуте android:name и укажите ссылку на файл ресурсов шаблонов запросов в атрибуте queryPatterns .

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

Имена пользовательских намерений не могут начинаться с actions.intent , поскольку это пространство имен зарезервировано для BII. Вместо этого при именовании ваших пользовательских намерений используйте префикс custom.actions.intent , чтобы отличить ваши пользовательские намерения от BII и намерений Android, которые функционируют по-разному.

Для каждого параметра укажите поддерживаемый тип Schema.org , который лучше всего описывает значение параметра. Например, вы можете использовать https://schema.org/Date для описания даты, которую вы ожидаете получить:

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

Определите ярлыки для пользовательских намерений в shortcuts.xml используя тот же формат, что и ярлыки для BII.

Следующий код описывает действие приложения, которое использует указанные шаблоны запросов для запуска специального намерения SCHEDULE_APPOINTMENT и использует определенный набор значений DRIVERS_LICENSE и VEHICLE_REGISTRATION для параметра apptType .

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

Вы можете настроить пользовательские параметры намерений с помощью встроенного инвентаря , который можно использовать для направления извлечения сущностей к набору поддерживаемых сущностей, указанных в shortcuts.xml .

Шаблоны запросов

Каждое используемое вами пользовательское намерение требует набора запросов, ожидаемых от пользователя для этого намерения. Этот подход отличается от BII, где запросы уже моделируются для общих способов, с помощью которых пользователи выражают задачи, которые они пытаются выполнить, или информацию, которую они ищут.

В файле ресурсов Android (обычно /res/values/strings.xml ) укажите шаблоны запросов как элементы массива строк . Когда вызывается ваше действие приложения, Google Assistant проверяет запрос пользователя на соответствие вашим шаблонам запросов в рамках сопоставления намерений пользователя по выполнению. Каждый предоставленный вами шаблон запроса представляет собой фразу, которую вы считаете допустимой для соответствующего специального намерения.

При предоставлении шаблонов запросов для пользовательских намерений ожидайте, что каждый шаблон будет следовать явному вызову, например «открыть пример приложения и» или «запустить пример приложения и». Например, рассмотрим следующие запросы пользователей:

  • «Окей, Google, открой приложение «Пример игры» и начни печь торт».
  • «Окей, Google, открой пример игрового приложения и начни готовить яблочный пирог».
  • «Окей, Google, запусти приложение «Пример игры» и создай 5 тортов».
  • «Окей, Google, воспользуйтесь примером игрового приложения, чтобы приготовить торт 5 раз».

Чтобы соответствовать запросам пользователей, предоставьте шаблоны запросов, содержащие часть запроса после фразы вызова. Для информации, которую вы хотите извлечь из запроса (например, текста или числа, предоставленного пользователем), вы присваиваете значения соответствующему параметру намерения с заполнителями в шаблоне запроса.

Чтобы сослаться на параметр в шаблоне запроса, добавьте $ к имени параметра в шаблоне. Например, чтобы создать значение-заполнитель для такого параметра, как <parameter name="date1" ... (в actions.xml ) или <parameter android:name="date1" ... (в shortcuts.xml ), вы используйте $date1 .

Следующий код описывает шаблоны запросов, соответствующие предыдущим пользовательским запросам, и извлекает значения для имен элементов и количества элементов, которые необходимо создать:

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

Шаблоны запросов поддерживают условные выражения. Например, set (an)? appointment $date $time . В этом случае и «назначить встречу сегодня в полдень», и «назначить встречу сегодня в полдень» являются допустимыми запросами.