Эта страница переведена с помощью Cloud Translation API.

Расширьте приложение Android до Google Assistant с помощью действий приложения (уровень 2).

1. Обзор

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

В первом практическом занятии по App Actions вы узнали, как расширить функциональность Google Assistant для примера фитнес-приложения, реализовав встроенные интенты (BII) из категории «Здоровье и фитнес». BII организованы по категориям, представляющим типы задач, которые пользователи часто просят выполнить Assistant.

В этом практическом занятии вы узнаете, как добавлять действия приложения (App Actions) с помощью BII-объектов из категории "Common" , которая представляет собой распространенные задачи приложений, которые может выполнять практически любое приложение Android.

Данный практический урок посвящен концепциям среднего уровня сложности разработки с использованием App Actions. Вам потребуется опыт разработки Android-приложений и реализации Android-интентов.

Что вы построите

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

Для доступа к функциям приложения используйте BII-объект actions.intent.OPEN_APP_FEATURE .
Используйте поиск внутри приложения с помощью BII-объекта actions.intent.GET_THING .

Три последовательных экрана, на которых Google Ассистент отображает активные задачи в приложении.

Рисунок 1. Три последовательных экрана, на которых Google Ассистент отображает активные задачи в приложении.

Что вы узнаете

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

Предварительные требования

Терминал для выполнения команд оболочки при установленном Git.
Последняя стабильная версия Android Studio .
Для проверки ваших действий вам потребуется физическое или виртуальное устройство Android с доступом в Интернет и магазином Google Play.
Для корректной работы необходимо, чтобы в Android Studio был авторизован один и тот же аккаунт Google, а на тестовом устройстве были установлены как приложение Google, так и приложение Google Assistant .

В этом практическом задании вы будете использовать устройство Android (физическое или виртуальное) для тестирования своих действий. Если вы используете физическое устройство, убедитесь, что оно подключено к вашей локальной машине для разработки. Вы также должны быть авторизованы в приложении Google на устройстве и в Android Studio , используя ту же учетную запись Google. На устройстве также должно быть установлено приложение Google Assistant .

2. Разберитесь, как это работает.

Функция App Actions связывает пользователей Google Assistant с вашим Android-приложением. Но как она работает?

Когда пользователь сообщает Ассистенту о желании использовать ваше приложение, Ассистент ищет зарегистрированные в вашем приложении действия приложения в файле shortcuts.xml . Этот файл содержит возможности приложения, которые связывают встроенный или пользовательский интент Ассистента с интентом Android или глубокой ссылкой.

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

На следующей диаграмме показан этот процесс работы помощника:

Рисунок 2. Схема обработки голосового запроса Google Assistant.

Файл проекта shortcuts.xml содержит следующую информацию для каждого действия приложения:

Какое встроенное или пользовательское намерение использует действие приложения
Какое действие Android или глубокую ссылку следует предоставить пользователю?
Как параметры встроенного намерения сопоставляются с информацией, предоставленной Ассистенту пользователем.

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

3. Подготовьте среду разработки.

В этом практическом занятии используется демонстрационное приложение «Список дел» для Android. Это приложение позволяет добавлять элементы в списки дел, искать элементы по категориям и просматривать информацию о выполненных задачах.

Загрузите базовые файлы.

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

git clone --branch codelab-start https://github.com/actions-on-google/appactions-common-biis-kotlin.git

После клонирования репозитория выполните следующие действия, чтобы открыть его в Android Studio:

В диалоговом окне «Добро пожаловать в Android Studio» нажмите «Импорт проекта» .
Найдите и выберите папку, куда вы клонировали репозиторий.

Чтобы увидеть версию приложения, соответствующую пройденному практическому заданию, клонируйте репозиторий с примерами приложений, используя флаг --branch master .

Обновите идентификатор приложения Android.

Обновление идентификатора приложения позволяет однозначно идентифицировать приложение на вашем тестовом устройстве и избежать ошибки «Дублирующееся имя пакета», если приложение загружено в Play Console. Чтобы обновить идентификатор приложения, откройте файл app/build.gradle :

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

Замените "MYUNIQUENAME" в поле applicationId на уникальное для вас имя.

Протестируйте приложение на своем устройстве.

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

В Android Studio выберите Run > Run app или нажмите Run. на панели инструментов.
В диалоговом окне «Выбор целевого устройства развертывания» выберите устройство и нажмите «ОК» . Рекомендуемая версия ОС — Android 10 (уровень API 30) или выше, хотя Actions работает на устройствах, начиная с Android 5 (уровень API 21) .
Нажмите и удерживайте кнопку «Домой» , чтобы настроить Ассистента и проверить его работоспособность. Вам потребуется войти в Ассистента на вашем устройстве, если вы еще этого не сделали.

Для получения дополнительной информации о виртуальных устройствах Android см. раздел «Создание и управление виртуальными устройствами» .

Анимация, демонстрирующая пример приложения «Список дел».

Рисунок 3. Анимация, демонстрирующая пример приложения «Список дел».

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

Установите тестовый плагин

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

Перейдите в меню Файл > Настройки ( в Android Studio > Настройки на MacOS).
В разделе «Плагины» перейдите в Marketplace и найдите «Google Assistant». Вы также можете вручную загрузить и установить инструмент тестирования.
- Если вы не можете найти плагин на Marketplace , загрузите его вручную и следуйте инструкциям по установке плагина с диска .
Установите инструмент и перезапустите Android Studio.

4. Добавить возможность Get Thing BII.

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

Определите возможности функции «Получить вещь».

В процессе выполнения действий приложения, связанных с поиском, Ассистент извлекает поисковые запросы из запроса пользователя и помещает их в параметр BII thing.name , а затем передает это значение в приложение Android.

Чтобы добавить GET_THING BII в ваше приложение, обновите shortcuts.xml , расположенный в каталоге примера проекта app/src/main/res/xml , добавив элемент <capability> внутри тега <shortcuts> верхнего уровня:

shortcuts.xml

<shortcuts ....>
    <capability android:name="actions.intent.GET_THING">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.yourApplicationId.appaction"
            android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
            <parameter
                android:name="thing.name"
                android:key="q"/>
        </intent>
    </capability>
</shortcuts>

Приведенная выше конфигурация:

Указывает, что приложение отвечает на BII-код GET_THING .
Указывает, как создать Android-интент, который запускает приложение в ответ на этот BII.
- Объект Activity идентифицируется с помощью targetPackage и targetClass .
- Параметр BII thing.name сопоставляется с дополнительным элементом Intent Extra, названным q .

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

Предоставленное Android-приложение содержит метаданные , поэтому AndroidManifest знает о файле shortcuts.xml :

<meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />

Протестируйте действие вашего приложения.

Чтобы проверить поиск вашего приложения в Google Ассистенте, выполните следующие действия:

Убедитесь, что ваше устройство Android подключено.
Перейдите в меню Инструменты > Google Ассистент > Инструмент проверки действий приложения .
Нажмите «Создать предварительный просмотр» , чтобы принять значения по умолчанию для имени приложения и языка . При необходимости ознакомьтесь с политикой и условиями обслуживания App Actions и примите их.
На первом шаге, когда инструмент запрашивает выбор и настройку BII, выберите actions.intent.GET_THING . Измените значение name с running shoes на milk .
Нажмите «Запустить действие приложения» .

В этом тесте GET_THING BII использует атрибут name для поиска в приложении задач, содержащих слово "milk". Как и в предыдущем случае с App Action, вы можете протестировать свое действие с помощью инструмента тестирования или просто сказать: "Привет, Google, найди смесь для торта в списке задач" или другие поисковые фразы на своем тестовом устройстве.

5. Добавить функцию открытия приложения с возможностью BII.

На этом шаге вы реализуете компонент BII «Открыть приложение» , позволяющий пользователям просматривать свои активные и завершенные задачи с помощью Ассистента. Для этого заполните описание возможности в shortcuts.xml , который содержит информацию о том, как запускается эта возможность, как передаются параметры и какие Android-интенты следует вызывать. Для этого практического занятия вы будете использовать компонент BII OPEN_APP_FEATURE . После реализации этого компонента BII вы протестируете действие на своем устройстве.

Добавить возможность открытия приложения.

Добавьте вторую возможность для функции «Открыть приложение» в shortcuts.xml под элементом Get Thing Capability:

shortcuts.xml

<capability android:name="actions.intent.OPEN_APP_FEATURE">
   <intent
       android:action="android.intent.action.VIEW"
       android:targetPackage="yourApplicationId"
       android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
       <parameter
           android:name="feature"
           android:key="feature"/>
   </intent>
</capability>

Эта функция сопоставляет BII-код функции «Открыть приложение» и интент Android, поэтому при активации функции «Открыть приложение» будет активирован интент Android.

Перед запуском Android-интента из пользовательского ввода извлекаются поддерживаемые параметры. Интент OPEN_APP_FEATURE поддерживает один параметр, feature , представляющий собой функцию приложения, извлеченную из пользовательского запроса. Это приложение будет поддерживать два типа функций: «Активная задача» и «Выполненная задача». Эти функции позволяют пользователям открывать приложение с отфильтрованным списком своих задач. Для поддержки этих функций необходимо использовать встроенный инвентарь .

Обработка параметров намерений с использованием встроенного инвентаря.

Параметры намерения представляют собой элементы, извлеченные из запроса пользователя. Например, если пользователь говорит что-то вроде: «Привет, Google, закажи пиццу в ExampleApp», Ассистент извлекает слово «пицца» в параметр намерения food.item schema.org и передает этот параметр вашему действию для обработки.

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

Для обработки параметра "намерение использовать feature добавьте ярлык в файл shortcuts.xml со следующим кодом над параметром "Открыть приложение":

shortcuts.xml

<shortcut
   android:shortcutId="active_tasks"
   android:shortcutShortLabel="@string/label_active"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/active_tasks_synonyms" />
   </capability-binding>
</shortcut>

<shortcut
   android:shortcutId="completed_tasks"
   android:shortcutShortLabel="@string/label_completed"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/completed_tasks_synonyms" />
   </capability-binding>
</shortcut>

В приведенном выше коде вы определили встроенный инвентарь, представленный в виде элементов shortcut с привязками возможностей и параметров. Ярлыки можно использовать в качестве инвентаря для параметров BII. Google Ассистент сопоставляет запрос пользователя со значениями в привязке параметров ярлыков. Для найденного значения параметра в намерение выполнения будет добавлен shortcutId . Когда пользователь активирует BII OPEN_APP_FEATURE с помощью запроса, Ассистент сопоставляет значение параметра функции с атрибутом value ярлыка, передавая это значение в targetClass в качестве parameter в Extra .

Например, если пользователь говорит что-то вроде: «Привет, Google, покажи мои выполненные задачи в ExampleApp», Ассистент сопоставляет значение параметра намерения функции, «выполненные задачи», с соответствующим ярлыком в инвентаре, который передает это значение в возможность OPEN_APP_FEATURE . Затем Ассистент запускает намерение Android.

Протестируйте действие вашего приложения.

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

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

Подключите ваше физическое тестовое устройство Android или запустите эмулятор Android.
Если инструмент тестирования не отображается, откройте его, перейдя в меню Инструменты > Google Ассистент > Инструмент тестирования действий приложения .
Нажмите кнопку «Обновить» , чтобы обновить предварительный просмотр.
На первом шаге, когда инструмент запрашивает выбор и настройку BII, выберите actions.intent.OPEN_APP_FEATURE .
В поле «Функция» обновите значение по умолчанию History , указав Completed tasks .
Нажмите «Запустить действие приложения» .

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

6. Дальнейшие шаги

Поздравляем!

Теперь у вас есть возможность обеспечить работу практически любого приложения Android с Google Assistant, используя распространенные BII-идентификаторы.

Что мы рассмотрели

В ходе этого практического занятия вы узнали:

Как позволить пользователям углубленно изучать конкретные функции приложения с помощью Ассистента.
Как пользователи могут получить доступ к поиску внутри приложения через Ассистент.
Как проверить распространенные BII-идентификаторы с помощью плагина Google Assistant .

Что дальше?

Отсюда вы можете попробовать внести дальнейшие улучшения в ваше приложение-список дел. Чтобы посмотреть готовый проект, перейдите в ветку репозитория –master на GitHub.

Вот несколько рекомендаций для дальнейшего изучения возможностей расширения функциональности этого приложения с помощью App Actions:

Ознакомьтесь с примером списка задач с использованием Google Analytics для Firebase, чтобы узнать, как отслеживать эффективность действий вашего приложения.
Чтобы узнать больше о способах расширения функциональности ваших приложений для Google Ассистента, посетите раздел «Справочник по встроенным интентам в App Actions».

Чтобы продолжить работу с Actions on Google, ознакомьтесь с этими ресурсами:

developers.google.com/assistant : Официальный сайт документации по Actions on Google.
Указатель примеров приложений и кода для изучения возможностей App Actions.
Действия в репозитории Google GitHub : примеры кода и библиотек.
r/GoogleAssistantDev : Официальное сообщество Reddit для разработчиков, работающих с Google Assistant.

Подписывайтесь на нас в Твиттере @ActionsOnGoogle , чтобы быть в курсе наших последних анонсов, и делитесь своими разработками в твиттере с хэштегом #AoGDevs !

Опрос обратной связи

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