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

1. Обзор

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

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

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

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

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

Что ты построишь

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

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

Примечание. Приложения с функцией поиска необходимы для реализации actions.intent.GET_THING BII. Узнайте больше о требованиях к развертыванию App Actions.

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

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

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

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

• Терминал для запуска команд оболочки с установленным git.
• Последняя стабильная версия Android Studio .
• Физическое или виртуальное устройство Android с доступом в Интернет к Google Play Store для проверки ваших действий.
• Ваша та же учетная запись Google должна войти в Android Studio , а также в приложение Google и приложение Google Assistant на тестовом устройстве.

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

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

2. Поймите, как это работает

Действия приложения подключают пользователей Google Assistant к вашему приложению Android. Но как они работают?

Когда пользователь указывает Ассистенту, что он хочет использовать ваше приложение, Ассистент ищет действия приложения, зарегистрированные в вашем приложении, в файле shortcuts.xml . Этот файл содержит возможности приложения, которые связывают встроенное или пользовательское намерение Ассистента с намерением 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:

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

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

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

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

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

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

Примечание . После обновления applicationId вы получите предупреждение «Файлы Gradle изменились с момента последней синхронизации проекта...» в Android Studio. Нажмите «Синхронизировать сейчас» , чтобы избежать проблем при загрузке приложения.

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

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

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

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

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

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

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

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

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

Примечание. Тестовый плагин отправляет информацию Ассистенту через приложение Google на вашем устройстве Android.

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

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

Совет: GET_THING BII используется для поиска контента или объектов с использованием функции поиска внутри приложения по умолчанию. Заполните критерии поиска содержимым или именем сущности, используя параметр thing.name , и представьте пользователю наиболее релевантные результаты поиска.

Определить возможность получения вещи

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

Чтобы добавить GET_THING BII в свое приложение, обновите shortcuts.xml , расположенный в каталоге примера проекта app/src/main/res/xml , добавив элемент <capability> в тег <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>

Конфигурация выше:

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

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

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

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

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

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

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

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

Совет: Если у вас возникнут проблемы при работе с инструментом тестирования, обратитесь к руководству по устранению неполадок .

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

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

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

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

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

ярлыки.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 BII поддерживает один параметр feature , представляющий функцию приложения, извлеченную из запроса пользователя. Это приложение поддерживает два типа функций: активная задача и завершенная задача. Эти функции позволяют пользователям открывать приложение с отфильтрованным списком задач. Для поддержки этих функций вам необходимо использовать встроенный инвентарь .

Ключевой термин : встроенная инвентаризация направляет извлечение объектов для BII, предоставляя набор объектов, которые понимает приложение, в параметр BII, который поддерживает встроенную инвентаризацию. Подробную информацию см. в разделе Встроенная инвентаризация для действий приложения .

Обработка параметров намерений с помощью встроенного инвентаря

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

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

Чтобы обработать параметр назначения feature , добавьте ярлык в файл shortcuts.xml со следующим кодом над функцией «Открыть приложение»:

ярлыки.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 Assistant сопоставляет запрос пользователя со значениями в привязке параметров ярлыков. Для соответствующего значения параметра shortcutId будет добавлен к намерению выполнения. Когда пользователь активирует OPEN_APP_FEATURE BII с помощью запроса, Assistant сопоставляет значение параметра функции со значением атрибута ярлыка, передавая значение в targetClass в качестве parameter в Extra .

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

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

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

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

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

Совет: Если у вас возникнут проблемы при работе с инструментом тестирования, обратитесь к руководству по устранению неполадок .

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

6. Следующие шаги

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

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

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

В этой лаборатории вы узнали:

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

Что дальше

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

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

• Ознакомьтесь с примером списка дел с помощью Google Analytics для Firebase, чтобы узнать, как отслеживать эффективность действий в приложении.
• Посетите справочник по встроенным намерениям App Actions, чтобы узнать больше о способах расширения возможностей ваших приложений для Ассистента.

Чтобы продолжить свое путешествие по Actions on Google, изучите эти ресурсы:

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

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

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

Наконец, пожалуйста, заполните этот опрос , чтобы оставить отзыв о своем опыте работы с этой лабораторией кода.