Веб-инвентарь

С помощью действий приложения пользователи могут сразу перейти к содержимому вашего приложения, сказав что-то вроде: «Эй, Google, покажи мне меню Three Dot Cafe в exampleApp». Эта функция называется глубокими ссылками и может облегчить пользователям работу с вашим приложением.

Чтобы выполнить запрос такого типа, Google Assistant создает глубокую ссылку на соответствующий контент в вашем приложении. Если вы активно поддерживаете свой веб-сайт с контентом или информацией о продуктах, а ваши глубокие ссылки в приложении организованы вокруг этого общедоступного веб-контента, вы можете настроить Ассистента для получения URL-адресов для выполнения действий с вашего веб-сайта с помощью веб-инвентаря.

Веб-инвентаризация – это расположение на веб-сайте URL-адресов элементов, поддерживаемых вашим приложением. Когда пользователь вызывает действие вашего приложения, Ассистент сопоставляет пользовательский запрос, например «Кафе «Три точки»,» с соответствующими URL-адресами в индексе поиска Google веб-сайта, который вы указываете в файле shortcuts.xml для вашего приложения Android.

Преимущества

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

  • Данные веб-инвентаризации находятся на вашем веб-сайте, в отличие от встроенных данных инвентаризации , которые хранят списки элементов в вашем приложении. Предоставление Помощнику доступа к веб-данным позволяет избежать риска устаревших встроенных данных инвентаризации, которые можно обновить только путем публикации новой версии приложения.

  • Встроенные запасы ограничены 1000 единицами. Напротив, веб-инвентарь не имеет ограничений по количеству элементов и может расширяться вместе с вашими потребностями.

  • Веб-инвентаризация может упростить логику приложения, позволяя вашему исполнению обрабатывать только предсказуемые URL-адреса контента, полученные с вашего веб-сайта. Напротив, если инвентаризация не настроена, Ассистент генерирует глубокие ссылки для выполнения, сопоставляя параметры намерения с переменными в шаблоне URL-адреса. Затем вам необходимо будет проанализировать этот динамически генерируемый URL-адрес, чтобы определить, запросил ли пользователь поддерживаемый объект в вашем приложении.

Как это работает

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

Существует три метода создания глубоких ссылок для выполнения:

  • Сопоставление параметров : сопоставляет параметры намерения с заполнителями в шаблоне URL-адреса выполнения.
  • Встроенная инвентаризация : сопоставляет параметры намерения со списком поддерживаемых entities определенных в приложении.
  • Веб-инвентаризация: сопоставляет параметры намерений с содержимым, найденным в поисковом индексе Google веб-сайта.

Веб-инвентаризация — это определенный разработчиком шаблон URL-адреса веб-сайта, например https://www.exampleapp.com/restaurants/.* , представляющий набор сущностей, поддерживаемых приложением.

Если параметр BII настроен для веб-инвентаря, Ассистент запрашивает веб-сайт, чтобы выполнить сопоставление объекта с запросом пользователя. Затем Ассистент передает результаты URL-адресов, соответствующие настроенному шаблону URL-адресов, например https://www.exampleapp.com/restaurants/three-dot-cafe , для вашего выполнения.

Рис. 1. Пример запроса Ассистента с использованием веб-инвентаризации для получения элемента сущности ресторана.

Поддерживаемые встроенные намерения

Веб-инвентаризация поддерживается для определенных параметров намерений следующими BII:

  • [ actions.intent.CREATE_REVIEW ]
  • [ actions.intent.GET_NEWS_ARTICLE ]
  • [ actions.intent.GET_REVIEW ]
  • [ actions.intent.GET_THING ]
  • [ actions.intent.ORDER_MENU_ITEM ]
  • [ actions.intent.GET_EXERCISE_PLAN ]
  • [ actions.intent.GET_DIGITAL_DOCUMENT ]
  • [ actions.intent.GET_ITEM_LIST ]
  • [ actions.intent.GET_OFFER ]
  • [ actions.intent.CREATE_OFFER ]
  • [ actions.intent.GET_PRODUCT ]
  • [ actions.intent.UPDATE_CART ]
  • [ actions.intent.CREATE_SOCIAL_MEDIA_CONNECTION ]
  • [ actions.intent.GET_IMAGE_OBJECT ]
  • [ actions.intent.GET_SOCIAL_MEDIA_POSTING ]
  • [ actions.intent.GET_SOCIAL_MEDIA_PROFILE ]
  • [ actions.intent.CREATE_TAXI_RESERVATION ]
  • [ actions.intent.CREATE_FLIGHT_RESERVATION ]
  • [ actions.intent.CREATE_LODGING_RESERVATION ]
  • [ actions.intent.GET_LOCAL_BUSINESS ]
  • [ actions.intent.GET_RESERVATION ]
  • [ actions.intent.UPDATE_RESERVATION ]

Добавить веб-ресурсы

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

Чтобы использовать веб-инвентаризацию для поддерживаемого BII, выполните следующие действия:

  1. В файле shortcuts.xml вашего приложения добавьте тег <capability> с атрибутом android:name равным имени BII, который вы обрабатываете с помощью веб-инвентаря, например: actions.intent.ORDER_MENU_ITEM .

  2. В теге <capability> добавьте тег <intent> с атрибутом android:action , равным имени представления, которое будет активировано этим намерением.

  3. В тот же тег <intent> добавьте тег <parameter> и установите для его атрибута android:name параметр BII, который наиболее точно соответствует объекту, описанному на ваших веб-страницах. Например, при предоставлении веб-инвентаря для ORDER_MENU_ITEM вам следует связать страницы меню с menuItem.name .

  4. В новый тег <parameter> добавьте тег <data> и задайте для его атрибута android:pathPattern шаблон URL-адреса пути, который вы хотите использовать для веб-инвентаря.

Когда вы настраиваете shortcuts.xml с помощью этих шагов, Ассистент может получать веб-контент из индекса поиска Google по шаблону URL-адреса, который вы указали в атрибуте android:pathPattern . Затем Ассистент предоставляет вам значение URL-адреса, используя результаты, соответствующие заданному вами шаблону пути URL-адреса. Затем ваше приложение направляет пользователя в определенное место в вашем приложении на основе данных URL-адреса, предоставленных Ассистентом.

Например, ваш веб-сайт содержит списки продуктов, URL-адрес которых начинается с https://www.examplecafe.com/items/ . Вы используете значение pathPattern https://www.examplecafe.com/items/.* , а Ассистент использует этот шаблон URL-адреса при веб-поиске, чтобы найти URL-адрес выполнения, например https://www.examplecafe.com/items/item123 .

Если Ассистент находит соответствующий URL-адрес веб-ресурса, он предоставляет URL-адрес в поле <data> намерения выполнения, как если бы это была глубокая ссылка. Используйте метод getData() намерения, чтобы получить URL-адрес как объект Uri . Действие приложения, которое получает намерение, отвечает за интерпретацию URL-адреса и активацию соответствующего пользовательского интерфейса приложения.

Пример ярлыка.xml

В следующем примере определяется BII ORDER_MENU_ITEM , который предоставляет веб-инвентаризацию для возврата результатов URL-адресов для запросов, содержащих параметр BII menuItem.name :

<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <capability android:name="actions.intent.ORDER_MENU_ITEM">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.OrderMenuItemActivity">
      <!-- Define URL match pattern in the pathPattern data field -->
      <parameter android:name="menuItem.name">
        <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
      </parameter>
    </intent>
  </capability>
</shortcuts>

В приведенном выше примере для menuItem.name указан pathPattern , что указывает Ассистенту возвращать только те URL-адреса, которые соответствуют шаблону URL-адреса: https://www.examplecafe.com/items/.*

Дополнительные примеры BII в shortcuts.xml , поддерживающие веб-инвентаризацию, доступны в справочной документации .

Обработка резервного варианта для отсутствующих результатов

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

  • Отсутствует параметр намерения : пользователь пропустил ожидаемый параметр в своем запросе или Ассистент не понял параметр в запросе пользователя.
  • Отсутствует результат URL : Ассистенту не удалось найти на вашем веб-сайте объект, соответствующий запросу пользователя.

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

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

В следующем примере файла shortcuts.xml BII ORDER_MENU_ITEM определяет два выполнения: первое ожидает URL-адрес из параметра menuItem.name . Второй не требует параметров и направляет пользователя на страницу, на которой показаны все пункты меню.

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
    </parameter>
  </intent>
  <!-- Fallback intent with no required parameters -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ViewMenuActivity">
    <url-template android:value="myapp://app.examplecafe.com/menu/all-items" />
  </intent>
</capability>

В ситуациях, когда URL-адрес веб-инвентаря не возвращается, содержимое пользовательского запроса все равно может использоваться в резервных целях, например, для отображения результатов поиска.

В следующем примере shortcuts.xml определены два элемента намерения:

  1. Для первого требуется глубокая ссылка на веб-ресурсы из параметра menuItem.name .
  2. Если глубокая ссылка не возвращается, второе намерение отображает результаты поиска, используя пользовательский запрос из menuItem.name , если он присутствует. 
<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- Fallback intent displaying search results, using "menuItem.name" -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.SearchMenuActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

Добавьте поиск в приложении с веб-инвентарем

Вы можете разрешить пользователям искать веб-контент в вашем приложении, объединив веб-инвентарь с реализацией actions.intent.GET\_THING BII.

Этот BII ищет контент или объекты, используя встроенную функцию поиска по умолчанию в приложении, позволяя запрашивать такие запросы, как: «Эй, Google, покажи мне походы по водопаду в SampleApp». При настройке веб-инвентаризации для параметра thing.name , передаваемого GET_THING BII, результаты сопоставления объектов с вашего веб-сайта передаются для выполнения.

Примеры файла shortcuts.xml веб-инвентаря см. в справочнике GET\_THING BII .

Тестирование веб-ресурсов

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

В следующем примере ORDER_MENU_ITEM BII Ассистент создает ссылки для выполнения веб-инвентаря, соответствующие шаблону urlFilter , указанному в параметре menuItem.name , например: https://www.examplecafe.com/items/nuggets . Второе намерение принимает значение menuItem.name и выполняет поиск, если первое намерение не соответствует шаблону URL-адреса.

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <!-- web inventory fulfillment -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- search intent -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MenuSearchActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

Используйте инструмент тестирования действий приложения , чтобы протестировать веб-инвентарь на физическом или виртуальном устройстве.

Чтобы использовать инструмент тестирования, выполните следующие действия:

  1. Подключите тестовое устройство с работающим приложением.
  2. В Android Studio выберите «Инструменты» > «Действия приложения» > «Инструмент проверки действий приложения» .
  3. Нажмите Создать предварительный просмотр .
  4. В Android Studio запустите приложение на тестовом устройстве.
  5. Используйте приложение «Ассистент» на тестовом устройстве, чтобы протестировать действие приложения. Например, вы можете сказать что-то вроде: «Окей, Google, закажи наггетсы в exampleCafe».
  6. Наблюдайте за поведением своего приложения или используйте отладчик Android Studio , чтобы проверить желаемый результат действия.