ym88659208ym87991671
Настраиваем голосовое управление | Документация для разработчиков

Настраиваем голосовое управление

Обновлено 08 декабря 2022

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

Каждый раз когда пользователь работает с приложением (запускает или останавливает приложение, произносит команду, нажимает на кнопку в интерфейсе), ОС формирует запрос, который ассистент передает в сценарий смартапа.

Сценарий — часть бэкенда приложения, работающего на поверхностях Салют, с помощью которой приложение понимает, что сказал или сделал пользователь, и определяет как на это должен отреагировать ассистент и фронтенд приложения. Для разработки сценария Native App лучше всего подходят инструменты Code, SaluteJS и SmartApp Framework.

note

В этом разделе обработка запросов ассистента рассматривается на примере сценария демонстрационного приложения. Сценарий хранится в архиве проекта Code smartapp_script.zip. Для большей наглядности импортируйте проект в личном пространстве.

Чтобы запустить демонстрационный Native App, скажите ассистенту на умном устройстве Sber: «Открой демо новый зеленый». Работает не на всех устройствах.

Запросы ассистента

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

Голосовые команды

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

Схема обработки голосового запроса
note

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

Описание этапов обработки голосовой команды:

  1. Пользователь говорит: «Надень шапку».

  2. ОС устройства получает данные о состоянии фронтенда приложения и передает их ассистенту.

  3. Ассистент передает запрос MESSAGE_TO_SKILL в сценарий смартапа.

    Данные о состоянии приложения передаются в поле payload.meta.current_app.state.<имя_состояния_из_системного_хранилища>, а разбор реплики пользователя в поле payload.message.

  4. Сценарий определяет в запросе наличие интента dressUp и переходит в состояние ЧтоНадеть.

    note

    Интенты настраиваются вручную в разделе Редактор → Интенты.

    state: ЧтоНадеть
    intent!: /dressUp
    script:
    var whatToWear = $parseTree["одежда"][0]["value"]
    reply( {
    "pronounceText": whatToWear + " надели на андроида",
    items: [

    # Вспомогательная функция, которая возвращает данные для фронтенда
    formWearCommand(whatToWear)
    ]
    },
    $response);
  5. Сценарий возвращает ассистенту объект с описанием ответа ассистента.

    Код вспомогательной функции formWearCommand(whatToWear) хранится в файле /src/utils/utils.js проекта Code.

  6. В ответе ANSWER_TO_USER ассистент передает данные в ОС, которая передает их во фронтенд.

  7. Фронтенд использует методы библиотеки Messaging чтобы получить сообщение от ОС.

В результате пользователю отображается андроид в шапке, а ассистент сообщает: «Шапка надета на андроида».

note

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

Фоновые запросы и выбор элемента интерфейса

При выборе элементов интерфейса и обмене данными в фоне ассистент может передавать в сценарий запросы SERVER_ACTION.

Схема обработки фоновых запросов

Описание этапов обработки запроса SERVER_ACTION:

  1. Пользователь нажимает на кнопку в интерфейсе.

  2. Фронтенд передает в ОС данные с помощью методов библиотеки Messaging.

    При этом обязательно заполняется параметр action_id.

  3. ОС устройства получает данные о состоянии фронтенда приложения и передает их ассистенту.

  4. Ассистент, на основе полученных от ОС данных, передает запрос SERVER_ACTION в сценарий.

  5. Сценарий получает сообщение с помощью тегов event или event!.

    Чтобы получить сообщение в теге нужно указать значение параметра action_id.

    state: ActionNativeApp
    event!: ACTION_FROM_NATIVE_APP
    script:
    var request = $jsapi.context().request;

    $payment.clearItems();
    $payment.addItem(request.data.eventData.cardInfo);

    var orderInfo = { order: request.data.eventData.orderInfo };
    $jsapi.log("ORDER INFO " + JSON.stringify(orderInfo))

    var response = $payment.createPayment(orderInfo);
    $jsapi.log("Response: " + JSON.stringify(response))

    $session.invoice_id = response.invoice_id;
    $reactions.pay($session.invoice_id);
  6. Сценарий возвращает ассистенту объект с описанием ответа ассистента.

  7. В запросе ANSWER_TO_USER ассистент передает данные в ОС, которая передает их во фронтенд.

  8. Фронтенд использует методы библиотеки Messaging чтобы получить сообщение от ОС.

Запуск приложения

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

По голосовой команде ассистент передает в сценарий запрос MESSAGE_TO_SKILL с интентом (поле payload.intent) run_app.

При запуске по кнопке в каталоге ассистент передает запрос RUN_APP, который содержит поле payload.server_action.action_id (по умолчанию run_app).

Обработать запрос можно с помощью тега event!, в котором следует указать значение поля intent / server_action.action_id.

note

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

В демонстрационном Native App сценарий определяет команду в стейте runApp с помощью тега q! (вкладка Сценарии, файл main.sc):

# cтейт нужен для запуска Native App на устройстве
# команда старта приходит в тег q, а в теге script передается команда smart_app_data
# которая приводит к запуску Native App на устройстве
# поле smart_app_data может содержать произвольный JSON-объект
state: runApp
event!: runApp
q!: /start
script:
$response.replies = $response.replies || [];
$response.replies.push({
type: 'raw',
body: {
items: [
{
command: {
type: "smart_app_data",
smart_app_data: {
type: "app_action",
message: "запустиприложение"
},
},
},
],
},
});

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

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

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней