Привлекайте пользователей с помощью Action for Google Assistant

1. Обзор

Внимание: поддержка разговорных действий прекращена 13 июня 2023 г. Для получения дополнительной информации см. раздел «Завершение поддержки разговорных действий» .

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

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

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

В практической работе рассматриваются функции взаимодействия с пользователями и передовой опыт использования Actions on Google.

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

Вы улучшите уже существующую функцию, включив в нее следующие возможности:

• Отправляйте пользователям ежедневные обновления, нажав на которые, они смогут связаться с вашим приложением.
• Отправляйте пользователям push-уведомления, которые ссылаются на ваше действие
• Создайте ссылку, которая перенаправит пользователей на ваше действие из мобильного веб-браузера.

Чему вы научитесь

• Что такое вовлеченность пользователей и почему она важна для успеха действия
• Как изменить действие, чтобы повысить вовлеченность пользователей
• Какие функции взаимодействия с пользователем использовать в разных типах действий
• Как использовать Actions API для отправки уведомлений через Assistant

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

Вам необходимо иметь следующие инструменты:

• IDE/текстовый редактор по вашему выбору, например WebStorm , Atom или Sublime
• Терминал для запуска команд оболочки с установленными Node.js, npm и git
• Веб-браузер, например Google Chrome
• Локальная среда разработки с интерфейсом командной строки Firebase
• Мобильное устройство (Android или iOS) с Ассистентом (вам необходимо войти в Ассистента, используя ту же учетную запись Google, которую вы будете использовать для создания этого проекта).

Также настоятельно рекомендуется, хотя и не обязательно, знание JavaScript (ES6) для понимания кода веб-перехватчика.

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

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

Ключевые термины:

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

Понять образец

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

На следующей диаграмме показан ход беседы в примере Action Gym:

Вы внесёте небольшие изменения в диалог, чтобы он лучше соответствовал добавленным функциям взаимодействия. Однако общий дизайн беседы не сильно изменится.

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

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

git clone https://github.com/actions-on-google/user-engagement-codelab-nodejs

Настройте свой проект и агента

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

1. Откройте консоль действий .
2. Нажмите «Новый проект» .
3. Введите название проекта , например engagement-codelab .
4. Нажмите «Создать проект» .
5. Вместо того чтобы выбирать категорию, прокрутите вниз до раздела «Дополнительные параметры» и нажмите на карточку «Разговор» .
6. Нажмите «Создать свое действие» , чтобы развернуть параметры, и выберите «Добавить действие(я)» .
7. Нажмите «Добавить первое действие» .
8. В диалоговом окне «Создать действие» выберите «Пользовательское намерение», а затем нажмите «Создать» , чтобы запустить консоль Dialogflow.
9. На странице создания агента консоли Dialogflow нажмите кнопку Создать .
10. Нажмите на (значок шестеренки) на левой навигационной панели.
11. Нажмите «Экспорт и импорт» , затем «Восстановить из Zip» .
12. Загрузите файл agent.zip из каталога /user-engagement-codelab-nodejs/start/ вы скачали ранее.
13. Введите RESTORE и нажмите Восстановить .
14. Нажмите Готово .

Разверните свое выполнение

Теперь, когда ваш проект Actions и агент Dialogflow готовы, разверните локальный файл index.js с помощью Firebase Functions CLI.

Из каталога /user-engagement-codelab-nodejs/start/functions/ клона базовых файлов выполните следующие команды:

firebase use <PROJECT_ID>

Совет : найдите идентификатор проекта вашего действия в консоли действий в разделе «Обзор» > (значок шестеренки) > Настройки проекта .

npm install

firebase deploy

Если вы видите сообщение об ошибке «В CLI произошла непредвиденная ошибка», попробуйте еще раз выполнить команду firebase deploy .

Через несколько минут вы должны увидеть сообщение « Развертывание завершено! », которое означает, что вы успешно развернули свой веб-перехватчик в Firebase.

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

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

1. Откройте консоль Firebase .
2. Выберите свой проект Actions из списка вариантов.
3. Перейдите в раздел «Разработка» > «Функции» на левой панели навигации. Если вам будет предложено выбрать параметры совместного доступа к данным, вы можете проигнорировать этот вариант, нажав «Сделать это позже ».
4. На вкладке «Панель управления» вы увидите запись «Выполнение» с URL-адресом в поле «Триггер» . Сохраните этот URL-адрес; его нужно будет скопировать в Dialogflow в следующем разделе.

Установите URL-адрес веб-перехватчика в Dialogflow

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

1. Откройте консоль Dialogflow (при желании консоль Firebase можно закрыть).
2. Нажмите «Выполнение» на левой навигационной панели.
3. Включить Webhook .
4. Вставьте URL-адрес, скопированный с панели управления Firebase, если он еще не появился.
5. Нажмите «Сохранить» .

Убедитесь, что ваш проект правильно настроен

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

Совет: Актуальную информацию об использовании симулятора действий можно найти в руководстве по симулятору действий . Если у вас возникнут какие-либо проблемы при выполнении действий, перечисленных ниже, обратитесь к нему.

Чтобы протестировать свое действие в симуляторе действий:

1. В левой навигационной панели консоли Dialogflow нажмите Интеграции > Google Assistant .
2. Убедитесь, что функция автоматического предварительного просмотра изменений включена, и нажмите кнопку «Тест» , чтобы обновить проект действий.
3. Симулятор действий загрузит ваш проект действий. Чтобы протестировать действие, введите Talk to my test app в поле ввода и нажмите Enter.
4. Вы увидите приветственный ответ от Action Gym. Следуйте подсказкам, чтобы продолжить диалог, и убедитесь, что на каждый ваш запрос есть ответ.

Если вы не видите эти ответы, вероятно, возникла проблема с настройкой Firebase. В этом случае попробуйте повторить шаги из раздела «Развертывание системы выполнения заказов».

3. Добавьте подписку на ежедневные обновления.

Распространённый способ взаимодействия с пользователями — предоставлять им информацию в момент её максимальной пользы. Это достигается путём предоставления пользователям возможности подписаться на ежедневные обновления по определённому намерению, что позволяет им получать уведомления от Помощника, напрямую связанные с выполнением этого намерения.

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

Как это привлечет пользователей?

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

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

• Убедитесь, что ежедневные обновления позволяют пользователю видеть разную полезную информацию каждый день. Если при нажатии на ежедневное обновление каждый раз отображается одно и то же сообщение, пользователь, вероятно, отпишется через пару дней.
• Убедитесь, что ваш диалог понятен пользователю, если он сразу переходит к теме вашего ежедневного обновления. Пользователь не обязательно начнёт диалог с самого начала, поэтому не стоит ожидать от него подробного контекста.
• Покажите пользователю преимущества вашего действия, прежде чем предлагать ему подписаться на ежедневные обновления. Когда пользователю предлагается подписаться, он должен думать: «Я хочу получать этот контент каждый день».
• Не перегружайте пользователя многократными предложениями подписаться. Предложите подписку на ежедневные обновления сразу после того, как покажете пользователю, на что он хотел бы подписаться, и не надоедайте ему этим вопросом в других местах.
• Поддерживайте краткий диалог после срабатывания намерения обновиться. Большинство ежедневных обновлений должны состоять из одного ответа, а затем закрываться без необходимости ввода данных пользователем.

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

Включить ежедневные обновления

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

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

1. В консоли «Действия» откройте вкладку «Разработка» и выберите «Действия» на левой панели навигации.
2. Нажмите «Список классов» под списком «Действия» .
3. В разделе «Вовлеченность пользователей» включите опцию «Хотите ли вы предлагать пользователям ежедневные обновления?» .
4. Задайте описательный заголовок контента , описывающий ежедневные обновления. Контекст будет таким: «Во сколько вы хотите, чтобы я отправлял вам ежедневные новости?», поэтому убедитесь, что заголовок описательный и правильно произносится вслух. В этом примере задайте заголовок контента « list of upcoming Action Gym classes .
5. Нажмите кнопку «Сохранить» в верхней части страницы.

Настройка Dialogflow

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

Предложить пользователю подписаться

1. Создайте новое намерение для обработки запроса пользователя на подписку на ежедневные обновления. В консоли Dialogflow нажмите кнопку «+» рядом с разделом «Намерения» в левой навигационной панели, чтобы создать новое намерение.
2. Назовите это новое намерение Setup Updates .
3. В разделе «Фразы обучения» добавьте следующие пользовательские выражения :

• Send daily reminders
• Reminder
• Remind me
• Updates
• Upcoming classes

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

Обрабатывать решение пользователя

1. Создайте новое намерение для обработки ответа пользователя на запрос подписки на ежедневные обновления. Нажмите кнопку «+» рядом с разделом «Намерения» в левой навигационной панели, чтобы создать новое намерение.
2. Назовите это новое намерение Confirm Updates .
3. В разделе «События» добавьте actions_intent_REGISTER_UPDATE . Это событие Dialogflow будет инициировано пользователем, завершившим подписку на ежедневные обновления, независимо от того, оформил ли он подписку или нет.
4. В разделе «Выполнение» включите опцию Включить вызов веб-перехватчика для этого намерения .
5. Нажмите кнопку «Сохранить» в верхней части страницы.

Реализовать выполнение

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

Зависимости загрузки

В файле index.js обновите функцию require() , чтобы добавить пакет RegisterUpdate из пакета actions-on-google , чтобы ваш импорт выглядел следующим образом:

index.js

const {
  dialogflow,
  Suggestions,
  RegisterUpdate,
} = require('actions-on-google');

Обновление фишек предложений

В файле index.js добавьте запись DAILY в список заголовков чипов предложений, чтобы определение Suggestion выглядело следующим образом:

index.js

// Suggestion chip titles
const Suggestion = {
  HOURS: 'Ask about hours',
  CLASSES: 'Learn about classes',
  DAILY: 'Send daily reminders',
};

Добавьте реализацию новых намерений

Когда пользователь захочет подписаться, запустите процесс подписки на ежедневные обновления, вызвав вспомогательный метод RegisterUpdate с указанием целевого намерения обновления ( Class List ) и типа ( DAILY ). После завершения процесса подписки Помощник активирует событие actions_intent_REGISTER_UPDATE с аргументом status , который описывает, была ли подписка успешной или нет. Предлагайте пользователю подсказки для дальнейших действий, которые меняются в зависимости от статуса подписки.

В файл index.js добавьте следующий код:

index.js

// Start opt-in flow for daily updates
app.intent('Setup Updates', (conv) => {
  conv.ask(new RegisterUpdate({
    intent: 'Class List',
    frequency: 'DAILY',
  }));
});

// Confirm outcome of opt-in for daily updates
app.intent('Confirm Updates', (conv, params, registered) => {
  if (registered && registered.status === 'OK') {
     conv.ask(`Gotcha, I'll send you an update everyday with the ` +
     'list of classes. Can I help you with anything else?');
  } else {
    conv.ask(` I won't send you daily reminders. Can I help you with anything else?`);
  }
  if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.HOURS, Suggestion.CLASSES]));
  }
});

Предлагайте альтернативные подсказки для пользователя

В конце вашего ответа на Class List будет предложена подписка на ежедневные обновления, но это создаёт проблему. Поскольку этот же ответ будет срабатывать при нажатии пользователем на уведомление о ежедневном обновлении, пользователю всё равно будет предложено подписаться на ежедневные обновления, даже если он только что получил одно из них. Как сделать так, чтобы пользователь не думал, что ему нужно подписаться снова?

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

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

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  const classesMessage =
  `On ${day} we offer the following classes: ${classes}. ` +
  `Can I help you with anything else?`;
  conv.ask(classesMessage);
  if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.HOURS]));
  }
});

с этим:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like me to send you daily reminders of upcoming classes, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.HOURS]));
    };
  };
});

Тестируйте ежедневные обновления

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

firebase deploy

Совет: Актуальную информацию об использовании симулятора действий можно найти в руководстве по симулятору действий . Если у вас возникнут какие-либо проблемы при выполнении действий, перечисленных ниже, обратитесь к нему.

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

1. В консоли действий перейдите к пункту Тест .
2. Введите Talk to my test app в поле ввода и нажмите Enter.
3. Введите Learn about classes и нажмите Enter. Теперь ответ вашего действия должен предлагать ежедневную отправку напоминаний.
4. Введите Send daily reminders и нажмите Enter.
5. Введите время, когда вы хотели бы увидеть обновление, и нажмите Enter. Для проверки попробуйте ответить на 3–5 минут позже текущего времени.

Если при попытке подписаться на ежедневные обновления на шаге 4 возникает ошибка, вернитесь в раздел «Сборка» > «Действия» > «Список классов» и отключите ежедневные обновления. Нажмите «Сохранить» , снова включите ежедневные обновления, снова нажмите «Сохранить» , а затем повторите попытку тестирования в симуляторе.

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

4. Добавьте push-уведомления

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

Ключевые термины:

• Actions API: Actions API — это REST API помощника, используемый для отправки уведомлений пользователям. С разрешения пользователя вы можете отправить POST запрос к конечной точке Actions API, которая отправит ему push-уведомление, используя содержимое запроса.

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

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

Ключевые термины:

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

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

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

Как это привлечет пользователей?

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

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

• Запланируйте несколько примеров расписания push-уведомлений. Если вы планируете отправлять только одно push-уведомление в день, рассмотрите возможность использования ежедневных обновлений.
• Убедитесь, что ваши push-уведомления будут предоставлять полезную информацию при каждом получении. Уведомления также могут ссылаться на одно из намерений вашего действия, поэтому убедитесь, что намерение полезно и релевантно.
• Просите пользователя подписаться на push-уведомления, давая ему чёткую информацию. Он должен понимать, чего ожидать от каждого push-уведомления, и иметь представление о частоте их отправки.

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

Включить API действий

1. Откройте консоль Google Cloud и выберите название своего проекта Actions в раскрывающемся списке.

2. В навигационном меню ( ☰) перейдите в раздел API и службы > Библиотека.
3. Найдите Actions API и нажмите Включить .

Создать учетную запись службы

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

1. В навигационном меню Google Cloud Console (☰) перейдите в раздел API и службы > Учетные данные .
2. Нажмите Создать учетные данные > Ключ учетной записи службы .
3. В раскрывающемся меню Учетная запись службы выберите Новая учетная запись службы.
4. Заполните следующую информацию:

• Имя учетной записи службы : service-account
• Роль : Проект > Владелец
• Идентификатор учетной записи службы: service-account (всегда сопровождается @<project_id>.iam.gserviceaccount.com)
• Тип ключа : JSON

5. Нажмите «Создать».
6. Переместите загруженный JSON-файл в каталог /user-engagement-codelab/start/functions/ вашего проекта.
7. Переименуйте JSON-файл в service-account.json .

Включить Firestore

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

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

1. В консоли Firebase выберите имя вашего проекта Actions.
2. В левой навигационной панели выберите Разработка > База данных и нажмите Создать базу данных .
3. Выберите Запустить в тестовом режиме .
4. Нажмите «Включить» .

Совет: мы используем правила безопасности тестового режима только для целей тестирования. Перед публикацией вашего действия в рабочей среде вам понадобятся более надежные правила безопасности данных. Подробнее о правилах безопасности Cloud Firestore см. в документации Firestore .

Настройка Dialogflow

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

Предложить пользователю подписаться

1. Создайте новое намерение для обработки запроса пользователя на подписку на push-уведомления об отменённых занятиях. В консоли Dialogflow нажмите кнопку «+» рядом с разделом «Намерения» в левой навигационной панели, чтобы создать новое намерение.
2. Назовите это новое намерение Setup Push Notifications .
3. В разделе «Фразы обучения» добавьте следующие пользовательские выражения :

• Subscribe to notifications
• Send notification
• Notify me
• Send class notifications
• Cancelled notifications

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

Обрабатывать решение пользователя

1. Настройте новое намерение для обработки ответа пользователя на запрос подписки на push-уведомления. Нажмите кнопку «+» рядом с разделом «Намерения» в левой навигационной панели, чтобы создать новое намерение.
2. Назовите это новое намерение Confirm Push Notifications .
3. В разделе «События» добавьте actions_intent_PERMISSION . Это событие Dialogflow будет вызвано, когда пользователь завершит процесс подписки на push-уведомления, независимо от того, оформил ли он подписку или нет.
4. В разделе «Выполнение» включите опцию Включить вызов веб-перехватчика для этого намерения .
5. Нажмите кнопку «Сохранить» в верхней части страницы.

Обработка push-уведомлений

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

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

1. В консоли Dialogflow нажмите кнопку + рядом с пунктом Намерения в левой навигационной панели, чтобы создать новое намерение.
2. Назовите это новое намерение Class Canceled .
3. В разделе Фразы обучения добавьте Cancelations как пользовательское выражение .
4. В разделе «Выполнение» включите опцию Включить вызов веб-перехватчика для этого намерения .
5. Нажмите кнопку «Сохранить» в верхней части страницы.

Отправлять тестовые уведомления во время разговора

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

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

1. Для тестирования и отладки создайте новое намерение, позволяющее отправлять push-уведомления подписчикам. В консоли Dialogflow нажмите кнопку «+» рядом с разделом «Намерения» в левой навигационной панели, чтобы создать новое намерение.
2. Назовите это новое намерение Test Notification .
3. В разделе Фразы обучения добавьте Test notification как выражение пользователя .
4. В разделе «Выполнение» включите опцию Включить вызов веб-перехватчика для этого намерения .
5. Нажмите кнопку «Сохранить» в верхней части страницы.

Включить push-уведомления

Выполните следующие действия, чтобы включить push-уведомления для намерения «Класс отменен» :

1. В консоли Dialogflow перейдите в раздел Интеграции на панели навигации.
2. На карточке Google Ассистента нажмите Настройки интеграции .
3. Добавьте «Класс отменен» в качестве неявного намерения вызова . Этот шаг необходим для того, чтобы Dialogflow распознавал, что пользователи могут начать диалог с намерением « Класс отменен» (нажав на push-уведомление).
4. Нажмите «Закрыть» .

5. В консоли «Действия» откройте вкладку «Разработка» и выберите «Действия» на левой панели навигации.
6. Нажмите «Занятие отменено» под списком действий .
7. В разделе «Взаимодействие с пользователями» включите опцию « Хотите ли вы отправлять push-уведомления?» .
8. Задайте описательный заголовок контента , описывающий push-уведомление. Контекст будет таким: «Можно ли отправлять push-уведомления для ?», поэтому убедитесь, что заголовок описательный и правильно произносится вслух. В этом примере задайте заголовок контента « class cancelations .
9. Нажмите кнопку «Сохранить» в верхней части страницы.

Реализовать выполнение

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

Зависимости загрузки

В файле index.js обновите функцию require() , чтобы добавить пакет UpdatePermission из пакета actions-on-google , чтобы ваш импорт выглядел следующим образом:

index.js

const {
  dialogflow,
  Suggestions,
  RegisterUpdate,
  UpdatePermission,
} = require('actions-on-google');

Обновление фишек предложений

В файле index.js добавьте запись NOTIFICATIONS в список заголовков чипов предложений, чтобы определение Suggestion выглядело следующим образом:

index.js

// Suggestion chip titles
const Suggestion = {
  HOURS: 'Ask about hours',
  CLASSES: 'Learn about classes',
  DAILY: 'Send daily reminders',
  NOTIFICATIONS: 'Get notifications',
};

Настройте новый импорт

Чтобы подключиться к базе данных Firestore, добавьте пакет firebase-admin и константы для полей, хранящихся в базе данных. Также импортируйте пакеты google-auth-library и request для обработки аутентификации и запросов к Actions API.

В файле index.js добавьте следующий код к вашим импортам:

index.js

// Firebase admin import
const admin = require('firebase-admin');

// Initialize Firestore
admin.initializeApp();
const db = admin.firestore();

// Firestore constants
const FirestoreNames = {
 INTENT: 'intent',
 USER_ID: 'userId',
 USERS: 'users',
};

// Actions API authentication imports
const {auth} = require('google-auth-library');
const request = require('request');

Предложение настроить уведомления об отмене занятий

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

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like me to send you daily reminders of upcoming classes, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.HOURS]));
    };
  };
});

с этим:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like to receive daily reminders of upcoming classes, subscribe to notifications about cancelations, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.NOTIFICATIONS,
Suggestion.HOURS]));
    };
  };
});

Добавьте реализацию новых намерений

Когда пользователь хочет подписаться на push-уведомления, вызовите вспомогательный метод UpdatePermission , чтобы запросить разрешение. В случае успеха аргумент PERMISSION будет добавлен к аргументам объекта conv , которые можно проверить, чтобы изменить ход обсуждения.

Получив разрешение пользователя, извлеките его идентификатор из аргументов объекта conv и сохраните его в базе данных. Позже вы отправите этот идентификатор в Actions API, и именно по нему Помощник определит, кто получает уведомление.

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

В файл index.js добавьте следующий код:

index.js

// Call the User Information helper for permission to send push notifications
app.intent('Setup Push Notifications', (conv) => {
 conv.ask('Update permission for setting up push notifications');
 conv.ask(new UpdatePermission({intent: 'Class Canceled'}));
});

// Handle opt-in or rejection of push notifications
app.intent('Confirm Push Notifications', (conv) => {
 if (conv.arguments.get('PERMISSION')) {
   let userId = conv.arguments.get('UPDATES_USER_ID');
   if (!userId) {
     userId = conv.request.conversation.conversationId;
   }
   // Add the current conversation ID and the notification's
   // target intent to the Firestore database.
   return db.collection(FirestoreNames.USERS)
   .add({
     [FirestoreNames.INTENT]: 'Class Canceled',
     [FirestoreNames.USER_ID]: userId,
   })
   .then(() => {
     conv.ask(`Great, I'll notify you whenever there's a class cancelation. ` +
     'Can I help you with anything else?');
   });
 } else {
   conv.ask(`Okay, I won't send you notifications about class cancelations. ` +
     'Can I help you with anything else?');
 }
 if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.CLASSES, Suggestion.HOURS]));
  }
});

// Intent triggered by tapping the push notification
app.intent('Class Canceled', (conv) => {
 conv.ask('Classname at classtime has been canceled.');
});

Добавить тестовые уведомления

Чтобы отправить пользователю push-уведомление, отправьте POST запрос к Actions API с идентификатором пользователя, заголовком уведомления и целевым намерением. В этом примере запуск намерения «Тестовое уведомление» пройдёт по базе данных Firestore и отправит push-уведомления всем пользователям, подписанным на уведомления.

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

В файл index.js добавьте следующий код:

index.js

// Debug intent to trigger a test push notification
app.intent('Test Notification', (conv) => {
 // Use the Actions API to send a Google Assistant push notification.
 let client = auth.fromJSON(require('./service-account.json'));
 client.scopes = ['https://www.googleapis.com/auth/actions.fulfillment.conversation'];
 let notification = {
   userNotification: {
     title: 'Test Notification from Action Gym',
   },
   target: {},
 };
 client.authorize((err, tokens) => {
   if (err) {
     throw new Error(`Auth error: ${err}`);
   }
   // Iterate through Firestore and send push notifications to every user
   // who's currently opted in to canceled class notifications.
   db.collection(FirestoreNames.USERS)
       .where(FirestoreNames.INTENT, '==', 'Class Canceled')
       .get()
       .then((querySnapshot) => {
         querySnapshot.forEach((user) => {
           notification.target = {
             userId: user.get(FirestoreNames.USER_ID),
             intent: user.get(FirestoreNames.INTENT),
           };
           request.post('https://actions.googleapis.com/v2/conversations:send', {
             'auth': {
               'bearer': tokens.access_token,
             },
             'json': true,
             'body': {'customPushMessage': notification, 'isInSandbox': true},
           }, (err, httpResponse, body) => {
             if (err) {
               throw new Error(`API request error: ${err}`);
             }
             console.log(`${httpResponse.statusCode}: ` +
               `${httpResponse.statusMessage}`);
             console.log(JSON.stringify(body));
           });
         });
       })
       .catch((error) => {
         throw new Error(`Firestore query error: ${error}`);
       });
 });
 conv.ask('A notification has been sent to all subscribed users.');
});

Протестируйте свои push-уведомления

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

firebase deploy

Совет: Актуальную информацию об использовании симулятора действий можно найти в руководстве по симулятору действий . Если у вас возникнут какие-либо проблемы при выполнении действий, перечисленных ниже, обратитесь к нему.

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

1. В консоли Действия перейдите на вкладку Тест .
2. Введите Talk to my test app в поле ввода и нажмите Enter.
3. Введите Learn about classes и нажмите Enter.
4. Введите Get notifications и нажмите Enter.
5. Если вы еще не предоставили своему приложению разрешение на отправку вам push-уведомлений, введите yes и нажмите Enter.
6. Введите yes и нажмите Enter. Теперь ваш аккаунт Google должен быть подписан на push-уведомления для этого действия.

Если при попытке подписаться на push-уведомления на шаге 4 возникает ошибка, вернитесь в раздел «Сборка» > «Действия» > «Класс отменен» и отключите push-уведомления. Нажмите «Сохранить» , снова включите push-уведомления, снова нажмите «Сохранить» , а затем повторите попытку тестирования в симуляторе.

7. Введите no и нажмите Enter, чтобы выйти.
8. Введите Talk to my test app и нажмите Enter, чтобы начать новый разговор.
9. Введите Test notification и нажмите Enter.

В течение нескольких минут вы получите push-уведомление от помощника Action Gym «Тестовое уведомление от Action Gym» на своё мобильное устройство. Нажатие на это уведомление перенаправит вас к намерению «Занятие отменено» вашего действия.

Если у вас возникли проблемы с появлением уведомления, попробуйте выполнить тестовые инструкции на телефоне. Откройте Ассистент на телефоне и скажите « talk to my test app », затем следуйте инструкциям, начиная с шага 3.

5. Создайте ссылку на помощника

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

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

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

Как это привлечет пользователей?

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

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

• Помощники ссылок работают только после публикации ваших действий. В то время как ваш проект находится в проекте штата, ссылка будет работать только на ваших собственных устройствах. Любой другой будет доставлен на страницу 404 в каталоге действий.
• Вы можете позволить пользователям тестировать помощник ссылки до публикации, выпустив ваше действие в альфа -или бета -среде . Обратите внимание, что только пользователи, которые участвуют в вашей альфа или бета -версии, смогут проверить вашу ссылку «Помощник».
• Убедитесь, что намерение пункта назначения для вашей ассистентной ссылки производит хорошее первое впечатление с новыми пользователями. Ваше приветственное намерение - пункт назначения по умолчанию для ассистентной ссылки, потому что она уже должна хорошо представить ваше действие

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

Включите помощники

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

1. В консоли «Действия» нажмите на вкладку «Разработать» и выберите «Действия» в левой навигационной панели.
2. Нажмите на actions.intent.main в списке действий .
3. В разделе «Ссылки» переключите бы, что вы хотели бы включить URL для этой опции действия .
4. Установите название описательной ссылки , которое описывает ваше действие. Сделайте свой заголовок простой парой глаголов, которая описывает то, что пользователь может достичь с помощью вашего действия. Для этого примера установите заголовок ссылки , чтобы learn about Action Gym .
5. Скопируйте фрагмент HTML от нижней части этой страницы и сохраните его на потом.
6. Нажмите Сохранить в верхней части страницы.

Развернуть тестовый веб -сайт

Чтобы проверить свою ссылку «Помощник», вы можете использовать инструменты Firebase для развертывания тестового веб -сайта вместе с вашим выполнением. Мы уже создали простой тестовый веб -сайт для этого примера, вам просто нужно добавить свою ссылку «Помощник».

Перейдите к вашему исполнению /user-engagement-codelab-nodejs/start/public/ Directory и откройте файл index.html в текстовом редакторе.

В файле index.html вставьте фрагмент HTML вашей помощника ссылки в элемент кузова. Файл должен в конечном итоге выглядеть как фрагмент ниже:

index.html

<body>
    <p>
     <a href="https://assistant.google.com/services/invoke/uid/000000efb5f2fd97">🅖 Ask my test app to learn about Action Gym
     </a>
    </p>
</body>

Проверьте свою ассистентную ссылку

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

firebase deploy

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

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

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

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

Поздравляю!

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

Дополнительные учебные ресурсы

Изучите эти ресурсы, чтобы узнать больше о вовлечении пользователей для ваших действий:

• Привлечение пользователей и помощники ссылки документы : официальные действия по документации Google по функциям, обсуждаемым в этом коделабе и вовлечении пользователей в целом.
• Аналитика удержания пользователей : документация для аналитической функции в консоли действий, которая показывает удержание пользователей для вашего опубликованного действия.
• Рекомендации по разговору о дизайне : лучшие практики и руководящие принципы для разработки функций взаимодействия с пользователями.
• Действия на Google Github Repo : Пример кода и библиотеки.
• R/GoogleasSistantDev : официальное сообщество Reddit для разработчиков, работающих с помощником.

Следите за нами в Twitter @Actchongoogle, чтобы следить за обновлениями на наши последние объявления, и твитнуть #AogDevs , чтобы поделиться тем, что вы создали!

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

Прежде чем уйти, пожалуйста, заполните эту форму, чтобы сообщить нам, как у нас дела!