Игра для тренировки правописания с использованием Google Assistant и Cloud Firestore

1. Обзор

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

Этот практический урок охватывает концепции среднего уровня сложности для разработки приложений с использованием Google Assistant, Cloud Functions и Cloud Firestore. В ходе урока вы создадите игру под названием «Практика правописания», которая использует Google Assistant, чтобы задавать пользователям вопросы по написанию слов.

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

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

  • Получает от пользователя ответы на вопросы по орфографии и, в зависимости от значения, изменяет диалоговые подсказки.
  • В ответ он дает подсказки, связанные с правописанием слова, например, его определение или повторяет слово.
  • Создает игровой цикл, позволяющий пользователю снова взаимодействовать с Ассистентом после того, как слово будет произнесено по буквам.

Прежде чем начать разработку, вы можете взаимодействовать с этим действием на своем устройстве с поддержкой Google Ассистента, сказав: «Привет, Google, поговори со Spelling Practice». Для повторного пользователя стандартный путь взаимодействия с этим действием будет выглядеть следующим образом:

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

2e9f94dc0ceafc96.png

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

  • Как взаимодействовать с Cloud Firestore
  • Как использовать слоты для сбора данных от пользователя
  • Как обработать ввод пользователя и вернуть ответ.
  • Как использовать условия для добавления логики в сцену
  • Как добавить игровой цикл

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

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

  • Веб-браузер, например, Google Chrome.
  • Среда разработки для написания облачных функций.
  • Способ оплаты. В этом практическом занятии используется Cloud Functions for Firebase, поэтому для его проведения требуется тарифный план Firebase Blaze ( подробнее ).
  • Терминал для выполнения команд оболочки.
  • Node.js 10 или более поздняя версия

2. Получите код функций.

Клонируйте репозиторий GitHub из командной строки:

$ git clone https://github.com/FirebaseExtended/codelab-actions-firestore

3. Создайте проект Firebase и настройте приложение.

Создайте проект Firebase.

  1. Войдите в Firebase .
  2. В консоли Firebase нажмите «Добавить проект» (или «Создать проект» ), затем назовите свой проект Firebase Spelling-Practice .

66ae8d1894f4477.png

  1. Пройдите все этапы создания проекта. Примите условия использования Firebase, если появится соответствующий запрос. Пропустите настройку Google Analytics, поскольку вы не будете использовать Analytics для этого приложения.

Чтобы узнать больше о проектах Firebase, см. раздел «Понимание проектов Firebase» .

Перейдите на тарифный план Blaze.

Для использования Cloud Functions для Firebase вам потребуется обновить свой проект Firebase до тарифного плана Blaze , что означает привязку учетной записи Google Cloud Billing к вашему проекту. Для этого вам потребуется указать данные кредитной карты или другой способ оплаты.

Все проекты Firebase, включая те, что используют тарифный план Blaze, по-прежнему имеют доступ к бесплатным квотам использования Cloud Functions. Шаги, описанные в этом практическом руководстве, будут соответствовать бесплатным лимитам использования. Однако вы будете платить небольшую сумму ( около 0,03 доллара США ) из Cloud Storage, который используется для размещения образов сборки Cloud Functions.

4. Установите Firebase CLI.

Интерфейс командной строки Firebase (CLI) позволяет развертывать облачные функции.

Существует несколько вариантов установки Firebase CLI в зависимости от вашей операционной системы и сценария использования. Следующие шаги описывают наиболее распространенный вариант, если вы также используете Cloud Functions.

  1. Убедитесь, что у вас установлен npm , который обычно поставляется вместе с Node.js.
  2. Установите или обновите CLI, выполнив следующую команду npm:
$ npm -g install firebase-tools
  1. Убедитесь в правильности установки интерфейса командной строки, выполнив следующую команду:
$ firebase --version

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

  1. Для авторизации Firebase CLI выполните следующую команду:
$ firebase login
  1. В каталоге spelling-functions-start настройте Firebase CLI для использования вашего проекта Firebase. Выполните следующую команду, выберите идентификатор вашего проекта, а затем следуйте инструкциям. При появлении запроса вы можете выбрать любой псевдоним, например, codelab .
$ firebase use --add

5. Каталог функций

Теперь вы добавите функциональность, используя Firebase SDK для Cloud Functions, чтобы создать бэкэнд для игры Spelling Practice .

Cloud Functions позволяет запускать код в облаке без необходимости настройки сервера. В этом практическом занятии мы покажем, как создавать функции, реагирующие на события Firebase Authentication, Cloud Storage и Firebase Realtime Database. Начнём с аутентификации.

При использовании Firebase SDK для Cloud Functions код ваших функций будет находиться в каталоге functions (по умолчанию). Для вашего удобства мы уже создали файл functions/index.js , куда будет помещен ваш код. Перед продолжением вы можете ознакомиться с содержимым каталога functions .

$ cd functions
$ ls

Код ваших функций также является приложением Node.js , и поэтому ему необходим package.json , который содержит некоторую информацию о вашем приложении и перечисляет зависимости.

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

В файле package.json уже указаны две необходимые зависимости: Firebase SDK для Cloud Functions и Firebase Admin SDK . Чтобы установить их локально, выполните команду npm install из каталога functions :

$ npm install

Теперь давайте посмотрим на файл index.js :

index.js

/**
 * Copyright 2021 Google Inc. All Rights Reserved.
 * ...
 */
// TODO(DEVELOPER): Import the Cloud Functions for Firebase and Firebase Admin modules here. Also import the Actions SDK here.
// TODO(DEVELOPER): Write the getWordDetailsFromDictionaryAPI function here.
// TODO(DEVELOPER): Write the createSpellingPracticeWord function here.
// TODO(DEVELOPER): Write the app Handle getSpellingWordList function here.
// TODO(DEVELOPER): Write the app Handle getSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle repeatSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle definitionOfSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle verifySpellingWord function here.

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

6. Импортируйте необходимые модули.

Для выполнения этого практического задания требуется три модуля.

  • Модуль firebase-functions позволяет нам писать триггеры для наших облачных функций.
  • Модуль firebase-admin позволяет использовать платформу Firebase на сервере с правами администратора, например, для записи в Cloud Firestore.
  • Библиотека выполнения Actions SDK для Node.js обеспечивает обработку запросов Actions SDK для Google Ассистента.
  1. Установите Actions SDK, выполнив следующую команду npm:
$ npm install @assistant/conversation
  1. В файле index.js замените первую строку TODO на следующую.

Эти изменения импортируют все необходимые модули.

Кроме того, Firebase Admin SDK может быть автоматически настроен при развертывании в среде Cloud Functions или другом контейнере Google Cloud. Вот что происходит, когда мы вызываем admin.initializeApp(); в приведенных ниже изменениях.

index.js

/**
 * Copyright 2021 Google Inc. All Rights Reserved.
 * ...
 */

// Import the Actions SDK
const {conversation} = require('@assistant/conversation');
const https = require('https');
const app = conversation();
const cors = require('cors')({origin: true});

// Import the Firebase SDK for Cloud Functions.
const functions = require('firebase-functions');
// Import and initialize the Firebase Admin SDK.
const admin = require('firebase-admin');
admin.initializeApp();
// To access Cloud Firestore
const db = admin.firestore();
// TODO(DEVELOPER): Write the getWordDetailsFromDictionaryAPI function here.
// TODO(DEVELOPER): Write the createSpellingPracticeWord function here.
// TODO(DEVELOPER): Write the shuffleWordList function here.
// TODO(DEVELOPER): Write the app Handle getSpellingWordList function here.
// TODO(DEVELOPER): Write the app Handle getSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle repeatSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle definitionOfSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle verifySpellingWord function here.

Теперь добавим бизнес-логику с использованием функций для поддержки действий ассистента.

7. Создайте функции

Получите определения слов и запишите их в Cloud Firestore.

Для получения определений слов вы будете использовать общедоступный API dictionaryapi.dev .

В файле index.js замените TODO для getWordDetailsFromDictionaryAPI следующим текстом:

index.js

// Retrieves word definition and audio pronunciation from api.dictionaryapi.dev service
// Function uses service provided by https://dictionaryapi.dev/
async function getWordDetailsFromDictionaryAPI(word) {
  let responseData="";
  let req = https.request({
    host: 'api.dictionaryapi.dev',
    port: 443,
    path:'/api/v2/entries/en/' + word,
    method:'GET'
  }, (res) => {
    res.setEncoding('utf8');
    res.on('data', d => {
        responseData+=d;
    })
    res.on('end',function(){
        let object = JSON.parse(responseData)
        const wordListRef = db.collection('wordlist');
        wordListRef.doc(object[0].word).set(
          object[0]
        );
       return responseData;
     });
  });
  req.end();
}

Добавьте триггер Cloud Firestore.

Далее вам нужно будет создать облачную функцию, которая будет запускаться всякий раз, когда в Cloud Firestore создается новый документ. Она будет вызывать API dictionaryapi.dev для получения определений слов с помощью функции getWordDetailsFromDictionaryAPI которую мы написали выше.

В файле index.js замените TODO для createSpellingPracticeWord следующим текстом:

index.js

// Триггер Firestore, который получает определения слов через getWordDetailsFromDictionaryAPI для каждого нового документа Firestore

exports.createSpellingPracticeWord = functions.firestore
  .document('wordlist/{word}')
  .onCreate((snap, context) => {
    const newValue = snap.data();
    const word = newValue.word;
    getWordDetailsFromDictionaryAPI(word);
});

Составьте список слов для игры.

Вы можете написать облачную функцию, которая будет получать список слов для тренировки правописания из Cloud Firestore для Google Ассистента. Для этого мы используем обработчик приложения.

В файле index.js замените TODO для getSpellingWordList следующим кодом.

Добавление этой функции в специальный app.handle — это способ сделать её доступной из Google Assistant.

index.js

// Store the list of spelling words in Assistant session
app.handle('getSpellingWordList', conv => {
  const wordListRef = db.collection('wordlist').limit(50);
  const snapshot = wordListRef;

  if (snapshot.empty) {
    console.log('No matching documents.');
    return;
  }
  VocabularyList = []

  return snapshot.get().then(snapshot => {
    snapshot.forEach(doc => {
      if (doc.data().word) {
          let definition = 'unknown';
          let audio = 'unknown';
          try {
            if(doc.data().hasOwnProperty('meanings')) {
              if(doc.data().meanings[0].hasOwnProperty('definitions')) {
                  definition = doc.data().meanings[0].definitions[0].definition;
              }
            }
            if(doc.data().hasOwnProperty('phonetics')) {
              if(doc.data().phonetics.length > 0)
                audio = doc.data().phonetics[0].audio;
            }
          } catch (error) {
            console.log(error);
          }

          let obj = {
            word: doc.data().word,
            answer: doc.data().word.split("").join(" "),
            definition: definition,
            audio: audio
          }
          VocabularyList.push(obj);
      }
      // Shuffle the array
      let currentIndex = VocabularyList.length, temporaryValue, randomIndex;
      while (0 !== currentIndex) {
        randomIndex = Math.floor(Math.random() * currentIndex);
        currentIndex -= 1;
        temporaryValue = VocabularyList[currentIndex];
        VocabularyList[currentIndex] = VocabularyList[randomIndex];
        VocabularyList[randomIndex] = temporaryValue;
      }
      conv.session.params.vocabWord = VocabularyList;
      conv.session.params.vocabWordIndex = 0;
    });
  });
})

Получите комментарий от ассистента во время сессии

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

В файле index.js замените TODO для getSpellingWord следующим кодом:

index.js

// Returns a spelling practice word to Google Assistant and uses Speech Synthesis Markup Language (SSML) to format the response
app.handle('getSpellingWord',  conv => {
  if (!conv.session.params.vocabWord.empty) {
    conv.session.params.vocabWordIndex+=1;
    const ssml = '<speak>' +
    '<audio src="'+ conv.session.params.vocabWord[conv.session.params.vocabWordIndex].audio +'">Use phonetics to spell the word.</audio> ' +
    '</speak>';
    conv.add(ssml);
  }
  else
    conv.add('Great job! You completed the Spelling practice');
});

Разрешите игре повторять слово.

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

В файле index.js замените TODO для repeatSpellingWord следующим текстом:

index.js

// Returns current spelling word
app.handle('repeatSpellingWord',  conv => {
  if (!conv.session.params.vocabWord.empty) {
    const ssml = '<speak>' +
    '<audio src="'+ conv.session.params.vocabWord[conv.session.params.vocabWordIndex].audio +'">Use phonetics to spell the word. </audio> ' +
    '</speak>';
    conv.add(ssml);
  }
  else
    conv.add('Great job! You completed the Spelling practice');
});

Узнайте определение этого слова.

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

В файле index.js замените TODO вместо definitionOfSpellingWord следующим текстом:

index.js

// Returns spelling word definition from Assistant session parameter
app.handle('definitionOfSpellingWord',  conv => {
  conv.add( 'It means ' + conv.session.params.vocabWord[conv.session.params.vocabWordIndex].definition);
});

Проверьте орфографический ответ пользователя.

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

В файле index.js замените TODO для verifySpellingWord следующим кодом:

index.js

// Verifies user spelling response
app.handle('verifySpellingWord', conv => {
  try {
    userResponse = conv.intent.params.userresponse.resolved.join("");
    if (userResponse.toLowerCase() === conv.session.params.vocabWord[conv.session.params.vocabWordIndex].word.toLowerCase()) {
      conv.add('You are correct. Say next to continue.');
    }
    else {
      conv.add('Sorry, wrong answer. The correct answer is ' + conv.session.params.vocabWord[conv.session.params.vocabWordIndex].answer + ' . Say next to continue.');
    }
  } catch (error) {
    conv.add('Sorry. I did not understand your response' );
  }
});
exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

Разверните все свои функции

Ваши облачные функции станут активны только после того, как вы развернете их в Firebase.

Из корневого каталога spelling-functions-start выполните следующую команду:

$ firebase deploy --only functions

Вот что вы должны увидеть в консоли:

i  deploying functions
i  functions: ensuring necessary APIs are enabled...
⚠  functions: missing necessary APIs. Enabling now...
i  env: ensuring necessary APIs are enabled...
⚠  env: missing necessary APIs. Enabling now...
i  functions: waiting for APIs to activate...
i  env: waiting for APIs to activate...
✔  env: all necessary APIs are enabled
✔  functions: all necessary APIs are enabled
i  functions: preparing functions directory for uploading...
i  functions: packaged functions (X.XX KB) for uploading
✔  functions: functions folder uploaded successfully
i  starting release process (may take several minutes)...
i  functions: creating function createSpellingPracticeWord(us-central1)...
✔  functions[createSpellingPracticeWord(us-central1)]: Successful create operation.
i  functions: creating function ActionsOnGoogleFulfillment(us-central1)...
✔  functions[ActionsOnGoogleFulfillment(us-central1)]: Successful create operation.

✔  Deploy complete!
Project Console: https://console.firebase.google.com/project/spelling-practice-1234/overview

Запишите URL-адрес конечной точки HTTP функции ActionsOnGoogleFulfillment для дальнейшего использования. Чтобы получить доступ к конечной точке, откройте консоль Firebase , а затем щелкните проект spelling-practice . Откройте панель инструментов Functions, чтобы просмотреть конечную точку функции.

332cb0437411a242.png

Вы завершили добавление всех необходимых функций. Теперь перейдём к настройке Cloud Firestore.

8. Включите Cloud Firestore

Вам потребуется включить Cloud Firestore.

В разделе «Сборка» консоли Firebase нажмите Firestore . Затем нажмите «Создать базу данных» .

5c0b4abf4410ffcf.png

Доступ к данным в Cloud Firestore контролируется правилами безопасности. Для начала необходимо установить несколько основных правил для данных. Щелкните Firestore, затем на вкладке «Правила» в консоли Firebase добавьте следующие правила и нажмите «Опубликовать» .

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

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      //
      // WARNING: These rules are insecure! We will replace them with
      // more secure rules later in the codelab
      //
      allow read, write: if request.auth != null;
    }
  }
}

9. Добавьте данные о прочитанных словах в Cloud Firestore.

На этом этапе вы запишете данные о словарном запасе в Cloud Firestore, чтобы сгенерировать список слов для Ассистента (и игры).

Данные Cloud Firestore структурированы в коллекции, документы, поля и подколлекции. Каждое слово для игры будет храниться как отдельный документ в коллекции верхнего уровня под названием wordlist . Для каждого нового документа в коллекции Firestore будет запускаться функция createSpellingPracticeWord для получения сведений о слове из сервиса Dictionary API .

Создайте коллекцию Cloud Firestore

  1. В консоли Firebase перейдите в раздел Cloud Firestore.
  2. Нажмите + Начать сбор коллекции .
  3. В текстовом поле «Идентификатор коллекции» введите wordlist , затем нажмите «Далее» .

1b4ccadb90f52f02.png

Далее мы создадим документ для слова: agreement

  1. В текстовом поле «Идентификатор документа» введите agreement .
  2. В текстовое поле «Поле» введите word , а в текстовое поле «Значение»agreement .
  3. Нажмите « Сохранить ».

379037e011e8511e.png

При добавлении этого документа в Cloud Firestore запускается функция createSpellingPracticeWord , которая получает подробные определения слова. Добавьте другие слова (например: awe, car, true, tell, better, commute и т. д.), создав для каждого слова новый документ.

10. Настройте Google Ассистента

В следующих разделах описано, как настроить среду разработки Google Assistant и создать проект Actions.

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

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

  1. Перейдите на страницу «Управление действиями» .
  2. Если вы еще этого не сделали, войдите в систему с помощью своей учетной записи Google.
  3. Включите следующие разрешения:
  • Активность в интернете и приложениях
  • В разделе «Активность в Интернете и приложениях» установите флажок рядом с пунктом «Включать историю и активность Chrome с сайтов, приложений и устройств, использующих сервисы Google» .

c988e1e639e6d6e1.png

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

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

  1. Откройте консоль «Действия» .
  2. Нажмите «Создать проект» .
  3. Принять условия предоставления услуг

b174d45710b8086b.png

  1. Введите или выберите файл spelling-practice-codelab , который вы создали с помощью консоли Firebase. (Это название предназначено для внутреннего использования. Позже вы сможете задать внешнее имя для своего проекта.)

a2951de5d2001fac.png

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

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

Для развертывания вашего действия в производственной среде необходимо указать отображаемое имя; однако для тестирования действия указывать отображаемое имя не требуется. Вместо этого вы можете использовать фразу "Поговорить с моим тестовым приложением" в симуляторе для вызова вашего действия.

Настройка выполнения

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

Для настройки процесса выполнения заказов выполните следующие шаги:

  1. В боковой панели навигации нажмите «Веб-перехватчик» .
  2. Выберите HTTPS-адрес в качестве варианта выполнения:

d523bf003e96e66f.png

  1. Введите URL-адрес конечной точки вашей функции в текстовое поле «Конечная точка HTTPS» , затем нажмите «Сохранить» .

be53e2cd0d914d54.png

В следующем разделе вы настроите приглашение для основного вызова в консоли действий.

Настройте основной вызов

Необходимо отредактировать основной вызов , чтобы определить, что произойдет после того, как пользователь вызовет ваше действие.

По умолчанию Actions Builder выдает стандартное сообщение при запуске действия ( «Начните создавать действие, определив основной вызов»).

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

  1. В меню навигации нажмите «Основной вызов» .

9ff088c04c995cde.png

  1. Установите флажок Call your webhook и добавьте в текстовое поле имя обработчика событий getSpellingWordList .
  2. В редакторе кода замените текст в поле speech следующим приветственным сообщением: Welcome to Spelling Practice

Примечание: Для редактирования запросов вы можете использовать формат YAML или JSON .

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

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

Консоль Actions предоставляет веб-инструмент для тестирования вашего Action, называемый симулятором . Интерфейс имитирует аппаратные устройства и их настройки, поэтому вы можете взаимодействовать с вашим Action так, как если бы он работал на смарт-дисплее, телефоне, колонке или KaiOS.

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

  1. В верхней панели навигации нажмите «Тест» , чтобы перейти в симулятор.
  2. Чтобы выполнить действие в симуляторе, введите Talk to Spelling Practice в поле ввода в левом верхнем углу, а затем нажмите Enter на клавиатуре.

651fc8da1ac9aa0a.png

Когда вы запускаете основное действие, Ассистент отвечает вашим персонализированным приветственным сообщением. На этом этапе диалог завершается после того, как Ассистент ответит приветствием.

Просмотреть журналы событий

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

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

a6fb192f94426824.png

11. Подготовьте почву для обсуждения правил правописания.

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

Переход от основного вызова к начальной сцене

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

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

  1. В верхней панели навигации нажмите «Разработка» . Затем в левой панели навигации нажмите «Основной вызов» .
  2. В разделе «Переход» справа щелкните раскрывающееся меню, затем введите Start в текстовое поле.

dd4f1807a57f794d.png

  1. Нажмите «Добавить» . Это создаст сцену под названием Start и укажет действию перейти к сцене Start после того, как действие отобразит приветственное сообщение пользователю.
  2. Чтобы отобразить список сцен, нажмите «Сцены» в левой панели навигации.
  3. В разделе «Сцены» нажмите «Старт» , чтобы увидеть Start сцену.
  4. Нажмите кнопку + в разделе «При нажатии Enter» в Start сцене.
  5. Выберите «Отправить запросы» .
  6. Замените предложение в поле speech ( Enter the response that users will see or hear... ) вопросом, который нужно задать пользователю: Use phonetic alphabet to spell the word. For example alpha for a, bravo for b, charlie for c etc. Do you want to continue?

В этом разделе вы добавляете всплывающие подсказки, которые пользователь может кликнуть, и ваше действие обрабатывает их как пользовательский ввод. Подсказки отображаются под только что настроенным запросом (« Do you want to play

Spelling Practice

? ) для поддержки пользователей на устройствах с экранами.

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

  1. В Start сцене нажмите кнопку «Подсказки» под редактором кода. Это действие добавит один значок подсказки.
  2. В поле title замените Suggested Response на 'Yes' .
  3. Используя тот же формат, вручную добавьте подсказки с заголовками 'No' и 'Help with Phonetics' . Ваш код должен выглядеть примерно так:
  4. Нажмите « Сохранить ».

5ff2ecdc56801b91.png

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

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

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

  1. В панели навигации нажмите «Тест» , чтобы перейти в симулятор.
  2. Чтобы протестировать ваше действие в симуляторе, введите Talk to Spelling Practice в поле ввода.
  3. Нажмите Enter . Ваше действие должно ответить приглашением к Main invocation и добавленным приглашением Start сцене: «Добро пожаловать в раздел «Практика правописания». Используйте фонетический алфавит, чтобы написать слово. Например, alpha для a, bravo для b, charlie для c и т. д. Хотите продолжить?» .

На следующем скриншоте показано это взаимодействие:

338c9570b02a618e.png

  1. Нажмите на значок Yes , « No или Help with Phonetics , чтобы ответить на запрос. (Вы также можете сказать «Да» , «Нет» , «Помощь с фонетикой» или ввести Yes , « No » или « Help with Phonetics в поле ввода .)

Когда вы отвечаете на запрос, ваше действие выдает сообщение о том, что оно не может понять ваш ввод: «Извините, я не расслышал. Можете попробовать еще раз?» Поскольку вы еще не настроили свое действие на понимание и реагирование на ввод «Да» или «Нет» , ваше действие сопоставляет ваш ввод с намерением NO_MATCH .

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

Добавить «нет» и фонетические намерения

Теперь, когда пользователи могут отвечать на вопрос, заданный вашим действием, вы можете настроить его так, чтобы оно понимало ответы пользователей ( «Да» , «Нет» или «Помощь с фонетикой» ). В следующих разделах вы создадите пользовательские интенты, которые будут совпадать с ответами пользователя «Да» , «Нет» или «Помощь с фонетикой», и добавите эти интенты в Start сцену. Мы будем использовать системный интент yes и создадим другие интенты.

no создавать намерение

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

  1. В меню навигации нажмите «Разработка» .
  2. Чтобы открыть список интентов, нажмите «Пользовательские интенты» в меню навигации.
  3. Нажмите + (знак плюс) в конце списка интентов. Назовите новый no и нажмите Enter .
  4. Нажмите «Нет» , чтобы открыть страницу no намерения».
  5. В разделе «Добавить обучающие фразы» щелкните текстовое поле «Введите фразу» и введите следующие фразы:
  • No
  • N
  • I don't want
  • nope

98b0c9a7b67ea9b9.png

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

no добавлять намерение в Start сцену

Теперь действие может понимать, когда пользователь выражает «нет» или что-то похожее на «нет» , например, «нет» . Вам нужно добавить намерение пользователя no в Start сцену, потому что пользователь отвечает на подсказку Start » (« Добро пожаловать в практику правописания. Используйте фонетический алфавит, чтобы написать слово. Например, альфа для a, браво для b, чарли для c и т. д. Хотите продолжить?» ).

Чтобы добавить этот интент для сцены Start , выполните следующие шаги:

  1. В меню навигации нажмите кнопку « Начать» .
  2. Нажмите на знак + (плюс) в Start сцене рядом с пунктом «Обработка пользовательских намерений».
  3. В разделе «Намерение» выберите «нет» в раскрывающемся списке.

51f752e78c8b4942.png

  1. Нажмите «Отправить подсказки» и обновите поле speech , указав следующий текст: Good Bye .

В вашем редакторе код должен выглядеть примерно так:

candidates:
  - first_simple:
      variants:
        - speech: >-
             Goodbye.
  1. В разделе «Переход» выберите «Завершить разговор» из выпадающего списка.
  2. Нажмите « Сохранить ».

Проверка no намерения в симуляторе.

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

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

  1. В панели навигации нажмите «Тест» .
  2. Введите в поле ввода Talk to Spelling Practice и нажмите Enter .
  3. Введите No в поле ввода и нажмите Enter. В качестве альтернативы, нажмите на значок подсказки «Нет».

7727a456b522f31b.png

Добавьте системный интент YES в Start сцену.

Теперь добавим интент SYSTEM "YES" в Start сцену, поскольку пользователь отвечает "да" на запрос " Start " (" Добро пожаловать в раздел "Практика правописания". Используйте фонетический алфавит, чтобы написать слово. Например, alpha для a, bravo для b, charlie для c и т. д. Хотите продолжить?" ).

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

  1. В меню навигации нажмите кнопку « Начать» .
  2. Нажмите на знак + (плюс) в Start сцене рядом с пунктом «Обработка пользовательских намерений» .
  3. В разделе «Все системные намерения» выберите «ДА» в раскрывающемся списке намерений.

f6cbe789cde49e8f.png

  1. Нажмите «Вызвать веб-перехватчик» и обновите текстовое поле event handler , указав созданную ранее функцию: getSpellingWordList
  2. В разделе «Переход» щелкните раскрывающийся список и выберите «Завершить разговор» .
  3. Нажмите « Сохранить ».

Проверьте намерение YES в симуляторе.

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

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

  1. В панели навигации нажмите «Тест» .
  2. Чтобы проверить работу вашего действия в симуляторе, введите Talk to Spelling Practice в поле ввода и нажмите Enter .
  3. Введите Yes в поле ввода и нажмите Enter . В качестве альтернативы, нажмите на значок подсказки Yes .

Ваше действие получает список всех слов для тренировки правописания и сохраняет их в сессии. Затем ваше действие завершает сессию, поскольку вы выбрали переход End conversation для намерения YES .

Создать Phonetics намерение

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

  1. В меню навигации нажмите «Разработка» .
  2. Чтобы открыть список интентов, нажмите «Пользовательские интенты» в меню навигации.
  3. Нажмите + (знак плюс) в конце списка намерений. Назовите новое намерение phonetics и нажмите Enter .
  4. Нажмите на phonetics запрос, чтобы открыть страницу phonetics запросом.
  5. В разделе «Добавить обучающие фразы» нажмите на текстовое поле «Введите фразу» и введите следующие фразы:
  • how do I spell words
  • phonetics
  • help me with phonetics
  • phonetic alphabet

1455bdfca8dae46.png

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

Добавить phonetics намерение в Start сцену

Теперь Action может понимать, когда пользователь выражает «фонетическое» намерение. Вы можете добавить phonetics намерение пользователя в Start сцену, поскольку пользователь отвечает на подсказку StartДобро пожаловать в практику правописания. Используйте фонетический алфавит, чтобы написать слово. Например, alpha для a, bravo для b, charlie для c и т. д. Хотите продолжить?» ).

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

  1. В меню навигации нажмите кнопку « Начать» .
  2. Нажмите на знак + (плюс) в Start сцене рядом с пунктом «Обработка пользовательских намерений».
  3. Выберите фонетический вариант в раскрывающемся списке «Намерение».

67ee2e08000b2aee.png

  1. В разделе «Переход» щелкните раскрывающийся список и выберите «Завершить разговор».
  2. Нажмите « Сохранить ».

Переход от начальной сцены к сцене проверки орфографии.

В этом разделе вы создаёте новую сцену под названием «Правописание» , которая отправляет пользователю запрос на написание слова с использованием фонетического алфавита.

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

  1. В верхней панели навигации нажмите «Разработка» . Затем в левой панели навигации нажмите «Начать сцену».
  2. В разделе «Обработка намерений пользователя» щелкните, when actions.intent.YES is matched , а справа в разделе «Переходы » щелкните раскрывающееся меню и введите Spelling в текстовое поле.
  3. Нажмите «Добавить» . Это создаст сцену под названием Spelling » и укажет действию перейти к сцене Spelling после совпадения с намерением «ДА».
  4. Разверните раздел «Сцены» в левой навигационной панели, чтобы отобразить список сцен.
  5. В разделе «Сцены» нажмите «Правописание», чтобы просмотреть сцену Spelling .
  6. Нажмите кнопку + в разделе «При нажатии Enter» в окне Spelling .
  7. Нажмите «Вызвать ваш веб-перехватчик» и введите getSpellingWord в текстовое поле обработчика событий.
  8. Выберите «Отправить запросы» .
  9. Замените предложение в поле speech ( Enter the response that users will see or hear... ) на {} . Фактическое сообщение будет заполнено веб-хуком.

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

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

  1. В разделе Spelling » нажмите «Подсказки» под редактором кода. Это действие добавит три значка с подсказками.
  2. В поле title замените Suggested Response » на 'Repeat' .
  3. Используя тот же формат, вручную добавьте подсказку с заголовком 'Skip' .
  4. Используя тот же формат, вручную добавьте подсказку с заголовком 'Quit' . Ваш код должен выглядеть примерно так:
  5. Нажмите « Сохранить ».
suggestions:
      - title: 'Repeat'
      - title: 'Skip'
      - title: 'Quit'

e1d437f714ea1539.png

Создать Repeat намерение

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

  1. В меню навигации нажмите «Разработка» .
  2. Чтобы открыть список интентов, нажмите «Пользовательские интенты» в меню навигации.
  3. Нажмите + (знак плюс) в конце списка интентов. Назовите новый интент repeat и нажмите Enter .
  4. Нажмите на кнопку repeat намерение», чтобы открыть страницу definition намерения.
  5. В разделе «Добавить обучающие фразы» нажмите на текстовое поле «Введите фразу» и введите следующие фразы:
  • one more time please
  • say the word again
  • repeat the word
  • tell me again
  • repeat

e61f0b9f80510bc9.png

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

Добавить repeat намерение в сцену Spelling

Теперь Action может понимать, когда пользователь выражает намерение «повторить» . Вы можете добавить намерение repeat действие в сцену Spelling , поскольку пользователь отвечает на подсказку SpellingНапишите слово, используя фонетический алфавит »).

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

  1. В меню навигации выберите пункт « Проверка орфографии» .
  2. Нажмите на знак + (плюс) в разделе Spelling рядом с пунктом «Обработка намерений пользователя» .
  3. Выберите пункт «Повторять» в раскрывающемся списке «Намерение».

5cfd623b25bedbed.png

  1. Проверьте, вызываете ли вы свой веб-хук и вводите repeatSpellingWord в текстовое поле обработчика событий, чтобы получить определение слова.
  2. Установите флажок «Отправлять подсказки» .
  3. Замените предложение в поле speech ( Enter the response that users will see or hear... ) на ''. Фактическое сообщение будет заполнено веб-хуком.

Добавьте подсказки в поле "При совпадении с повтором".

  1. В разделе « При совпадении с Repeat » в подразделе «Обработка намерений пользователя» нажмите «Подсказки» под редактором кода. Это действие добавит три значка подсказок.
  2. В поле title замените Suggested Response » на 'Skip' .
  3. Используя тот же формат, вручную добавьте подсказку с заголовком 'Quit' . Ваш код должен выглядеть примерно так:
suggestions:
      - title: 'Skip'
      - title: 'Quit'

ab40e4b0c432b97c.png

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

Создать definition намерения

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

  1. В меню навигации нажмите «Разработка» .
  2. Чтобы открыть список интентов, нажмите «Пользовательские интенты» в меню навигации.
  3. Нажмите + (знак плюс) в конце списка интентов. Присвойте имя новому definition интента и нажмите Enter .
  4. Нажмите на поле definition намерения, чтобы открыть страницу definition намерения.
  5. В разделе «Добавить обучающие фразы» нажмите на текстовое поле «Введите фразу» и введите следующие фразы:
  • I would like to know the definition
  • tell me the definition
  • what does it mean
  • meaning
  • definition
  • what is the definition?

c1b88a9c0b1ac082.png

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

Добавить definition намерения в сцену Spelling

Теперь действие может понимать, когда пользователь выражает намерение «определение» . Вы можете добавить намерение пользователя definition , в сцену Spelling , поскольку пользователь отвечает на подсказку SpellingНапишите слово, используя фонетический алфавит »).

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

  1. В меню навигации выберите пункт « Проверка орфографии» .
  2. Нажмите на знак + (плюс) в разделе Spelling рядом с пунктом «Обработка намерений пользователя» .
  3. Выберите «Определение» в раскрывающемся списке «Намерение».

646bdcac3ad3eb0c.png

  1. Установите флажок «Вызвать веб-перехватчик» и введите definitionOfSpellingWord в текстовое поле обработчика событий, чтобы получить определение слова.
  2. Установите флажок «Отправлять подсказки» .
  3. Замените предложение в поле speech ( Enter the response that users will see or hear... ) на ''`. Фактическое сообщение будет заполнено веб-хуком.

Добавьте вставки с подсказками в ответ веб-перехватчика.

  1. В Start сцене нажмите кнопку «Подсказки» под редактором кода. Это действие добавит три значка подсказок.
  2. In the title field, replace Suggested Response with 'Skip' .
  3. Using the same formatting, manually add a suggestion chip titled 'Quit' .Your code should look like the following snippet:
suggestions:
      - title: 'Skip'
      - title: 'Quit'

25227545839d933f.png

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

Create skip intent

To create the skip intent, follow these steps:

  1. Click Develop in the navigation.
  2. Click Intents in the navigation to open the list of intents.
  3. Click + (plus sign) at the end of the list of intents. Name the new intent skip and press Enter .
  4. Click the skip intent to open the skip intent page.
  5. In the Add training phrases section, click the Enter Phrase text box and enter the following phrases:
  • next word
  • go next
  • next
  • skip
  • skip word

d1c4908a3d7882f8.png

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

Add Skip intent to Spelling scene

Now, the Action can understand when a user is expressing a "skip" intent. You can add the skip user intent to the Spelling scene, since the user is responding to the Spelling prompt (" Spell the word using phonetic alphabet ").

To add this user intent to the Spelling scene, follow these steps:

  1. Click the Spelling scene in the navigation.
  2. Click the + (plus sign) in the Spelling scene next to User intent handlin g.
  3. Select skip in the intent drop-down.

5465f97542217964.png

  1. In the Transition section on the right, click the drop-down menu and select Spelling .

c8072485ca82bd3f.png

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

Create quit intent

To create the Quit intent, follow these steps:

  1. Click Develop in the navigation.
  2. Click Intents in the navigation to open the list of intents.
  3. Click + (plus sign) at the end of the list of intents. Name the new intent Quit and press Enter .
  4. Click the Quit intent to open the definition intent page.
  5. In the Add training phrases section, click the Enter Phrase text box and enter the following phrases:
  • I quit
  • Goodbye
  • Cancel
  • Exit
  • Quit

9916f77b8766541e.png

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

Add Quit intent to Spelling scene

Now, the Action can understand when a user is expressing a "quit" intent. You can add the quit user intent to the Spelling scene, since the user is responding to the Spelling prompt (" Spell the word using phonetic alphabet ").

To add this user intent to the Spelling scene, follow these steps:

  1. Click the Spelling scene in the navigation.
  2. Click the + (plus sign) in the Spelling scene next to User intent handling .
  3. Select quit in the intent drop-down.

5f62fb18a3653d66.png

  1. In the Transition section on the right, click the drop-down menu and select End conversation . 1ffbe35a7bbbb4b0.png
  2. Нажмите « Сохранить ».

Create phonetic_alphabet type

In this section, you create a new type called phonetic_alphabet , which specifies the phonetic alphabet options the users can choose to spell the word. You can also define a few synonyms for these options in case a user says something similar. In a later section, you add the phonetic_alphabet type to a slot to specify that you want to obtain the user's response.

To create the phonetic_alphabet type, follow these steps:

  1. Click Develop in the navigation.
  2. Click the + (plus sign) under Types .
  3. Type phonetic_alphabet and press Enter .
  4. Click phonetic_alphabet to open the options.
  5. In the What kind of values will this Type support? section, select the Words and synonyms option
  6. Enter the following entries and corresponding values in the Add entries section:

а

alpha, apple, amsterdam

б

bravo, butter, baltimore

с

charlie, cat, casablanca

д

delta, dog, denmark

е

echo, edward, edison

ф

foxtrot, fox, florida

г

golf, george, gallipoli

час

hotel, harry, havana

я

india, ink, italia

дж

juliette, johnny, jerusalem

к

kilo, king, kilogramme

л

lima, love, london

м

mike, money, madagascar

н

november, new york, nancy

о

oscar, orange, oslo

п

papa, paris, peter

q

quebec, queen

р

romeo, roma, robert

с

sierra, sugar, santiago

т

tango, tommy, tripoli

у

uniform, umbrella, uncle

в

victor, vinegar, Valencia

в

whiskey, william, washington

х

рентген

й

yankee, yellow, yorker

з

zulu, zebra, zurich

Your key-value table should look like the following:

5b5a5cd9fa557e1b.png

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

Configure slot filling

Next, you need to configure slot filling in the Spelling scene. To configure the slot-filling logic, follow these steps:

  1. Click the Spelling scene in the navigation.
  2. Click the + (plus sign) in the Spelling scene for Slot filling .
  3. In the Enter slot name field, add userresponse as the slot name.
  4. In the Select type drop-down, select phonetic_alphabet as the slot type.
  5. Check This slot accepts a list of values
  6. Check This slot is required .
  7. Select Customize slot value writeback option and enter userresponse in the session parameter textbox.

ba57a419877a07f3.png

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

Add Condition to Spelling screen

To add Condition to the Spelling scene, follow these steps:

  1. Click the Spelling scene in the navigation.
  2. Click the + (plus sign) in the Spelling scene next to Condition.
  3. Enter scene.slots.status == "FINAL" as condition
  4. Check the Call your webhook and enter verifySpellingWord in the event handler textbox to verify the user response.
  5. Check Send prompts.
  6. Replace the sentence in the speech field ( Enter the response that users will see or hear... ) with {} . The actual prompt will be populated by webhook.

Add suggestion chips to the webhook response

  1. In the Start scene, click suggestions below the code editor. This action adds three suggestion chips.
  2. In the title field, replace Suggested Response with 'Next' .
  3. Using the same formatting, manually add a suggestion chip titled 'Quit' .Your code should look like the following snippet:
suggestions:
      - title: 'Next'
      - title: 'Quit'

ac3d7a9366ebc1b1.png

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

12. Test Spelling Practice in the simulator

To test your Action in the simulator, follow these steps:

  1. In the navigation bar, click Test to take you to the simulator.
  2. To test your Action in the simulator, type Talk to Spelling Practice in the Input field.
  3. Press Enter . Your Action should respond with the Main invocation prompt and the added Start scene prompt, "Welcome to Spelling Practice. Use the phonetic alphabet to spell the word. For example alpha for a, bravo for b, charlie for c etc. Do you want to continue?" .
  4. Say Yes to continue
  5. Simulator will play a word sound to spell
  6. You can spell the word using phonetic alphabets. For example, for better say or type "bravo echo tango tango echo romeo"
  7. Simulator will respond with either the correct or incorrect response.
  8. Say next to continue to the next word or say quit to exit the game loop.

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

Congratulations, you've successfully built your game, Spelling Practice !

You now know the key steps required to build a game using Cloud Firestore, Cloud Functions, and Google Assistant Action Builder.

Что вы осветили

  • How to interact with Cloud Firestore
  • How to use slots to gather data from the user
  • How to process a user's input and return a response
  • How to use conditions to add logic to a scene
  • How to add a game loop

Additional learning resources

You can explore these resources for learning about building Actions for Google Assistant:

Clean up your project [recommended]

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:

  1. To delete your Firebase project and resources, complete the steps listed in the Shutting down (deleting) projects section.

Caution: Ensure that you select the correct project for deletion on the Google Cloud Console's Settings page.

  1. Optional: To immediately remove your project from the Actions console, complete the steps listed in the Deleting a project section. If you don't complete this step, your project will automatically be removed after approximately 30 days.

Follow @ActionsOnGoogle & @Firebase on Twitter to stay tuned to our latest announcements and tweet to #GoogleIO to share what you have built!