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

Создайте действие интерактивного холста для Google Assistant с помощью Action Builder

1. Обзор

Actions on Google — это платформа для разработчиков, позволяющая создавать программное обеспечение для расширения функциональности Google Assistant , виртуального персонального помощника Google, на более чем миллиарде устройств, включая умные колонки, телефоны, автомобили, телевизоры, наушники и многое другое. Пользователи взаимодействуют с Google Assistant в диалоге, чтобы выполнять различные действия, например, покупать продукты или заказывать такси; полный список доступных возможностей можно найти в каталоге Actions . Разработчики могут использовать Actions on Google для простого создания и управления удобными и полезными диалогами между пользователями и вашими собственными сторонними сервисами.

Этот практический курс — продвинутый модуль, предназначенный для читателей, уже имеющих опыт создания Actions для Google Assistant. Если у вас нет опыта разработки Actions на Google, ознакомьтесь с платформой, пройдя вводные практические курсы ( Уровень 1 и Уровень 2 ). Эти модули познакомят вас с рядом функций, которые помогут расширить функциональность вашего Actions и увеличить аудиторию.

В этом практическом задании вы используете Interactive Canvas — фреймворк, созданный на основе Google Assistant, — для добавления полноэкранной игры в диалоговое действие. Игра представляет собой интерактивное веб-приложение, которое Assistant отправляет в ответ пользователю в диалоге. Затем пользователь может играть в игру, используя голосовой или текстовый ввод на умных дисплеях и мобильных устройствах Android.

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

Рисунок 1. Частично завершенная игра Snow Pal.

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

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

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

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

Ассистент: Welcome to Snow Pal! Would you like to start playing the game?

Пользователь: Yes.

Помощник: Try guessing a letter in the word or guessing the word.

Пользователь: Я предполагаю . I guess the letter E

Ассистент: Let's see if your guess is there...E is right. Right on! Good guess.

Пользователь продолжает угадывать буквы или само неизвестное слово до тех пор, пока игра не закончится.

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

Как создать и развернуть интерактивное действие на холсте
Как обновлять словесную игру в зависимости от голосового и тактильного ввода пользователя.
Как передавать данные в веб-приложение различными способами
Как отлаживать действия на интерактивном холсте

Что вам понадобится

Для участия в этом практическом занятии необходимы следующие предварительные условия:

Веб-браузер, например, Google Chrome.
Среда разработки (IDE) или текстовый редактор на ваш выбор.
На вашем компьютере должны быть установлены Node.js , npm и git.

Для понимания кода, используемого в этом практическом занятии, настоятельно рекомендуется знание JavaScript (ES6).

Дополнительно: Получите полный пример кода

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

2. Введение в интерактивный холст

Interactive Canvas — это фреймворк, созданный на основе Google Assistant, который позволяет добавлять полноэкранные визуальные элементы и анимацию к вашим диалоговым действиям.

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

Пользователь вводит данные в веб-приложение либо голосом, либо касанием, пока диалог не завершится.

Рисунок 2. Действие, созданное с помощью интерактивного холста.

В этом практическом занятии ваш проект состоит из трех основных частей:

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

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

В общих чертах, диалоговое действие, веб-перехватчик и веб-приложение в Snow Pal Action работают следующим образом:

В диалоговом окне пользователю предлагается угадать букву в слове или угадать все слово целиком.
Пользователь говорит веб-приложению Snow Pal на смарт-дисплее : «Я думаю, это буква i» .
Вводимые пользователем данные направляются в ваше диалоговое действие, которое определяется в вашем проекте Actions Builder и/или Actions SDK.
Диалоговое действие обрабатывает ввод пользователя и, в зависимости от того, что это за ввод, либо запускает логику в веб-хуке, которая обновляет веб-приложение, либо отправляет метаданные для непосредственного обновления веб-приложения.
Веб-приложение обновляется, показывая, где буква встречается в слове, и пользователю предлагается снова угадать.

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

3. Настройка

Проверьте настройки разрешений Google.

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

Перейдите в раздел «Управление действиями» .
При необходимости войдите в систему, используя свою учетную запись Google.
Включите следующие разрешения:

Активность в интернете и приложениях
В разделе «Действия в Интернете и приложениях» установите флажок « Включать историю и действия Chrome с сайтов, приложений и устройств, использующих сервисы Google» .

Установите интерфейс командной строки gactions.

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

Для установки инструмента командной строки gactions следуйте инструкциям в разделе «Установка инструмента командной строки gactions» .

Установите интерфейс командной строки Firebase.

Интерфейс командной строки Firebase (CLI) позволяет развернуть ваш проект Actions в Cloud Functions и разместить ваше веб-приложение.

В этом практическом задании для установки Firebase CLI используется npm . Убедитесь, что вы установили npm, который обычно входит в состав Node.js.

Для установки или обновления CLI откройте терминал и выполните следующую команду npm :

npm install -g firebase-tools

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

firebase --version

Убедитесь, что версия Firebase CLI — 8 или выше, чтобы в ней были все последние функции, необходимые для Cloud Functions. Если это не так, выполните npm install -g firebase-tools для обновления.

Для входа в Firebase выполните следующую команду:

firebase login

При входе в Firebase убедитесь, что вы используете ту же учетную запись Google, которую использовали для создания проекта Actions.

Клонируйте репозиторий

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

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

git clone https://github.com/actions-on-google/actions-builder-canvas-codelab-nodejs

Откройте каталог start/ . Этот репозиторий содержит следующие важные каталоги, с которыми вы будете работать:

public/ : В этом каталоге содержится HTML, CSS и JavaScript код вашего веб-приложения.
sdk/custom/ : В этом каталоге содержится логика для ваших диалоговых действий (сцены, намерения и типы).
sdk/webhooks/ : Эта директория содержит ваш веб-хук и игровую логику.

Рисунок 3. Структура кода start каталога.

4. Настройте свой проект Actions.

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

Создайте проект Actions

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

Откройте консоль «Действия» .
Нажмите «Создать проект» .
Введите название проекта , например, canvas-codelab . Это название предназначено для внутреннего использования. Позже вы сможете задать внешнее имя для своего проекта.

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

Сохраните идентификатор проекта для вашего действия.

Идентификатор проекта (Project ID) — это уникальный идентификатор вашего действия. Идентификатор проекта понадобится вам на нескольких этапах этого практического занятия.

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

В консоли «Действия» щелкните три вертикальные точки > Настройки проекта .

Скопируйте идентификатор проекта.

Привязать платежный аккаунт

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

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

Перейдите на страницу оплаты Google Cloud Platform .
Нажмите «Добавить платежный аккаунт» или «Создать аккаунт» .
Заполните платежную информацию.
Нажмите «Начать бесплатную пробную версию» или «Отправить» и включите оплату .
Перейдите на страницу оплаты в Google Cloud .
Нажмите вкладку «Мои проекты» .
Нажмите на три точки > Изменить способ оплаты .
В выпадающем меню выберите настроенный вами платежный аккаунт.
Нажмите «Настроить учетную запись» .

Чтобы избежать дополнительных расходов, выполните действия, описанные в разделе «Упорядочение проекта» .

Развернуть веб-приложение

В этом разделе вы развертываете свое веб-приложение (игру Snow Pal ) с помощью Firebase CLI. После развертывания вы можете получить URL-адрес веб-приложения и посмотреть, как игра выглядит в браузере.

Для развертывания веб-приложения выполните следующие шаги:

В терминале перейдите в каталог start/ .
Выполните следующую команду, заменив {PROJECT_ID} на идентификатор вашего проекта:

firebase deploy --project {PROJECT_ID} --only hosting

Через несколько минут вы увидите сообщение " Deploy complete! " , указывающее на успешное развертывание веб-приложения Snow Pal в Firebase.

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

Получите URL-адрес хостинга, указанный в выводе терминала. URL-адрес должен иметь следующий вид: https://<PROJECT_ID>.web.app

Вставьте URL-адрес в браузер. Вы должны увидеть стартовый экран игры Snow Pal с кнопкой «Начать игру» :

Добавьте URL-адрес веб-приложения и идентификатор проекта в проект Actions.

Далее добавьте URL-адрес вашего веб-приложения и идентификатор проекта в файл actions.intent.MAIN.yaml . Добавление URL-адреса веб-приложения позволяет диалоговому действию определить, на какой URL-адрес отправлять данные, а добавление идентификатора проекта в settings.yaml позволяет отправлять загруженные файлы в нужный проект в консоли Actions.

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

Откройте файл start/sdk/custom/global/actions.intent.MAIN.yaml в текстовом редакторе.
В поле URL замените строку-заполнитель на URL вашего веб-приложения.
Откройте файл start/sdk/settings/settings.yaml в текстовом редакторе.
В поле projectId замените строку-заполнитель на идентификатор вашего проекта.

Перенесите проект в консоль действий.

Чтобы обновить консоль Actions, добавив в нее свой локальный проект, необходимо отправить ваш проект Actions в консоль Actions. Для этого выполните следующие действия:

Перейдите в каталог sdk :

cd sdk/

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

gactions push

Развернуть веб-перехватчик

При выполнении команды gactions push вы импортировали исходный код веб-перехватчика в консоль Actions. В оставшейся части этого практического занятия вы можете редактировать код веб-перехватчика в консоли Actions. На этом этапе вы можете развернуть веб-перехватчик из консоли Actions.

Для развертывания веб-перехватчика выполните следующие действия:

В консоли «Действия» нажмите «Разработка» на панели навигации.
Нажмите вкладку «Веб-перехватчик» на панели навигации.
Нажмите «Развернуть выполнение» .

Внимание: После нажатия кнопки «Развернуть выполнение» появляется сообщение « Требуется учетная запись для выставления счетов» . Для развертывания веб-перехватчика необходимо связать учетную запись для выставления счетов с вашим проектом в Google Cloud. Чтобы настроить учетную запись для выставления счетов, нажмите «Открыть консоль Cloud» и следуйте инструкциям по ее привязке. Вы можете удалить этот проект в конце данного практического занятия, чтобы избежать дополнительных расходов. Дополнительную информацию см. в разделе «Очистка» .

Подготовка и развертывание вашего запроса в Cloud Functions может занять несколько минут. Вы должны увидеть сообщение « Развертывание Cloud Function в процессе...» . После успешного развертывания кода сообщение обновится до «Ваше развертывание Cloud Function актуально» .

Протестируйте в симуляторе.

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

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

В панели навигации консоли «Действия» нажмите «Тест» .
Введите в поле ввода текст Talk to Snow Pal sample и нажмите Enter .
Введите Yes в поле ввода и нажмите Enter . Или нажмите «Начать игру» .

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

5. Разберитесь в инфраструктуре интерактивного холста.

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

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

Разговорное действие

Компонент «Действие в диалоге» вашего Action отвечает за распознавание ввода пользователя, его обработку и отправку на соответствующую сцену, где формируется ответ пользователю. Например, если пользователь говорит «Я думаю, это буква e» в игре Snow Pal , ваше Действие в диалоге извлекает букву в качестве параметра Intent и передает ее соответствующей игровой логике, которая определяет, правильна ли догадка, и соответствующим образом обновляет веб-приложение. Вы можете просмотреть и изменить эту логику диалога в Actions Builder, веб-IDE в консоли Actions. На следующем снимке экрана показана часть вашего Действия в диалоге в Actions Builder:

Рисунок 4. Визуализация Main invocation в Actions Builder.

На этом скриншоте показан Main invocation вашего действия, которому пользователи соответствуют, произнося фразу типа «Привет, Google, поговори с образцом Snow Pal». Когда пользователь вызывает ваше действие, Main invocation отправляет запрос с ответом canvas , содержащего URL-адрес вашего веб-приложения.

Первый ответ canvas в вашем Action должен содержать URL-адрес веб-приложения. Этот ответ указывает Assistant отобразить веб-приложение по этому адресу на устройстве пользователя. Дополнительные ответы в Actions Builder могут включать поле send_state_data_to_canvas_app , значение которого установлено на true . Это поле canvas имя интента и любые значения параметров в веб-приложение при совпадении интента, и веб-приложение обновляется на основе данных, введенных пользователем.

Вебхук

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

Когда вашему действию необходимо выполнить игровую логику, Actions Builder вызывает веб-хук. Например, намерение guess в Game сцене вызывает веб-хук к обработчику guess , который затем выполняет логику для определения того, верна ли догадка пользователя или нет. Веб-хук может включать ответы Canvas в обработчики, которые сопоставляются с файлами веб-приложения и соответствующим образом обновляют веб-страницу.

Веб-приложение

Рисунок 5. Визуальное представление взаимодействия между диалоговым действием, веб-перехватчиком и веб-приложением в интерактивном действии на холсте.

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

Взаимодействие между диалоговым приложением и веб-приложением

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

Для корректного обновления веб-приложения необходимо передать веб-приложению букву «f» . Чтобы передать пользовательский ввод из диалогового окна в веб-приложение, необходимо загрузить API интерактивного холста.

Скрипт для этого API находится в файле /public/index.html , который является основным HTML-файлом игры Snow Pal . Этот файл определяет внешний вид пользовательского интерфейса и загружает несколько скриптов:

index.html

<!-- Load Assistant Interactive Canvas API -->
 <script type="text/javascript" src="https://www.gstatic.com/assistant/interactivecanvas/api/interactive_canvas.min.js"></script>

Для обновления веб-приложения на основе ввода пользователя необходимо также зарегистрировать и настроить обратные вызовы в файле веб-приложения. Обратные вызовы позволяют вашему веб-приложению реагировать на информацию или запросы от диалогового действия.

В файле /public/js/action.js находится предварительно настроенный класс Action для объявления и регистрации коллбэков. Класс Action представляет собой обертку над API интерактивного холста. При создании веб-приложения с помощью функции create() в scene.js создается новый экземпляр Action и вызывается setCallbacks() , как показано в следующем фрагменте кода:

scene.js

// Set Assistant at game level.
this.assistant = new Action(this);
// Call setCallbacks to register Assistant Action callbacks.
this.assistant.setCallbacks();

Функция setCallbacks() определена в классе Action файла /public/js/action.js . Эта функция объявляет коллбэки и регистрирует их в API интерактивного холста при создании игры:

  setCallbacks() {
    // Declare the Interactive Canvas Action callbacks.
    const callbacks = {
      onUpdate: (data) => {
     ...
    // Called by the Interactive Canvas web app once web app has loaded to
    // register callbacks.
    this.canvas.ready(callbacks);
  }

Функция setCallbacks() объявляет функцию обратного вызова onUpdate() , которая вызывается каждый раз при отправке ответа Canvas .

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

Обновление веб-приложения на основе отзывов пользователей.

В этом практическом задании вы используете карту команд для обновления веб-приложения на основе ввода пользователя. Например, когда в сцене Welcome срабатывает намерение start_game , ответ canvas , содержащийся в подсказке, отправляется в веб-приложение. onUpdate() анализирует метаданные из ответа canvas и вызывает команду START_GAME , которая, в свою очередь, вызывает функцию start() в scene.js и обновляет веб-приложение для начала новой игровой сессии.

Функция start() в scene.js также вызывает функцию updateCanvasState() , которая использует метод setCanvasState() для добавления данных состояния, к которым может получить доступ ваш веб-хук.

Метод updateCanvasState() вызывается в конце каждой команды (вы будете добавлять эти команды на протяжении всего практического занятия) и обновляет состояние веб-приложения. Каждый раз, когда вызывается updateCanvasState() , значения displayedWord и incorrectGuesses обновляются в соответствии с текущим состоянием:

scene.js

...
  updateCanvasState() {
    window.interactiveCanvas.setCanvasState({
      correctWord: this.word.text,
      displayedWord: this.word.displayText.text,
      incorrectGuesses: this.incorrectGuesses,
    });

Обновленное состояние становится доступным для следующего хода диалога. Доступ к этому состоянию в веб-хуке можно получить через conv.context.canvas.state , как показано в следующем фрагменте кода:

index.js

...
  let displayedWord = conv.context.canvas.state.displayedWord;
...

6. Добавить функцию угадывания.

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

Разговорное действие

В разделе «Тест» в симуляторе вы получили ответ, содержащий: «Похоже, нам нужно добавить больше функциональности, чтобы это работало правильно». Теперь вы можете удалить это сообщение в консоли действий, чтобы вызывать только веб-хук (в сцене Game намерение « guess уже настроено на вызов веб-хука при совпадении).

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

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

Вебхук

В этом разделе вы обновляете свой веб-хук, добавляя логику, которая сопоставляет правильное или неправильное предположение пользователя с логикой в файле веб-приложения, что затем соответствующим образом обновляет веб-приложение. Обработчик намерения guess уже настроен для вас в веб-хуке, поэтому вам нужно только добавить ответы Canvas к этому намерению, чтобы запустить логику, которая обновляет веб-приложение.

Чтобы обновить веб-перехватчик, выполните следующие действия:

В консоли «Действия» в панели навигации щелкните «Веб-перехватчик» .
Добавьте следующий код в index.js в раздел обработчика guess :

index.js (Раздел A):

// Add Section A `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'CORRECT_ANSWER',
    displayedWord: displayedWord
  },
}));

index.js (Раздел B):

// Add Section B `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'INCORRECT_ANSWER',
  },
}));

Нажмите «Сохранить выполнение заказа» .
Нажмите кнопку «Развернуть» . После завершения развертывания появится сообщение «Ваше развертывание облачной функции обновлено» .

Веб-приложение

Теперь вы можете настроить свое веб-приложение для обработки команд CORRECT_ANSWER и INCORRECT_ANSWER .

Откройте public/js/action.js в текстовом редакторе.
Обновите веб-приложение для обработки команд CORRECT_ANSWER и INCORRECT_ANSWER :

action.js (Раздел C):

// Add Section C `CORRECT_ANSWER: (params) => {` content here.
      CORRECT_ANSWER: (params) => {
        this.gameScene.correctAnswer(params);
      },
      INCORRECT_ANSWER: (params) => {
        this.gameScene.incorrectAnswer();
      },

Для обновления веб-приложения выполните следующую команду:

firebase deploy --project {PROJECT_ID} --only hosting

Проверьте свои действия в симуляторе.

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

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

В панели навигации нажмите «Тест» .
Введите в поле ввода текст Talk to Snow Pal sample и нажмите Enter .
Введите Yes в поле ввода и нажмите Enter . Или же нажмите кнопку «Да» .
Введите букву, которую хотите угадать, в поле ввода и нажмите Enter .

Разберитесь в коде.

В предыдущем разделе вы добавили код, который позволяет пользователям угадывать буквы в вашей игре и видеть эти угадывания либо в слове, либо в игре Snow Pal. В общих чертах, вы выполняете вызов веб-хука в Actions Builder, когда срабатывает намерение guess , который передает данные в ваше веб-приложение для соответствующего обновления. Например, если пользователь угадывает букву в игре Snow Pal , которая есть в слове, веб-приложение обновляется, чтобы показать букву в правильной позиции в слове.

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

Введенные пользователем данные соответствуют намерению, включающему ответ Canvas .
Диалоговое действие или веб-хук отправляет ответ Canvas , который запускает функцию обратного вызова onUpdate() .
Функция обратного вызова onUpdate() отвечает за пользовательскую логику, которая соответствующим образом обновляет веб-приложение.

В данном конкретном проекте код работает следующим образом:

Когда пользователь выбирает вариант guess намерению, Actions Builder извлекает букву из введенных пользователем данных и передает ее в качестве параметра.
Actions Builder вызывает обработчик guess в вашем веб-хуке, который содержит логику для определения того, встречается ли угаданная пользователем буква в слове.
Обработчик guess содержит два ответа Canvas один, который выполняется, когда буква верна, и другой, который выполняется, когда буква неверна. Каждый ответ Canvas передает соответствующие данные (команду CORRECT_ANSWER или INCORRECT_ANSWER ) веб-приложению.
Данные, содержащиеся в поле data ответа Canvas , передаются методу onUpdate() в action.js . onUpdate() вызывает соответствующую команду из карты команд в файле scene.js .
Карта команд соответствует функциям correctAnswer() и incorrectAnswer() в scene.js . Эти функции соответствующим образом обновляют веб-приложение, отражая предположение пользователя, и вызывают setCanvasState() для отправки данных о состоянии из вашего веб-приложения в ваш веб-хук.

7. Добавить функцию определения победы/поражения.

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

Разговорное действие

Функциональность, отвечающая за победу или поражение пользователя в игре, будет настроена внутри намерения guess , поэтому вам не потребуется выполнять дополнительную настройку в Actions Builder.

Вебхук

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

Чтобы обновить веб-перехватчик, выполните следующие действия:

В консоли «Действия» в панели навигации щелкните «Веб-перехватчик» .
Добавьте следующий код в index.js в раздел обработчика guess :

index.js (Раздел D):

// Add Section D `if (userHasWon)` content here.
    if (userHasWon) {
      conv.add(`<speak>Let's see if your guess is there...<break
        time='2500ms'/> ${guess} is right. That spells ${correctWord}!  
        ${randomArrayItem(WIN_RESPONSES)}</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'WIN_GAME',
          displayedWord: displayedWord
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (Раздел E):

// Add Section E `}` here.
}

index.js (Раздел F):

// Add Section F `Check if the user has exceeded the maximum` content here.
// Check if the user has exceeded the maximum amount of max guesses allowed.
    const userHasLost = conv.context.canvas.state.incorrectGuesses + 1 >= MAX_INCORRECT_GUESSES;
    if (userHasLost) {
      conv.add(`<speak>Let's see if your guess is there...<break
      time='2500ms'/> ${guess} is wrong. Sorry you lost. The word is ${correctWord}!</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'LOSE_GAME',
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (Раздел G):

// Add Section G `}` here.
}

Нажмите «Сохранить выполнение заказа» .
Нажмите кнопку «Развернуть» . После завершения развертывания появится сообщение «Ваше развертывание облачной функции обновлено» .

Здесь вы добавили два ответа Canvas с командами WIN_GAME и LOSE_GAME для обработки выигрыша или проигрыша пользователя в игре. В следующем разделе вы добавите функциональность, которая обновляет веб-приложение в зависимости от того, выиграл пользователь или проиграл.

Веб-приложение

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

Откройте public/js/action.js в текстовом редакторе.
Обновите ваше веб-приложение, чтобы оно обрабатывало команды WIN_GAME и LOSE_GAME :

action.js (Раздел H):

// Add Section H `WIN_GAME: (params) => {` content here.
      WIN_GAME: (params) => {
        this.gameScene.winGame(params);
      },
      LOSE_GAME: (params) => {
        this.gameScene.loseGame();
      },

Для обновления веб-приложения выполните следующую команду:

firebase deploy --project {PROJECT_ID} --only hosting

Проверьте свои действия в симуляторе.

На этом этапе ваше действие может обрабатывать исход игры (выигрыш или проигрыш) и отображать соответствующий экран для каждого результата.

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

В панели навигации консоли «Действия» нажмите «Тест» .
Введите в поле ввода текст Talk to Snow Pal sample и нажмите Enter .
Введите Yes в поле ввода и нажмите Enter . Или нажмите кнопку «Начать игру» .
Угадывайте буквы и слова, пока не выиграете или не проиграете.

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

Разберитесь в коде.

Функция определения победы и поражения работает аналогично функции угадывания: пользователь соответствует его guess , и ваш веб-хук оценивает это предположение. Если предположение верно, код проверяет, выиграл ли пользователь; если да, то в веб-приложение отправляется команда WIN_GAME . Если предположение неверно, код проверяет, проиграл ли пользователь; если да, то в веб-приложение отправляется команда LOSE_GAME . Эти команды запускают функции winGame() и loseGame() в scene.js , которые обновляют веб-приложение, отображая экран с информацией о победе или поражении, и обновляют состояние игры.

8. Добавить функцию повторного воспроизведения.

В этом разделе вы добавляете функциональность, позволяющую пользователю либо сказать «Играть снова» , либо нажать кнопку « Играть снова» в веб-приложении, чтобы начать новую игру. Вы изменяете интент play_again в Actions Builder, чтобы он отправлял ответ canvas , который соответствующим образом обновляет веб-приложение, и добавляете логику, которая запускает интент play_again когда пользователь нажимает кнопку «Играть снова» .

Разговорное действие

При тестировании действия в предыдущем разделе при попытке повторного запуска игры вы получали следующее сообщение: «Это было бы здорово, но мы реализуем эту функциональность в следующем разделе. А пока просто сбросьте действие». Теперь вы можете удалить это сообщение и заменить его сообщением, которое отвечает пользователю, когда он запрашивает другую игру ( «Хорошо, вот еще одна игра!» ), и включает в себя ответ canvas , который запускает веб-приложение для начала новой игры.

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

В консоли действий щелкните раскрывающееся меню «Сцена» .
Нажмите на сцену «Игра» .
Нажмите кнопку «При совпадении play_again» в разделе «Обработка намерений пользователя» .
Замените подсказку следующим текстом:

candidates:
  - first_simple:
      variants:
        - speech: 'Okay, here''s another game!' 
    canvas:
      sendStateDataToCanvasApp: true

Нажмите « Сохранить ».

Вебхук

В этом практическом задании веб-хук управляет игровой логикой. Поскольку функция повторной игры не требует какой-либо проверки логики, вам не нужно вызывать веб-хук; вместо этого вы можете отправить ответ canvas непосредственно из Actions Builder, чтобы передать необходимые данные в веб-приложение (вы настроили это в предыдущем разделе).

Веб-приложение

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

Откройте public/js/action.js в текстовом редакторе.
Обновите веб-приложение для обработки команды PLAY_AGAIN :

action.js (Раздел I):

// Add Section I `PLAY_AGAIN: (params) => {` content here.
      PLAY_AGAIN: (params) => {
        this.gameScene.start();
      },

Откройте public/js/scene.js в текстовом редакторе.
Update the web app to start a new game session when the user clicks the ' Play Again ' button:

scene.js (Section J):

// Add Section J `sendTextQuery` content here.
     window.interactiveCanvas.sendTextQuery('Play again');

Run the following command to update the web app:

firebase deploy --project {PROJECT_ID} --only hosting

Проверьте свои действия в симуляторе.

Your Action can now start a new game session when the user says "Play again" or clicks the Play Again button.

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

In the navigation bar, click Test .
Type Talk to Snow Pal sample in the Input field and press Enter .
Type Yes in the Input field and press Enter . Alternatively, click the Start game button.
Guess letters and words until you either win or lose.
Type Play again in the Input field and press Enter . Alternatively, click the Play again button.

Разберитесь в коде.

When you tested your Action, you could start a new game through either voice input ( "Play again" ) or touch input (click the Play again button).

For the voice input option, when the user says "Play again" or some variation of that, the play_again intent is matched and adds a prompt ( "Okay, here's another game!" ) to the prompt queue. The canvas response included in the prompt sends the intent name and other metadata to the web app. The intent name is passed to the onUpdate() callback, which maps the corresponding command, PLAY_AGAIN , to the command map in action.js . The PLAY_AGAIN command triggers the start() function in scene.js and updates the web app with a new game session.

For the touch input option, you use sendTextQuery() , an Interactive Canvas API that allows you to trigger an intent through touch input, to make the button work.

In this codelab, you use sendTextQuery() to invoke the play_again intent when a user clicks the Play again button. The Play again argument matches a training phrase in the play_again intent and triggers this intent in the same way a user saying "Play again" does. The play_again intent then triggers logic that updates the web app and begins a new game session.

9. Update PLAY_GAME built-in intent

In this section, you update the PLAY_GAME built-in intent .

The PLAY_GAME built-in intent allows users to invoke your Action when they make a general request, such as "I want to play a game."

The source code contains the PLAY_GAME built-in intent, which is located at /sdk/custom/global/actions.intent.PLAY_GAME.yaml . This is reflected in the console in the Invocation section as PLAY_GAME , as shown in the following screenshot:

To enable users to invoke your Action through this built-in intent, you need to add a canvas response with the web app URL to the PLAY_GAME built-in intent. To do so, follow these steps:

In the Actions console, click PLAY_GAME in the navigation bar.
Update the prompt to include your web app URL, as shown in the following snippet:

candidates:
  - canvas:
      url: 'https://<PROJECT_ID>.web.app'

Нажмите « Сохранить ».

Проверьте свои действия в симуляторе.

Your Action now supports the PLAY_GAME built-in intent.

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

In the navigation bar, click Test .
Click Test built-in intent handling .
Click Invoke Action .

Your Action should be invoked in the simulator.

10. Appendix: Troubleshooting the Interactive Canvas Action

In this section, you learn how to debug your Interactive Canvas Action when it's not working properly. The Snow Pal project comes pre-packaged with a debugging overlay that you can enable. The overlay displays all console.log() and console.error() output to the bottom right of the display, as shown in the following screenshot:

To enable this overlay, open the /public/css/main.css file and comment the line display: none !important; , as shown in the following snippet:

main.css

.debug {
 display: flex;
 flex-direction: column;

/* Comment below to view debug overlay */
/* display: none !important; */

 width: 500px;
 height: 150px;
 right: 0;
 bottom: 0;
 position: absolute;
}

Приведите свой проект в порядок [рекомендуется]

To avoid incurring possible charges, it is recommended to remove projects that you don't intend to use. To delete the projects you created in this codelab, follow these steps:

To delete the Google Cloud Project and resources, complete the steps listed in the Shutting down (deleting) projects section.

Необязательно: чтобы немедленно удалить свой проект из консоли «Действия», выполните действия, описанные в разделе «Удаление проекта» . Если вы не выполните этот шаг, ваш проект будет автоматически удален примерно через 30 дней.

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

You've completed the introductory Interactive Canvas codelab and now have the skills necessary to build your own Interactive Canvas Action.

Что вы узнали

How to build, deploy, and test an Interactive Canvas Action
How to use Canvas responses to update the web app
How to use different methods to enhance your Action, like sendTextQuery() and setCanvasState()
How to debug your Action

Узнать больше

Check out the following resources to learn more about Interactive Canvas:

Interactive Canvas documentation : The official Actions on Google documentation for Interactive Canvas.
Interactive Canvas sample : The code for a simple Interactive Canvas game that lets you spin a triangle and modify its colors.
Games portal : The guidelines for building games on Google Assistant.

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

Перед уходом, пожалуйста, заполните короткую анкету о ваших впечатлениях.