Встроенный инвентарь

Когда вы реализуете действия приложения для своего приложения Android, вам может потребоваться обрабатывать запросы, которые являются вариациями темы. Например, предположим, что ваше фитнес-приложение реализует встроенное намерение START_EXERCISE (BII), позволяющее пользователям начинать широкий спектр тренировок, спрашивая Ассистента, например: «Окей, Google, начни пробежку в приложении-примере».

Для реализации этого намерения требуется, чтобы ваша логика сопоставления запросов обрабатывала каждый тип тренировки, включая такие варианты, как «пробежка», «спринт» или «гонка». Эта логика быстро становится громоздкой по мере увеличения числа поддерживаемых тренировок.

Для поддерживаемых BII, таких как START_EXERCISE , вы можете избежать этой сложной логики сопоставления, используя встроенную инвентаризацию. Встроенный инвентарь — это набор статических ярлыков Android, определенных в shortcuts.xml представляющих функции и контент вашего приложения.

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

Встроенная инвентаризация позволяет Google Assistant упростить значения параметров BII, предоставляемые вашему приложению во время вызовов действий приложения.

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

Схема пользовательского процесса встроенного инвентаря
Рис. 1. Блок-схема функции START_EXERCISE , которая использует встроенный инвентарь для интерпретации предоставленных пользователем названий тренировок для поддерживаемых типов упражнений в приложении.

Ограничения и альтернативы

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

  • Ограничение ярлыков: для каждого приложения можно определить максимум 1000 встроенных ярлыков инвентаря.
  • Ограничение на синонимы. Каждый ярлык встроенного инвентаря может содержать не более 20 значений синонимов.
  • Статическое определение. Ярлыки встроенного инвентаря статически объявлены в shortcuts.xml и могут быть обновлены для ваших пользователей только путем публикации новой версии вашего приложения.

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

  • Инвентаризация веб-страниц: позволяет Ассистенту запрашивать общедоступный веб-контент при сопоставлении запросов пользователей с поддерживаемыми идентификаторами контента приложения. Запросы веб-инвентаря происходят в режиме реального времени во время вызова, что позволяет вам добавлять в Assistant каталоги продуктов, публикации в социальных сетях и другой часто обновляемый контент.

  • Динамические ярлыки: расширяйте список персонализированного содержимого приложений для Ассистента. Динамические ярлыки позволяют пользователям быстро воспроизводить типичные действия, например повторный заказ любимого напитка из приложения для заказа еды или открытие списка покупок в приложении для создания заметок.

Создайте встроенную инвентаризацию

Встроенная инвентаризация упрощает разработку, предоставляя Ассистенту удобный способ преобразовать различные способы, которыми пользователи запрашивают контент и функции вашего приложения, в предсказуемые идентификаторы, ожидаемые вашим приложением. Например, предположим, что ваше приложение предлагает различные тренировки, которые пользователи могут начать с помощью голоса, и ваше приложение ожидает, что пользователи будут делать следующие запросы для одного и того же типа упражнений:

  • Окей, Google, запусти пример приложения.
  • Окей, Google, начни пробежку в примере приложения.

В ярлыке встроенного инвентаря вы устанавливаете для shortcutId "CARDIO_RUN" идентификатор упражнения, ожидаемый вашим приложением. Затем вы указываете «бег» и «пробежка» как синонимы, связанные с shortcutId . Затем, когда пользователь запускает действие вашего приложения с помощью предыдущих запросов, Ассистент использует идентификатор "CARDIO_RUN" для параметра BII при формировании намерения выполнения.

Следующий фрагмент из примера файла app/res/shortcuts.xml реализует этот случай:

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

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
    </capability-binding>
</shortcut>

В предыдущем примере встроенный shortcut инвентаризации объявляет тег <parameter-binding> внутри элемента <capability-binding> , привязывая его к BII-параметру exercise.name , определенному в <capability> .

Ресурс массива строк @array/run_names указывает список синонимов в res/values/arrays.xml , который Assistant распознает и сопоставляет с идентификатором элемента "CARDIO_RUN" :

<!-- Synonym values for "CARDIO_RUN" inline inventory -->
<resources>
  <string-array name="run_names">
    <item>Run</item>
    <item>Jog</item>
    <item>Sprint</item>
  </string-array>
</resources>

Если для возможности указан <url-template> , shortcutId для соответствующего значения вставляется в сгенерированный URL-адрес в соответствующий заполнитель для параметра. Следующий код из примера файла app/res/shortcuts.xml реализует этот случай:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://workout{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
</shortcut>

В предыдущем примере Ассистент создает глубокую ссылку выполнения myapp://workout?exercise=CARDIO_RUN .

Выполнение с использованием ярлыков намерений

По умолчанию ярлык предоставляет shortcutId , соответствующий встроенному значению инвентаря, соответствующему intent capability , к которой привязан ярлык, как объявлено в теге <capability-binding> ярлыка. В качестве альтернативы вы можете указать, что intent , определенное в самом ярлыке, будет использоваться для выполнения, добавив тег <shortcut-fulfillment> к capability .

Следующий код из примера файла app/res/shortcuts.xml реализует выполнение ярлыков:

<capability android:name="actions.intent.START_EXERCISE">
  <shortcut-fulfillment>
    <parameter android:name="exercise.name"/>
  </shortcut-fulfillment>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
  <intent android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</shortcut>

В предыдущем примере, если пользовательский запрос соответствует встроенному значению инвентаризации для параметра exercise.name , тег <shortcut-fulfillment> указывает, что intent связанного ярлыка используется для выполнения.

Встроенная инвентаризация для функции открытого приложения BII

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

Следующий код из примера файла app/res/shortcuts.xml реализует этот BII с помощью одного ярлыка, представляющего функцию статуса заказа приложения:

<capability android:name="actions.intent.OPEN_APP_FEATURE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="feature"
       android:key="featureParam" />
  </intent>
  <!-- Required fallback fulfillment to handle when parameters are missing from user query. -->
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="HOME_SCREEN"
       android:key="featureParam" />
  </intent>
</capability>

<!-- Inline inventory for OPEN_APP_FEATURE. -->

<shortcut android:shortcutId="ORDER_STATUS">
  <capability-binding android:key="actions.intent.OPEN_APP_FEATURE">
    <parameter-binding
      android:key="feature"
      android:value="@array/order_status_names" />
    </capability-binding>
</shortcut>

Ресурсы строкового массива в res/values/arrays.xml , @array/order_status_names , определяют список синонимов для этой функции:

<resources>
  <string-array name="order_status_names">
    <item>Order status</item>
    <item>Orders</item>
    <item>Order history</item>
  </string-array>
</resources>

При наличии предыдущей возможности Ассистент может выполнять различные фразы для одной и той же функции:

  • «Окей, Google, покажи статус моего заказа в приложении-примере».
  • «Окей, Google, покажи мои заказы в приложении-примере».
  • «Окей, Google, покажи мою историю заказов в приложении-примере».

Тестирование встроенного инвентаря

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

Например, возможность START_EXERCISE BII может использовать встроенную инвентаризацию для преобразования предоставленного пользователем параметра BII «run» в соответствующий идентификатор упражнения "CARDIO_RUN" .

Плагин Google Assistant позволяет просматривать действия приложения со встроенным инвентарем в Ассистенте на тестовом устройстве. Проверьте свой инвентарь с помощью плагина, выполнив следующие действия:

  1. Настройте параметры, привязанные к инвентаризации, для вашей возможности BII, используя значения синонимов, связанные с вашей встроенной инвентаризацией.
  2. Запустите BII из плагина, вызвав его на тестовом устройстве.
  3. Проверьте результирующие значения параметров, которые Ассистент предоставляет вашему приложению во время выполнения действия приложения.