Выбор элемента интерфейса

Обновлено 29 июня 2023

SmartApp API

Интерфейс приложения может быть представлен в виде галереи или списка.

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

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

1. Пользователь произносит команду «Положи в корзину килограмм бананов».

2. Ассистент запрашивает данные об экране приложения (состояние фронтенда) с помощью метода getState().

3. Данные передаются в объекте AssistantAppState, содержащем объект item_selector с описанием элементов экрана, которые может выбрать пользователь.

   Пример формирования объекта item_selector на фронтенде:

   useEffect(() => {
          assistantStateRef.current = {
              item_selector: {
                  items: appState.notes.map(({ id, title }, index) => ({
                      number: index + 1,
                      id,
                      title,
                  })),
              },
          };
      }, [appState]);

   Фронтенд должен вернуть данные в течение 200 мс, в противном случае сценарий получит устаревшие данные или пустой объект, если данные отсутствуют.

4. Ассистент разбирает реплику пользователя, формирует сообщение MESSAGE_TO_SKILL и передает его в сценарий. Если реплика пользователя содержит элемент, описанный в item_selector, ассистент сохраняет его в поле payload.selected_item запроса.

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

5. Сценарий обрабатывает сообщение и возвращает ассистенту ответ в формате ANSWER_TO_USER.

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

Описание доступных элементов в item_selector

Пример элементов, которые пользователь может выбрать на экране приложения, в объекте item_selector:

Пример

required	Array of objects[ items ] Массив объектов, описывающих элементы интерфейса которые может выбрать пользователь
ignored_words	Array of strings Массив слов, которые будут проигнорированы при распознавании реплик пользователя

{

• "items": [

  • {

    • "number": 0,
    • "visible": true,
    • "id": "string",
    • "aliases": [

      • "сок"

      ],
    • "title": "Яблочный сок"

    }

  ],
• "ignored_words": [

  • [

    • "удали",
    • "добавь"

    ]

  ]

}

Описание

required	Array of objects[ items ] Массив объектов, описывающих элементы интерфейса которые может выбрать пользователь
ignored_words	Array of strings Массив слов, которые будут проигнорированы при распознавании реплик пользователя

{

• "items": [

  • {

    • "number": 0,
    • "visible": true,
    • "id": "string",
    • "aliases": [

      • "сок"

      ],
    • "title": "Яблочный сок"

    }

  ],
• "ignored_words": [

  • [

    • "удали",
    • "добавь"

    ]

  ]

}

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

Описание выбранного элемента selected_item

Элемент, который выбрал пользователь, ассистент сохраняет в поле payload.selected_item и передает его в сценарий приложения в сообщении MESSAGE_TO_SKILL. Если пользователь ничего не выбрал, объект selected_item будет пустым.

Описание полей объекта selected_item:

Пример

index required	integer <int32> Номер элемента из списка item_selector.items, начиная с 0
title required	string Название элемента
is_query_by_number required	boolean Указывает на выбор элемента по номеру в списке, а не по тексту

{

• "index": 0,
• "title": "Яблочный сок",
• "is_query_by_number": true

}

Описание

index required	integer <int32> Номер элемента из списка item_selector.items, начиная с 0
title required	string Название элемента
is_query_by_number required	boolean Указывает на выбор элемента по номеру в списке, а не по тексту

{

• "index": 0,
• "title": "Яблочный сок",
• "is_query_by_number": true

}

Сценарий приложения обрабатывает выбранный элемент и передает результат обработки на фронтенд через ассистента в сообщении ANSWER_TO_USER.

Смотрите также

• Обмен данными при голосовых запросах в Canvas App.