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

1. Обзор

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Каждый элемент возможностей определяет:

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

Намерения

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4. Добавьте возможность «Начать упражнение BII».

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

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

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

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

BII START_EXERCISE поддерживает параметр BII exercise.name . Вы будете использовать этот параметр, чтобы позволить пользователям указывать тип упражнений для отслеживания в приложении.

Добавьте START_EXERCISE BII в свое приложение, добавив эту 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:

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

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

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

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

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

<!-- 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 ссылается на тот же START_EXCERCISE BII, определенный для возможности.
• Элемент parameter-binding каждой клавиши быстрого доступа к параметру BII exercise.name .

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

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

Атрибуты android:value элемента parameter-binding в предыдущих ярлыках инвентаря относятся к ресурсу массива синонимов для каждого элемента инвентаря. Синонимы позволяют вариантам типа элемента, например «бег», «пробежка» и «спринт», ссылаться на один и тот же 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 .

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

Во время разработки App Actions вы используете плагин 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 BII позволяет пользователям остановить сеанс тренировки, спросив что-то вроде: «Эй, Google, останови мою пробежку в exampleApp». Реализуйте этот BII в приложении Fitness, добавив вторую 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 , что и START_EXERCISE BII, что позволяет пользователям указывать, какую активную тренировку они хотят завершить. Чтобы включить это, добавьте второй набор элементов ярлыков инвентаря в 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

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

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

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

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

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

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

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

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

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

Что дальше

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

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

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

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

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

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

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

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