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

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

1. Обзор

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

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

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

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

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

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

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

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

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

Ассистент: 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, которая позволяет добавлять полноэкранные визуальные эффекты и анимацию в ваше диалоговое действие.

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

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

Рисунок 2. Действие, созданное с помощью Interactive Canvas.

В этой кодовой лаборатории ваш проект разделен на следующие три основные части:

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

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

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

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

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

3. Настройка

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

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

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

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

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

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

Чтобы установить интерфейс командной строки gactions, следуйте инструкциям в разделе «Установка инструмента командной строки gactions» .

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

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

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

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

npm install -g firebase-tools

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

firebase --version

Убедитесь, что версия Firebase CLI 8 или выше, чтобы в ней были все новейшие функции, необходимые для облачных функций. Если это не так, запустите 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 с помощью интерфейса командной строки gactions и развернете свое веб-приложение и веб-перехватчик.

Создать проект действий

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

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

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

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

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

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

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

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

Свяжите платежный аккаунт

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

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

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

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

Развертывание веб-приложения

В этом разделе вы развернете свое веб-приложение (игру Snow Pal ) с помощью интерфейса командной строки Firebase. После развертывания вы можете получить 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 позволяет отправлять загруженные файлы в правильный проект в консоли действий.

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

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

Отправить проект в консоль действий

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

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

cd sdk/

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

gactions push

Развертывание вебхука

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

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

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

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

Облачным функциям может потребоваться несколько минут для подготовки и развертывания вашего выполнения. Вы должны увидеть сообщение «Выполняется развертывание облачной функции…» . При успешном развертывании кода сообщение об обновлении развертывания вашей облачной функции становится актуальным .

Тест в симуляторе

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

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

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

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

5. Понимание инфраструктуры Interactive Canvas.

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

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

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

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

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

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

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

Вебхук

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

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

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

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

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

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

Вам необходимо включить связь между вашим диалоговым действием и веб-приложением, чтобы ваше веб-приложение могло обновляться на основе пользовательского ввода. Например, если пользователь говорит : «Я думаю, это буква 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 Interactive Canvas. Когда веб-приложение создается с помощью функции create() в scene.js , создается новый экземпляр Action и вызывается setCallbacks() , как показано в следующем фрагменте:

сцена.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 . Эта функция объявляет обратные вызовы и регистрирует их с помощью Interactive Canvas 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 .

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

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

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

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

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

сцена.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 .

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

В предыдущем разделе вы добавили код, который позволяет пользователям угадывать буквы в вашей игре и видеть эти предположения, отраженные либо в слове, либо в Снежном приятеле. На высоком уровне вы вызываете веб-перехватчик в 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 в вашем текстовом редакторе.
Обновите веб -приложение, чтобы запустить новую игровую сеанс, когда пользователь нажимает кнопку « Воспроизвести снова »:

Scene.js (раздел J):

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

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

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

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

Ваше действие теперь может запустить новую игровую сеанс, когда пользователь говорит «воспроизвести снова» или нажимает кнопку «Воспроизведение» .

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

В панели навигации нажмите тест .
Введите Talk to Snow Pal sample в поле ввода и нажмите Enter .
Введите Yes в поле ввода и нажмите Enter . В качестве альтернативы нажмите кнопку «Пуск» .
Угадайте письма и слова, пока не выиграете или не проиграете.
Введите Play again в поле ввода и нажмите Enter . В качестве альтернативы нажмите кнопку «Воспроизвести» снова .

Понять код

Когда вы тестировали свое действие, вы можете начать новую игру с помощью голосового ввода ( «воспроизвести снова» ) или ввести ввод (нажмите кнопку «Воспроизведение» ).

Для опции голосового ввода, когда пользователь говорит «воспроизвести снова» или какую -то изменение этого, намерение play_again соответствует и добавляет подсказку ( «Хорошо, вот еще одна игра!» ) В очередь Ответ canvas , включенный в приглашение, отправляет имя намерения и другие метаданные в веб -приложение. Имя намерения передается в обратный вызов onUpdate() , который отображает соответствующую команду, PLAY_AGAIN , на карту команд в action.js . Команда PLAY_AGAIN запускает функцию start() в scene.js и обновляет веб -приложение новым игровым сеансом.

Для опции Touch Input вы используете sendTextQuery() , интерактивный API Canvas, который позволяет запустить намерение с помощью сенсорного ввода, чтобы заставить кнопку работать.

В этом CodeLab вы используете sendTextQuery() чтобы вызвать намерение play_again , когда пользователь нажимает кнопку «Воспроизведение» . Аргумент Play again соответствует учебной фразе в намерении play_again и запускает это намерение так же, как и пользователь, который говорит «воспроизводить снова» . Затем намерение play_again запускает логику, которая обновляет веб -приложение и начинает новую игру.

9. Обновление встроенного намерения Play_game

В этом разделе вы обновляете встроенное намерение PLAY_GAME .

Встроенное намерение PLAY_GAME позволяет пользователям вызывать ваше действие, когда они делают общий запрос, например , «Я хочу играть в игру».

Исходный код содержит встроенное намерение PLAY_GAME , которое расположено по адресу /sdk/custom/global/actions.intent.PLAY_GAME.yaml . Это отражено в консоли в разделе «Вызов» как PLAY_GAME , как показано на следующем скриншоте:

Чтобы пользователи могли вызвать ваши действия с помощью этого встроенного намерения, вам необходимо добавить ответ canvas с URL веб-приложения в встроенное намерение PLAY_GAME . Для этого выполните следующие действия:

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

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

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

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

Ваше действие теперь поддерживает встроенные намерения PLAY_GAME .

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

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

Ваше действие должно быть вызвано в симуляторе.

10. Приложение: Устранение неполадок интерактивного действия Canvas

В этом разделе вы узнаете, как отладить свое интерактивное действие Canvas, когда оно не работает должным образом. Проект Snow Pals поставляется в предварительном упаковке с отладкой, который вы можете включить. Наложение отображает все console.log() и console.error() вывод в правой нижней части дисплея, как показано на следующем скриншоте:

Чтобы включить это наложение, откройте файл /public/css/main.css и прокомментируйте линию display: none !important; , как показано в следующем фрагменте:

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;
}

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

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

Чтобы удалить проект Google Cloud и ресурсы, выполните шаги, перечисленные в разделе «Выключение» (удаление) проектов .

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

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

Вы завершили вступительный интерактивный Canvas CodeLab и теперь у вас есть навыки, необходимые для создания собственного интерактивного действия Canvas.

Что вы узнали

Как построить, развернуть и проверить интерактивное действие Canvas
Как использовать ответы Canvas для обновления веб -приложения
Как использовать различные методы для улучшения вашего действия, например, sendTextQuery() и setCanvasState()
Как отладить свое действие

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

Проверьте следующие ресурсы, чтобы узнать больше о интерактивном холсте:

Интерактивная документация на холсте : официальные действия по документации Google для интерактивного холста.
Интерактивный образец холста : код для простой интерактивной игры Canvas, которая позволяет вращать треугольник и изменить его цвета.
Игр портал : руководящие принципы построения игр в Google Assistant.

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

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