Перейти к основному содержимому

Подключение Google Assistant для проекта на JAICF

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

  1. Подготовьте проект.
  2. Подключите канал.
  3. Скачайте Action Package.
  4. Зарегистрируйте Action в Actions Console.
  5. Задайте активационную фразу.
  6. Скопируйте Project ID.
  7. Скачайте gactions.
  8. Загрузите Action Package в проект.
  9. Протестируйте бота в симуляторе Actions Console.
предупреждение
Данная интеграция с Google Assistant активна только для проектов, созданных с устаревшей версией Actions SDK. Для проектов, созданных с использованием Conversational Actions, используйте канал Dialogflow.

Подготовка проекта​

Перед подключением канала предварительно подготовьте проект JAICF:

  • Укажите в файле build.gradle.kts в зависимостях настройки:
dependencies {
    // ...
    implementation("com.just-ai.jaicf:jaicp:$jaicfVersion")
    implementation("com.just-ai.jaicf:google-actions:$jaicfVersion")
}
подсказка
Замените $jaicfVersion последней версией фреймворка.
  1. Сконфигурируйте в зависимости от способа подключения к платформе:

  • long polling — бот будет сам подключаться к серверу Just AI при взаимодействии с платформой. Простое решение, подходит для локальной разработки и отладки.

    Для этого способа укажите в файле JaicpPoller.kt канал ActionsFulfillment.ActionsFulfillmentSDK:

package com.just-ai.jaicf.template.connections

fun main() {
    JaicpPollingConnector(
        templateBot,
        accessToken,
        channels = listOf(
            ChatApiChannel,
            ChatWidgetChannel,
            TelephonyChannel,
            ActionsFulfillment.ActionsFulfillmentSDK
        )
    ).runBlocking()
}

  • webhook — по указанной ссылке бот будет принимать сообщения платформы. Необходимо конфигурировать для подключения в JAICP Cloud.

    Для этого способа укажите в файле JaicpServer.kt канал ActionsFulfillment.ActionsFulfillmentSDK:

package com.just-ai.jaicf.template.connections

fun main() {
    JaicpServer(
        botApi = templateBot,
        accessToken = accessToken,
        channels = listOf(
            ChatApiChannel,
            ChatWidgetChannel,
            TelephonyChannel,
            ActionsFulfillment.ActionsFulfillmentSDK
        )
    ).start(wait = true)
}

Подключение канала​

Перейдите в проект JAICF на JAICP. Нажмите на панели управления Каналы → Входящие → Подключить канал. В разделе Голосовые Ассистенты выберите Google Ассистент.

Заполните поля:

  • Название канала — здесь вы можете сменить имя канала на удобное для вас.
  • Web app URL — укажите ссылку на веб-приложение Interactive Canvas при необходимости.
  • Триггеры — укажите фразы, которые будут ассоциироваться с вашим навыком. Если пользователь произнесет одну из этих фраз, Google Assistant предложит запустить ваш навык.

Нажмите Создать

Action Package​

Скачайте JSON вашего Action Package. Для этого нажмите на ссылку Скачать action.json под названием добавленного канала.

Регистрация Action в Actions Console​

Зайдите в Action Console и создайте новый проект. Для этого нажмите Add/import Project. Укажите название для проекта, язык и страну. Выберите категорию для проекта из представленных.

Активационная фраза​

На панели управления перейдите в меню Setup → Invocation. В поле Display name укажите активационную фразу для Action вашего бота.

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

Project ID​

Перейдите в настройки проекта Project settings → скопируйте значение поля Project ID.

gactions​

Скачайте на компьютер программу gactions для вашей операционной системы.

Загрузка Action Package в проект​

Запустите консоль (Windows) или терминал (macOS, Linux). Перейдите в папку, в которую вы сохранили программу gations и JSON-файл для Action Package. Выполните команду:

gactions update --action_package PACKAGE_NAME --project PROJECT_ID
  • Вместо PACKAGE_NAME подставьте имя JSON-файла.
  • Вместо PROJECT_ID подставьте Project ID, который вы скопировали из настроек проекта.

Нажмите Enter.

Разрешение на использование​

Вы получите от gactions URL, который нужно открыть в любом браузере. Скопируйте URL, а затем вставьте в строку браузера.

подсказка
Если вы совершаете эти действия не в первый раз, то вы уже авторизованы и URL для авторизации может не выдаваться.

В браузере откроется страница, на которой вас попросят выбрать аккаунт и дать разрешения на управление проектами. Выберите аккаунт, на котором вы создали проект в Actions Console, нажмите Разрешить.

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

Тестирование​

Теперь вы можете протестировать Action на устройстве с Google Assistant в том же аккаунте, под которым был создан проект. А также вы можете тестировать бота в симуляторе Action Console.

Перед тестированием проставьте разрешения на отслеживание действий в вашем Google Assistant. Для этого перейдите в настройки аккаунта выберите пункт Конфиденциальность → Действия в сервисах Google. Проверьте настройки Отслеживания действий, должны быть активны пункты:

  • история приложений и веб-поиска;
  • информация с устройств;
  • история голосового управления.

Нативные возможности канала​

Хранение пользовательского контекста​

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

fun main() {
    JaicpServer(
        botApi = templateBot,
        accessToken = accessToken,
        channels = listOf(
            ActionsFulfillment.ActionsFulfillmentSDK(useDataStorage = true)
        )
    ).start(wait = true)
}
подсказка
Запросы, приходящие из Google Assistant, будут содержать контекст пользователя.

Нативные реакции​

JAICF предоставляет универсальные реакции, доступные во всех каналах, а также реакции, уникальные для Google Assistant. Чтобы использовать специфические реакции Google Assistant, используйте reactions.actions, например:

action {
    reactions.say("Привет!")
    reactions.actions?.addSimpleResponse("display text", "ssml of text")
}

Вы также можете напрямую обратиться к объекту с ответом через reactions.actions.response:

action {
    val builder = reactions.actions?.response?.builder
    builder?.add("Hello")
}

Ограничения канала​

При разработке сценария для Google Assistant учитывайте следующие ограничения канала:

  1. Каждый ответ должен содержать хотя бы один текстовой элемент. Для этого нужно использовать реакцию say.
  2. Ответ может содержать максимум 1 изображение, аудио или другой медиаконтент.
  3. Ответ с изображением, аудио или медиаконтентом должен содержать кнопки. Для этого воспользуйтесь реакцией buttons.
предупреждение
При отправке изображения и текста порядок, в котором они будут выведены, может отличаться от порядка вызовов реакций.