Настраиваем запросы ассистента в Native App

Обновлено 20 декабря 2023

Code

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

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

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

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

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

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

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

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

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

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

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

   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 чтобы получить сообщение от ОС.

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

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

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

При выборе элементов интерфейса и обмене данными в фоне ассистент может передавать в сценарий запросы 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.

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

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