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

1. Обзор

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

Этот практический урок охватывает базовые концепции разработки с использованием App Actions. Для выполнения этого урока вам потребуется опыт разработки приложений для Android и работы с Android Intents . Если вы новичок в Android, вы можете начать с одного из практических уроков по основам разработки Android .

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

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

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

Вы узнаете, как использовать BII-элементы из категории «Здоровье и фитнес» для расширения функциональности Assistant в приложении Android. Вы также научитесь использовать плагин Google Assistant для Android Studio для тестирования ваших BII-элементов.

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

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

• Терминал для выполнения команд оболочки при установленном Git .
• Последняя версия Android Studio .
• Учетная запись Google с доступом к [Google Play Console][].
• Физическое или виртуальное устройство Android с доступом в Интернет и магазином Play Store.

Прежде чем продолжить, убедитесь, что в Android Studio и на тестовом устройстве используется одна и та же учетная запись Google.

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

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

Когда пользователь просит Ассистента выполнить задачу с помощью вашего приложения, Ассистент сопоставляет его запрос с capability действий приложения, определенной в XML-ресурсе shortcuts.xml вашего приложения.

Ключевой термин: Элементы Capability — это шаблоны, которые вы определяете в shortcuts.xml , чтобы объявить типы действий, которые пользователи могут выполнить для запуска вашего приложения и прямого перехода к определенной задаче. Подробнее см. документацию Android по элементам Capability .

Рисунок 1. Блок-схема, демонстрирующая, как Ассистент обрабатывает голосовой запрос действий приложения.

Каждый элемент функциональности определяет:

• Интент : Голосовой интент App Actions, который должен активировать данную функцию.
• Одно или несколько реализаций : интенты Android или глубокие ссылки, которые генерирует Ассистент для запуска приложения и выполнения голосового запроса пользователя. Определения реализаций указывают, какие параметры ожидаются от запроса пользователя и как эти параметры должны быть закодированы в инструкциях запуска.

Намерения

В обработке естественного языка (NLU) намерение — это группа фраз пользователя, имеющих схожее значение. Google предоставил десятки «встроенных» намерений (BII), охватывающих широкий спектр типов запросов, доступных в App Actions. Например, Ассистент обучен связывать фразы «Заказать пиццу» или «Показать меню десертов» с BII ORDER_MENU_ITEM . С помощью App Actions вы можете использовать эти BII для быстрого расширения функциональности распространенных голосовых запросов в приложениях.

Выполнения заказов

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

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

В этом практическом задании используется демонстрационное приложение Fitness для Android. Это приложение позволяет пользователям запускать и останавливать таймер тренировки, а также просматривать статистику своих тренировок.

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

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

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

После клонирования репозитория откройте его в Android Studio:

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

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

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

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

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

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

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

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

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

1. Откройте виртуальное или физическое тестовое устройство Android.
2. Проверка работоспособности приложения «Ассистент».
3. Используйте Android Studio для развертывания и запуска тестового приложения на вашем устройстве.

Выполните следующие шаги, чтобы протестировать ваше приложение:

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

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

Рисунок 2. Пример приложения Fit Actions, отображающий статистику упражнений.

Кратко изучите приложение, чтобы увидеть, что оно может делать. Нажатие на значок «Бег» запускает таймер тренировки, а нажатие на значок «X» останавливает его. Это те задачи, которые вы сможете включить для голосового управления с помощью действий приложения.

Установите плагин Google Ассистента.

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

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

Примечание: тестовый плагин отправляет информацию в Ассистент через приложение Google на вашем устройстве Android. Для корректной работы функций App Actions вашему тестовому устройству необходим доступ к Play Store для обновления приложения Google.

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

BII actions.intent.START_EXERCISE позволяет пользователям открывать приложение и начинать тренировку с помощью голоса. На этом шаге вы реализуете возможность для этого BII, которая позволяет пользователям просить Ассистента начать пробежку в приложении «Фитнес».

Определите возможности

Голосовой помощник использует элементы capability , определенные в файле shortcuts.xml , для обработки голосовых команд, выполняя следующие шаги:

1. Ассистент сопоставляет голосовой запрос пользователя с BII, определенным в возможностях вашего приложения.
2. Ассистент извлекает значения из запроса и преобразует их в параметры BII. Каждый параметр добавляется в Bundle , прикрепленный к сгенерированному Intent .
3. Ассистент использует Intent для запуска приложения, предоставляя приложению доступ к встроенным параметрам.

Библиографический интерфейс START_EXERCISE поддерживает параметр exercise.name . Этот параметр позволяет пользователям указывать тип упражнений для отслеживания в приложении.

Добавьте BII- START_EXERCISE в ваше приложение, указав следующую capability в файле shortcuts.xml , расположенном в каталоге примера проекта app/src/main/res/xml :

<!-- shortcuts.xml -->

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <parameter
      android:name="exercise.name"
      android:key="exerciseType"/>
  </intent>
</capability>

Замените PUT_YOUR_APPLICATION_ID_HERE на уникальный applicationId который вы определили на предыдущем шаге.

Приведенный выше пример XML:

• Объявляет возможность для BII START_EXERCISE .
• Указывает intent Android, которое генерирует Ассистент для запуска приложения:
  • Атрибуты targetPackage и targetClass определяют тип получаемого объекта.
  • Атрибут parameter сопоставляет параметр exercise.name BII с exerciseType в дополнительных данных Bundle , полученных действием.

Обработка параметров BII с помощью встроенной системы учета запасов.

Параметры BII представляют собой элементы, извлеченные из запроса пользователя к Ассистенту. Например, когда пользователь говорит: «Привет, Google, начни пробежку в ExampleApp», Ассистент извлекает слово «run» в параметр BII exercise.name schema.org . Для некоторых BII можно указать Ассистенту сопоставлять параметры BII с набором идентификаторов, ожидаемых вашим приложением.

Это делается путем привязки встроенных элементов инвентаризации к параметру BII. Встроенная инвентаризация представляет собой набор поддерживаемых значений параметров BII, таких как «run», «hike» и «jog», и соответствующих им идентификаторов ярлыков, например EXERCISE_RUN . Эта привязка инвентаризации позволяет Assistant передавать идентификатор ярлыка для соответствующих параметров, а не исходное значение запроса, в вашу операцию выполнения.

Для работы некоторых параметров BII, таких как exercise.name , требуется встроенный список инвентаря. Для обработки этого параметра добавьте следующие элементы shortcut инвентаря в shortcuts.xml :

<!-- shortcuts.xml -->

<shortcuts>
  <shortcut
    android:shortcutId="running"
    android:shortcutShortLabel="@string/activity_running">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/runningSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="walking"
    android:shortcutShortLabel="@string/activity_walking">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/walkingSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="cycling"
    android:shortcutShortLabel="@string/activity_cycling">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/cyclingSynonyms"/>
    </capability-binding>
  </shortcut>

  <capability> ... </capability>
</shortcuts>

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

• Атрибут android:key каждого элемента capability-binding ссылается на один и тот же BII-объект START_EXCERCISE определенный для данной возможности.
• Элемент parameter-binding каждого сочетания клавиш соответствует параметру exercise.name BII.

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

Добавить синонимы к товарам в инвентарь

Атрибуты android:value элемента parameter-binding в приведенных выше ярлыках инвентаря ссылаются на массив синонимов для каждого элемента инвентаря. Синонимы позволяют вариантам одного типа элемента, таким как "run", "jog" и "sprint", ссылаться на один и тот же shortcutId . Добавьте следующие записи синонимов в ресурс array.xml проекта:

<!-- array.xml -->
<array name="runningSynonyms">
  <item>Run</item>
  <item>Jog</item>
  <item>Jogging</item>
  <item>Sprint</item>
</array>

<array name="walkingSynonyms">
  <item>Walk</item>
  <item>Hike</item>
  <item>Hiking</item>
</array>

<array name="cyclingSynonyms">
  <item>Biking</item>
  <item>Riding</item>
  <item>Pedaling</item>
</array>

Выполнить входящие намерения Android

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

Во-первых, замените функцию Intent.handleIntent следующим кодом:

//FitMainActivity.kt

private fun Intent.handleIntent() {
  when (action) {
    // When the BII is matched, Intent.Action_VIEW will be used
    Intent.ACTION_VIEW -> handleIntent(data)
    // Otherwise start the app as you would normally do.
    else -> showDefaultView()
  }
}

Далее добавьте в класс новую функцию handleIntent со следующим кодом:

//FitMainActivity.kt

/**
 * Use extras provided by the intent to handle the different BIIs
 */

private fun handleIntent(data: Uri?) {
  // path is normally used to indicate which view should be displayed
  // i.e https://fit-actions.firebaseapp.com/start?exerciseType="Running" -> path = "start"
  var actionHandled = true

  val startExercise = intent?.extras?.getString(START_EXERCISE)
  // Add stopExercise variable here

  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  else{
   // path is not supported or invalid, start normal flow.
   showDefaultView()

   // Unknown or invalid action
   actionHandled = false
  }
  notifyActionSuccess(actionHandled)
}

В предыдущей функции Intent.handleIntent , когда срабатывает ACTION_VIEW , данные интента действия приложения передаются в функцию handleIntent . Доступ к параметрам BII, содержащимся в интенте START_EXERCISE осуществляется через intent?.extras?.getString(START_EXERCISE) . Остальная часть функции обновляет FitTrackingFragment , чтобы отобразить выбранный тип физической активности startExercise .

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

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

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

1. Запустите приложение в Android Studio, выбрав «Запуск» > «Запустить приложение» или нажав значок «Запуск» на верхней панели инструментов.
2. Перейдите в меню Инструменты > Действия приложения > Google Ассистент > Инструмент проверки действий приложения .
3. Нажмите «Создать предварительный просмотр» . При необходимости ознакомьтесь с политикой и условиями использования App Actions и примите их.
4. Выберите встроенный интент actions.intent.START_EXERCISE .
5. В поле для упражнения оставьте значение по умолчанию, соответствующее текущему состоянию .
6. Нажмите «Запустить действие приложения» . Убедитесь, что Ассистент переходит по прямой ссылке на таймер тренировки в приложении и что таймер запустил тренировку типа бега.

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

Вы успешно реализовали свои первые действия приложения с помощью START_EXERCISE BII. Поздравляем! Далее мы добавим возможность остановки беговой тренировки в вашем приложении.

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

Библиографический интерфейс actions.intent.STOP_EXERCISE позволяет пользователям остановить тренировку, задав, например, вопрос: «Привет, Google, останови мою пробежку в ExampleApp». Реализуйте этот интерфейс в приложении «Фитнес», добавив вторую capability в shortcuts.xml :

<!-- shortcuts.xml -->

<capability android:name="actions.intent.STOP_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <!-- Eg. name = "Running" -->
    <parameter
        android:name="exercise.name"
        android:key="stopExercise"/>
  </intent>
</capability>

Замените PUT_YOUR_APPLICATION_ID_HERE на ваш уникальный applicationId .

Обработка параметров BII с помощью встроенной системы учета запасов.

Этот BII поддерживает тот же параметр exercise.name , что и BII START_EXERCISE , позволяя пользователям указывать, какую активную тренировку они хотят завершить. Чтобы включить эту функцию, добавьте второй набор элементов ярлыков инвентаря в shortcuts.xml :

<!-- shortcuts.xml -->

<shortcut
  android:shortcutId="running"
  android:shortcutShortLabel="@string/activity_running">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/runningSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="walking"
  android:shortcutShortLabel="@string/activity_walking">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/walkingSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="cycling"
  android:shortcutShortLabel="@string/activity_cycling">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/cyclingSynonyms"/>
  </capability-binding>
</shortcut>

Выполнить входящие намерения Android

Чтобы приложение могло обрабатывать входящие Android-интенты STOP_EXERCISE , обновите класс FitMainActivity . Сначала добавьте переменную в функцию handleIntent для хранения данных интента STOP_EXERCISE :

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  val stopExercise = intent?.extras?.getString(STOP_EXERCISE)
  //...
}

Далее обновите условную логику функции handleIntent для обработки намерений STOP_EXERCISE :

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  //...
  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  <strong>
  } else if(stopExercise != null){
    // Stop the tracking service if any and return to home screen.
    stopService(Intent(this, FitTrackingService::class.java))
    updateView(FitStatsFragment::class.java)
  }
  </strong>
  //...
}

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

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

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

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

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

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

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

Теперь вы понимаете, как активировать голосовое управление в Android-приложении с помощью встроенных интентов Google Assistant. В этом практическом занятии вы узнали:

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

Что дальше?

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

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

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

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

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

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

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

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